` instead of semantic elements (`<nav>`, `<main>`, `<article>`)
- **Color-only information**: Status indicated only by color without icon/text
- **Missing labels**: Form inputs without associated `<label>` or `aria-label`
- **Keyboard traps**: Focus that cannot escape without Escape key
- **Removing focus outline**: `outline: none` without replacement indicator
- **Positive tabindex**: Using `tabindex > 0` (disrupts natural order)
- **Div with onClick**: Using `
` instead of `<button>` or `useButton`
- **Manual focus in modals**: Using `useEffect` + `ref.focus()` instead of `FocusScope`
- **Auto-playing media**: Audio/video that plays without user action
- **ARIA overuse**: Using ARIA when semantic HTML suffices
## Upstream coverage (do not restate)
Vendor tutorials, API references, and criterion walkthroughs removed in the 2026-07-31 wrap-plus-delta thinning. Consult the first-party source; only the ork delta (floors, scars, house decisions) lives in `$\{CLAUDE_PLUGIN_ROOT\}/skills/accessibility/references/ork-delta.md`.
| Topic | First-party source |
|-------|--------------------|
| WCAG 2.2 success-criterion walkthroughs and audit checklists | [WCAG 2.2 quick reference](https://www.w3.org/WAI/WCAG22/quickref/) and [WCAG 2.2 spec](https://www.w3.org/TR/WCAG22/) |
| ARIA widget patterns and keyboard interaction models | [WAI-ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/) |
| React Aria hook APIs (useButton, useMenu, useComboBox, useModalOverlay, useTooltip, usePopover), component checklists, worked examples | [React Aria docs](https://react-spectrum.adobe.com/react-aria/) |
| Focus trap, focus restoration, roving tabindex, and skip-link algorithms | [React Aria FocusScope](https://react-spectrum.adobe.com/react-aria/FocusScope.html) and [APG patterns](https://www.w3.org/WAI/ARIA/apg/patterns/) |
| Cognitive accessibility guidance (COGA) | [W3C Making Content Usable](https://www.w3.org/TR/coga-usable/) |
| Screen reader testing walkthroughs (NVDA, JAWS, VoiceOver, TalkBack) | [WebAIM screen reader testing](https://webaim.org/articles/screenreader_testing/) |
## Detailed Documentation
| Resource | Description |
|----------|-------------|
| `$\{CLAUDE_PLUGIN_ROOT\}/skills/accessibility/scripts` | Templates: accessible form, focus trap, React Aria components |
| `$\{CLAUDE_PLUGIN_ROOT\}/skills/accessibility/references/ork-delta.md` | Ork-specific floors, scars, and house decisions (cognitive ceilings, overlay recipe, canonical focus-trap selector) |
| `$\{CLAUDE_PLUGIN_ROOT\}/skills/accessibility/references/ux-thresholds-quick.md` | UI/UX thresholds quick reference: contrast, touch targets, cognitive load, typography, forms |
| `$\{CLAUDE_PLUGIN_ROOT\}/skills/accessibility/examples/wcag-examples.md` | Complete accessible form, modal, and navigation examples |
## Related Skills
- `ork:testing-e2e` - E2E testing patterns including accessibility testing
- `design-system-starter` - Accessible component library patterns
- `ork:i18n-date-patterns` - RTL layout and locale-aware formatting
- `motion-animation-patterns` - Reduced motion and animation accessibility
---
## Rules (10)
### Grep-able anti-patterns detectable via static code analysis without a browser — HIGH
# Accessibility Anti-Patterns: Static Detection
These patterns are detectable by grep, ESLint, or code review — no browser required.
## Anti-Pattern Table
| Anti-Pattern | Detection Regex | WCAG | Fix |
|---|---|---|---|
| Focus removal | `outline:\s*(none\|0)` without `:focus-visible` companion | 2.4.11 | Add `:focus-visible` ring with 3:1 contrast |
| Non-descriptive links | Link text `/^(click here\|read more\|here\|more\|learn more)$/i` | 2.4.4 | Use descriptive text meaningful out of context |
| Autoplay media | `<(video\|audio)[^>]*autoplay` without `muted` | 1.4.2 | Add `muted` or remove `autoplay` |
| Missing language | `<html(?![^>]*lang)` | 3.1.1 | Add `<html lang="en">` (or correct BCP 47 tag) |
| Disabled zoom | `(user-scalable=no\|maximum-scale=1)` in viewport meta | 1.4.4 | Remove these restrictions entirely |
| SR content hidden wrong | `display:\s*none\|visibility:\s*hidden` on ARIA-role elements | 1.3.1 | Use `.sr-only` (visually hidden, SR accessible) |
| Placeholder as label | `<input[^>]*placeholder` without nearby `<label` | 3.3.2 | Add `<label for="id">` linked via matching `id` |
| Heading skip | `<h[1-6]` followed later by level +2 or more | 1.3.1 | Maintain sequential hierarchy (h1 > h2 > h3) |
| Image without alt | `]*\balt\b)` | 1.1.1 | Add `alt="description"` or `alt=""` for decorative |
| Button without text | `<button[^>]*>(\s*<[^/])` with no `aria-label` | 4.1.2 | Add `aria-label="Action name"` |
| Positive tabindex | `tabindex="[1-9]` | 2.4.3 | Use `tabindex="0"` or `-1` only |
| Div/span click handler | `<(div\|span)[^>]*onClick` | 4.1.2 | Replace with `<button>` or add `role="button"` + keyboard handler |
## Detailed Fixes
### Focus Removal
**Incorrect:**
```css
/* Removes focus for all users including keyboard-only users */
* { outline: none; }
button:focus { outline: 0; }
```
**Correct:**
```css
/* Only hide outline for mouse users; preserve for keyboard users */
button:focus:not(:focus-visible) { outline: none; }
button:focus-visible {
outline: 3px solid #0052cc;
outline-offset: 2px;
}
```
### Placeholder as Label
**Incorrect:**
```html
```
**Correct:**
```html
```
### Autoplay Media
**Incorrect:**
```html
```
**Correct:**
```html
```
### Icon-Only Button
**Incorrect:**
```html
```
**Correct:**
```html
```
### Visually Hidden Content (SR-only)
**Incorrect:**
```css
/* Hides from screen readers too */
.hidden-label { display: none; }
```
**Correct:**
```css
/* Visible to screen readers, hidden visually */
.sr-only {
position: absolute;
width: 1px;
height: 1px;
padding: 0;
margin: -1px;
overflow: hidden;
clip: rect(0, 0, 0, 0);
white-space: nowrap;
border: 0;
}
```
## ESLint Rule Mapping
| Anti-Pattern | ESLint Rule (`eslint-plugin-jsx-a11y`) |
|---|---|
| Image without alt | `jsx-a11y/alt-text` |
| Missing label | `jsx-a11y/label-has-associated-control` |
| Non-descriptive links | `jsx-a11y/anchor-ambiguous-text` |
| Div with click handler | `jsx-a11y/click-events-have-key-events` + `jsx-a11y/no-static-element-interactions` |
| Button without text | `jsx-a11y/accessible-emoji` + custom rule |
| Autoplay | `jsx-a11y/media-has-caption` |
### Build accessible buttons, dialogs, and menus with React Aria keyboard support — HIGH
# React Aria Components (useButton, useDialog, useMenu)
## useButton - Accessible Button
```tsx
import { useRef } from 'react';
import { useButton, useFocusRing, mergeProps } from 'react-aria';
import type { AriaButtonProps } from 'react-aria';
function Button(props: AriaButtonProps & { className?: string }) {
const ref = useRef(null);
const { buttonProps, isPressed } = useButton(props, ref);
const { focusProps, isFocusVisible } = useFocusRing();
return (
);
}
```
**Key Props:**
- `onPress` - Triggered on click, tap, Enter, or Space
- `isDisabled` - Disables all interaction
- `elementType` - Custom element type (default: button)
## useDialog - Modal Dialog
```tsx
import { useRef } from 'react';
import { useDialog, useModalOverlay, FocusScope, mergeProps } from 'react-aria';
import { useOverlayTriggerState } from 'react-stately';
function Modal({ state, title, children }) {
const ref = useRef(null);
const { modalProps, underlayProps } = useModalOverlay({}, state, ref);
const { dialogProps, titleProps } = useDialog({ 'aria-label': title }, ref);
return (
);
}
```
## useMenu - Dropdown Menu
```tsx
import { useRef } from 'react';
import { useButton, useMenuTrigger, useMenu, useMenuItem, mergeProps } from 'react-aria';
import { useMenuTriggerState, useTreeState } from 'react-stately';
import { Item } from 'react-stately';
export function MenuButton(props: { label: string; onAction: (key: string) => void }) {
const state = useMenuTriggerState({});
const ref = useRef(null);
const { menuTriggerProps, menuProps } = useMenuTrigger({}, state, ref);
const { buttonProps } = useButton(menuTriggerProps, ref);
return (
(null);
const state = useTreeState({ ...props, selectionMode: 'none' });
const { menuProps } = useMenu(props, state, ref);
return (
(null);
const { menuItemProps, isFocused, isPressed } = useMenuItem(
{ key: item.key, onAction, onClose }, state, ref
);
return (
{item.rendered}
);
}
```
## mergeProps Utility
Safely merge multiple prop objects (combines event handlers):
```tsx
import { mergeProps } from 'react-aria';
const combinedProps = mergeProps(
{ onClick: handler1, className: 'base' },
{ onClick: handler2, className: 'extra' }
);
// Result: onClick calls both handlers
```
## Hooks vs Components Decision
| Approach | Use When |
|----------|----------|
| `useButton` hooks | Maximum control over rendering and styling |
| `Button` from react-aria-components | Fast prototyping, less boilerplate |
## Anti-Patterns
```tsx
// NEVER use div with onClick for interactive elements
(null);
const { buttonProps } = useButton({ onPress: handleClick }, ref);
return ;
```
### Create accessible form controls with React Aria labels and keyboard navigation — HIGH
# React Aria Forms (useComboBox, useTextField, useListBox)
## useComboBox - Accessible Autocomplete
```tsx
import { useRef } from 'react';
import { useComboBox, useFilter } from 'react-aria';
import { useComboBoxState } from 'react-stately';
function ComboBox(props) {
const { contains } = useFilter({ sensitivity: 'base' });
const state = useComboBoxState({ ...props, defaultFilter: contains });
const inputRef = useRef(null), buttonRef = useRef(null), listBoxRef = useRef(null);
const { buttonProps, inputProps, listBoxProps, labelProps } = useComboBox(
{ ...props, inputRef, buttonRef, listBoxRef }, state
);
return (
{state.isOpen && (
);
}
```
**Features:**
- Type-ahead filtering with `useFilter`
- Arrow keys navigate options, Enter selects, Escape closes
- Label associated with input via `labelProps`
- `aria-expanded` indicates dropdown state
## useTextField - Accessible Text Input
```tsx
import { useRef } from 'react';
import { useTextField } from 'react-aria';
function TextField(props) {
const ref = useRef(null);
const { labelProps, inputProps, descriptionProps, errorMessageProps } = useTextField(props, ref);
return (
{item.rendered}
);
}
// Usage
- Red
- Green
- Blue
```
**Selection Modes:**
- `"single"` - Select one item
- `"multiple"` - Select multiple items
- `"none"` - No selection (display only)
## useSelect - Dropdown Select
```tsx
import { useRef } from 'react';
import { HiddenSelect, useSelect } from 'react-aria';
import { useSelectState } from 'react-stately';
function Select(props) {
const state = useSelectState(props);
const ref = useRef(null);
const { triggerProps, valueProps, menuProps } = useSelect(props, state, ref);
return (
([]);
const handleKeyDown = (e: KeyboardEvent, index: number) => {
const keyMap: Record = {
ArrowRight: (index + 1) % tabs.length,
ArrowLeft: (index - 1 + tabs.length) % tabs.length,
Home: 0, End: tabs.length - 1,
};
if (e.key in keyMap) {
e.preventDefault();
setActiveIndex(keyMap[e.key]);
tabRefs.current[keyMap[e.key]]?.focus();
}
};
return (
(
itemCount: number,
orientation: Orientation = 'vertical'
) {
const [activeIndex, setActiveIndex] = useState(0);
const itemsRef = useRef>(new Map());
const handleKeyDown = useCallback((event: React.KeyboardEvent) => {
const keys = orientation === 'horizontal'
? { next: 'ArrowRight', prev: 'ArrowLeft' }
: { next: 'ArrowDown', prev: 'ArrowUp' };
let nextIndex: number | null = null;
if (event.key === keys.next) {
nextIndex = (activeIndex + 1) % itemCount;
} else if (event.key === keys.prev) {
nextIndex = (activeIndex - 1 + itemCount) % itemCount;
} else if (event.key === 'Home') {
nextIndex = 0;
} else if (event.key === 'End') {
nextIndex = itemCount - 1;
}
if (nextIndex !== null) {
event.preventDefault();
setActiveIndex(nextIndex);
itemsRef.current.get(nextIndex)?.focus();
}
}, [activeIndex, itemCount, orientation]);
const getItemProps = useCallback((index: number) => ({
ref: (element: T | null) => {
if (element) {
itemsRef.current.set(index, element);
} else {
itemsRef.current.delete(index);
}
},
tabIndex: index === activeIndex ? 0 : -1,
onFocus: () => setActiveIndex(index),
}), [activeIndex]);
return { activeIndex, setActiveIndex, handleKeyDown, getItemProps };
}
// Usage: Toolbar
function Toolbar() {
const { getItemProps, handleKeyDown } = useRovingTabindex(
3, 'horizontal'
);
return (
);
}
```
## Skip Links
Allow keyboard users to bypass repeated navigation:
```tsx
export function SkipLinks() {
return (
);
}
// Layout usage
export function Layout({ children }) {
return (
<>
{children}
);
}
```
```css
.skip-link {
position: absolute;
top: -40px;
left: 0;
background: #000;
color: #fff;
padding: 8px;
z-index: 100;
}
.skip-link:focus {
top: 0;
}
```
## Focus Within Detection
```tsx
export function useFocusWithin() {
const ref = useRef(null);
const [isFocusWithin, setIsFocusWithin] = useState(false);
useEffect(() => {
const element = ref.current;
if (!element) return;
const handleFocusIn = () => setIsFocusWithin(true);
const handleFocusOut = (e: FocusEvent) => {
if (!element.contains(e.relatedTarget as Node)) {
setIsFocusWithin(false);
}
};
element.addEventListener('focusin', handleFocusIn);
element.addEventListener('focusout', handleFocusOut);
return () => {
element.removeEventListener('focusin', handleFocusIn);
element.removeEventListener('focusout', handleFocusOut);
};
}, []);
return { ref, isFocusWithin };
}
```
## Focus Indicator Styles
```css
/* Use :focus-visible (not :focus) for keyboard-only indicators */
:focus-visible {
outline: 3px solid #0052cc;
outline-offset: 2px;
}
/* Ensure scroll margin for sticky headers */
:focus {
scroll-margin-top: var(--header-height, 64px);
}
```
## Anti-Patterns
```tsx
// NEVER use positive tabindex - breaks natural tab order
// NEVER remove focus outline without replacement (WCAG 2.4.7)
button:focus { outline: none; }
// NEVER auto-focus without user expectation
useEffect(() => inputRef.current?.focus(), []);
// NEVER hide skip links permanently - must be visible on focus
.skip-link { display: none; }
```
**Incorrect — Removing focus outline globally:**
```css
*:focus {
outline: none;
}
/* Violates WCAG 2.4.7, keyboard users can't see focus */
```
**Correct — Using focus-visible for keyboard-only indicators:**
```css
:focus-visible {
outline: 3px solid #0052cc;
outline-offset: 2px;
}
```
### Concrete pass/fail exit criteria for each POUR principle mapped to WCAG 2.2 criteria — CRITICAL
# POUR Exit Criteria (WCAG 2.2 AA)
Pass/fail thresholds for each principle. Every item must pass before marking a feature accessible.
## Perceivable
- [ ] Every `![]()
` has `alt`. Decorative images use `alt=""`. Complex images use `aria-describedby` pointing to adjacent descriptive text. (1.1.1, Level A)
- [ ] Normal text contrast >= 4.5:1 against its background. Large text (>= 18pt or >= 14pt bold) contrast >= 3:1. (1.4.3, AA)
- [ ] UI component boundaries (input borders, icon strokes, button outlines) contrast >= 3:1 against adjacent color. (1.4.11, AA)
- [ ] No information is conveyed by color alone — every color-coded element also has an icon, pattern, or visible text label. (1.4.1, A)
- [ ] Page content reflows without horizontal scrolling at 320px viewport width (equivalent to 400% zoom on 1280px display). No fixed-width containers wider than 320px. (1.4.10, AA)
- [ ] Text spacing overrides do not break layout: `line-height: 1.5`, `letter-spacing: 0.12em`, `word-spacing: 0.16em`, `paragraph spacing: 2em` all applied simultaneously produce no clipped or overlapping content. (1.4.12, AA)
## Operable
- [ ] Every interactive element (links, buttons, inputs, custom widgets) is reachable and activatable via keyboard alone. Tab order follows visual reading order (left-to-right, top-to-bottom for LTR). (2.1.1, A)
- [ ] No keyboard trap exists — pressing Escape or a documented key sequence always exits any component that receives focus. (2.1.2, A)
- [ ] A skip link to `<main id="main-content">` is the first focusable element on every page. It becomes visible on focus. (2.4.1, A)
- [ ] All focus indicators: minimum 2px perimeter outline, >= 3:1 contrast between focused and unfocused states. Default browser outlines are acceptable only if they pass the contrast check. (2.4.11, AA — WCAG 2.2)
- [ ] Touch targets are >= 24x24 CSS pixels. No adjacent interactive target falls within a 24px radius of another target's boundary. Primary CTAs should be >= 44x44px. (2.5.8, AA — WCAG 2.2)
- [ ] No content moves, blinks, scrolls, or auto-updates for more than 3 seconds without a mechanism to pause, stop, or hide it. (2.2.2, A)
- [ ] Page titles describe topic or purpose uniquely within the site (e.g., "Login — AppName", not just "Login"). (2.4.2, A)
## Understandable
- [ ] `<html lang="xx">` is set and matches the primary language of the page. Language changes within content use `lang` on the containing element. (3.1.1, A)
- [ ] Every form input has an associated `<label for="id">`, or `aria-label`, or `aria-labelledby`. Placeholder text alone does not count as a label. (3.3.2, A)
- [ ] Error messages: identify the affected field by name, describe the cause of the error, and suggest a specific fix. Errors are announced to assistive technology via `aria-live="polite"` or `role="alert"`. (3.3.1 + 3.3.3, A/AA)
- [ ] No link text is "click here", "read more", "here", "more", or "link" when read out of context. Each link's accessible name uniquely identifies its destination or action. (2.4.4, A)
- [ ] Links that open in a new tab include a visible icon (e.g., external-link icon) with `aria-label` supplement (e.g., `aria-label="Opens in new tab"`). (2.4.4 advisory)
- [ ] Navigation menus appear in the same relative order on every page where they repeat. (3.2.3, AA)
- [ ] Components with the same function have the same accessible name across all pages. (3.2.4, AA)
## Example: Focus Indicator (2.4.11)
**Incorrect:**
```css
/* Removes all focus indicators — keyboard users are blind */
*:focus { outline: none; }
```
**Correct:**
```css
/* 2px outline with sufficient contrast for focus visibility */
*:focus-visible {
outline: 2px solid var(--focus-ring, #005fcc);
outline-offset: 2px;
}
```
## Robust
- [ ] No duplicate `id` attributes on interactive elements in the same document. No unclosed or improperly nested landmark elements (`<main>`, `<nav>`, `<header>`, `<footer>`). (4.1.1, A)
- [ ] Custom interactive widgets expose correct ARIA state attributes:
- Toggle buttons: `aria-pressed="true|false"`
- Disclosure widgets: `aria-expanded="true|false"`
- Tabs: `aria-selected="true|false"` on tab elements, `role="tablist"` on container
- Custom checkboxes: `aria-checked="true|false|mixed"`
- Comboboxes: `aria-autocomplete`, `aria-activedescendant` (4.1.2, A)
- [ ] Status messages (toasts, loading indicators, success confirmations, live regions) use `role="status"` or `aria-live="polite"`. Urgent alerts use `role="alert"` or `aria-live="assertive"`. (4.1.3, AA)
- [ ] All `aria-*` attributes reference existing IDs. No orphaned `aria-labelledby` or `aria-describedby` values. (4.1.2, A)
### Meet WCAG 4.5:1 minimum contrast ratio for text and UI component readability — CRITICAL
# Color Contrast (WCAG 1.4.3, 1.4.11)
## Contrast Requirements
| Element Type | Minimum Ratio | WCAG Criterion |
|-------------|---------------|----------------|
| Normal text (< 18pt / < 14pt bold) | 4.5:1 | 1.4.3 |
| Large text (>= 18pt / >= 14pt bold) | 3:1 | 1.4.3 |
| UI components (borders, icons, focus) | 3:1 | 1.4.11 |
| Focus indicators | 3:1 | 2.4.7 |
## CSS Custom Properties
```css
:root {
--text-primary: #1a1a1a; /* 16.1:1 on white - normal text */
--text-secondary: #595959; /* 7.0:1 on white - secondary */
--focus-ring: #0052cc; /* 7.3:1 - focus indicator */
}
/* High visibility focus indicator */
:focus-visible {
outline: 3px solid var(--focus-ring);
outline-offset: 2px;
}
/* Button border 3:1 contrast */
.button {
background: #ffffff;
border: 2px solid #757575; /* 4.5:1 on white */
}
/* Minimum target size (WCAG 2.5.8) */
button, a[role="button"], input[type="checkbox"] {
min-width: 24px;
min-height: 24px;
}
/* Touch-friendly target size */
@media (hover: none) {
button {
min-width: 44px;
min-height: 44px;
}
}
```
## Non-Color Status Indicators
Never convey information through color alone:
```tsx
// FORBIDDEN: Color-only status
Error
// CORRECT: Color + icon + text
Error: Invalid email address
```
## Text Spacing (WCAG 1.4.12)
Content must remain usable when text spacing is adjusted:
```css
body {
line-height: 1.5; /* at least 1.5x font size */
}
p {
margin-bottom: 2em; /* at least 2x font size */
}
```
## Reflow (WCAG 1.4.10)
Content must reflow without horizontal scrolling at 320px width:
```css
/* Responsive design */
.card {
width: 100%;
max-width: 600px;
}
/* FORBIDDEN: Fixed width that forces horizontal scroll */
.card {
width: 800px;
}
```
## Testing Tools
- **WebAIM Contrast Checker**: [webaim.org/resources/contrastchecker](https://webaim.org/resources/contrastchecker/)
- **Chrome DevTools**: Inspect > Color picker > Contrast ratio
- **Lighthouse**: Accessibility audit built into Chrome DevTools
## Common Mistakes
| Mistake | Fix |
|---------|-----|
| Insufficient text contrast (#b3b3b3 = 2.1:1) | Use #595959 or darker (7.0:1+) |
| Removing focus outline globally | Use `:focus-visible` with custom outline |
| Color-only error indication | Add icon + text alongside color |
| Fixed-width layouts | Use responsive `max-width` + `width: 100%` |
| Tiny touch targets | Minimum 24px, 44px for touch devices |
**Incorrect — Insufficient text contrast:**
```css
.secondary-text {
color: #b3b3b3; /* 2.1:1 ratio on white - fails WCAG AA */
}
```
**Correct — Meeting 4.5:1 contrast minimum:**
```css
.secondary-text {
color: #595959; /* 7.0:1 ratio on white - passes WCAG AA */
}
```
### Prefer native HTML elements over custom ARIA widgets for built-in accessibility — CRITICAL
# Native HTML First (2026 Best Practice)
## Principle
Use the platform. Native HTML elements (`<dialog>`, `
{title}
{children}
{state.isOpen && (
{
props.onAction(key as string);
state.close();
}}
/>
)}
);
}
function MenuPopup(props: any) {
const ref = useRef-
{[...state.collection].map((item) => (
))}
Click me
// Missing keyboard support!
// ALWAYS use useButton or native button
const { buttonProps } = useButton({ onPress: handleClick }, ref);
Click me
// NEVER forget aria-live for dynamic announcements
{errorMessage}
// Screen readers won't announce!
// ALWAYS use aria-live for status updates
{errorMessage}
```
**Incorrect — div with onClick, no keyboard support:**
```tsx
Click me
// No keyboard access, no screen reader announcement
```
**Correct — useButton hook provides full accessibility:**
```tsx
const ref = useRef-
{[...state.collection].map((item) => (
- {item.rendered} ))}
{props.description && (
);
}
```
**Key Props:**
- `label` - Accessible label text
- `description` - Helper text (linked via `aria-describedby`)
- `errorMessage` - Error text (linked via `aria-describedby`)
- `isRequired` - Adds `aria-required="true"`
- `isInvalid` - Adds `aria-invalid="true"`
## useListBox - Accessible List with Selection
```tsx
import { useRef } from 'react';
import { useListBox, useOption } from 'react-aria';
import { useListState } from 'react-stately';
import { Item } from 'react-stately';
function ListBox(props) {
const state = useListState(props);
const ref = useRef(null);
const { listBoxProps } = useListBox(props, state, ref);
return (
{props.description}
)}
{props.errorMessage && (
{props.errorMessage}
)}
-
{[...state.collection].map((item) => (
))}
{tabs.map((tab, i) => (
))}
);
}
```
## useRovingTabindex Hook
Reusable hook for toolbars, menus, and lists:
```tsx
type Orientation = 'horizontal' | 'vertical';
export function useRovingTabindex`, `<select>`, `<button>`) ship with keyboard handling, focus management, and screen reader announcements built in. Custom ARIA widgets should only be used when **no native equivalent exists**.
## Native Element Replacements
| Instead of... | Use native | Why |
|--------------|-----------|-----|
| Custom modal + focus trap JS | `<dialog>` + `showModal()` | Built-in focus trap, Escape close, inert backdrop |
| Custom accordion + ARIA | `
` / `` | Built-in expand/collapse, keyboard, screen reader |
| Custom dropdown + listbox ARIA | `<select>` | Built-in keyboard nav, mobile-optimized |
| Custom toggle + aria-checked | `<input type="checkbox">` | Built-in state, label association, form submission |
| `
` | Built-in expand/collapse, keyboard, screen reader |
| Custom dropdown + listbox ARIA | `<select>` | Built-in keyboard nav, mobile-optimized |
| Custom toggle + aria-checked | `<input type="checkbox">` | Built-in state, label association, form submission |
| `` | `<button>` | Built-in focus, Enter/Space, role announcement |
## Dialog — Use `<dialog>` + `showModal()`
**Incorrect — Custom modal with manual focus trap:**
```tsx
function Modal({ isOpen, onClose, children }) {
const ref = useRef(null);
useEffect(() => {
if (isOpen) ref.current?.focus();
// manual focus trap, Escape handler, inert siblings...
}, [isOpen]);
return isOpen ? (
{children}
) : null;
}
```
**Correct — Native `<dialog>` with built-in focus management:**
```tsx
function Modal({ children }) {
const dialogRef = useRef(null);
return (
);
}
// Open with showModal() for built-in focus trap + backdrop + Escape
dialogRef.current?.showModal();
```
## Accordion — Use `` / ``
**Incorrect — Custom accordion with ARIA:**
```tsx
{content}
```
**Correct — Native `` with CSS styling:**
```tsx
Section Title
{content}
```
```css
details summary { cursor: pointer; padding: 0.75rem; font-weight: 600; }
details[open] summary { border-bottom: 1px solid var(--border); }
details summary::marker { content: ''; } /* Note: ::marker on is supported in Chrome 89+, Firefox 68+, Safari 15.4+ */
details summary::after { content: '\25B6'; transition: transform 0.2s; }
details[open] summary::after { transform: rotate(90deg); }
```
## When Custom ARIA Is Justified
Use custom ARIA only when native elements cannot meet the requirement:
| Use case | Why native fails | ARIA approach |
|----------|-----------------|---------------|
| Combobox with async search | `<datalist>` lacks async, filtering control | `role="combobox"` + `useComboBox` |
| Tab panel widget | No native tab element | `role="tablist"` + `role="tab"` |
| Tree view | No native tree element | `role="tree"` + `role="treeitem"` |
| Menu with submenus | `<menu>` has limited support | `role="menu"` + `role="menuitem"` |
## Audit Checklist
- [ ] Every `role="dialog"` — can it be `<dialog>`?
- [ ] Every custom accordion — can it be ``?
- [ ] Every `` — should it be `<button>` or ``?
- [ ] Every custom select — does `<select>` + CSS suffice?
- [ ] ARIA attributes are only used where no native equivalent exists
### Use semantic HTML and ARIA attributes for proper screen reader document structure — CRITICAL
# Semantic HTML & ARIA (WCAG 1.3.1, 4.1.2)
## Document Structure
```tsx
Page Title
Features
- Feature 1
```
## Heading Hierarchy
Always follow h1-h6 order without skipping levels:
```tsx
// CORRECT
Page Title
Section
Subsection
// FORBIDDEN: Skipping levels
Page Title
Subsection
// Skipped h2!
```
## ARIA Labels and States
```tsx
// Icon-only button
// Form field with error
{error && {error}
}
// Custom widget with explicit role
{
if (e.key === ' ' || e.key === 'Enter') handleToggle();
}}
/>
```
## Form Structure
```tsx
```
## Live Regions
```tsx
// Polite: status updates (default, avoids interruption)
{items.length} items in cart
// Assertive: errors that need immediate announcement
{error}
```
## Page Language
```html
The French phrase Je ne sais quoi means...
```
## Skip Links
```tsx
Skip to main content
{children}
```
```css
.skip-link {
position: absolute;
top: -40px;
left: 0;
background: #000;
color: #fff;
padding: 8px;
z-index: 100;
}
.skip-link:focus {
top: 0;
}
```
## WCAG 2.2 AA Checklist
| Criterion | Requirement | Test |
|-----------|-------------|------|
| 1.1.1 Non-text | Alt text for images | axe-core scan |
| 1.3.1 Info | Semantic HTML, headings | Manual + automated |
| 1.4.3 Contrast | 4.5:1 text, 3:1 large | WebAIM checker |
| 2.1.1 Keyboard | All functionality via keyboard | Tab through |
| 2.4.3 Focus Order | Logical tab sequence | Manual test |
| 2.4.7 Focus Visible | Clear focus indicator | Visual check |
| 2.4.11 Focus Not Obscured | Focus not hidden by sticky elements | scroll-margin-top |
| 2.5.8 Target Size | Min 24x24px interactive | CSS audit |
| 4.1.2 Name/Role/Value | Proper ARIA, labels | Screen reader test |
## Anti-Patterns
- **Div soup**: Using `` where `<nav>`, `<main>`, `<article>` should be used
- **Empty links/buttons**: Interactive elements without accessible names
- **ARIA overuse**: Using ARIA when semantic HTML suffices (prefer `<button>` over ``)
- **Positive tabindex**: Using `tabIndex > 0` disrupts natural tab order
- **Decorative images without alt=""**: Must use `alt=""` or `role="presentation"`
**Incorrect — Skipping heading levels:**
```tsx
Page Title
Subsection
{/* Skipped h2 */}
// Screen readers rely on heading hierarchy
```
**Correct — Following h1-h6 order without skipping:**
```tsx
Page Title
Section
Subsection
```
### Test accessibility compliance with axe-core automation and manual screen reader verification — CRITICAL
# Accessibility Testing
## Automated Testing with axe-core
### Component-Level (jest-axe)
```tsx
import { render } from '@testing-library/react';
import { axe, toHaveNoViolations } from 'jest-axe';
expect.extend(toHaveNoViolations);
test('form has no accessibility violations', async () => {
const { container } = render(;
export function AccessibleForm() {
const [formData, setFormData] = useState({
email: '',
password: '',
agreeToTerms: false,
});
const [errors, setErrors] = useState>>({});
const [submitStatus, setSubmitStatus] = useState('');
const handleSubmit = (e: React.FormEvent) => {
e.preventDefault();
const result = FormSchema.safeParse(formData);
if (!result.success) {
const fieldErrors: Partial> = {};
result.error.issues.forEach((issue) => {
const field = issue.path[0] as keyof FormData;
fieldErrors[field] = issue.message;
});
setErrors(fieldErrors);
setSubmitStatus('Please correct the errors below');
return;
}
setErrors({});
setSubmitStatus('Form submitted successfully!');
// Submit form...
};
return (
);
}
```
**Key accessibility features:**
- All inputs have associated labels with `htmlFor`
- Required fields marked with `aria-required="true"`
- Invalid fields marked with `aria-invalid="true"`
- Error messages use `role="alert"` for immediate announcement
- Error messages linked with `aria-describedby`
- Hint text linked with `aria-describedby`
- Status message uses `role="status"` with `aria-live="polite"`
- Visible focus indicators
- AutoComplete attributes for password managers
---
## 2. Accessible Modal Dialog
Modal with focus trap, Esc to close, and backdrop click handling.
```tsx
import { useEffect, useRef } from 'react';
import { motion, AnimatePresence } from 'motion/react';
import { modalBackdrop, modalContent } from '@/lib/animations';
interface ModalProps {
isOpen: boolean;
onClose: () => void;
title: string;
children: React.ReactNode;
}
export function AccessibleModal({ isOpen, onClose, title, children }: ModalProps) {
const modalRef = useRef(null);
const triggerElementRef = useRef(null);
// Store the element that opened the modal
useEffect(() => {
if (isOpen) {
triggerElementRef.current = document.activeElement as HTMLElement;
}
}, [isOpen]);
// Focus trap and Esc key handler
useEffect(() => {
if (!isOpen) return;
const handleKeyDown = (e: KeyboardEvent) => {
if (e.key === 'Escape') {
onClose();
return;
}
if (e.key === 'Tab') {
const modal = modalRef.current;
if (!modal) return;
const focusableElements = modal.querySelectorAll(
'a[href], button:not([disabled]), textarea, input, select'
);
const firstElement = focusableElements[0];
const lastElement = focusableElements[focusableElements.length - 1];
if (e.shiftKey && document.activeElement === firstElement) {
e.preventDefault();
lastElement.focus();
} else if (!e.shiftKey && document.activeElement === lastElement) {
e.preventDefault();
firstElement.focus();
}
}
};
document.addEventListener('keydown', handleKeyDown);
return () => document.removeEventListener('keydown', handleKeyDown);
}, [isOpen, onClose]);
// Focus first element when modal opens
useEffect(() => {
if (isOpen && modalRef.current) {
const firstFocusable = modalRef.current.querySelector(
'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
);
firstFocusable?.focus();
}
}, [isOpen]);
// Return focus to trigger element when modal closes
useEffect(() => {
if (!isOpen && triggerElementRef.current) {
triggerElementRef.current.focus();
triggerElementRef.current = null;
}
}, [isOpen]);
return (
{isOpen && (
<>
{/* Backdrop */}
{/* Modal */}
{/* Title */}
{title}
{/* Content */}
{children}
{/* Close button */}
{/* Close icon button */}
)}
);
}
```
**Key accessibility features:**
- `role="dialog"` and `aria-modal="true"`
- Title linked with `aria-labelledby`
- Focus trapped within modal
- Esc key closes modal
- Focus returns to trigger element on close
- Close button has `aria-label`
- Backdrop click closes modal
- First focusable element receives focus on open
---
## 3. Skip Navigation Link
Allow keyboard users to bypass repeated navigation.
```tsx
export function SkipLink() {
return (
Skip to main content
);
}
// In your layout component:
export function Layout({ children }: { children: React.ReactNode }) {
return (
<>
{children}
);
}
```
```css
/* styles/globals.css */
.skip-link {
position: absolute;
top: -40px;
left: 0;
background: #000;
color: #fff;
padding: 8px;
text-decoration: none;
z-index: 100;
}
.skip-link:focus {
top: 0;
}
```
---
## 4. Accessible Tab Component
Tabs with keyboard navigation (arrow keys, Home, End).
```tsx
import { useState, useRef, useEffect } from 'react';
interface TabProps {
tabs: { id: string; label: string; content: React.ReactNode }[];
}
export function AccessibleTabs({ tabs }: TabProps) {
const [activeTab, setActiveTab] = useState(0);
const tabListRef = useRef(null);
const handleKeyDown = (e: React.KeyboardEvent, index: number) => {
let newIndex = index;
switch (e.key) {
case 'ArrowRight':
e.preventDefault();
newIndex = (index + 1) % tabs.length;
break;
case 'ArrowLeft':
e.preventDefault();
newIndex = (index - 1 + tabs.length) % tabs.length;
break;
case 'Home':
e.preventDefault();
newIndex = 0;
break;
case 'End':
e.preventDefault();
newIndex = tabs.length - 1;
break;
default:
return;
}
setActiveTab(newIndex);
// Focus the new tab
const newTab = tabListRef.current?.children[newIndex] as HTMLElement;
newTab?.focus();
};
return (
{/* Tab list */}
{tabs.map((tab, index) => (
))}
{/* Tab panels */}
{tabs.map((tab, index) => (
{tab.content}
))}
);
}
```
**Key accessibility features:**
- `role="tablist"`, `role="tab"`, `role="tabpanel"`
- `aria-selected` indicates active tab
- `aria-controls` links tab to panel
- Only active tab is focusable (`tabIndex=\{0\}`)
- Arrow keys navigate between tabs
- Home/End keys jump to first/last tab
- Panels hidden with `hidden` attribute (not CSS display:none)
---
## 5. Focus Management in Complex Widgets
Custom dropdown with roving tabindex.
```tsx
import { useState, useRef, useEffect } from 'react';
interface DropdownProps {
label: string;
options: string[];
value: string;
onChange: (value: string) => void;
}
export function AccessibleDropdown({ label, options, value, onChange }: DropdownProps) {
const [isOpen, setIsOpen] = useState(false);
const [focusedIndex, setFocusedIndex] = useState(0);
const buttonRef = useRef(null);
const listRef = useRef(null);
const handleKeyDown = (e: React.KeyboardEvent) => {
switch (e.key) {
case 'ArrowDown':
e.preventDefault();
if (!isOpen) {
setIsOpen(true);
} else {
setFocusedIndex((prev) => (prev + 1) % options.length);
}
break;
case 'ArrowUp':
e.preventDefault();
if (!isOpen) {
setIsOpen(true);
} else {
setFocusedIndex((prev) => (prev - 1 + options.length) % options.length);
}
break;
case 'Enter':
case ' ':
e.preventDefault();
if (isOpen) {
onChange(options[focusedIndex]);
setIsOpen(false);
buttonRef.current?.focus();
} else {
setIsOpen(true);
}
break;
case 'Escape':
e.preventDefault();
setIsOpen(false);
buttonRef.current?.focus();
break;
}
};
// Focus first option when opening
useEffect(() => {
if (isOpen) {
setFocusedIndex(options.indexOf(value));
}
}, [isOpen, value, options]);
return (
{isOpen && (
{options.map((option, index) => (
- {
onChange(option);
setIsOpen(false);
buttonRef.current?.focus();
}}
className={`px-4 py-2 cursor-pointer ${
index === focusedIndex ? 'bg-blue-100' : ''
} ${option === value ? 'bg-blue-50 font-semibold' : ''}`}
>
{option}
))}
)}
);
}
```
**Key accessibility features:**
- `role="listbox"` and `role="option"`
- `aria-haspopup="listbox"` on trigger
- `aria-expanded` indicates open/closed state
- `aria-selected` on current option
- Arrow keys navigate options
- Enter/Space selects option
- Esc closes dropdown and returns focus
- Focus returns to trigger on close
---
## 6. Live Region for Dynamic Updates
Announce changes to screen reader users without interrupting.
```tsx
import { useState, useEffect } from 'react';
export function ShoppingCart() {
const [items, setItems] = useState([]);
const [statusMessage, setStatusMessage] = useState('');
const addItem = (item: string) => {
setItems([...items, item]);
setStatusMessage(`${item} added to cart. ${items.length + 1} items total.`);
};
const removeItem = (index: number) => {
const removedItem = items[index];
setItems(items.filter((_, i) => i !== index));
setStatusMessage(`${removedItem} removed from cart. ${items.length - 1} items total.`);
};
return (
Shopping Cart
{/* Live region for status updates */}
{statusMessage}
{/* Visible cart count */}
{items.map((item, index) => (
-
{item}
))}
);
}
```
**Key accessibility features:**
- `role="status"` with `aria-live="polite"` announces changes
- `aria-atomic="true"` ensures entire message is read
- `.sr-only` class hides visual duplicate
- Remove buttons have descriptive `aria-label`
---
## 7. Accessible Error Summary
Error summary at top of form that links to fields with errors.
```tsx
interface ErrorSummaryProps {
errors: Record;
}
export function ErrorSummary({ errors }: ErrorSummaryProps) {
const errorEntries = Object.entries(errors);
if (errorEntries.length === 0) return null;
return (
There {errorEntries.length === 1 ? 'is' : 'are'} {errorEntries.length}{' '}
{errorEntries.length === 1 ? 'error' : 'errors'} in this form
{errorEntries.map(([field, message]) => (
-
{
e.preventDefault();
document.getElementById(field)?.focus();
}}
>
{message}
))}
);
}
```
**Key accessibility features:**
- `role="alert"` announces errors immediately
- Links to fields with errors
- Clicking link focuses the field
- Descriptive error count
---
## Resources
- [WCAG 2.2 Spec](https://www.w3.org/TR/WCAG22/)
- [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/)
- [Radix UI Primitives](https://www.radix-ui.com/) - Accessible components
- [Inclusive Components](https://inclusive-components.design/)
- [A11y Project Checklist](https://www.a11yproject.com/checklist/)
---
**Version**: 1.0.0
**Last Updated**: 2026-01-16
{children}
) : null;
}
```
**Correct — Native `<dialog>` with built-in focus management:**
```tsx
function Modal({ children }) {
const dialogRef = useRef` / ``
**Incorrect — Custom accordion with ARIA:**
```tsx
`
**Incorrect — Custom accordion with ARIA:**
```tsx
{content}
```
**Correct — Native `` with CSS styling:**
```tsx
Section Title
{content}
```
```css
details summary { cursor: pointer; padding: 0.75rem; font-weight: 600; }
details[open] summary { border-bottom: 1px solid var(--border); }
details summary::marker { content: ''; } /* Note: ::marker on is supported in Chrome 89+, Firefox 68+, Safari 15.4+ */
details summary::after { content: '\25B6'; transition: transform 0.2s; }
details[open] summary::after { transform: rotate(90deg); }
```
## When Custom ARIA Is Justified
Use custom ARIA only when native elements cannot meet the requirement:
| Use case | Why native fails | ARIA approach |
|----------|-----------------|---------------|
| Combobox with async search | `<datalist>` lacks async, filtering control | `role="combobox"` + `useComboBox` |
| Tab panel widget | No native tab element | `role="tablist"` + `role="tab"` |
| Tree view | No native tree element | `role="tree"` + `role="treeitem"` |
| Menu with submenus | `<menu>` has limited support | `role="menu"` + `role="menuitem"` |
## Audit Checklist
- [ ] Every `role="dialog"` — can it be `<dialog>`?
- [ ] Every custom accordion — can it be ``?
- [ ] Every `` — should it be `<button>` or ``?
- [ ] Every custom select — does `<select>` + CSS suffice?
- [ ] ARIA attributes are only used where no native equivalent exists
### Use semantic HTML and ARIA attributes for proper screen reader document structure — CRITICAL
# Semantic HTML & ARIA (WCAG 1.3.1, 4.1.2)
## Document Structure
```tsx
Page Title
Features
- Feature 1
```
## Heading Hierarchy
Always follow h1-h6 order without skipping levels:
```tsx
// CORRECT
Page Title
Section
Subsection
// FORBIDDEN: Skipping levels
Page Title
Subsection
// Skipped h2!
```
## ARIA Labels and States
```tsx
// Icon-only button
// Form field with error
{error && {error}
}
// Custom widget with explicit role
{
if (e.key === ' ' || e.key === 'Enter') handleToggle();
}}
/>
```
## Form Structure
```tsx
```
## Live Regions
```tsx
// Polite: status updates (default, avoids interruption)
{items.length} items in cart
// Assertive: errors that need immediate announcement
{error}
```
## Page Language
```html
The French phrase Je ne sais quoi means...
```
## Skip Links
```tsx
Skip to main content
{children}
```
```css
.skip-link {
position: absolute;
top: -40px;
left: 0;
background: #000;
color: #fff;
padding: 8px;
z-index: 100;
}
.skip-link:focus {
top: 0;
}
```
## WCAG 2.2 AA Checklist
| Criterion | Requirement | Test |
|-----------|-------------|------|
| 1.1.1 Non-text | Alt text for images | axe-core scan |
| 1.3.1 Info | Semantic HTML, headings | Manual + automated |
| 1.4.3 Contrast | 4.5:1 text, 3:1 large | WebAIM checker |
| 2.1.1 Keyboard | All functionality via keyboard | Tab through |
| 2.4.3 Focus Order | Logical tab sequence | Manual test |
| 2.4.7 Focus Visible | Clear focus indicator | Visual check |
| 2.4.11 Focus Not Obscured | Focus not hidden by sticky elements | scroll-margin-top |
| 2.5.8 Target Size | Min 24x24px interactive | CSS audit |
| 4.1.2 Name/Role/Value | Proper ARIA, labels | Screen reader test |
## Anti-Patterns
- **Div soup**: Using `` where `<nav>`, `<main>`, `<article>` should be used
- **Empty links/buttons**: Interactive elements without accessible names
- **ARIA overuse**: Using ARIA when semantic HTML suffices (prefer `<button>` over ``)
- **Positive tabindex**: Using `tabIndex > 0` disrupts natural tab order
- **Decorative images without alt=""**: Must use `alt=""` or `role="presentation"`
**Incorrect — Skipping heading levels:**
```tsx
Page Title
Subsection
{/* Skipped h2 */}
// Screen readers rely on heading hierarchy
```
**Correct — Following h1-h6 order without skipping:**
```tsx
Page Title
Section
Subsection
```
### Test accessibility compliance with axe-core automation and manual screen reader verification — CRITICAL
# Accessibility Testing
## Automated Testing with axe-core
### Component-Level (jest-axe)
```tsx
import { render } from '@testing-library/react';
import { axe, toHaveNoViolations } from 'jest-axe';
expect.extend(toHaveNoViolations);
test('form has no accessibility violations', async () => {
const { container } = render(;
export function AccessibleForm() {
const [formData, setFormData] = useState({
email: '',
password: '',
agreeToTerms: false,
});
const [errors, setErrors] = useState>>({});
const [submitStatus, setSubmitStatus] = useState('');
const handleSubmit = (e: React.FormEvent) => {
e.preventDefault();
const result = FormSchema.safeParse(formData);
if (!result.success) {
const fieldErrors: Partial> = {};
result.error.issues.forEach((issue) => {
const field = issue.path[0] as keyof FormData;
fieldErrors[field] = issue.message;
});
setErrors(fieldErrors);
setSubmitStatus('Please correct the errors below');
return;
}
setErrors({});
setSubmitStatus('Form submitted successfully!');
// Submit form...
};
return (
);
}
```
**Key accessibility features:**
- All inputs have associated labels with `htmlFor`
- Required fields marked with `aria-required="true"`
- Invalid fields marked with `aria-invalid="true"`
- Error messages use `role="alert"` for immediate announcement
- Error messages linked with `aria-describedby`
- Hint text linked with `aria-describedby`
- Status message uses `role="status"` with `aria-live="polite"`
- Visible focus indicators
- AutoComplete attributes for password managers
---
## 2. Accessible Modal Dialog
Modal with focus trap, Esc to close, and backdrop click handling.
```tsx
import { useEffect, useRef } from 'react';
import { motion, AnimatePresence } from 'motion/react';
import { modalBackdrop, modalContent } from '@/lib/animations';
interface ModalProps {
isOpen: boolean;
onClose: () => void;
title: string;
children: React.ReactNode;
}
export function AccessibleModal({ isOpen, onClose, title, children }: ModalProps) {
const modalRef = useRef(null);
const triggerElementRef = useRef(null);
// Store the element that opened the modal
useEffect(() => {
if (isOpen) {
triggerElementRef.current = document.activeElement as HTMLElement;
}
}, [isOpen]);
// Focus trap and Esc key handler
useEffect(() => {
if (!isOpen) return;
const handleKeyDown = (e: KeyboardEvent) => {
if (e.key === 'Escape') {
onClose();
return;
}
if (e.key === 'Tab') {
const modal = modalRef.current;
if (!modal) return;
const focusableElements = modal.querySelectorAll(
'a[href], button:not([disabled]), textarea, input, select'
);
const firstElement = focusableElements[0];
const lastElement = focusableElements[focusableElements.length - 1];
if (e.shiftKey && document.activeElement === firstElement) {
e.preventDefault();
lastElement.focus();
} else if (!e.shiftKey && document.activeElement === lastElement) {
e.preventDefault();
firstElement.focus();
}
}
};
document.addEventListener('keydown', handleKeyDown);
return () => document.removeEventListener('keydown', handleKeyDown);
}, [isOpen, onClose]);
// Focus first element when modal opens
useEffect(() => {
if (isOpen && modalRef.current) {
const firstFocusable = modalRef.current.querySelector(
'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
);
firstFocusable?.focus();
}
}, [isOpen]);
// Return focus to trigger element when modal closes
useEffect(() => {
if (!isOpen && triggerElementRef.current) {
triggerElementRef.current.focus();
triggerElementRef.current = null;
}
}, [isOpen]);
return (
{isOpen && (
<>
{/* Backdrop */}
{/* Modal */}
{/* Title */}
{title}
{/* Content */}
{children}
{/* Close button */}
{/* Close icon button */}
)}
);
}
```
**Key accessibility features:**
- `role="dialog"` and `aria-modal="true"`
- Title linked with `aria-labelledby`
- Focus trapped within modal
- Esc key closes modal
- Focus returns to trigger element on close
- Close button has `aria-label`
- Backdrop click closes modal
- First focusable element receives focus on open
---
## 3. Skip Navigation Link
Allow keyboard users to bypass repeated navigation.
```tsx
export function SkipLink() {
return (
Skip to main content
);
}
// In your layout component:
export function Layout({ children }: { children: React.ReactNode }) {
return (
<>
{children}
);
}
```
```css
/* styles/globals.css */
.skip-link {
position: absolute;
top: -40px;
left: 0;
background: #000;
color: #fff;
padding: 8px;
text-decoration: none;
z-index: 100;
}
.skip-link:focus {
top: 0;
}
```
---
## 4. Accessible Tab Component
Tabs with keyboard navigation (arrow keys, Home, End).
```tsx
import { useState, useRef, useEffect } from 'react';
interface TabProps {
tabs: { id: string; label: string; content: React.ReactNode }[];
}
export function AccessibleTabs({ tabs }: TabProps) {
const [activeTab, setActiveTab] = useState(0);
const tabListRef = useRef(null);
const handleKeyDown = (e: React.KeyboardEvent, index: number) => {
let newIndex = index;
switch (e.key) {
case 'ArrowRight':
e.preventDefault();
newIndex = (index + 1) % tabs.length;
break;
case 'ArrowLeft':
e.preventDefault();
newIndex = (index - 1 + tabs.length) % tabs.length;
break;
case 'Home':
e.preventDefault();
newIndex = 0;
break;
case 'End':
e.preventDefault();
newIndex = tabs.length - 1;
break;
default:
return;
}
setActiveTab(newIndex);
// Focus the new tab
const newTab = tabListRef.current?.children[newIndex] as HTMLElement;
newTab?.focus();
};
return (
{/* Tab list */}
{tabs.map((tab, index) => (
))}
{/* Tab panels */}
{tabs.map((tab, index) => (
{tab.content}
))}
);
}
```
**Key accessibility features:**
- `role="tablist"`, `role="tab"`, `role="tabpanel"`
- `aria-selected` indicates active tab
- `aria-controls` links tab to panel
- Only active tab is focusable (`tabIndex=\{0\}`)
- Arrow keys navigate between tabs
- Home/End keys jump to first/last tab
- Panels hidden with `hidden` attribute (not CSS display:none)
---
## 5. Focus Management in Complex Widgets
Custom dropdown with roving tabindex.
```tsx
import { useState, useRef, useEffect } from 'react';
interface DropdownProps {
label: string;
options: string[];
value: string;
onChange: (value: string) => void;
}
export function AccessibleDropdown({ label, options, value, onChange }: DropdownProps) {
const [isOpen, setIsOpen] = useState(false);
const [focusedIndex, setFocusedIndex] = useState(0);
const buttonRef = useRef(null);
const listRef = useRef(null);
const handleKeyDown = (e: React.KeyboardEvent) => {
switch (e.key) {
case 'ArrowDown':
e.preventDefault();
if (!isOpen) {
setIsOpen(true);
} else {
setFocusedIndex((prev) => (prev + 1) % options.length);
}
break;
case 'ArrowUp':
e.preventDefault();
if (!isOpen) {
setIsOpen(true);
} else {
setFocusedIndex((prev) => (prev - 1 + options.length) % options.length);
}
break;
case 'Enter':
case ' ':
e.preventDefault();
if (isOpen) {
onChange(options[focusedIndex]);
setIsOpen(false);
buttonRef.current?.focus();
} else {
setIsOpen(true);
}
break;
case 'Escape':
e.preventDefault();
setIsOpen(false);
buttonRef.current?.focus();
break;
}
};
// Focus first option when opening
useEffect(() => {
if (isOpen) {
setFocusedIndex(options.indexOf(value));
}
}, [isOpen, value, options]);
return (
{isOpen && (
{options.map((option, index) => (
- {
onChange(option);
setIsOpen(false);
buttonRef.current?.focus();
}}
className={`px-4 py-2 cursor-pointer ${
index === focusedIndex ? 'bg-blue-100' : ''
} ${option === value ? 'bg-blue-50 font-semibold' : ''}`}
>
{option}
))}
)}
);
}
```
**Key accessibility features:**
- `role="listbox"` and `role="option"`
- `aria-haspopup="listbox"` on trigger
- `aria-expanded` indicates open/closed state
- `aria-selected` on current option
- Arrow keys navigate options
- Enter/Space selects option
- Esc closes dropdown and returns focus
- Focus returns to trigger on close
---
## 6. Live Region for Dynamic Updates
Announce changes to screen reader users without interrupting.
```tsx
import { useState, useEffect } from 'react';
export function ShoppingCart() {
const [items, setItems] = useState([]);
const [statusMessage, setStatusMessage] = useState('');
const addItem = (item: string) => {
setItems([...items, item]);
setStatusMessage(`${item} added to cart. ${items.length + 1} items total.`);
};
const removeItem = (index: number) => {
const removedItem = items[index];
setItems(items.filter((_, i) => i !== index));
setStatusMessage(`${removedItem} removed from cart. ${items.length - 1} items total.`);
};
return (
Shopping Cart
{/* Live region for status updates */}
{statusMessage}
{/* Visible cart count */}
{items.map((item, index) => (
-
{item}
))}
);
}
```
**Key accessibility features:**
- `role="status"` with `aria-live="polite"` announces changes
- `aria-atomic="true"` ensures entire message is read
- `.sr-only` class hides visual duplicate
- Remove buttons have descriptive `aria-label`
---
## 7. Accessible Error Summary
Error summary at top of form that links to fields with errors.
```tsx
interface ErrorSummaryProps {
errors: Record;
}
export function ErrorSummary({ errors }: ErrorSummaryProps) {
const errorEntries = Object.entries(errors);
if (errorEntries.length === 0) return null;
return (
There {errorEntries.length === 1 ? 'is' : 'are'} {errorEntries.length}{' '}
{errorEntries.length === 1 ? 'error' : 'errors'} in this form
{errorEntries.map(([field, message]) => (
-
{
e.preventDefault();
document.getElementById(field)?.focus();
}}
>
{message}
))}
);
}
```
**Key accessibility features:**
- `role="alert"` announces errors immediately
- Links to fields with errors
- Clicking link focuses the field
- Descriptive error count
---
## Resources
- [WCAG 2.2 Spec](https://www.w3.org/TR/WCAG22/)
- [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/)
- [Radix UI Primitives](https://www.radix-ui.com/) - Accessible components
- [Inclusive Components](https://inclusive-components.design/)
- [A11y Project Checklist](https://www.a11yproject.com/checklist/)
---
**Version**: 1.0.0
**Last Updated**: 2026-01-16
{content}
Section Title
{content}
is supported in Chrome 89+, Firefox 68+, Safari 15.4+ */
details summary::after { content: '\25B6'; transition: transform 0.2s; }
details[open] summary::after { transform: rotate(90deg); }
```
## When Custom ARIA Is Justified
Use custom ARIA only when native elements cannot meet the requirement:
| Use case | Why native fails | ARIA approach |
|----------|-----------------|---------------|
| Combobox with async search | `<datalist>` lacks async, filtering control | `role="combobox"` + `useComboBox` |
| Tab panel widget | No native tab element | `role="tablist"` + `role="tab"` |
| Tree view | No native tree element | `role="tree"` + `role="treeitem"` |
| Menu with submenus | `<menu>` has limited support | `role="menu"` + `role="menuitem"` |
## Audit Checklist
- [ ] Every `role="dialog"` — can it be `<dialog>`?
- [ ] Every custom accordion — can it be ``?
- [ ] Every `` — should it be `<button>` or ``?
- [ ] Every custom select — does `<select>` + CSS suffice?
- [ ] ARIA attributes are only used where no native equivalent exists
### Use semantic HTML and ARIA attributes for proper screen reader document structure — CRITICAL
# Semantic HTML & ARIA (WCAG 1.3.1, 4.1.2)
## Document Structure
```tsx
Page Title
Features
- Feature 1
```
## Heading Hierarchy
Always follow h1-h6 order without skipping levels:
```tsx
// CORRECT
Page Title
Section
Subsection
// FORBIDDEN: Skipping levels
Page Title
Subsection
// Skipped h2!
```
## ARIA Labels and States
```tsx
// Icon-only button
// Form field with error
{error && {error}
}
// Custom widget with explicit role
{
if (e.key === ' ' || e.key === 'Enter') handleToggle();
}}
/>
```
## Form Structure
```tsx
```
## Live Regions
```tsx
// Polite: status updates (default, avoids interruption)
{items.length} items in cart
// Assertive: errors that need immediate announcement
{error}
```
## Page Language
```html
The French phrase Je ne sais quoi means...
```
## Skip Links
```tsx
Skip to main content
{children}
```
```css
.skip-link {
position: absolute;
top: -40px;
left: 0;
background: #000;
color: #fff;
padding: 8px;
z-index: 100;
}
.skip-link:focus {
top: 0;
}
```
## WCAG 2.2 AA Checklist
| Criterion | Requirement | Test |
|-----------|-------------|------|
| 1.1.1 Non-text | Alt text for images | axe-core scan |
| 1.3.1 Info | Semantic HTML, headings | Manual + automated |
| 1.4.3 Contrast | 4.5:1 text, 3:1 large | WebAIM checker |
| 2.1.1 Keyboard | All functionality via keyboard | Tab through |
| 2.4.3 Focus Order | Logical tab sequence | Manual test |
| 2.4.7 Focus Visible | Clear focus indicator | Visual check |
| 2.4.11 Focus Not Obscured | Focus not hidden by sticky elements | scroll-margin-top |
| 2.5.8 Target Size | Min 24x24px interactive | CSS audit |
| 4.1.2 Name/Role/Value | Proper ARIA, labels | Screen reader test |
## Anti-Patterns
- **Div soup**: Using `` where `<nav>`, `<main>`, `<article>` should be used
- **Empty links/buttons**: Interactive elements without accessible names
- **ARIA overuse**: Using ARIA when semantic HTML suffices (prefer `<button>` over ``)
- **Positive tabindex**: Using `tabIndex > 0` disrupts natural tab order
- **Decorative images without alt=""**: Must use `alt=""` or `role="presentation"`
**Incorrect — Skipping heading levels:**
```tsx
Page Title
Subsection
{/* Skipped h2 */}
// Screen readers rely on heading hierarchy
```
**Correct — Following h1-h6 order without skipping:**
```tsx
Page Title
Section
Subsection
```
### Test accessibility compliance with axe-core automation and manual screen reader verification — CRITICAL
# Accessibility Testing
## Automated Testing with axe-core
### Component-Level (jest-axe)
```tsx
import { render } from '@testing-library/react';
import { axe, toHaveNoViolations } from 'jest-axe';
expect.extend(toHaveNoViolations);
test('form has no accessibility violations', async () => {
const { container } = render(;
export function AccessibleForm() {
const [formData, setFormData] = useState({
email: '',
password: '',
agreeToTerms: false,
});
const [errors, setErrors] = useState>>({});
const [submitStatus, setSubmitStatus] = useState('');
const handleSubmit = (e: React.FormEvent) => {
e.preventDefault();
const result = FormSchema.safeParse(formData);
if (!result.success) {
const fieldErrors: Partial> = {};
result.error.issues.forEach((issue) => {
const field = issue.path[0] as keyof FormData;
fieldErrors[field] = issue.message;
});
setErrors(fieldErrors);
setSubmitStatus('Please correct the errors below');
return;
}
setErrors({});
setSubmitStatus('Form submitted successfully!');
// Submit form...
};
return (
);
}
```
**Key accessibility features:**
- All inputs have associated labels with `htmlFor`
- Required fields marked with `aria-required="true"`
- Invalid fields marked with `aria-invalid="true"`
- Error messages use `role="alert"` for immediate announcement
- Error messages linked with `aria-describedby`
- Hint text linked with `aria-describedby`
- Status message uses `role="status"` with `aria-live="polite"`
- Visible focus indicators
- AutoComplete attributes for password managers
---
## 2. Accessible Modal Dialog
Modal with focus trap, Esc to close, and backdrop click handling.
```tsx
import { useEffect, useRef } from 'react';
import { motion, AnimatePresence } from 'motion/react';
import { modalBackdrop, modalContent } from '@/lib/animations';
interface ModalProps {
isOpen: boolean;
onClose: () => void;
title: string;
children: React.ReactNode;
}
export function AccessibleModal({ isOpen, onClose, title, children }: ModalProps) {
const modalRef = useRef(null);
const triggerElementRef = useRef(null);
// Store the element that opened the modal
useEffect(() => {
if (isOpen) {
triggerElementRef.current = document.activeElement as HTMLElement;
}
}, [isOpen]);
// Focus trap and Esc key handler
useEffect(() => {
if (!isOpen) return;
const handleKeyDown = (e: KeyboardEvent) => {
if (e.key === 'Escape') {
onClose();
return;
}
if (e.key === 'Tab') {
const modal = modalRef.current;
if (!modal) return;
const focusableElements = modal.querySelectorAll(
'a[href], button:not([disabled]), textarea, input, select'
);
const firstElement = focusableElements[0];
const lastElement = focusableElements[focusableElements.length - 1];
if (e.shiftKey && document.activeElement === firstElement) {
e.preventDefault();
lastElement.focus();
} else if (!e.shiftKey && document.activeElement === lastElement) {
e.preventDefault();
firstElement.focus();
}
}
};
document.addEventListener('keydown', handleKeyDown);
return () => document.removeEventListener('keydown', handleKeyDown);
}, [isOpen, onClose]);
// Focus first element when modal opens
useEffect(() => {
if (isOpen && modalRef.current) {
const firstFocusable = modalRef.current.querySelector(
'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
);
firstFocusable?.focus();
}
}, [isOpen]);
// Return focus to trigger element when modal closes
useEffect(() => {
if (!isOpen && triggerElementRef.current) {
triggerElementRef.current.focus();
triggerElementRef.current = null;
}
}, [isOpen]);
return (
{isOpen && (
<>
{/* Backdrop */}
{/* Modal */}
{/* Title */}
{title}
{/* Content */}
{children}
{/* Close button */}
{/* Close icon button */}
)}
);
}
```
**Key accessibility features:**
- `role="dialog"` and `aria-modal="true"`
- Title linked with `aria-labelledby`
- Focus trapped within modal
- Esc key closes modal
- Focus returns to trigger element on close
- Close button has `aria-label`
- Backdrop click closes modal
- First focusable element receives focus on open
---
## 3. Skip Navigation Link
Allow keyboard users to bypass repeated navigation.
```tsx
export function SkipLink() {
return (
Skip to main content
);
}
// In your layout component:
export function Layout({ children }: { children: React.ReactNode }) {
return (
<>
{children}
);
}
```
```css
/* styles/globals.css */
.skip-link {
position: absolute;
top: -40px;
left: 0;
background: #000;
color: #fff;
padding: 8px;
text-decoration: none;
z-index: 100;
}
.skip-link:focus {
top: 0;
}
```
---
## 4. Accessible Tab Component
Tabs with keyboard navigation (arrow keys, Home, End).
```tsx
import { useState, useRef, useEffect } from 'react';
interface TabProps {
tabs: { id: string; label: string; content: React.ReactNode }[];
}
export function AccessibleTabs({ tabs }: TabProps) {
const [activeTab, setActiveTab] = useState(0);
const tabListRef = useRef(null);
const handleKeyDown = (e: React.KeyboardEvent, index: number) => {
let newIndex = index;
switch (e.key) {
case 'ArrowRight':
e.preventDefault();
newIndex = (index + 1) % tabs.length;
break;
case 'ArrowLeft':
e.preventDefault();
newIndex = (index - 1 + tabs.length) % tabs.length;
break;
case 'Home':
e.preventDefault();
newIndex = 0;
break;
case 'End':
e.preventDefault();
newIndex = tabs.length - 1;
break;
default:
return;
}
setActiveTab(newIndex);
// Focus the new tab
const newTab = tabListRef.current?.children[newIndex] as HTMLElement;
newTab?.focus();
};
return (
{/* Tab list */}
{tabs.map((tab, index) => (
))}
{/* Tab panels */}
{tabs.map((tab, index) => (
{tab.content}
))}
);
}
```
**Key accessibility features:**
- `role="tablist"`, `role="tab"`, `role="tabpanel"`
- `aria-selected` indicates active tab
- `aria-controls` links tab to panel
- Only active tab is focusable (`tabIndex=\{0\}`)
- Arrow keys navigate between tabs
- Home/End keys jump to first/last tab
- Panels hidden with `hidden` attribute (not CSS display:none)
---
## 5. Focus Management in Complex Widgets
Custom dropdown with roving tabindex.
```tsx
import { useState, useRef, useEffect } from 'react';
interface DropdownProps {
label: string;
options: string[];
value: string;
onChange: (value: string) => void;
}
export function AccessibleDropdown({ label, options, value, onChange }: DropdownProps) {
const [isOpen, setIsOpen] = useState(false);
const [focusedIndex, setFocusedIndex] = useState(0);
const buttonRef = useRef(null);
const listRef = useRef(null);
const handleKeyDown = (e: React.KeyboardEvent) => {
switch (e.key) {
case 'ArrowDown':
e.preventDefault();
if (!isOpen) {
setIsOpen(true);
} else {
setFocusedIndex((prev) => (prev + 1) % options.length);
}
break;
case 'ArrowUp':
e.preventDefault();
if (!isOpen) {
setIsOpen(true);
} else {
setFocusedIndex((prev) => (prev - 1 + options.length) % options.length);
}
break;
case 'Enter':
case ' ':
e.preventDefault();
if (isOpen) {
onChange(options[focusedIndex]);
setIsOpen(false);
buttonRef.current?.focus();
} else {
setIsOpen(true);
}
break;
case 'Escape':
e.preventDefault();
setIsOpen(false);
buttonRef.current?.focus();
break;
}
};
// Focus first option when opening
useEffect(() => {
if (isOpen) {
setFocusedIndex(options.indexOf(value));
}
}, [isOpen, value, options]);
return (
{isOpen && (
{options.map((option, index) => (
- {
onChange(option);
setIsOpen(false);
buttonRef.current?.focus();
}}
className={`px-4 py-2 cursor-pointer ${
index === focusedIndex ? 'bg-blue-100' : ''
} ${option === value ? 'bg-blue-50 font-semibold' : ''}`}
>
{option}
))}
)}
);
}
```
**Key accessibility features:**
- `role="listbox"` and `role="option"`
- `aria-haspopup="listbox"` on trigger
- `aria-expanded` indicates open/closed state
- `aria-selected` on current option
- Arrow keys navigate options
- Enter/Space selects option
- Esc closes dropdown and returns focus
- Focus returns to trigger on close
---
## 6. Live Region for Dynamic Updates
Announce changes to screen reader users without interrupting.
```tsx
import { useState, useEffect } from 'react';
export function ShoppingCart() {
const [items, setItems] = useState([]);
const [statusMessage, setStatusMessage] = useState('');
const addItem = (item: string) => {
setItems([...items, item]);
setStatusMessage(`${item} added to cart. ${items.length + 1} items total.`);
};
const removeItem = (index: number) => {
const removedItem = items[index];
setItems(items.filter((_, i) => i !== index));
setStatusMessage(`${removedItem} removed from cart. ${items.length - 1} items total.`);
};
return (
Shopping Cart
{/* Live region for status updates */}
{statusMessage}
{/* Visible cart count */}
{items.map((item, index) => (
-
{item}
))}
);
}
```
**Key accessibility features:**
- `role="status"` with `aria-live="polite"` announces changes
- `aria-atomic="true"` ensures entire message is read
- `.sr-only` class hides visual duplicate
- Remove buttons have descriptive `aria-label`
---
## 7. Accessible Error Summary
Error summary at top of form that links to fields with errors.
```tsx
interface ErrorSummaryProps {
errors: Record;
}
export function ErrorSummary({ errors }: ErrorSummaryProps) {
const errorEntries = Object.entries(errors);
if (errorEntries.length === 0) return null;
return (
There {errorEntries.length === 1 ? 'is' : 'are'} {errorEntries.length}{' '}
{errorEntries.length === 1 ? 'error' : 'errors'} in this form
{errorEntries.map(([field, message]) => (
-
{
e.preventDefault();
document.getElementById(field)?.focus();
}}
>
{message}
))}
);
}
```
**Key accessibility features:**
- `role="alert"` announces errors immediately
- Links to fields with errors
- Clicking link focuses the field
- Descriptive error count
---
## Resources
- [WCAG 2.2 Spec](https://www.w3.org/TR/WCAG22/)
- [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/)
- [Radix UI Primitives](https://www.radix-ui.com/) - Accessible components
- [Inclusive Components](https://inclusive-components.design/)
- [A11y Project Checklist](https://www.a11yproject.com/checklist/)
---
**Version**: 1.0.0
**Last Updated**: 2026-01-16
` — should it be `<button>` or ``?
- [ ] Every custom select — does `<select>` + CSS suffice?
- [ ] ARIA attributes are only used where no native equivalent exists
### Use semantic HTML and ARIA attributes for proper screen reader document structure — CRITICAL
# Semantic HTML & ARIA (WCAG 1.3.1, 4.1.2)
## Document Structure
```tsx
```
## Heading Hierarchy
Always follow h1-h6 order without skipping levels:
```tsx
// CORRECT
Page Title
Features
- Feature 1
Page Title
Section
Subsection
// FORBIDDEN: Skipping levelsPage Title
Subsection
// Skipped h2! ``` ## ARIA Labels and States ```tsx // Icon-only button // Form field with error {error &&{error}
} // Custom widget with explicit role {
if (e.key === ' ' || e.key === 'Enter') handleToggle();
}}
/>
```
## Form Structure
```tsx
```
## Live Regions
```tsx
// Polite: status updates (default, avoids interruption)
{children}
```
```css
.skip-link {
position: absolute;
top: -40px;
left: 0;
background: #000;
color: #fff;
padding: 8px;
z-index: 100;
}
.skip-link:focus {
top: 0;
}
```
## WCAG 2.2 AA Checklist
| Criterion | Requirement | Test |
|-----------|-------------|------|
| 1.1.1 Non-text | Alt text for images | axe-core scan |
| 1.3.1 Info | Semantic HTML, headings | Manual + automated |
| 1.4.3 Contrast | 4.5:1 text, 3:1 large | WebAIM checker |
| 2.1.1 Keyboard | All functionality via keyboard | Tab through |
| 2.4.3 Focus Order | Logical tab sequence | Manual test |
| 2.4.7 Focus Visible | Clear focus indicator | Visual check |
| 2.4.11 Focus Not Obscured | Focus not hidden by sticky elements | scroll-margin-top |
| 2.5.8 Target Size | Min 24x24px interactive | CSS audit |
| 4.1.2 Name/Role/Value | Proper ARIA, labels | Screen reader test |
## Anti-Patterns
- **Div soup**: Using `
{items.length} items in cart
// Assertive: errors that need immediate announcement
{error}
```
## Page Language
```html
The French phrase Je ne sais quoi means...
``` ## Skip Links ```tsx Skip to main content` where `<nav>`, `<main>`, `<article>` should be used
- **Empty links/buttons**: Interactive elements without accessible names
- **ARIA overuse**: Using ARIA when semantic HTML suffices (prefer `<button>` over `
`)
- **Positive tabindex**: Using `tabIndex > 0` disrupts natural tab order
- **Decorative images without alt=""**: Must use `alt=""` or `role="presentation"`
**Incorrect — Skipping heading levels:**
```tsx
;
export function AccessibleForm() {
const [formData, setFormData] = useState({
email: '',
password: '',
agreeToTerms: false,
});
const [errors, setErrors] = useState>>({});
const [submitStatus, setSubmitStatus] = useState('');
const handleSubmit = (e: React.FormEvent) => {
e.preventDefault();
const result = FormSchema.safeParse(formData);
if (!result.success) {
const fieldErrors: Partial> = {};
result.error.issues.forEach((issue) => {
const field = issue.path[0] as keyof FormData;
fieldErrors[field] = issue.message;
});
setErrors(fieldErrors);
setSubmitStatus('Please correct the errors below');
return;
}
setErrors({});
setSubmitStatus('Form submitted successfully!');
// Submit form...
};
return (
);
}
```
**Key accessibility features:**
- All inputs have associated labels with `htmlFor`
- Required fields marked with `aria-required="true"`
- Invalid fields marked with `aria-invalid="true"`
- Error messages use `role="alert"` for immediate announcement
- Error messages linked with `aria-describedby`
- Hint text linked with `aria-describedby`
- Status message uses `role="status"` with `aria-live="polite"`
- Visible focus indicators
- AutoComplete attributes for password managers
---
## 2. Accessible Modal Dialog
Modal with focus trap, Esc to close, and backdrop click handling.
```tsx
import { useEffect, useRef } from 'react';
import { motion, AnimatePresence } from 'motion/react';
import { modalBackdrop, modalContent } from '@/lib/animations';
interface ModalProps {
isOpen: boolean;
onClose: () => void;
title: string;
children: React.ReactNode;
}
export function AccessibleModal({ isOpen, onClose, title, children }: ModalProps) {
const modalRef = useRef(null);
const triggerElementRef = useRef(null);
// Store the element that opened the modal
useEffect(() => {
if (isOpen) {
triggerElementRef.current = document.activeElement as HTMLElement;
}
}, [isOpen]);
// Focus trap and Esc key handler
useEffect(() => {
if (!isOpen) return;
const handleKeyDown = (e: KeyboardEvent) => {
if (e.key === 'Escape') {
onClose();
return;
}
if (e.key === 'Tab') {
const modal = modalRef.current;
if (!modal) return;
const focusableElements = modal.querySelectorAll(
'a[href], button:not([disabled]), textarea, input, select'
);
const firstElement = focusableElements[0];
const lastElement = focusableElements[focusableElements.length - 1];
if (e.shiftKey && document.activeElement === firstElement) {
e.preventDefault();
lastElement.focus();
} else if (!e.shiftKey && document.activeElement === lastElement) {
e.preventDefault();
firstElement.focus();
}
}
};
document.addEventListener('keydown', handleKeyDown);
return () => document.removeEventListener('keydown', handleKeyDown);
}, [isOpen, onClose]);
// Focus first element when modal opens
useEffect(() => {
if (isOpen && modalRef.current) {
const firstFocusable = modalRef.current.querySelector(
'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
);
firstFocusable?.focus();
}
}, [isOpen]);
// Return focus to trigger element when modal closes
useEffect(() => {
if (!isOpen && triggerElementRef.current) {
triggerElementRef.current.focus();
triggerElementRef.current = null;
}
}, [isOpen]);
return (
{isOpen && (
<>
{/* Backdrop */}
{/* Modal */}
{/* Title */}
{/* Close icon button */}
)}
);
}
```
**Key accessibility features:**
- `role="dialog"` and `aria-modal="true"`
- Title linked with `aria-labelledby`
- Focus trapped within modal
- Esc key closes modal
- Focus returns to trigger element on close
- Close button has `aria-label`
- Backdrop click closes modal
- First focusable element receives focus on open
---
## 3. Skip Navigation Link
Allow keyboard users to bypass repeated navigation.
```tsx
export function SkipLink() {
return (
Skip to main content
);
}
// In your layout component:
export function Layout({ children }: { children: React.ReactNode }) {
return (
<>
{children}
);
}
```
```css
/* styles/globals.css */
.skip-link {
position: absolute;
top: -40px;
left: 0;
background: #000;
color: #fff;
padding: 8px;
text-decoration: none;
z-index: 100;
}
.skip-link:focus {
top: 0;
}
```
---
## 4. Accessible Tab Component
Tabs with keyboard navigation (arrow keys, Home, End).
```tsx
import { useState, useRef, useEffect } from 'react';
interface TabProps {
tabs: { id: string; label: string; content: React.ReactNode }[];
}
export function AccessibleTabs({ tabs }: TabProps) {
const [activeTab, setActiveTab] = useState(0);
const tabListRef = useRef(null);
const handleKeyDown = (e: React.KeyboardEvent, index: number) => {
let newIndex = index;
switch (e.key) {
case 'ArrowRight':
e.preventDefault();
newIndex = (index + 1) % tabs.length;
break;
case 'ArrowLeft':
e.preventDefault();
newIndex = (index - 1 + tabs.length) % tabs.length;
break;
case 'Home':
e.preventDefault();
newIndex = 0;
break;
case 'End':
e.preventDefault();
newIndex = tabs.length - 1;
break;
default:
return;
}
setActiveTab(newIndex);
// Focus the new tab
const newTab = tabListRef.current?.children[newIndex] as HTMLElement;
newTab?.focus();
};
return (
(null);
const listRef = useRef(null);
const handleKeyDown = (e: React.KeyboardEvent) => {
switch (e.key) {
case 'ArrowDown':
e.preventDefault();
if (!isOpen) {
setIsOpen(true);
} else {
setFocusedIndex((prev) => (prev + 1) % options.length);
}
break;
case 'ArrowUp':
e.preventDefault();
if (!isOpen) {
setIsOpen(true);
} else {
setFocusedIndex((prev) => (prev - 1 + options.length) % options.length);
}
break;
case 'Enter':
case ' ':
e.preventDefault();
if (isOpen) {
onChange(options[focusedIndex]);
setIsOpen(false);
buttonRef.current?.focus();
} else {
setIsOpen(true);
}
break;
case 'Escape':
e.preventDefault();
setIsOpen(false);
buttonRef.current?.focus();
break;
}
};
// Focus first option when opening
useEffect(() => {
if (isOpen) {
setFocusedIndex(options.indexOf(value));
}
}, [isOpen, value, options]);
return (
([]);
const [statusMessage, setStatusMessage] = useState('');
const addItem = (item: string) => {
setItems([...items, item]);
setStatusMessage(`${item} added to cart. ${items.length + 1} items total.`);
};
const removeItem = (index: number) => {
const removedItem = items[index];
setItems(items.filter((_, i) => i !== index));
setStatusMessage(`${removedItem} removed from cart. ${items.length - 1} items total.`);
};
return (
);
}
```
**Key accessibility features:**
- `role="status"` with `aria-live="polite"` announces changes
- `aria-atomic="true"` ensures entire message is read
- `.sr-only` class hides visual duplicate
- Remove buttons have descriptive `aria-label`
---
## 7. Accessible Error Summary
Error summary at top of form that links to fields with errors.
```tsx
interface ErrorSummaryProps {
errors: Record;
}
export function ErrorSummary({ errors }: ErrorSummaryProps) {
const errorEntries = Object.entries(errors);
if (errorEntries.length === 0) return null;
return (
);
}
```
**Key accessibility features:**
- `role="alert"` announces errors immediately
- Links to fields with errors
- Clicking link focuses the field
- Descriptive error count
---
## Resources
- [WCAG 2.2 Spec](https://www.w3.org/TR/WCAG22/)
- [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/)
- [Radix UI Primitives](https://www.radix-ui.com/) - Accessible components
- [Inclusive Components](https://inclusive-components.design/)
- [A11y Project Checklist](https://www.a11yproject.com/checklist/)
---
**Version**: 1.0.0
**Last Updated**: 2026-01-16
Page Title
Subsection
{/* Skipped h2 */} // Screen readers rely on heading hierarchy ``` **Correct — Following h1-h6 order without skipping:** ```tsxPage Title
Section
Subsection
``` ### Test accessibility compliance with axe-core automation and manual screen reader verification — CRITICAL # Accessibility Testing ## Automated Testing with axe-core ### Component-Level (jest-axe) ```tsx import { render } from '@testing-library/react'; import { axe, toHaveNoViolations } from 'jest-axe'; expect.extend(toHaveNoViolations); test('form has no accessibility violations', async () => { const { container } = render({title}
{/* Content */}{children}
{/* Close button */}
{/* Tab list */}
);
}
```
**Key accessibility features:**
- `role="tablist"`, `role="tab"`, `role="tabpanel"`
- `aria-selected` indicates active tab
- `aria-controls` links tab to panel
- Only active tab is focusable (`tabIndex=\{0\}`)
- Arrow keys navigate between tabs
- Home/End keys jump to first/last tab
- Panels hidden with `hidden` attribute (not CSS display:none)
---
## 5. Focus Management in Complex Widgets
Custom dropdown with roving tabindex.
```tsx
import { useState, useRef, useEffect } from 'react';
interface DropdownProps {
label: string;
options: string[];
value: string;
onChange: (value: string) => void;
}
export function AccessibleDropdown({ label, options, value, onChange }: DropdownProps) {
const [isOpen, setIsOpen] = useState(false);
const [focusedIndex, setFocusedIndex] = useState(0);
const buttonRef = useRef
{tabs.map((tab, index) => (
))}
{/* Tab panels */}
{tabs.map((tab, index) => (
{tab.content}
))}
{isOpen && (
);
}
```
**Key accessibility features:**
- `role="listbox"` and `role="option"`
- `aria-haspopup="listbox"` on trigger
- `aria-expanded` indicates open/closed state
- `aria-selected` on current option
- Arrow keys navigate options
- Enter/Space selects option
- Esc closes dropdown and returns focus
- Focus returns to trigger on close
---
## 6. Live Region for Dynamic Updates
Announce changes to screen reader users without interrupting.
```tsx
import { useState, useEffect } from 'react';
export function ShoppingCart() {
const [items, setItems] = useState-
{options.map((option, index) => (
- { onChange(option); setIsOpen(false); buttonRef.current?.focus(); }} className={`px-4 py-2 cursor-pointer ${ index === focusedIndex ? 'bg-blue-100' : '' } ${option === value ? 'bg-blue-50 font-semibold' : ''}`} > {option} ))}
Shopping Cart
{/* Live region for status updates */}
{statusMessage}
{/* Visible cart count */}
-
{items.map((item, index) => (
- {item} ))}
There {errorEntries.length === 1 ? 'is' : 'are'} {errorEntries.length}{' '} {errorEntries.length === 1 ? 'error' : 'errors'} in this form
-
{errorEntries.map(([field, message]) => (
- { e.preventDefault(); document.getElementById(field)?.focus(); }} > {message} ))}