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
Section titled “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
Section titled “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
Section titled “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
Section titled “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-describedbyon their inner control and announce the message withrole="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 ownaria-labeloraria-labelledbykeeps it, including one added later. In a browser without ARIA element reflection, the message becomes the host’saria-descriptioninstead. - A control keeps any
aria-describedbyyou give it and reads its own message first. In React and Svelte it also keeps youraria-invalid. In the web components, putaria-describedbyon the element and the control inside reads it too. The exception is a web checkbox, switch, checkbox group or radio group: anaria-describedbyon 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.