Skip to content
Nana UI

Guides

Accessibility

What Nana UI checks against WCAG 2.2 AA, how it is checked, and the gaps still open.

View .md Download

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.

CheckWeb componentsSvelte
axe-core, WCAG 2.0, 2.1 and 2.2 A and AA rulesevery live example on every component pageevery Svelte demo
The Nana theme loaded, so colours are the real onesyesyes, with the docs’ Tailwind stylesheet
Entrance animations finished before measuringyesyes

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.

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.

  • 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.

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.