Accessibility

Accessibility

Standard: WCAG 2.2 AA required · AAA aspirational Stack: React 19 · DSAI Design System · Bootstrap 5 · CSS Custom Properties (--dsai-* tokens) POUR Principles: Perceivable · Operable · Understandable · Robust

Implement WCAG 2.2 AA compliant accessibility in React 19 components using the draft_v0 stack. Items marked (AAA) exceed the required AA level and are aspirational best practices to pursue where feasible.

POUR Reference Map

WCAG 2.2 New Criteria — Enterprise Baseline

WCAG 2.2 added 9 success criteria not present in WCAG 2.1. All AA items are required; AAA items are aspirational.

See wcag22-new-criteria.md for detailed implementation guidance, code examples, common failures, and test procedures for each criterion.

Accessibility Utilities in This Project

DSAI Built-in Accessibility

DSAI components implement accessibility patterns directly — using SafeHTMLAttributes, ARIA props, keyboard hooks, and focus management. Components handle ARIA roles, keyboard navigation, and focus management through the DSAI hook system.

Install via: dsai add modal tabs select — components appear in src/client/components/ui/ as local source code you own and can customize.

Landmark Regions

Use native HTML5 elements — they carry implicit ARIA roles and need no role attribute.

Rules: one <main> per page · label every <nav> when multiple exist · never nest <main> inside another landmark · give <main> id="main-content" tabIndex={-1} for skip-link targeting.

See semantic-html.md for the full AppLayout implementation.

Skip Links

Skip links bypass repeated navigation — required by WCAG 2.4.1 (Level A). Place <SkipLink /> as the first element in <App />. It uses visually-hidden (shown on focus via CSS) so it appears only on keyboard Tab.

Requirements:

• First focusable element in DOM order
• Href target (#main-content) must have tabIndex={-1} to receive programmatic focus
• For multi-section pages add more: "Skip to search", "Skip to filters"

See focus-management.md for the SkipLink component and App.tsx placement.

Page Title Management

WCAG 2.4.2 (Level A): every page needs a unique, descriptive document.title that updates on route change.

• Call useDocumentTitle(pageTitle) in every route component. Format: "Page Name — Site Name".
• Add <RouteAnnouncer /> once in <App /> — announces the new title to screen readers on navigation without moving focus.

See focus-management.md for both implementations.

Keyboard Navigation

See keyboard-navigation.md for:

• Required keys by component type (button, link, menu, tabs, modal, combobox, tree, data grid, carousel, toolbar)
• useKeyPress hook
• Roving tabindex pattern
• Data grid two-dimensional navigation model (Arrow + Home/End/Ctrl+Home/Ctrl+End)
• Tree view expand/collapse key model
• Carousel Previous/Next/Pause patterns
• Pointer cancellation (WCAG 2.5.2 AA)

ARIA Attributes

See aria-attributes.md for:

• Button, input, checkbox, radio group, switch/toggle patterns
• Dialog/modal, alert, menu patterns
• Combobox (autocomplete input + listbox), data grid, tree view, carousel patterns
• Tooltip, breadcrumb, pagination, loading/spinner patterns
• Live region and status message patterns

Focus Management

See focus-management.md for:

• useFocusTrap (DSAI) — focus trapping for modals
• Return focus pattern — restore trigger element focus on close
• Focus Not Obscured (WCAG 2.4.11 AA) — scroll-margin-top fix for sticky headers
• Skip link focus target setup
• Focus management on SPA route change

Screen Reader Announcements

Live Regions in JSX

Place live region containers in your layout so they persist between renders — the container must exist in the DOM before content is injected:

// Polite — screen reader finishes current speech before announcing
<div aria-live="polite" aria-atomic="true">
  {statusMessage}
</div>

// Assertive — interrupts screen reader immediately (use sparingly)
<div role="alert" aria-live="assertive">
  {errorMessage}
</div>

// Status updates (WCAG 4.1.3 A) — equivalent to aria-live="polite" + aria-atomic
<div role="status">
  {`${resultCount} results found`}
</div>

Reusable Announcement Hook

For imperative announcements (filter applied, item saved, search complete) without moving focus, use the useAnnounce hook from @/hooks/useAnnounce.

See aria-attributes.md for the implementation.

Reduced Motion

See reduced-motion.md for:

• useReducedMotion hook
• CSS @media (prefers-reduced-motion: reduce) (preferred approach)
• Framer Motion useReducedMotion integration
• CSS @media (prefers-reduced-motion: reduce) global overrides
• WCAG 2.3.3 Animation from Interactions (AAA)

Color Contrast

Minimum Ratios (WCAG 2.2 AA)

(AAA) Enhanced contrast (SC 1.4.6): Normal text 7:1 · Large text 4.5:1

Compliant Combinations (Project Design System)

Use DSAI semantic color tokens — they map to CSS custom properties via the token pipeline:

Use WebAIM Contrast Checker or APCA Calculator to verify contrast for custom color combinations. DSAI tokens are pre-validated for AA compliance.

Non-text Contrast (WCAG 1.4.11 AA)

Input borders, button outlines, checkbox frames, focus rings, and icon-only controls must have 3:1 contrast against adjacent colors. Use DSAI tokens var(--dsai-border-color) / var(--dsai-color-primary) and verify in the contrast checker when customizing.

Visible Focus

Use CSS :focus-visible pseudo-class (keyboard only — does not appear on mouse click). DSAI provides focus styles via CSS custom properties:

:focus-visible {
  outline: 3px solid var(--dsai-color-primary);
  outline-offset: 2px;
}

Add scroll-margin-top to prevent the focused element hiding behind a sticky header (WCAG 2.4.11 AA).

• Never use :focus alone for ring styles — it triggers on mouse too
• Use DSAI token var(--dsai-color-primary) for focus ring color (consistent across themes)
• (AAA) 2.4.13 — focus indicator must encircle with ≥ 2px perimeter and ≥ 3:1 contrast between focused/unfocused states

See focus-management.md for the sticky-header fix.

Screen Reader Only Text

// Icon-only button — always provide visually-hidden label
<button aria-label="Close modal">
  <XIcon aria-hidden="true" />
</button>

// Or use visually-hidden span (Bootstrap class, either approach is valid)
<button>
  <XIcon aria-hidden="true" />
  <span className="visually-hidden">Close modal</span>
</button>

Forms & Input

See forms-a11y.md for:

• autocomplete attributes and WCAG 1.3.5 Identify Input Purpose (AA)
• Redundant Entry — WCAG 3.3.7 (A): auto-populate previously entered data in multi-step flows
• Accessible Authentication — WCAG 3.3.8 (AA) / 3.3.9 (AAA): no cognitive tests in auth flows; password manager and paste must work
• fieldset/legend for grouped inputs (radio groups, checkboxes, date parts)
• Multi-step form state management and progress communication
• Comprehensive error identification, description, and suggestion patterns

Semantic HTML

See semantic-html.md for:

• img alt text decision tree (informative vs decorative vs functional)
• Decorative images: alt="" + aria-hidden="true"
• SVG accessibility: role="img", <title>, <desc>, aria-labelledby
• Landmark regions in depth (header, nav, main, aside, footer)
• Heading hierarchy rules (h1–h6, one h1 per page, no skipping levels)
• Data tables: <caption>, scope, headers attribute for complex tables
• Ordered vs. unordered lists — when to use each

Mobile & Touch

See mobile-touch.md for:

• Target Size (AA): 24×24 CSS px minimum — WCAG 2.5.8
• Target Size (AAA): 44×44 CSS px recommended — WCAG 2.5.5
• Pointer Gestures (AA): multi-touch gesture alternatives — WCAG 2.5.1
• Pointer Cancellation (AA): activate on pointerup, not pointerdown — WCAG 2.5.2
• Orientation (AA): support portrait and landscape — WCAG 1.3.4
• Motion Actuation (AA): device-motion (shake/tilt) alternatives — WCAG 2.5.4
• Dragging Movements (AA): single-pointer alternative for all drag UIs — WCAG 2.5.7
• Content on Hover/Focus (AA): tooltips/popovers must be dismissible, hoverable, persistent — WCAG 1.4.13
• Reflow (AA): no horizontal scrolling at 320px CSS width — WCAG 1.4.10
• Text Spacing (AA): layout survives user text-spacing overrides — WCAG 1.4.12

Testing Accessibility

See testing-a11y.md for:

• Browser DevTools accessibility tree inspection (zero setup)
• Playwright + @axe-core/playwright automated audits (recommended for CI)
• Vitest + vitest-axe component-level unit tests
• Screen reader test matrix — NVDA · JAWS · VoiceOver · TalkBack · Narrator with browser pairings
• CI/CD GitHub Actions — automated axe scan on every PR
• VPAT / accessibility statement guidance for enterprise reporting
• Manual test checklist organized by POUR principle

WCAG 2.2 AA Compliance Checklist

Use this checklist for every new component or page before merge. Each item maps to a WCAG 2.2 success criterion.

Perceivable

• 1.1.1 A — Every <img> has meaningful alt; decorative images use alt="" and aria-hidden="true"
• 1.3.1 A — Semantic HTML used for structure (headings, lists, tables); data relationships programmatically defined
• 1.3.2 A — DOM reading order matches visual presentation order
• 1.3.3 A — Instructions don't rely solely on shape, color, size, or spatial position
• 1.3.4 AA — Content works in both portrait and landscape orientation
• 1.3.5 AA — User data input fields have correct autocomplete attribute values
• 1.4.1 A — Color is not the only means of conveying information, indicating an action, or distinguishing an element
• 1.4.3 AA — Text and images of text meet 4.5:1 contrast ratio (3:1 for large text)
• 1.4.4 AA — Text resizes to 200% without loss of content or functionality
• 1.4.5 AA — Images of text not used where styled text could achieve the same visual effect (except logos)
• 1.4.10 AA — Content reflows at 320px CSS width without requiring horizontal scrolling
• 1.4.11 AA — UI component boundaries (input borders, button outlines, focus indicators) meet 3:1 non-text contrast
• 1.4.12 AA — Layout and content survive user text-spacing overrides (line-height 1.5×, letter-spacing 0.12em, word-spacing 0.16em)
• 1.4.13 AA — Hover/focus-triggered popovers and tooltips are dismissible (Escape), hoverable (pointer can move over them), and persistent until explicitly dismissed

Operable

• 2.1.1 A — All functionality is operable by keyboard; no functionality requires specific timing or a path-dependent gesture
• 2.1.2 A — No keyboard trap — user can always Tab away from any focused component
• 2.4.1 A — A skip link is provided to bypass repeated navigation blocks
• 2.4.2 A — Every page/view has a unique, descriptive document.title that updates on route change
• 2.4.3 A — Focus order follows a logical sequence that matches reading order
• 2.4.4 A — Link text (or link + context) describes the link's purpose clearly
• 2.4.6 AA — Headings and labels describe their topic or purpose
• 2.4.7 AA — A visible keyboard focus indicator is present on all keyboard-operable elements
• 2.4.11 AA — When a component receives focus, it is not entirely hidden behind sticky/fixed UI (cookie banners, sticky headers, toolbars)
• 2.5.1 AA — Multi-touch gestures (pinch, swipe) have a single-pointer alternative (tap, button)
• 2.5.2 AA — Click/tap functionality activates on pointer-up, not pointer-down; or up-event abort is available
• 2.5.3 AA — The accessible name of interactive elements contains the visible label text
• 2.5.7 AA — Drag interactions have a single-pointer (click/tap) alternative mechanism
• 2.5.8 AA — Interactive targets are at least 24×24 CSS pixels (with spacing exceptions for inline text)

Understandable

• 3.1.1 A — Page language declared: <html lang="en"> (or appropriate BCP-47 language code)
• 3.2.1 A — Receiving focus does not trigger unexpected context changes (form submit, page navigation)
• 3.2.2 A — Changing an input setting does not auto-submit or change context without prior user notice
• 3.2.3 AA — Navigation components (nav bars, breadcrumbs, sidebars) are consistent across pages
• 3.2.4 AA — Components with the same function are labeled consistently across the site
• 3.2.6 A — Help mechanisms (contact link, chat, FAQ) appear in the same relative position across pages
• 3.3.1 A — Errors are automatically detected, the erroneous item identified, and the error described in text
• 3.3.2 A — Labels or instructions are provided for all form inputs before or alongside them
• 3.3.3 AA — Error correction suggestions are provided when an input error is detected and suggestions are known
• 3.3.4 AA — Legal, financial, or data-destructive submissions are reversible, checkable, or confirmable
• 3.3.7 A — Previously entered information is auto-populated or selectable in the same process/session
• 3.3.8 AA — Authentication does not require solving a puzzle, transcribing characters, or memorization unless a supported alternative or assistance mechanism exists (paste and password managers must work)

Robust

• 4.1.2 A — Every UI component has a programmatically determinable name, role, and value; states and properties are settable; changes are notified to assistive technologies
• 4.1.3 A — Status messages (save confirmations, error counts, progress updates, loading complete) are conveyed to screen readers via live regions or role="status" without moving focus

AAA Aspirational

These exceed the required AA level. Implement where feasible to provide a superior experience.

Platform Notes

See skill-creator/reference/platform-specific.md for the full platform compatibility guide.

Resources