What the framework guarantees, and what your app must do
The framework's accessibility work is in @shadow-js/primitives and the copied kit in @shadow-js/ui.
The framework's accessibility work is in @shadow-js/primitives and the copied kit in @shadow-js/ui. The
primitives are headless: they give you the keyboard behavior of the WAI-ARIA Authoring Practices 1.2 patterns,
the roles and states, focus movement, and the names that the pattern needs. The kit adds the visual states
(focus rings, forced-colors colors, reduced motion, logical RTL classes). The application still owns what
the framework cannot know.
| The framework guarantees | Your app must |
|---|---|
The roles, states and aria-* wiring of each primitive (for example aria-expanded, aria-controls, aria-selected) |
Give every control a name it can see (visible text or a visible label), and a name for each landmark on the page |
| Keyboard behavior of each pattern (arrow keys, Home and End, Escape, typeahead) and one tab stop for composite widgets | Keep one h1 per page and headings in order; use landmarks (header, nav, main, footer) |
| Focus moves into a modal when it opens and returns to the trigger when it closes; a modal traps Tab | Put the focus target where the user expects after a route change (the route announcer does this for Dusk apps) |
| Dev warnings for a dialog, a slider thumb or a progress value that has no name or an invalid value | Remove the warnings: they are bugs in the page, not noise |
<html lang> and <html dir> follow the locale in the apps that ship one |
Write text in the right language and use logical CSS (start, end, ms-*, me-*) |
| Focus rings and forced-colors states in the kit's components | Check the contrast of your own colors. The kit's theme tokens are checked by the matrix; a color you add yourself is not |
Motion guards: the kit's animations stop under prefers-reduced-motion |
Do not animate essential content with your own CSS without a reduced-motion rule |
| Nothing about target size or reflow | Make controls at least 24 by 24 CSS pixels (WCAG 2.5.8) and keep the layout usable at 320 CSS pixels and 200 percent zoom |
The matrix of what is tested, partly tested and open for each component is in docs/research/17-a11y-audit.md
in the repository. The manual screen reader plan, which no automated test can replace, is
docs/research/17-screen-reader-manual-test-plan.md.