Accessibility (a11y)

Ensures WCAG 2.1/2.2 Level AA compliance: semantic structure, ARIA, contrast, keyboard nav.

When to Use

Building UI components with interactive elements
Implementing forms, modals, or custom widgets
Adding dynamic content or live regions
Ensuring keyboard navigation or reviewing accessibility compliance

Don't use for:

Tech-specific implementation (react, html skills)
Backend logic (no UI)

Critical Patterns

✅ REQUIRED: Document Language — SC 3.1.1 · Level A

<!-- SC 3.1.1 Level A — required for screen reader pronunciation -->
<html lang="en">
<html lang="es-MX">

Rule: Always set lang on <html>. Missing lang causes screen readers to mispronounce all content.

✅ REQUIRED: Semantic HTML Elements — SC 1.3.1 · Level A

<!-- ✅ CORRECT: Nav with list structure (SC 1.3.1) -->
<nav aria-label="Primary navigation">
  <ul>
    <li><a href="/home">Home</a></li>
    <li><a href="/about">About</a></li>
  </ul>
</nav>
<main>
  <article>Content</article>
</main>
<button onClick="{action}">Submit</button>

<!-- ❌ WRONG: Non-semantic divs -->
<div class="nav">
  <div onClick="{navigate}">Home</div>
</div>

✅ REQUIRED: Keyboard Accessibility — SC 2.1.1 · Level A

// ✅ CORRECT: Keyboard events
<button onClick={handleClick} onKeyDown={(e) => e.key === 'Enter' && handleClick()}>

// ❌ WRONG: Mouse-only events
<div onClick={handleClick}> // Not keyboard accessible

✅ REQUIRED: Form Labels — SC 1.3.1, SC 3.3.2 · Level A

<!-- ✅ CORRECT: Associated label -->
<label htmlFor="email">Email Address</label>
<input id="email" type="email" />

<!-- ❌ WRONG: No label association -->
<div>Email Address</div>
<input type="email" />

✅ REQUIRED: Alt Text for Images — SC 1.1.1 · Level A

<!-- ✅ Informative image -->
<img src="chart.png" alt="Sales increased 25% in Q4" />

<!-- ✅ Decorative image -->
<img src="border.png" alt="" />

<!-- ❌ WRONG: Missing alt -->
<img src="chart.png" />

✅ REQUIRED: SVG Accessibility — SC 1.1.1 · Level A

SVG loaded as <img> respects alt. SVG inline or via SVGR (React) does not — use role and aria-label directly.

<!-- Informative SVG -->
<svg role="img" aria-label="Company logo" focusable="false">
  <title>Company logo</title>
</svg>

<!-- Decorative SVG -->
<svg aria-hidden="true" focusable="false">...</svg>

// ❌ WRONG: alt is ignored by SVGR
<Logo alt="Company logo" />

// ✅ CORRECT: use role + aria-label on SVGR component
<Logo role="img" aria-label="Company logo" focusable="false" />

✅ REQUIRED: Disclosure Pattern (Accordion / Expandable) — SC 4.1.2 · Level A

// ✅ CORRECT
<button aria-expanded={isOpen} aria-controls="panel-id">
  Details  {/* Accessible name must NOT change with state */}
</button>
<div id="panel-id" hidden={!isOpen}>Panel content</div>

Rules: aria-controls must match the panel id. Do not change the button's accessible name based on open/closed state.

✅ REQUIRED: Form Validation Errors — SC 3.3.1 Level A · SC 3.3.3 Level AA

<!-- ✅ Error linked to field; announced via role="alert" -->
<label for="email">Email <span aria-hidden="true">*</span></label>
<input id="email" type="email" aria-required="true" aria-invalid="true"
       aria-describedby="email-error" />
<span id="email-error" role="alert">
  Enter a valid email address (e.g. user@example.com)
</span>

<!-- Error summary on multi-field submit — move focus here -->
<div role="alert" tabindex="-1" id="error-summary">
  <h2>3 errors prevented submission:</h2>
  <ul><li><a href="#email">Email: Enter a valid address</a></li></ul>
</div>

Rules: aria-invalid="true" on the input (not the error span). On submit with errors, move focus to error summary (element.focus(), needs tabindex="-1").

✅ REQUIRED: Dynamic Page / SPA Navigation — SC 2.4.2/2.4.3 Level A · SC 4.1.3 Level AA

// On every route change — framework-agnostic:
document.title = `${pageTitle} | My App`;  // 1. Update title
announcer.textContent = '';                // 2. Clear announcer
announcer.textContent = pageTitle;         // 3. Re-set triggers announcement
document.querySelector('main')?.focus();   // 4. Move focus to main

<!-- Persistent live region — render once in app root -->
<div aria-live="polite" aria-atomic="true" class="sr-only" id="route-announcer"></div>
<main id="main-content" tabindex="-1">...</main>

Rules: <main> needs tabindex="-1" to be programmatically focusable. Do NOT move focus to <body>.

Conventions

Framework-Native First

Before implementing accessibility patterns manually, check if your framework or UI library already provides them. Most production stacks (Tailwind, MUI, Radix UI, React Aria, Headless UI) ship accessible primitives that handle ARIA, focus, and keyboard contracts automatically. Use them — avoid duplicating CSS or markup that diverges from the design system.

Semantic HTML

Semantic elements (<nav>, <main>, <article>, <aside>, <footer>)
Heading hierarchy (h1 → h2 → h3, no skipping)
<button> for actions, <a> for navigation; labels associated with inputs

ARIA

Only when semantic HTML insufficient; prefer native elements
Common: aria-label, aria-labelledby, aria-describedby
Dynamic content: aria-live, aria-atomic
Active navigation: aria-current="page" on current link, aria-current="step" in wizards

Keyboard Navigation

All interactive elements keyboard accessible; logical tab order
Visible focus indicators; Escape closes modals/dropdowns

Color and Contrast

Text 4.5:1 min (7:1 AAA), large text 3:1 min; UI components 3:1; focus indicators 3:1 (WCAG 2.2)
Don't rely on color alone

Touch Targets

24×24px min (WCAG 2.2), 44×44px recommended; adequate spacing between targets

Decision Tree

Interactive element (button, link)?
  → Ensure keyboard accessible (Tab, Enter/Space)
  → Visible focus indicator, proper role and semantic element

Form field?
  → Associate <label> with input (htmlFor/id)
  → Mark required: aria-required="true" (or native required)
  → Field error: aria-invalid="true" + aria-describedby → error span + role="alert"
  → Submit errors: move focus to error summary (tabindex="-1") + role="alert"

SPA / route change?
  → Update document.title to reflect new page (SC 2.4.2)
  → Announce new page via persistent aria-live="polite" region
  → Move focus to <main tabindex="-1"> or <h1 tabindex="-1"> (not <body>)

Dynamic content change?
  → Non-urgent: aria-live="polite"
  → Critical alerts: aria-live="assertive"
  → Whole region: aria-atomic="true"

Custom widget (dropdown, modal, tabs)?
  → Follow WAI-ARIA Authoring Practices patterns
  → Implement keyboard navigation (Arrow keys, Escape, Enter)
  → See references/wai-aria-patterns.md for full widget patterns

Image?
  → <img>: decorative → alt="", informative → descriptive alt text
  → Inline SVG / SVGR: decorative → aria-hidden="true", informative → role="img" aria-label="..."

Color conveys meaning?
  → Add text label, icon, or pattern; verify 4.5:1 for text, 3:1 for UI

Modal or overlay?
  → Trap focus inside modal, restore focus on close
  → Allow Escape to dismiss; use aria-modal="true" and role="dialog"

Example

Accessible modal dialog: focus trap, ARIA labels, and keyboard navigation applied together.

function ConfirmDeleteModal({ isOpen, onClose, onConfirm }: ModalProps) {
  const firstFocusRef = useRef<HTMLButtonElement>(null);

  useEffect(() => {
    if (isOpen) firstFocusRef.current?.focus();
  }, [isOpen]);

  if (!isOpen) return null;
  return (
    <div role="dialog" aria-modal="true" aria-labelledby="modal-title"
         onKeyDown={(e) => e.key === 'Escape' && onClose()}>
      <h2 id="modal-title">Delete this item?</h2>
      <p id="modal-desc">This action cannot be undone.</p>
      <button ref={firstFocusRef} aria-describedby="modal-desc"
              onClick={onConfirm}>Confirm Delete</button>
      <button onClick={onClose}>Cancel</button>
    </div>
  );
}

Patterns applied: role="dialog", aria-modal, aria-labelledby, aria-describedby, focus on open, Escape to dismiss.

Edge Cases

WCAG 2.2 updates: 24×24px min target size; focus indicators 3:1 contrast; provide pointer alternatives for drag; CAPTCHAs need alternatives (no cognitive function tests).

Skip links: First focusable element, visually hidden, revealed on focus.

<a href="#main-content" class="skip-link">Skip to main content</a>
<main id="main-content">...</main>

Apply .skip-link:focus { position: fixed; top: 0; clip: auto; padding: 0.5rem 1rem; } to reveal visually.

sr-only pattern: Visually hidden but screen-reader accessible. Use for icon-button labels and status announcements. Standard CSS: position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0,0,0,0); white-space: nowrap; border: 0;

ARIA live regions throttling: Rapid updates may be throttled. Debounce or use aria-atomic="true".

Focus trap issues: Libraries like React may interfere with focus management. Test focus trap explicitly in modals.

Custom controls: For complex widgets (datepickers, sliders, menus, tabs), follow WAI-ARIA Authoring Practices. See references/wai-aria-patterns.md.

Resources

WCAG 2.1 Quick Reference
WAI-ARIA Authoring Practices Guide
WAI-ARIA Widget Patterns
Review & Compliance Checklist (optional — for code reviews, remediation, and accessibility audits)

a11y

Safety Notice

Copy this and send it to your AI assistant to learn