accessibility

Accessibility (a11y)

Principles (WCAG 2.1)

• Perceivable - Present information in ways users can perceive
• Operable - UI must be operable by all (keyboard, no traps)
• Understandable - Information and operation must be understandable
• Robust - Content must work with assistive technologies

Semantic HTML

• Use <button> for actions, <a href> for navigation — not <div onClick>
• Use <nav>, <main>, <article>, <section>, <aside>, <footer> for structure
• Headings: one <h1> per page; do not skip levels (h1 → h4)

// GOOD
<button onClick={handleClick}>Click me</button>
<nav aria-label="Main"><ul><li><a href="/home">Home</a></li></ul></nav>

// BAD
<div onClick={handleClick}>Click me</div>

ARIA Essentials

• Landmarks: role="navigation", aria-label="Main navigation" on nav; role="main" on main content
• Icon buttons: aria-label="Close" (no visible text) or aria-label="Delete user" with icon + aria-hidden="true" on icon
• States: aria-pressed, aria-expanded, aria-controls="id", aria-invalid={!!error}
• Live regions: role="status" aria-live="polite" for updates; role="alert" aria-live="assertive" for errors
• Decorative images: alt="" or role="presentation"

Focus and Keyboard

• Dialogs: Focus first focusable element on open; restore focus on close; handle Escape to close
• Focus trap: In modals, Tab cycles within modal only (custom hook or library)
• Skip link: <a href="#main-content" className="sr-only focus:not-sr-only ...">Skip to main content</a>; give main id="main-content" tabIndex={-1}
• Custom controls: If not <button>/<a>, add role="button", tabIndex={0}, and onKeyDown for Enter/Space

Forms

• Every input: <label htmlFor="id"> or aria-label; link with id on input
• Validation: aria-invalid={!!errors.field}, aria-describedby={errors.field ? 'error-id' : undefined}; error message in <span id="error-id" role="alert">
• Required: required + aria-required="true"; indicate in label (e.g. asterisk with aria-label="required")