React Accessibility

Build accessible React interfaces using semantic HTML, ARIA, focus management, keyboard navigation, and automated testing. Accessibility is not an add-on — it is a structural quality of the component architecture.

Semantic HTML First

Use native elements: <nav>, <main>, <button>, <header>, <section> instead of <div>. Native elements provide built-in keyboard behavior and screen reader announcements.

• Use React Fragments (<>...</>) to group elements without breaking semantic layout (lists, tables)
• Use htmlFor (not for) to associate labels with inputs
• First rule of ARIA: Use native semantic HTML instead of ARIA whenever possible

ARIA in JSX

All aria-* attributes remain hyphen-cased in JSX (unlike standard DOM props which use camelCase):

<button aria-expanded={isOpen} aria-controls="menu-panel">
  Menu
</button>

Keep ARIA states synchronized with React state — aria-expanded must reflect whether the menu is actually open.

Focus Management

React's constant DOM updates can cause focus to be lost or reset to the document body. Manage focus explicitly:

Restoring Focus

When content changes (route transitions, deleted items, view switches):

1. Apply tabIndex={-1} to the target element (makes it programmatically focusable)
2. Use useRef + useEffect to call .focus() after render

Focus Traps (Modals/Dialogs)

When a modal opens:

• Trap Tab/Shift+Tab cycling within the modal
• Make background content inert or aria-hidden="true"
• Escape key closes the dialog
• Restore focus to the trigger element on close

Skip Links

Hidden anchors that become visible on keyboard focus. Allow users to bypass repetitive navigation and jump to main content.

Keyboard Navigation

All interactive functionality must be operable with keyboard. Critical rules:

• Use natively focusable elements (<button>, <a>, <input>) — not <div onClick>
• Never remove focus outlines (outline: 0) without a visible replacement
• Use :focus-visible for keyboard-only focus styles
• Attach onFocus/onBlur alongside mouse events

Color Contrast

• Text: minimum 4.5:1 contrast ratio (WCAG AA)
• Large text (18pt regular / 14pt bold): 3:1 minimum
• Never use color alone to convey meaning — add icons or text

Screen Reader Considerations

• Informative images need descriptive alt text
• Decorative images use alt="" or role="presentation"
• Dynamic content (toasts, route changes) needs aria-live="polite" or role="alert"

Development Tools

eslint-plugin-jsx-a11y

Real-time AST linting in the editor. Flags missing alt text, incorrect ARIA roles, and inaccessible patterns during development.

react-axe (@axe-core/react)

Audits the rendered DOM at runtime. Logs violations to Chrome DevTools console, categorized by severity. Import dynamically in development only:

if (process.env.NODE_ENV !== 'production') {
  import('react-axe').then(axe => axe.default(React, ReactDOM, 1000));
}

Testing Accessibility

1. Manual keyboard test: Disconnect mouse, navigate entire app with Tab, Shift+Tab, Enter, Space, Escape
2. React Testing Library: Use getByRole and getByLabelText as primary selectors — if RTL cannot find the element, assistive technology cannot either
3. Screen readers: Test with NVDA (Firefox), JAWS (Chrome/Edge), VoiceOver (Safari)

Additional Resources

Reference Files

• `references/detailed-patterns.md` — Complete code examples for focus management, focus traps, skip links, ARIA patterns, and accessible component templates