Skip to content
Documentation

ADR-005: Accessibility & Release Gates

Decision

WCAG 2.2 AA is the accessibility floor (AAA where practical), and a fixed set of release gates enforces it before any merge.

Key rules

  • Semantic HTML first — the correct element for the job; heading hierarchy without skipped levels. Full reference: design-principles/references/foundation-a11y.md.
  • Contrast: 4.5:1 for normal text, 3:1 for large text and UI components. Every interactive element has a visible focus-visible ring; never outline-none without a replacement.
  • Touch targets ≥ 24×24px (AA) / 44×44px (AAA target). Never signal by color alone. Respect prefers-reduced-motion.
  • The axe audit passes at WCAG 2.2 AA — no new violations.
  • Release gates, all required before merge: pnpm typecheck, pnpm build, pnpm lint, pnpm test (≥ 50% line coverage), axe, Lost Pixel visual regression, bundle budget, and the docs gate (story + a docs page, ADR-021).
  • Visual regression is Lost Pixel, not Chromatic.

Why

Accessibility is a craft and a gate, not an afterthought. Automated axe catches roughly 30% of issues; the gates plus manual keyboard and screen-reader review cover the rest.

Applies when

You are building any component, or preparing a component or PR for release and setting up CI gates.

  • ADR-004 — motion and interaction (reduced motion, focus rings).
  • ADR-009 — icon role, placement & layout (icon a11y).
  • ADR-021 — self-documenting code examples (docs gate).