Web Accessibility (WCAG 2.2 AA)
Build for everyone — accessibility is a requirement, not a feature.
Contrast Ratios (WCAG AA)
| Element |
Minimum Ratio |
| Normal text (< 18pt) |
4.5:1 |
| Large text (>= 18pt or 14pt bold) |
3:1 |
| UI components and focus indicators |
3:1 |
WCAG 2.2 New AA Criteria
| Criterion |
Requirement |
| Target Size Minimum (2.5.8) |
Interactive targets at least 24x24 CSS pixels |
| Focus Not Obscured Minimum (2.4.11) |
Focused element at least partially visible, not hidden by sticky headers or overlays |
| Focus Appearance (2.4.13) |
Focus indicator has minimum area (2px perimeter) and 3:1 contrast change |
| Dragging Movements (2.5.7) |
Provide single-pointer alternative for any drag interaction |
| Redundant Entry (3.3.7) |
Do not require re-entering previously provided information |
| Consistent Help (3.2.6) |
Help mechanisms (chat, phone, FAQ) appear in same relative order across pages |
| Accessible Authentication (3.3.8) |
No cognitive function test for login (allow paste, autofill, or alternatives) |
Essential Keyboard Patterns
| Key |
Action |
| Tab / Shift+Tab |
Navigate between focusable elements |
| Enter / Space |
Activate buttons and links |
| Arrow keys |
Navigate within widgets (tabs, menus) |
| Escape |
Close dialogs and menus |
| Home / End |
Jump to first/last item in widget |
Element Selection
| Need |
Element |
| Navigates to page |
<a href="..."> |
| Submits form |
<button type="submit"> |
| Opens dialog |
<button aria-haspopup="dialog"> |
| Other action |
<button type="button"> |
| Self-contained article |
<article> |
| Navigation links |
<nav> |
| Supplementary info |
<aside> |
Common ARIA Attributes
| Attribute |
Purpose |
aria-label |
Name when no visible label exists |
aria-labelledby |
Reference existing text as label |
aria-describedby |
Additional description (hints, errors) |
aria-live |
Announce dynamic updates (polite or assertive) |
aria-expanded |
Collapsible/expandable state |
aria-hidden="true" |
Hide decorative elements from screen readers |
aria-invalid |
Mark form fields with errors |
aria-required="true" |
Mark required fields |
aria-busy |
Indicate loading state |
WCAG 2.2 AA Checklist Summary
| Principle |
Key Requirements |
| Perceivable |
Alt text on images, contrast >= 4.5:1, color not sole indicator, text resizable to 200%, captions on video, prefers-reduced-motion support |
| Operable |
Keyboard accessible, visible focus not obscured, focus appearance meets minimum, targets >= 24px, skip links, dragging alternatives |
| Understandable |
<html lang="en">, consistent navigation, consistent help placement, form labels, error identification, no redundant entry, accessible auth |
| Robust |
Valid HTML, name/role/value on all UI components, aria-live for status messages (SC 4.1.1 Parsing is obsolete in WCAG 2.2) |
Anti-Patterns
| Anti-Pattern |
Fix |
<div onClick> instead of <button> |
Use semantic HTML elements |
outline: none without replacement |
Use :focus-visible with visible outline |
| Placeholder as label |
Use <label> element |
tabindex > 0 |
Use DOM order or tabindex="0" / tabindex="-1" |
| Color-only state indicators |
Add icon and text label |
| Skipped heading levels |
Use sequential h1-h6, style with CSS |
role="button" on <button> |
Remove redundant ARIA |
aria-hidden on interactive elements |
Never hide interactive content |
| Fixed font sizes (px) |
Use rem units |
| No focus trap in modal dialogs |
Trap focus, close on Escape |
Common Mistakes
| Mistake |
Correct Pattern |
Adding aria-label to elements that already have visible text |
Use aria-labelledby to reference existing visible text instead |
Using aria-live="assertive" for non-urgent updates |
Use aria-live="polite" for most dynamic content; reserve assertive for errors and alerts |
Setting alt="" on informative images |
Provide descriptive alt text; only use empty alt on purely decorative images |
| Adding keyboard handlers to non-focusable elements |
Use native interactive elements or add tabindex="0" plus role and key handlers |
| Testing only with automated tools like axe |
Automated scans catch ~30% of issues; always supplement with keyboard-only and screen reader testing |
Screen Reader and Browser Pairings
| Screen Reader |
Browser |
Platform |
| JAWS |
Chrome |
Windows |
| NVDA |
Chrome |
Windows (free) |
| NVDA |
Firefox |
Windows (free) |
| VoiceOver |
Safari |
macOS / iOS |
| TalkBack |
Chrome |
Android |
| Narrator |
Edge |
Windows (built-in) |
Testing Quick Guide
| Method |
Tool |
Effort |
| Keyboard-only |
Hide mouse, Tab through page |
5 min |
| Screen reader |
JAWS + Chrome or NVDA + Chrome/Firefox |
10 min |
| Screen reader |
VoiceOver + Safari (macOS) |
10 min |
| Automated scan |
axe DevTools browser extension |
2 min |
| Lighthouse |
Chrome F12 > Lighthouse > Accessibility |
2 min |
| Unit tests |
jest-axe (Jest) or vitest-axe (Vitest) |
Ongoing |
Delegation
When working on accessibility, delegate to:
design-system — Color tokens and contrast verificationreact-patterns — Component patterns and hookstesting — jest-axe integration and test patterns
Resources
References
- Semantic HTML and Structure — Document landmarks, heading hierarchy, element selection, skip links
- Focus Management — Focus indicators, focus not obscured, dialog focus traps, SPA route focus, focus-visible patterns
- ARIA Patterns — Accessible tabs, live regions, data tables with ARIA attributes
- Forms and Validation — Label association, error announcement, redundant entry, accessible authentication
- Color and Media — Contrast requirements, reduced motion, dragging alternatives, video captions, alt text
- Testing — Keyboard testing, screen reader pairings, axe DevTools, jest-axe and vitest-axe unit tests