# Form

> Runs a whole form: checks every answer and shows what needs fixing before it sends.

- **Level**: organism · **Status**: stable · **Role**: input
- **Import**: `import { Form, FormCheckbox, FormErrorSummary, FormField, FormInput, FormRadioGroup } from "@rrios-forge/ui/organisms/form";`
- **Source**: `packages/ui/src/organisms/form`

Apple-style form orchestrator built around React Hook Form. Pass `methods` from `useForm()` (typically wired with a Zod resolver via `@hookform/resolvers/zod`) and the orchestrator handles `handleSubmit`, `FormProvider`, the auto-mounted ErrorSummary on failed submits, success transient on the Submit button, and the canonical Apple-app-shell action row. The compound parts — `Form.Field`, `Form.Input`, `Form.Textarea`, `Form.Checkbox`, `Form.Switch`, `Form.RadioGroup`, `Form.Select`, `Form.Slider`, `Form.Submit`, `Form.Reset`, `Form.ErrorSummary`, `Form.Section`, `Form.Surface` — read RHF state via `useFormContext()` so consumers never prop-drill.

## Use it for

- Complex validated form → `Form` organism (RHF + Zod)

## Axes

| Axis | Part | Values | Default | Meaning |
|---|---|---|---|---|
| `align` | — | `between` `end` | `end` | Distribution along the main axis. |
| `tone` | — | `neutral` `muted` | `neutral` | Which semantic colour family the element speaks in. |
| `material` | — | `vibrant` `solid` | `vibrant` | The layer's material (ADR-022, ADR-027). |

## Stories

- [Playground](/?path=/story/components-organisms-form--playground) · frame: `/iframe.html?id=components-organisms-form--playground&viewMode=story`
- [On a card](/?path=/story/components-organisms-form--surface) · frame: `/iframe.html?id=components-organisms-form--surface&viewMode=story`
- [Toggles and choices](/?path=/story/components-organisms-form--controlled-fields) · frame: `/iframe.html?id=components-organisms-form--controlled-fields&viewMode=story`
- [Repeating fields](/?path=/story/components-organisms-form--field-array) · frame: `/iframe.html?id=components-organisms-form--field-array&viewMode=story`
- [Errors on submit](/?path=/story/components-organisms-form--invalid-on-submit) — interaction test · frame: `/iframe.html?id=components-organisms-form--invalid-on-submit&viewMode=story`
- [Editing](/?path=/story/components-organisms-form--edit-intent) · frame: `/iframe.html?id=components-organisms-form--edit-intent&viewMode=story`
- [Fix and submit](/?path=/story/components-organisms-form--fix-and-submit) — interaction test · frame: `/iframe.html?id=components-organisms-form--fix-and-submit&viewMode=story`

## Decisions that name it

- ADR-019 — Composer organism (message/post authoring surface)

## Always

- Tokens only (R04); variants are semantic axes, never appearance (R02).
- Typography and actions are Poesía atoms, never raw HTML with utilities.
- Vibrant panes need a ground and never nest (ADR-027).