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 yourInput,FormControl,Field,FieldLabel,FieldDescriptionandFieldErrorput them on the DOM node (and show a visible focus) is up to them. A customField*primitive must forwardid/htmlFor. Test them with the real ones. - Rules axe skips in this suite —
color-contrast,regionandpage-has-heading-oneare 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
htmlfields you write.
Test your own form
- Run axe against the rendered form with your real primitives (
vitest-axe,@axe-core/playwrightor the browser extension), with the form in its error state too. - Tab through it without a mouse: every control reachable, focus always visible, the order matches the screen.
- Submit it empty and listen: each error should be announced once, next to its field.
- In a multi-step form, press Next and Back with a screen reader on and check that the new step is announced.
- 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. htmlfields 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.