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.

View as Markdown

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.