Accessibility

Comprehensive patterns for building accessible web applications: WCAG 2.2 AA compliance, keyboard focus management, and React Aria component patterns. Each category has individual rule files in rules/ loaded on-demand.

Quick Reference

Category	Rules	Impact	When to Use
WCAG Compliance	3	CRITICAL	Color contrast, semantic HTML, automated testing
Focus Management	3	HIGH	Focus traps, focus restoration, keyboard navigation
React Aria	3	HIGH	Accessible components, form hooks, overlay patterns

Total: 9 rules across 3 categories

Quick Start

// Semantic HTML with ARIA
<main>
  <article>
    <header><h1>Page Title</h1></header>
    <section aria-labelledby="features-heading">
      <h2 id="features-heading">Features</h2>
    </section>
  </article>
</main>

// Focus trap with React Aria
import { FocusScope } from 'react-aria';

<FocusScope contain restoreFocus autoFocus>
  <div role="dialog" aria-modal="true">
    {children}
  </div>
</FocusScope>

WCAG Compliance

WCAG 2.2 AA implementation for inclusive, legally compliant web applications.

Rule	File	Key Pattern
Color Contrast	rules/wcag-color-contrast.md	4.5:1 text, 3:1 UI components, focus indicators
Semantic HTML	rules/wcag-semantic-html.md	Landmarks, headings, ARIA labels, form structure
Testing	rules/wcag-testing.md	axe-core, Playwright a11y, screen reader testing

Focus Management

Keyboard focus management patterns for accessible interactive widgets.

Rule	File	Key Pattern
Focus Trap	rules/focus-trap.md	Modal focus trapping, FocusScope, Escape key
Focus Restoration	rules/focus-restoration.md	Return focus to trigger, focus first error
Keyboard Navigation	rules/focus-keyboard-nav.md	Roving tabindex, skip links, arrow keys

React Aria

Adobe React Aria hooks for building WCAG-compliant interactive UI.

Rule	File	Key Pattern
Components	rules/aria-components.md	useButton, useDialog, useMenu, FocusScope
Forms	rules/aria-forms.md	useComboBox, useTextField, useListBox
Overlays	rules/aria-overlays.md	useModalOverlay, useTooltip, usePopover

Key Decisions

Decision	Recommendation
Conformance level	WCAG 2.2 AA (legal standard: ADA, Section 508)
Contrast ratio	4.5:1 normal text, 3:1 large text and UI components
Target size	24px min (WCAG 2.5.8), 44px for touch
Focus indicator	3px solid outline, 3:1 contrast
Component library	React Aria hooks for control, react-aria-components for speed
State management	react-stately hooks (designed for a11y)
Focus management	FocusScope for modals, roving tabindex for widgets
Testing	jest-axe (unit) + Playwright axe-core (E2E)

Anti-Patterns (FORBIDDEN)

• Div soup: Using <div> instead of semantic elements (<nav>, <main>, <article>)
• Color-only information: Status indicated only by color without icon/text
• Missing labels: Form inputs without associated <label> or aria-label
• Keyboard traps: Focus that cannot escape without Escape key
• Removing focus outline: outline: none without replacement indicator
• Positive tabindex: Using tabindex > 0 (disrupts natural order)
• Div with onClick: Using <div onClick> instead of <button> or useButton
• Manual focus in modals: Using useEffect + ref.focus() instead of FocusScope
• Auto-playing media: Audio/video that plays without user action
• ARIA overuse: Using ARIA when semantic HTML suffices

Detailed Documentation

Resource	Description
scripts/	Templates: accessible form, focus trap, React Aria components
checklists/	WCAG audit, focus management, React Aria component checklists
references/	WCAG criteria reference, focus patterns, React Aria hooks API
examples/	Complete accessible component examples

Related Skills

• ork:testing-patterns - Comprehensive testing patterns including accessibility testing
• design-system-starter - Accessible component library patterns
• ork:i18n-date-patterns - RTL layout and locale-aware formatting
• motion-animation-patterns - Reduced motion and animation accessibility