# Accessibility

URL: https://docs.forms.saastro.io/docs/accessibility
> The accessibility target of @saastro/forms (WCAG 2.2 AA), what the package guarantees per field and per step, what its axe tests cover, what they do not, and how to test your own form.

# Accessibility

## Target

The goal is **WCAG 2.2 level AA** (a target: the tests below do not prove it) for the form as a whole. `@saastro/forms` is UI-agnostic: it renders the structure and the behaviour, and **your injected primitives** (`Input`, `Button`, `FormControl`, `Field`…) render the controls. So accessibility is shared: the package owns what it draws itself, and you own colours, focus styles and the controls you inject.

## What the package does

| Area | Behaviour |
| ---- | --------- |
| Validation errors | Each field's error sits in an `aria-live="polite"` region, so it is announced when it appears. |
| Form-level errors | A cross-field (`_form`) error, a submit error and the success message use `role="alert"`. |
| Step changes | In a form with more than one step, a visually hidden `role="status"` region announces "Step 2 of 3" (`Paso 2 de 3` in Spanish), and focus moves to the new step's heading. Without a step title, focus goes to the first control. It does not steal focus on first mount. |
| Going back to a step | `Back` and `goToStep` (what the review's Edit button uses) announce the step and focus its heading the same way. |
| Ids and labels | `FieldWrapper` generates ids with `useId()` and hands them to the renderer as `params.a11y`: the control gets `id`, and `FieldLabel` gets `id` and `htmlFor`, so the label is tied to the control. |
| Help and errors | The control's `aria-describedby` points to the helper text and to the error, and only to those that exist. `FieldDescription` and `FieldError` receive the `id` it points to. |
| Invalid state | `aria-invalid="true"` is set while the field has an error, and only on controls whose role allows it. |
| Groups | `radio`, `checkbox-group`, `switch-group`, `button-radio`, `button-checkbox`, `button-card`, `matrix` and `repeater` render as `<fieldset>` + `<legend>`; the `aria-describedby` of a group sits on the fieldset, not on each option. The legend is always present: with `hideLabel` it is only visually hidden. Option ids are index-based, so two fields with the same options never share ids. |
| Group options | The single-choice button groups (`button-radio`, and `button-card` unless `multiple`) are a `radiogroup` named by the legend through `aria-labelledby`, with `role="radio"` and `aria-checked` on each option. `radio` passes the same `aria-labelledby` and `aria-invalid` to your injected `RadioGroup`; the role of each option comes from your `RadioGroupItem`. `matrix` also draws each row as a `radiogroup` labelled with the row's label. The multiple-choice ones (`button-checkbox`, `button-card` with `multiple`) are toggle buttons with `aria-pressed`. |
| Date fields | The trigger is named with `aria-labelledby="<label> <trigger>"`, so the selected value stays part of its accessible name. |
| Lookups | While a `lookup` is running, Next and Submit are `disabled` and carry `aria-busy`. |

The step texts come from the form's `locale` and can be overridden with `setDefaultMessages`.

## What the tests cover

`a11y.dom.test.tsx` iterates over `BUILTIN_FIELD_TYPES` and a guard test fails if its configs stop covering exactly those **38 types**. For each type it runs **axe** and expects no violations:

- **All 38**, at rest.
- **The 32 that draw a control**, also with a validation error and helper text on screen. The other 6 (`hidden`, `html`, `button`, `submit`, `next`, `back`) have nothing to describe, so only the at-rest run applies to them.

The same file checks the wiring that axe cannot see: for those 32 types, some element (the control or the group's fieldset) cites both the helper and the error in `aria-describedby`, and both ids exist and differ; without an error only the helper is cited; a text field with an error has `aria-invalid` and its label points to its id; `radio`, `checkbox-group`, `switch-group`, `button-radio` and `matrix` are asserted to be `fieldset` + `legend` (the other groups in the table go through the same `FieldWrapper` path but are not asserted one by one), and option ids do not collide between `radio` and `checkbox-group`. A last test submits an empty `<Form>` and checks the same chain end to end, plus axe. `stepFocus.dom.test.tsx` covers the focus and announcement of step changes (first mount, Next, Back, `goToStep`, no title, Spanish, single-step forms).

These tests run against **minimal fake primitives**, so they catch structural problems of the package (roles, `aria-*`, labels) and nothing else.

## What they do not cover

- **Contrast** — colours come from your theme. Check them against 4.5:1 for text and 3:1 for controls.
- **Landmarks and page structure** — headings, `main`, skip links belong to your page.
- **Your primitives** — the package passes the ids and `aria-*` values, but whether your `Input`, `FormControl`, `Field`, `FieldLabel`, `FieldDescription` and `FieldError` put them on the DOM node (and show a visible focus) is up to them. A custom `Field*` primitive must forward `id`/`htmlFor`. Test them with the real ones.
- **Rules axe skips in this suite** — `color-contrast`, `region` and `page-has-heading-one` are turned off because they depend on the page and the theme, not on the package.
- **Interaction** — axe audits the rendered structure. Keyboard behaviour of each type is covered by interaction tests where they exist, not by axe.
- **A WCAG 2.2 AA claim** — passing axe on the structure is evidence, not conformance. No test here proves AA for a whole form.
- **Screen readers and keyboards** — axe finds roughly the mechanical failures. Whether the form makes sense read aloud, and whether it can be completed without a mouse, needs a person.
- **Your content** — labels that say what the field is, error messages that say how to fix it, and `html` fields you write.

## Test your own form

1. Run axe against the rendered form with your real primitives (`vitest-axe`, `@axe-core/playwright` or the browser extension), with the form in its error state too.
2. Tab through it without a mouse: every control reachable, focus always visible, the order matches the screen.
3. Submit it empty and listen: each error should be announced once, next to its field.
4. In a multi-step form, press Next and Back with a screen reader on and check that the new step is announced.
5. Zoom to 200% and 400% width and check nothing is cut off.

## Limitations

- The axe audit runs against minimal fake primitives, not against shadcn or your own: it proves the package's structure, not the final page.
- The audit renders one field at a time (and one empty-submit `<Form>`), so it does not check ids across a whole page or a multi-step flow.
- `html` fields are sanitised, not audited: the markup you write is yours.
- Third-party widgets you inject (date pickers, comboboxes) keep their own accessibility, good or bad.

## Related

- [Multi-Step Forms](/docs/multi-step)
- [Validation](/docs/validation)
- [Wizard with progress and review](/docs/recipes/wizard-progress-review)
