accessibility

Accessibility Patterns

Reference for web accessibility (WCAG 2.2 AA compliance), keyboard navigation, screen reader support, and inclusive design. Sources in references/sources.md.

Iron Law

EVERY INTERACTION MUST BE POSSIBLE WITHOUT A MOUSE [1][3]

Mouse-only interactions exclude users with motor disabilities, power users, and AT users. Tab order, focus management, and keyboard shortcuts are not optional enhancements. — WCAG 2.1 Principle 2 (Operable) [1]

Activates for: interactive UI components · forms · React/JSX or CSS · focus/ARIA/contrast reviews

---

Keyboard Navigation [1][3]

Focus management: On modal open, move focus to the first focusable element; on close, return to the trigger. Trap focus inside. [3]

// CORRECT: Focus trap — APG dialog pattern [3]
function Modal({ isOpen, onClose, children }) {
  const first = useRef<HTMLButtonElement>(null);
  useEffect(() => { if (isOpen) first.current?.focus(); }, [isOpen]);
  return (
    <div role="dialog" aria-modal="true"
      onKeyDown={(e) => { if (e.key === 'Escape') onClose(); }}>
      <button ref={first}>First action</button>{children}
    </div>
  );
}

Skip links: First focusable element — visible on focus, links to #main-content. [1][4] Roving tabIndex: Active item tabIndex={0}, others tabIndex={-1} — radio groups, toolbars, tabs. [3]

---

ARIA and Semantic HTML [2][15][18]

First rule of ARIA: Use native HTML before adding ARIA roles — no ARIA is better than bad ARIA. [15][18]

CORRECT [18]	VIOLATION [15]
<button>Submit</button>	<div role="button">Submit</div>
<nav aria-label="Main">	<div role="navigation">

Top WebAIM Million 2024 violations [5]: missing form labels (#1) · low contrast (#2) · missing alt text (#3) · missing button names (#4).

Live regions: aria-live="polite" for status updates; role="alert" for errors. [2]

---

Color and Contrast [1][16][19]

Element	Ratio	Level	SC
Normal text (<18px)	4.5:1	AA	[1] §1.4.3
Large text (≥18px bold, ≥24px)	3:1	AA	[1] §1.4.3
UI components & focus indicators	3:1	AA	[1] §1.4.11
Focus appearance (WCAG 2.2 new)	3:1 + ≥2px perimeter	AA	[16] §2.4.11