# Forms

Form composition: field stack, label / helper / error pairing, multi-step wizards. Reference: `kdcsurveyadd/components/surveys/SurveyWizard.tsx` (4-step wizard) and `kdcsurveyadd/components/surveys/StepIndicator.tsx`.

## Anatomy

See `anatomy.svg`. Field row = label + optional helper hint + control + error slot. Sections separated by 32px; fields within a section by 16px.

## Field structure

```
<label> field name                          (bodyM, 600, text.default)
<helper> optional hint                      (bodyS, 400, text.muted)
<input>                                     (input.default)
<error>  message when invalid               (bodyS, 500, semantic.danger, role="alert")
```

## Layout

- **Single column** by default — multi-column only for ≥ 3 closely-related short fields (address, date range).
- **Field width** matches expected content: numeric → 120px, short text → 240px, free text → fill container.
- **Required indicator** — append `*` to label in `semantic.danger`; never use placeholder text or icon-only.
- **Optional fields** — append `(optional)` in `text.muted` `caption`.

## Wizard pattern (multi-step)

- Step indicator on top: `step n of N` + horizontal progress (`StepIndicator`).
- Context strip below — pills summarising decisions so far (jump-back affordance).
- Footer fixed: `Back` (ghost, left) · `Save & exit` (outline) · `Continue` / `Submit` (primary or accent, right).
- Validate per-step on `Continue`; never reveal step `n+1` errors prematurely.

## Tokens used

`components.input.*`, `components.button.*`, `colors.semantic.danger`, `typography.bodyM`/`bodyS`/`caption`.

## Accessibility

- Use a `<form>` element with explicit `<button type="submit">`.
- Group related fields with `<fieldset>` + `<legend>`.
- Errors are announced via `role="alert"` and referenced by `aria-describedby`.
- On submit failure, focus moves to the first invalid field.
- Wizard step indicator uses `aria-current="step"` on the active step.

## Do / Don't

- ✅ Validate on blur for individual fields; on submit for the whole form.
- ✅ Preserve user input across step changes — never silently discard.
- ❌ Don't show inline validation on first focus (only on blur or submit attempt).
- ❌ Don't disable the submit button to indicate invalid state — show the errors instead.