# Accessibility

> Source: https://design.nanatec.co.ke/guides/accessibility/
> What Nana UI checks against WCAG 2.2 AA, how it is checked, and the gaps still open.

Nana UI targets **WCAG 2.2 level AA** in the web components and the Svelte components. This
page says what is checked automatically, what is checked by hand, and what is not yet done.

## Checked on every test run

| Check | Web components | Svelte |
| --- | --- | --- |
| axe-core, WCAG 2.0, 2.1 and 2.2 A and AA rules | every live example on every component page | every Svelte demo |
| The Nana theme loaded, so colours are the real ones | yes | yes, with the docs' Tailwind stylesheet |
| Entrance animations finished before measuring | yes | yes |

Both suites run in Chromium as part of `bun run test`, so an example that fails fails the
build. They live in `packages/components/tests/nana-a11y.test.ts` and
`packages/svelte/test/a11y.test.ts`.

The rules that most often catch something are text contrast (4.5:1, or 3:1 for large text),
accessible names on controls and dialogs, valid roles inside composite widgets, keyboard
reachability of scrolling regions, and the 24 × 24 px target size from WCAG 2.2.

One exception is made: where the background axe measures is clipped away with `clip-path` —
the sliding indicator under the active tab — axe cannot see the clip and reports the wrong
colour, so that contrast result is skipped.

## Checked by unit and contract tests

Keyboard behaviour is not something axe can test. It is defined once, as a rule in
`@nana-tec/ui-core` (`tabsKey`, `menuKey`, `treeKey`, `calendarKey` and the rest), and each
component asks that rule what a key means. The rules have their own tests, and the behaviour
React and Svelte must share — tabs, dialog, toggle and the date picker — is a contract in
`contracts/` that each target runs.

Dialogs use the native modal `<dialog>`, so focus containment, Escape and the inert page come
from the browser rather than from script.

## What these checks do not cover

- **Closed overlays.** Each example is checked as it first renders. Menus, popovers, comboboxes
  and dialogs that start closed are checked only where an example opens them.
- **Screen readers.** No assistive-technology pass with NVDA, JAWS or VoiceOver has been
  recorded yet. Roles and names are checked; how they are announced is not.
- **Dark mode.** The automated checks run in the light theme.
- **Your content.** A component cannot make the text or images you put into it accessible.

## Error messages

Every form control follows one rule. `invalid` marks the control `aria-invalid`, and
`error-message` shows beneath it, in the `error` part, only while `invalid` is set.
Setting the message alone shows nothing, so you can keep it in place and toggle `invalid`.
The message is linked to the control it describes:

- Input, textarea, select, combobox, number input, date picker, date range, range, rating,
  colour picker and OTP put `aria-describedby` on their inner control and announce the
  message with `role="alert"`.
- In the web components, checkbox, switch, checkbox group and radio group carry their role
  on the host element. They mark it invalid and link the label and the message through
  `ElementInternals`, so the message is read as the description, not as part of the name. A
  host that has its own `aria-label` or `aria-labelledby` keeps it, including one added
  later. In a browser without ARIA element reflection, the message becomes the host's
  `aria-description` instead.
- A control keeps any `aria-describedby` you give it and reads its own message first. In
  React and Svelte it also keeps your `aria-invalid`. In the web components, put
  `aria-describedby` on the element and the control inside reads it too. The exception is a web
  checkbox, switch, checkbox group or radio group: an `aria-describedby` on the element
  replaces its message, because an attribute on the host outranks what the element sets for
  itself.

In the web components and Svelte, changing a checkbox, switch, checkbox group or radio group
clears `invalid`; in Svelte, bind it to see the change. In React, `invalid` is controlled, so
clear it in `onCheckedChange` or `onValueChange`.

The deprecated `error` and `error-text` attributes still mark the control invalid on their
own, so markup written for them keeps working.

If you find something these checks miss, open an issue with the component, the target and what
your assistive technology did.
