Accessibility baseline

The repository target is WCAG 2.2 Level AA for user-facing web UI. Accessibility regressions are treated like failing tests.

Colour and contrast

• Normal text contrast is at least 4.5:1; large text at least 3:1.
• Component boundaries and focus indicators are at least 3:1 against adjacent colours.
• Information is never communicated by colour alone.
• Token pairs must be checked in both dark and light themes.

Keyboard and focus

• Every pointer action is keyboard operable.
• Focus order follows visual and reading order.
• Focus indicators remain visible.
• Overlays move focus inside, trap it only while open, and return it to the trigger.
• There are no keyboard traps.

Semantics and ARIA

• Use native elements before ARIA.
• Icon-only controls have accessible names.
• Decorative icons use aria-hidden; meaningful images have useful alt.
• Dynamic status uses an appropriate live region without excessive announcements.

Forms

• Every control has a programmatic label; placeholders are not labels.
• Invalid controls use aria-invalid.
• Error/help text is connected through aria-describedby.
• Required state is communicated programmatically and visually.
• The first failed submission moves focus or provides an announced summary when needed.

Motion, target size, and reflow

• Respect prefers-reduced-motion.
• Interactive targets are at least 24 × 24 CSS px or have equivalent spacing.
• Content remains usable at 320 CSS px and 400% zoom without losing information or actions.
• Text spacing changes do not clip content.

Verification

• Storybook a11y checks for shared components.
• Testing Library role/label assertions for behaviour.
• Browser screenshot tests for stable visual states, not as the only accessibility check.
• Manual keyboard pass for changed flows.
• Lighthouse/axe spot checks for non-trivial pages and overlays.

The full review checklist lives in .claude/rules/architecture-checklist.md.