Accessibility

Accessibility — WCAG 2.2 / React / HTML

Staff Engineer standard: accessibility is a design constraint, not a post-launch audit.

---

1. Core Principles (POUR)

Principle	Requirement
Perceivable	Content reachable via multiple senses (vision, hearing, text)
Operable	All functionality works via keyboard, no traps
Understandable	Language, errors, and navigation are clear
Robust	Works with assistive tech (screen readers, voice control)

Target: WCAG 2.2 AA (legal requirement in many jurisdictions). AAA is aspirational.

---

2. Must-Fix First (Critical Issues)

❌ Any of these = accessibility failure:
[ ] Form input with no programmatic label
[ ] Image with no alt attribute
[ ] Color contrast below 4.5:1 (normal text) / 3:1 (large/UI)
[ ] Keyboard trap — user cannot Tab out
[ ] No focus indicator visible

// ❌ Icon button — no accessible name
<button><svg>...</svg></button>

// ✅ aria-label or visually-hidden span
<button aria-label="Open menu">
  <svg aria-hidden="true">...</svg>
</button>

// ✅ Visually hidden text (reusable class)
// .sr-only { position: absolute; width: 1px; height: 1px; overflow: hidden; clip: rect(0,0,0,0); white-space: nowrap; }

---

3. Keyboard & Focus

/* ❌ Never remove focus outlines globally */
*:focus { outline: none; }

/* ✅ Keyboard-only focus via :focus-visible */
:focus { outline: none; }
:focus-visible { outline: 2px solid #005fcc; outline-offset: 2px; }

• All interactive elements reachable via Tab; activated via Enter/Space
• Focus order follows visual reading order
• Sticky headers/footers → scroll-margin-top prevents covered focus (WCAG 2.4.11)
• Skip link at page top bypasses repetitive nav (WCAG 2.4.1)
• Interactive targets min 24×24px AA (44×44px recommended)

See references/A11Y-PATTERNS.md for full focus trap, skip link, modal dialog patterns.

---

4. Color & Contrast

Text type	AA minimum	AAA
Normal (<18px / <14px bold)	4.5:1	7:1
Large (≥18px / ≥14px bold)	3:1	4.5:1
UI components & graphics	3:1	3:1

❌ Never rely on color alone to convey information
✅ Color + icon + text for errors, status, warnings

---

5. Forms & Errors

<!-- ❌ Unlabeled input -->
<input type="email" placeholder="Email">

<!-- ✅ Explicit label + error association -->
<label for="email">Email address</label>
<input id="email" type="email" aria-describedby="email-error" aria-invalid="true">
<span id="email-error" role="alert">Please enter a valid email</span>

• Errors announced via role="alert" or aria-live="polite"
• aria-invalid="true" on invalid fields
• Don't force re-entry of data from same session (WCAG 3.3.7)
• Allow paste in password fields — don't block autofill (WCAG 3.3.8)

---

6. Semantic HTML & ARIA

<!-- ❌ ARIA div when native element exists -->
<div role="button" tabindex="0">Click</div>

<!-- ✅ Native elements first — behavior + semantics built in -->
<button>Click</button>

ARIA rule: use ARIA only when HTML semantics are insufficient. First rule of ARIA: don't use ARIA.

See references/A11Y-PATTERNS.md for ARIA tabs, live regions, modal patterns.

---

7. Motion & Reduced Motion

@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
    scroll-behavior: auto !important;
  }
}

---

8. Testing

# Automated — catches ~30% of issues
pnpm exec lighthouse https://localhost:3000 --only-categories=accessibility
pnpm add -D @axe-core/playwright  # run in Playwright specs

Manual testing (catches the rest):

• Tab through entire page — logical order, no traps
• VoiceOver (Mac) or NVDA (Windows) — all content announced
• 200% zoom — no content overflow/overlap
• Windows High Contrast Mode — no info lost

See references/WCAG.md for full criteria reference.

---

9. WCAG 2.2 New Criteria

Criterion	Level	What it means
2.4.11 Focus Not Obscured	AA	Focused element not fully hidden by sticky bars
2.4.12 Focus Not Obscured	AAA	No part of focused element hidden
2.5.7 Dragging Movements	AA	Drag actions have single-pointer alternative
2.5.8 Target Size	AA	Targets ≥ 24×24px
3.2.6 Consistent Help	AA	Help UI in same position across pages
3.3.7 Redundant Entry	A	Don't re-ask for data given earlier in session
3.3.8 Accessible Auth	AA	Login must not require cognitive tests alone

---

10. Quick Checklist

[ ] Images have descriptive alt text (or alt="" for decorative)
[ ] All inputs have visible labels (not placeholder-only)
[ ] Errors use role="alert" + aria-invalid
[ ] Color contrast ≥ 4.5:1 for body text
[ ] Focus visible on all interactive elements
[ ] All functionality reachable by keyboard
[ ] No keyboard traps
[ ] Skip link present for main content
[ ] Interactive targets ≥ 24×24px
[ ] prefers-reduced-motion respected
[ ] lang attribute on <html>
[ ] Lighthouse a11y score ≥ 90