Docs Architecture
Accessibility policy
Every behavior defines its semantics, keyboard, focus and ARIA in a written contract, is tested in a real browser, and is never traded for bytes.
Markdown version of this page, for assistants (Markdown for AI)
On this page
Policy
- Native semantics first. No added role where a native element has the widget model; otherwise the WAI-ARIA Authoring Practices pattern.
- Correctness before bytes. Order: correctness, accessibility, developer experience, performance, bundle size.
- Behavior, not attributes. Tests press ArrowRight and check focus moved.
- Authored ids. Server markup is correct before hydration and identical after.
- axe and keyboard tests are not screen-reader testing; the site says which it has.
The contract
Every primitive ships a contract.md with the same sections, read here from the tabs contract
at build time:
- Required semantics
- Required parts
- Options
- Application-rendered panel
- Native part
- Looks
- Keyboard interaction
- Focus rules
- Disabled behavior
- Orientation
- RTL
- ARIA relationships
- Events
- Platform features and Baseline
- Attribute helper
- SSR expectations
- JS-disabled behavior
- Runtime budget
- Test cases
50 contracts, linked from each primitive page. Native ones also name their platform features, Baseline status and fallback (Browser support).
Focus and portal policy
No universal focus manager; each primitive has its own focus contract:
- Dialog: native
showModal(); the rest is inert, closing returns focus to the invoker. - Tabs: roving
tabindex. - Menu: first enabled item on open, the invoker on close.
- Combobox: focus stays in the input;
aria-activedescendantmarks the option.
No portal, overlay manager or z-index context: the top layer does it. Positioning: implicit anchor, then CSS anchor positioning, then the CSS fallback; no JavaScript positioning engine.
Regression budget
A behavior change runs the contract's test cases in a real browser in the same gate as the size budgets. A byte saved never outweighs a failing keyboard test.
Test layers
| Layer | What it proves | Where |
|---|---|---|
| Contract tests | Tier, routed events, registration module and native base of every primitive | packages/primitives/tests/registry.test.ts |
| Algorithm tests | Next and previous enabled item, Home and End, RTL, typeahead matching | packages/core/tests, packages/primitives/tests/tabs.test.ts, menu.test.ts |
| Browser interaction tests | Focus, dialog, popover, top layer and anchor positioning in a real browser | apps/playground/tests/primitives/native.spec.ts, tabs.spec.ts, menu.spec.ts |
| Keyboard contract tests | Arrow keys, Home and End, activation modes, disabled skipping, Escape and focus return | apps/playground/tests/primitives/tabs.spec.ts, menu.spec.ts, table/table.spec.ts |
| JavaScript-disabled tests | The native contracts with page JavaScript off | apps/playground/tests/primitives/native.spec.ts |
| SSR tests | Server HTML with authored state and ids; hydration changes nothing | apps/playground/tests/ssr.spec.ts, packages/*/tests/ssr.test.ts |
| Automated accessibility scans | No serious or critical axe violation on every page and on open dialog, popover and menu states | apps/playground/tests/primitives/a11y.spec.ts, apps/docs/tests/routes.spec.ts |
| Production bundle tests | The shipping invariants against real production output | fixtures/*, apps/playground/tests/bundle.spec.ts |
Focus, top layer and anchor positioning run in Playwright; happy-dom unit tests cover the algorithms only.
Test matrix
From the claim registry and the audit of 2026-09-27. "Not run": no recorded run (Firefox and WebKit run nightly, not on pull requests). "Not done": no session recorded.
| Area | Chromium | Firefox | WebKit | Screen reader |
|---|---|---|---|---|
| Keyboard | tested in Chromium | not run | not run | not done |
| Focus | tested in Chromium | not run | not run | not done |
| axe scan | tested in Chromium | not run | not run | n/a |
| RTL | tested in Chromium (tabs) | not run | not run | not done |
| Without JavaScript | tested in Chromium | not run | not run | n/a |
| Reduced motion | stylesheet rule; no browser test | not run | not run | n/a |
| Forced colors | stylesheet rule; no browser test | not run | not run | n/a |
| Screen reader smoke | not done | not done | not done | not done |
Recorded Firefox and WebKit runs are a stage 2 requirement, a screen-reader session per primitive (VoiceOver with Safari, NVDA with Chrome or Firefox) stage 3 (docs/release.md).
What is not claimed
- Screen-reader behavior, in any browser.
- Behavior in Firefox or WebKit on every pull request: the playground suite runs there in the
nightly cross-browser job (
SLEAN_BROWSERS=all), not in the pull-request job. - IME composition with an operating-system input method: the autocomplete and the select search are tested through the DevTools protocol only.
Source
- apps/playground/tests/primitives: the browser suite
- a11y.spec.ts: the axe scans
- packages/primitives/src: one contract per primitive
- docs/proof/claims.md: the status of every claim