accessibility

# Accessibility Comprehensive patterns for building accessible web applications: WCAG 2.2 AA compliance, keyboard focus management, React Aria component patterns, native HTML-first philosophy, cognitive inclusion, and user preference honoring. Each category has individual rule files in `rules/` loaded on-demand. ## Quick Reference | Category | Rules | Impact | When to Use | |----------|-------|--------|-------------| | [WCAG Compliance](#wcag-compliance) | 3 | CRITICAL | Color contrast, semantic HTML, automated testing | | [POUR Exit Criteria](#pour-exit-criteria) | 1 | CRITICAL | Falsifiable pass/fail thresholds for each WCAG 2.2 AA criterion | | [Static Anti-Patterns](#static-anti-patterns) | 1 | HIGH | Grep-able patterns detectable without a browser | | [Focus Management](#focus-management) | 1 | HIGH | Keyboard navigation; trap/restoration mechanics live upstream | | [React Aria](#react-aria) | 2 | HIGH | Accessible components and form hooks; overlay APIs live upstream | | [Modern Web Accessibility](#modern-web-accessibility) | 2 | CRITICAL/HIGH | Native HTML first, user preferences; cognitive ceilings in `references/ork-delta.md` | **Total: 10 rules across 6 categories** ## Quick Start ```tsx // 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> ``` ```tsx // 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 | ## POUR Exit Criteria Concrete pass/fail thresholds for each WCAG 2.2 AA criterion — replaces vague "meets requirements" checks. | Rule | File | Key Pattern | |------|------|-------------| | POUR Exit Criteria | `rules/pour-exit-criteria.md` | Falsifiable checklist: image alt, contrast ratios, focus indicators, touch targets, ARIA states | ## Static Anti-Patterns Grep-able anti-patterns detectable via static analysis or code review — no browser needed. | Rule | File | Key Pattern | |------|------|-------------| | A11y Anti-Patterns (Static) | `rules/a11y-antipatterns-static.md` | Focus removal, missing labels, autoplay, icon-only buttons, div-click handlers | ## Focus Management Keyboard focus management patterns for accessible interactive widgets. | Rule | File | Key Pattern | |------|------|-------------| | Keyboard Navigation | `rules/focus-keyboard-nav.md` | Roving tabindex, skip links, arrow keys | Focus trap and restoration mechanics are upstream's job: use React Aria `<FocusScope contain restoreFocus autoFocus>` (see [Upstream coverage](#upstream-coverage-do-not-restate)). When React Aria is unavailable, copy `scripts/focus-trap-template.tsx`; the house rules for both live in `references/ork-delta.md`. ## 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 | Overlay hook APIs (useModalOverlay, useTooltip, usePopover) are documented upstream (see [Upstream coverage](#upstream-coverage-do-not-restate)); the house overlay recipe (FocusScope plus shared motion presets) is in `references/ork-delta.md`. ## Modern Web Accessibility 2026 best practices: native HTML first, cognitive inclusion, and honoring user preferences. | Rule | File | Key Pattern | |------|------|-------------| | Native HTML First | `rules/wcag-native-html-first.md` | `<dialog>`, `<details>`, native over custom ARIA | | User Preferences | `rules/wcag-user-preferences.md` | prefers-reduced-motion, forced-colors, prefers-contrast, zoom | Cognitive inclusion (ADHD/autism/dyslexia support) is covered upstream by W3C COGA (see [Upstream coverage](#upstream-coverage-do-not-restate)); the house cognitive-load ceilings (notification cap, nav-item cap, reading-level targets) are in `references/ork-delta.md`. ## 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 ## Upstream coverage (do not restate) Vendor tutorials, API references, and criterion walkthroughs removed in the 2026-07-31 wrap-plus-delta thinning. Consult the first-party source; only the ork delta (floors, scars, house decisions) lives in `references/ork-delta.md`. | Topic | First-party source | |-------|--------------------| | WCAG 2.2 success-criterion walkthroughs and audit checklists | [WCAG 2.2 quick reference](https://www.w3.org/WAI/WCAG22/quickref/) and [WCAG 2.2 spec](https://www.w3.org/TR/WCAG22/) | | ARIA widget patterns and keyboard interaction models | [WAI-ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/) | | React Aria hook APIs (useButton, useMenu, useComboBox, useModalOverlay, useTooltip, usePopover), component checklists, worked examples | [React Aria docs](https://react-spectrum.adobe.com/react-aria/) | | Focus trap, focus restoration, roving tabindex, and skip-link algorithms | [React Aria FocusScope](https://react-spectrum.adobe.com/react-aria/FocusScope.html) and [APG patterns](https://www.w3.org/WAI/ARIA/apg/patterns/) | | Cognitive accessibility guidance (COGA) | [W3C Making Content Usable](https://www.w3.org/TR/coga-usable/) | | Screen reader testing walkthroughs (NVDA, JAWS, VoiceOver, TalkBack) | [WebAIM screen reader testing](https://webaim.org/articles/screenreader_testing/) | ## Detailed Documentation | Resource | Description | |----------|-------------| | `scripts/` | Templates: accessible form, focus trap, React Aria components | | `references/ork-delta.md` | Ork-specific floors, scars, and house decisions (cognitive ceilings, overlay recipe, canonical focus-trap selector) | | `references/ux-thresholds-quick.md` | UI/UX thresholds quick reference: contrast, touch targets, cognitive load, typography, forms | | `examples/wcag-examples.md` | Complete accessible form, modal, and navigation examples | ## Related Skills - `ork:testing-e2e` - E2E 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