accessibility-standards

name	accessibility-standards
description	WCAG 2.2 Level AA accessibility patterns for React/HTML/CSS. Use when creating or modifying UI components, forms, navigation, tables, images, or any user-facing elements. Covers keyboard navigation, screen reader semantics, low vision contrast, voice access, inclusive language.

Accessibility Standards

Code must conform to WCAG 2.2 Level AA.

Workflow: Plan accessible implementation → generate → review against WCAG 2.2 → iterate. Suggest Accessibility Insights for testing.

Language: People-first ("person using a screen reader," not "blind user"). No ability stereotypes. Flag uncertain implementations with reasoning.

Cognitive

Plain language; consistent landmarks, nav order across pages; minimal distractions.

Keyboard

• All interactive elements keyboard-navigable with visible focus in reading order.
• No tabindex on static elements; tabindex="-1" only for elements receiving programmatic focus.
• Hidden elements must not be focusable.

Composite components + detailed complex patterns moved to REFERENCE.md to keep this skill focused. See REFERENCE.md for roving tabindex, aria-activedescendant, composite widget examples.

Validation checkpoints (run-fix-repeat)

• Run automated audit: npx axe-core or integrate axe-core/axe-playwright in CI — fix high/critical findings.
• Verify keyboard tab order manually: Tab through page, ensure logical order, visible focus.
• Confirm contrast ratios (spot-check key pages): use axe, pa11y, or contrast tools; ensure ≥4.5:1 for body text.
• Fix; re-run audits; repeat until no high/critical a11y issues remain.

Skip link (first focusable element):

<a href="#maincontent" class="sr-only">Skip to main</a>
<main id="maincontent"></main>

.sr-only:not(:focus):not(:active) { clip: rect(0 0 0 0); clip-path: inset(50%); height: 1px; overflow: hidden; position: absolute; white-space: nowrap; width: 1px; }

Key	Action
Tab	Next interactive element
Arrow	Navigate within composite component
Enter	Activate focused control
Escape	Close dialogs/menus

Low Vision

Rule	Requirement
Text contrast	≥4.5:1 (≥3:1 for large text: 18.5px bold / 24px)
Graphics/controls	≥3:1 with adjacent colors
State indicators (pressed, focus, checked)	≥3:1
Color	Never the sole conveyor of information

Screen Reader

• Correct semantics (name, role, value, states). Prefer native HTML; ARIA only when necessary.
• Landmarks: <header>, <nav>, <main>, <footer>.
• One <h1> per page; <h1>–<h6> introduce sections; no skipping levels.

Voice Access

• Interactive element accessible name must contain its visible label text.
• aria-label must include visible label.

Forms

• Labels accurately describe control purpose.
• Required fields: asterisk in label + aria-required="true".
• Errors: aria-invalid="true" + aria-describedby pointing to error message.
• Don't disable submit — show errors instead; focus first invalid field on submit.

Images

Type	Pattern
Informative	alt="[meaning]" on <img>; role="img" + aria-label on <svg> / icon fonts
Decorative	alt="" on <img>; aria-hidden="true" on role="img"

Input Labels

• <label for="id"> for form inputs; all interactive elements need visible labels.
• Disambiguate repeated labels (e.g., "Remove") with aria-label.
• Help text via aria-describedby.

Navigation

<nav><ul>
  <li><button aria-expanded="false" tabindex="0">Section 1</button>
    <ul hidden><li><a href="..." tabindex="-1">Link 1</a></li></ul>
  </li>
</ul></nav>

• Use <nav> + <ul>, NOT menu/menubar roles.
• Toggle aria-expanded on expand/collapse; Escape closes menus.
• Roving tabindex across main items; arrow down into sub-menus.

Page Title

• <title> describes page purpose, unique per page.
• Front-load unique info: "[Page] - [Section] - [Site]".

Tables & Grids

• Column headers: <th> in first <tr>; row headers: <th> in each row.
• role="gridcell" nested within role="row".
• <table> for static data; role="grid" for interactive (date pickers, calendars).