Accessibility

What the automated gate checks

Every preview is scanned with axe-core and asserted to have zero critical or serious violations, across the full matrix of:

• Light and dark colour schemes.
• The customer and admin brand surfaces.
• Both desktop and mobile viewports (for layout / overflow).

That covers contrast, ARIA roles, attributes and names, label associations, nested interactive controls, list and landmark structure, target size, and more. Deterministic browser tests check keyboard behavior, focus traps, focus return, Escape, and state changes. Stable releases also need recorded keyboard and screen-reader tests.

Colour & contrast

Components never ship raw colour utilities or inline hsl() — they use semantic tokens (bg-primary, text-muted-foreground, border-input, …). The token palette is tuned so text and accents meet 4.5:1 in both light and dark, both as text on a surface and as a fill with its foreground. If you re-theme, keep that contrast: the theme tools include a live WCAG checker.

Keyboard & focus

Interactive elements are reachable and operable by keyboard, expose a visible focus-visible ring built from the ring token, and carry correct roles and accessible names. Scrollable regions are focusable so keyboard users can scroll them; collapsed panels are inert so hidden controls leave the tab order.

Motion

Animation respects prefers-reduced-motion. Decorative and looping motion is gated with motion-safe: / motion-reduce: (and the equivalent @media (prefers-reduced-motion) guard inside component <style> blocks), so users who ask for less motion get a still, readable interface.

RTL & semantics

Every primitive uses logical properties (ms-*, text-start, inset-inline-*) so it mirrors correctly under dir="rtl", and exposes a stable data-slot attribute for styling and scripting hooks. See the RTL guide.

Performance

The handful of WebGL components that need it (blob, mesh-gradient) load three.js lazily via a dynamic import('three'), so it's split into its own chunk — pages that don't use one never pay the ~600 KB cost. Canvas effects like globe use the 2D canvas API and ship no extra library.

How it's verified

Browser sweeps walk every component, block, and page preview, including all family variants: an axe-core accessibility sweep (the matrix above) and a render-health sweep (no blank renders, no horizontal overflow). A reduced-motion sweep checks that motion stops when requested. They run in CI and can be run locally:

cd apps/docs-registry && npm run test:a11y

The hand-written guard suite adds per-component checks — token usage, RTL mirroring, and interactive a11y — so regressions fail loudly at build time too.

Keeping it accessible in your app

The generated code is accessible out of the box — to keep it that way:

• Pass a real label where a component asks for one (icon-only buttons, inputs, charts, maps).
• Keep the semantic tokens; if you change them, re-check contrast in light and dark.
• Don't remove aria-*, roles, or focus-visible styles when restyling.
• Provide meaningful alt text for your own images and an accessible name for your own controls.