` of new page |
| Dynamic content insert | Announce with `aria-live`, optionally move focus |
| Item deleted from list | Focus next item, or previous if last was deleted |
| Accordion expand | Focus remains on trigger; content is next in tab order |
| Error in form | Move focus to first invalid field |
| Toast notification | Use `aria-live="polite"` — do NOT move focus |
| Skip link activation | Move focus to main content landmark |
**No focus-on-change (WCAG 3.2.1):**
- Receiving focus must not trigger a context change (page navigation, form submit, modal open)
- Hover or focus alone should not cause unexpected state changes
**Remediation pattern — SPA route change:**
```tsx
// After route change, move focus to main heading
useEffect(() => {
const heading = document.querySelector('h1');
if (heading) {
heading.setAttribute('tabindex', '-1');
heading.focus();
}
}, [pathname]);
```
### 5. Touch & Pointer (WCAG 2.5.5 / 2.5.7 / 2.5.8)
**Target size (WCAG 2.5.5 — enhanced, WCAG 2.5.8 — new in 2.2):**
| Level | Minimum Size | Notes |
|-------|-------------|-------|
| AA (2.5.8) | 24x24 CSS px | Or 24px spacing between targets |
| AAA (2.5.5) | 44x44 CSS px | Recommended for mobile |
| Exception | Inline links in text | Exempt from size requirement |
| Exception | User-agent controlled | Native browser elements |
**Dragging movements (WCAG 2.5.7 — new in 2.2):**
- Any drag-based operation must have a non-dragging alternative
- Drag-to-reorder → up/down buttons or keyboard arrows
- Drag-to-resize → resize handle with keyboard support
- Drag-to-draw → tap/click waypoints
**Remediation pattern — touch targets:**
```tsx
// Ensure 44x44 minimum touch area even for small visual elements
// For inline elements that can't be 44px, use padding/margin for spacing
```
### 6. Motion & Animation (WCAG 2.3.1 / 2.3.3 / 2.2.2)
| Rule | Requirement |
|------|-------------|
| No seizure triggers | No content flashes > 3 times/second |
| No auto-play without controls | Auto-playing content has pause/stop |
| Respect `prefers-reduced-motion` | All animation must check this |
| Parallax/scroll-linked | Must degrade to static under reduced-motion |
| Carousel/slideshow | Auto-advance has visible pause control |
| Video | Captions + audio description available |
**Non-negotiable reduced-motion pattern:**
```tsx
// CSS approach — always provide reduced-motion override
@media (prefers-reduced-motion: reduce) {
*, *::before, *::after {
animation-duration: 0.01ms !important;
animation-iteration-count: 1 !important;
transition-duration: 0.01ms !important;
scroll-behavior: auto !important;
}
}
// Tailwind approach
// React hook for programmatic animation control
function usePrefersReducedMotion(): boolean {
const [prefersReduced, setPrefersReduced] = useState(false);
useEffect(() => {
const mq = window.matchMedia('(prefers-reduced-motion: reduce)');
setPrefersReduced(mq.matches);
const handler = (e: MediaQueryListEvent) => setPrefersReduced(e.matches);
mq.addEventListener('change', handler);
return () => mq.removeEventListener('change', handler);
}, []);
return prefersReduced;
}
// Framer Motion integration
const fadeIn = {
initial: { opacity: 0 },
animate: { opacity: 1 },
transition: { duration: prefersReduced ? 0 : 0.3 },
};
```
### 7. Semantic Structure (WCAG 1.3.1 / 2.4.1 / 2.4.2 / 2.4.6)
**Heading hierarchy:**
- One `
` per page — matches ``
- Heading levels must not skip (h1 > h2 > h3, never h1 > h3)
- Headings must be descriptive (not "Section 1")
**Landmark regions:**
| Landmark | HTML Element | Notes |
|----------|-------------|-------|
| Banner | `<header>` | Site-wide header (one per page) |
| Navigation | `<nav>` | Label with `aria-label` if > 1 nav |
| Main | `<main>` | One per page, skip link target |
| Complementary | `<aside>` | Related but independent content |
| Content Info | `<footer>` | Site-wide footer |
| Search | `<search>` (HTML5.2) or `role="search"` | Search functionality |
| Form | `<form>` with accessible name | Named form regions |
**Lists:**
- Use `<ul>/<ol>/<dl>`, not styled `<div>` sequences
- Assistive tech announces list item count
- Definition lists (`<dl>`) for key-value pairs
**Tables:**
- Data tables: `<th scope="col/row">`, `<caption>` or `aria-labelledby`
- Layout tables: avoid; if unavoidable, use `role="presentation"`
**Page title (WCAG 2.4.2):**
- Every page must have a unique, descriptive `<title>`
- Format: "Page Name | Site Name" or "Page Name — Site Name"
### 8. Cognitive Accessibility (WCAG 2.2 New Criteria)
**Consistent help (WCAG 3.2.6 — new in 2.2):**
- Help mechanisms (chat, FAQ link, contact) must appear in the same relative position across pages
- If a footer has a "Help" link on one page, all pages must have it in the same spot
**Redundant entry (WCAG 3.3.7 — new in 2.2):**
- Don't ask users to re-enter information they've already provided in the same session
- Auto-populate from previous steps (shipping → billing address)
- Exception: security re-authentication, data confirmation
**Accessible authentication (WCAG 3.3.8 — new in 2.2):**
- No cognitive function test (puzzle, memorization) as sole auth method
- Allow password managers (don't block paste in password fields)
- Allow copy-paste for verification codes
- Biometric and passkey alternatives satisfy this criterion
**Remediation patterns:**
```tsx
// BAD: blocks paste in password field
<input type="password" onPaste={(e) => e.preventDefault()} />
// GOOD: allows paste, supports password managers
<input type="password" autoComplete="current-password" />
// BAD: cognitive test CAPTCHA as only option
<ReCaptcha />
// GOOD: multiple auth options
<fieldset>
<legend>Verify you're human</legend>
<button onClick={handlePasskey}>Sign in with passkey</button>
<button onClick={handleEmail}>Email verification code</button>
</fieldset>
```
### 9. Forms & Error Handling (WCAG 1.3.5 / 3.3.1 / 3.3.2 / 3.3.3 / 3.3.4)
| Criterion | Requirement |
|-----------|------------|
| Error identification (3.3.1) | Errors described in text, not color alone |
| Labels/instructions (3.3.2) | All inputs have visible labels |
| Error suggestion (3.3.3) | Suggest corrections when known |
| Error prevention (3.3.4) | Legal/financial: reversible, checked, confirmed |
| Input purpose (1.3.5) | `autocomplete` on personal data fields |
**Remediation pattern — form validation:**
```tsx
<form aria-describedby="form-errors" noValidate onSubmit={handleSubmit}>
{errors.length > 0 && (
<div id="form-errors" role="alert" className="text-red-600">
<h2>Please fix {errors.length} error{errors.length > 1 ? 's' : ''}:</h2>
<ul>
{errors.map(err => (
<li key={err.field}>
<a href={`#${err.field}`}>{err.message}</a>
</li>
))}
</ul>
</div>
)}
<div>
<label htmlFor="email">Email address</label>
<input
id="email"
type="email"
autoComplete="email"
aria-invalid={hasError('email')}
aria-describedby={hasError('email') ? 'email-error' : undefined}
/>
{hasError('email') && (
<p id="email-error" className="text-red-600">
Enter a valid email address (e.g., name@example.com)
</p>
)}
</div>
</form>
```
---
## Severity Levels
| Level | Meaning | Action | Examples |
|-------|---------|--------|----------|
| **Critical** | Blocks access for disabled users | Must fix before ship | Missing alt text on nav images, no keyboard access to primary actions, contrast below 2:1 |
| **Major** | Significant barrier, workaround exists | Fix in current sprint | Missing focus indicators, no skip link, heading hierarchy broken |
| **Minor** | Degraded experience, not a blocker | Fix in backlog | AAA contrast fail (passes AA), touch targets 36px (not 44px), missing autocomplete |
| **Info** | Best practice improvement | Track for next iteration | Could add aria-describedby for extra context, landmark labels for multiple navs |
---
## Automated Testing Tools
### Build-time / CI
| Tool | What It Catches | Integration |
|------|----------------|-------------|
| **axe-core** | 50+ WCAG rules, DOM-based | `@axe-core/react`, `jest-axe`, Playwright |
| **eslint-plugin-jsx-a11y** | Static JSX checks (missing alt, role misuse) | ESLint config |
| **pa11y** | Page-level WCAG scans | CI pipeline, URL-based |
| **Lighthouse** | Accessibility score + specific issues | Chrome DevTools, CI |
### Development-time
| Tool | Usage |
|------|-------|
| **axe DevTools** | Browser extension — real-time audit |
| **WAVE** | Browser extension — visual overlay of issues |
| **Accessibility Insights** | Microsoft tool — guided manual + automated |
| **VoiceOver** (macOS) | Cmd+F5 to test screen reader |
| **NVDA** (Windows) | Free screen reader for testing |
### Recommended test setup:
```typescript
// vitest + jest-axe for component-level a11y testing
import { axe, toHaveNoViolations } from 'jest-axe';
import { render } from '@testing-library/react';
expect.extend(toHaveNoViolations);
it('has no accessibility violations', async () => {
const { container } = render(<MyComponent />);
const results = await axe(container);
expect(results).toHaveNoViolations();
});
// Playwright + axe for page-level testing
import AxeBuilder from '@axe-core/playwright';
test('page has no a11y violations', async ({ page }) => {
await page.goto('/dashboard');
const results = await new AxeBuilder({ page }).analyze();
expect(results.violations).toEqual([]);
});
```
---
## Output Format
Each finding should produce:
```json
{
"id": "a11y-001",
"rule": "WCAG 1.4.3",
"level": "A",
"severity": "critical",
"component": "StatusBadge",
"element": "badge text on green background",
"issue": "Contrast ratio 2.8:1 — below 4.5:1 AA threshold for normal text",
"currentValue": "fg: #ffffff, bg: #22c55e → 2.8:1",
"remediation": "Darken text to #1a472a (7.2:1) or switch bg to #16a34a with white text (3.4:1 — still fails, use #15803d for 4.6:1)",
"effort": "low",
"automated": true,
"testWith": "axe-core rule: color-contrast"
}
```
---
## Integration with Memoire
### Spec feedback loop
- Findings map to spec `accessibility` field updates
- Critical/Major issues block codegen (emit warning in generation output)
- Color contrast findings update design token recommendations
- Keyboard nav findings add to component `keyboardNav` spec property
- Touch target findings set `touchTarget` spec property
### Codegen enforcement
- Generated components always include `aria-label` when spec says `"required"`
- Generated forms always include `<label>` associations
- Generated modals always include focus trap and Escape handler
- Generated images always include `alt` attribute (empty string for decorative)
- `prefers-reduced-motion` media query included when component has animations
### Design token validation
- All fg/bg token pairs are contrast-checked at token registration time
- Failing pairs are flagged in `memi tokens` output
- Design system health score includes accessibility compliance percentage
### WCAG 2.2 criteria coverage map
| Criterion | Spec Field | Agent Check | Codegen Enforced |
|-----------|-----------|-------------|-----------------|
| 1.4.3 Contrast | designTokens | a11yContrast | token validation |
| 1.4.11 Non-text Contrast | designTokens | a11yContrast | border/icon checks |
| 2.1.1 Keyboard | accessibility.keyboardNav | a11yKeyboard | focus styles |
| 2.4.7 Focus Visible | accessibility.focusStyle | a11yKeyboard | outline classes |
| 2.4.11 Focus Appearance | accessibility.focusStyle | a11yKeyboard | 2px outline |
| 2.5.5 Target Size | accessibility.touchTarget | a11yCognitive | min-h/min-w |
| 2.5.8 Target Size Min | accessibility.touchTarget | a11yCognitive | 24px minimum |
| 3.3.2 Labels | accessibility.ariaLabel | a11yAria | label elements |
| 4.1.2 Name/Role/Value | accessibility.role | a11yAria | ARIA attributes |