1---
2name: accessibility
3description: |
4 Build WCAG 2.2 AA compliant interfaces with semantic HTML, ARIA, keyboard navigation, focus management, color contrast, and screen reader support. Covers forms, dialogs, tabs, live regions, skip links, alt text, and data tables.
5
6 Use when implementing accessible UIs, auditing WCAG compliance, fixing screen reader issues, keyboard navigation, focus traps, or troubleshooting "focus outline missing", "aria-label required", "insufficient contrast", "missing alt text", "heading hierarchy".
7license: MIT
8metadata:
9 author: oakoss
10 version: '1.1'
11user-invocable: false
12---
13
14# Web Accessibility (WCAG 2.2 AA)
15
16Build for everyone — accessibility is a requirement, not a feature.
17
18## Contrast Ratios (WCAG AA)
19
20| Element | Minimum Ratio |
21| ---------------------------------- | ------------- |
22| Normal text (< 18pt) | 4.5:1 |
23| Large text (>= 18pt or 14pt bold) | 3:1 |
24| UI components and focus indicators | 3:1 |
25
26## WCAG 2.2 New AA Criteria
27
28| Criterion | Requirement |
29| ----------------------------------- | ------------------------------------------------------------------------------------ |
30| Target Size Minimum (2.5.8) | Interactive targets at least 24x24 CSS pixels |
31| Focus Not Obscured Minimum (2.4.11) | Focused element at least partially visible, not hidden by sticky headers or overlays |
32| Focus Appearance (2.4.13) | Focus indicator has minimum area (2px perimeter) and 3:1 contrast change |
33| Dragging Movements (2.5.7) | Provide single-pointer alternative for any drag interaction |
34| Redundant Entry (3.3.7) | Do not require re-entering previously provided information |
35| Consistent Help (3.2.6) | Help mechanisms (chat, phone, FAQ) appear in same relative order across pages |
36| Accessible Authentication (3.3.8) | No cognitive function test for login (allow paste, autofill, or alternatives) |
37
38## Essential Keyboard Patterns
39
40| Key | Action |
41| --------------- | ------------------------------------- |
42| Tab / Shift+Tab | Navigate between focusable elements |
43| Enter / Space | Activate buttons and links |
44| Arrow keys | Navigate within widgets (tabs, menus) |
45| Escape | Close dialogs and menus |
46| Home / End | Jump to first/last item in widget |
47
48## Element Selection
49
50| Need | Element |
51| ---------------------- | --------------------------------- |
52| Navigates to page | `<a href="...">` |
53| Submits form | `<button type="submit">` |
54| Opens dialog | `<button aria-haspopup="dialog">` |
55| Other action | `<button type="button">` |
56| Self-contained article | `<article>` |
57| Navigation links | `<nav>` |
58| Supplementary info | `<aside>` |
59
60## Common ARIA Attributes
61
62| Attribute | Purpose |
63| ---------------------- | -------------------------------------------------- |
64| `aria-label` | Name when no visible label exists |
65| `aria-labelledby` | Reference existing text as label |
66| `aria-describedby` | Additional description (hints, errors) |
67| `aria-live` | Announce dynamic updates (`polite` or `assertive`) |
68| `aria-expanded` | Collapsible/expandable state |
69| `aria-hidden="true"` | Hide decorative elements from screen readers |
70| `aria-invalid` | Mark form fields with errors |
71| `aria-required="true"` | Mark required fields |
72| `aria-busy` | Indicate loading state |
73
74## WCAG 2.2 AA Checklist Summary
75
76| Principle | Key Requirements |
77| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
78| Perceivable | Alt text on images, contrast >= 4.5:1, color not sole indicator, text resizable to 200%, captions on video, `prefers-reduced-motion` support |
79| Operable | Keyboard accessible, visible focus not obscured, focus appearance meets minimum, targets >= 24px, skip links, dragging alternatives |
80| Understandable | `<html lang="en">`, consistent navigation, consistent help placement, form labels, error identification, no redundant entry, accessible auth |
81| 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) |
82
83## Anti-Patterns
84
85| Anti-Pattern | Fix |
86| ------------------------------------- | ------------------------------------------------- |
87| `<div onClick>` instead of `<button>` | Use semantic HTML elements |
88| `outline: none` without replacement | Use `:focus-visible` with visible outline |
89| Placeholder as label | Use `<label>` element |
90| `tabindex` > 0 | Use DOM order or `tabindex="0"` / `tabindex="-1"` |
91| Color-only state indicators | Add icon and text label |
92| Skipped heading levels | Use sequential h1-h6, style with CSS |
93| `role="button"` on `<button>` | Remove redundant ARIA |
94| `aria-hidden` on interactive elements | Never hide interactive content |
95| Fixed font sizes (px) | Use `rem` units |
96| No focus trap in modal dialogs | Trap focus, close on Escape |
97
98## Common Mistakes
99
100| Mistake | Correct Pattern |
101| -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
102| Adding `aria-label` to elements that already have visible text | Use `aria-labelledby` to reference existing visible text instead |
103| Using `aria-live="assertive"` for non-urgent updates | Use `aria-live="polite"` for most dynamic content; reserve `assertive` for errors and alerts |
104| Setting `alt=""` on informative images | Provide descriptive alt text; only use empty alt on purely decorative images |
105| Adding keyboard handlers to non-focusable elements | Use native interactive elements or add `tabindex="0"` plus `role` and key handlers |
106| Testing only with automated tools like axe | Automated scans catch ~30% of issues; always supplement with keyboard-only and screen reader testing |
107
108## Screen Reader and Browser Pairings
109
110| Screen Reader | Browser | Platform |
111| ------------- | ------- | ------------------ |
112| JAWS | Chrome | Windows |
113| NVDA | Chrome | Windows (free) |
114| NVDA | Firefox | Windows (free) |
115| VoiceOver | Safari | macOS / iOS |
116| TalkBack | Chrome | Android |
117| Narrator | Edge | Windows (built-in) |
118
119## Testing Quick Guide
120
121| Method | Tool | Effort |
122| -------------- | --------------------------------------- | ------- |
123| Keyboard-only | Hide mouse, Tab through page | 5 min |
124| Screen reader | JAWS + Chrome or NVDA + Chrome/Firefox | 10 min |
125| Screen reader | VoiceOver + Safari (macOS) | 10 min |
126| Automated scan | axe DevTools browser extension | 2 min |
127| Lighthouse | Chrome F12 > Lighthouse > Accessibility | 2 min |
128| Unit tests | jest-axe (Jest) or vitest-axe (Vitest) | Ongoing |
129
130## Delegation
131
132When working on accessibility, delegate to:
133
134- `design-system` — Color tokens and contrast verification
135- `react-patterns` — Component patterns and hooks
136- `testing` — jest-axe integration and test patterns
137
138## Resources
139
140- [WCAG 2.2 Quick Reference](https://www.w3.org/WAI/WCAG22/quickref/)
141- [ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/)
142- [MDN Accessibility](https://developer.mozilla.org/en-US/docs/Web/Accessibility)
143- [WebAIM](https://webaim.org/)
144- [The A11y Project](https://www.a11yproject.com/)
145
146## References
147
148- [Semantic HTML and Structure](references/semantic-html.md) — Document landmarks, heading hierarchy, element selection, skip links
149- [Focus Management](references/focus-management.md) — Focus indicators, focus not obscured, dialog focus traps, SPA route focus, focus-visible patterns
150- [ARIA Patterns](references/aria-patterns.md) — Accessible tabs, live regions, data tables with ARIA attributes
151- [Forms and Validation](references/forms-validation.md) — Label association, error announcement, redundant entry, accessible authentication
152- [Color and Media](references/color-and-media.md) — Contrast requirements, reduced motion, dragging alternatives, video captions, alt text
153- [Testing](references/testing.md) — Keyboard testing, screen reader pairings, axe DevTools, jest-axe and vitest-axe unit tests
oakoss