coding-os 0.3.2__py3-none-any.whl

core/skills/a11y/SKILL.md

@@ -0,0 +1,305 @@
+---
+name: a11y
+tier: cross-cutting
+domain: [frontend, mobile]
+description: Accessibility (a11y) for web + mobile per WCAG 2.2 AA. Use when writing or reviewing UI code (React, React Native, Vue, Svelte) — screens, components, forms, modals, toasts, navigation. Covers semantic HTML / RN AccessibilityInfo props, ARIA patterns (use natives first), keyboard navigation, focus management, screen reader testing (VoiceOver / TalkBack / NVDA), color contrast, motion sensitivity, accessible forms with error handling, live regions, automated tooling (axe-core, Lighthouse, Playwright). Pairs with frontend-fundamentals (generic UI patterns).
+last_reviewed: "2026-05-11"
+
+---
+
+# Accessibility — WCAG 2.2 AA
+
+A practical playbook for making UI usable by people with disabilities. WCAG 2.2 (October 2023, current standard) at AA level is the legal compliance bar in most jurisdictions and the right minimum for any app shipping in 2026.
+
+## When to Use This Skill
+
+- Writing or reviewing any screen / component / form / modal.
+- Adding interactive UI (buttons, menus, dropdowns, tabs).
+- Setting up navigation (skip links, focus trap in modals).
+- Choosing colors / typography for the design system.
+- Auditing the app before launch.
+- Responding to accessibility user feedback / lawsuit risk assessment.
+
+For the cross-platform mobile concerns, see `mobile-fundamentals`. For component patterns, see `react-native-patterns` (RN) or `frontend-fundamentals` (web).
+
+## The Four POUR Principles (WCAG)
+
+WCAG organizes everything around four principles. Memorize the acronym; it's the lens for every UI decision.
+
+1. **Perceivable** — Users must be able to perceive the content. Text alternatives for images, captions for video, sufficient color contrast, no info conveyed by color alone.
+2. **Operable** — Users must be able to operate the UI. Keyboard accessible, enough time, no seizure-inducing flashes, navigable.
+3. **Understandable** — Users must be able to understand the content + UI. Readable language, predictable behavior, helpful error messages.
+4. **Robust** — Content works with current AND future assistive tech. Semantic markup, valid code, ARIA used correctly.
+
+## Use Native Elements First
+
+The most common a11y mistake: rebuilding a `<button>` as `<div onClick>`. The native element ships with:
+
+- Keyboard accessibility (Enter/Space to activate).
+- Focus indicator (browser default).
+- Role announcement to screen readers ("button").
+- Disabled state semantics.
+- Form integration (submit, reset).
+
+```html
+<!-- WRONG — div + onClick. Loses everything. -->
+<div onClick={handleClick}>Save</div>
+
+<!-- RIGHT -->
+<button type="button" onClick={handleClick}>Save</button>
+```
+
+```tsx
+{/* React Native — use Pressable, not View + onPress */}
+<Pressable
+  accessibilityRole="button"
+  accessibilityLabel="Save changes"
+  onPress={handlePress}>
+  <Text>Save</Text>
+</Pressable>
+```
+
+ARIA exists to fill gaps where native doesn't cover the pattern. The first rule of ARIA: don't use ARIA. The second rule: if you must, copy the pattern from the W3C ARIA Authoring Practices Guide (APG) — don't invent.
+
+## Color + Contrast (WCAG 1.4.3, 1.4.11)
+
+| Content | Minimum contrast ratio (AA) | Better (AAA) |
+|---|---|---|
+| Body text (< 18pt) | **4.5 : 1** | 7 : 1 |
+| Large text (≥ 18pt or 14pt bold) | **3 : 1** | 4.5 : 1 |
+| UI components, graphics (1.4.11) | **3 : 1** | n/a |
+
+Tools:
+
+- **Browser DevTools** — color picker shows contrast ratio inline.
+- **Stark** (Figma plugin) — design-time check.
+- **axe DevTools** (Chrome extension) — runtime audit.
+
+**Don't convey info by color alone** (1.4.1). A red border for "error" is fine, but pair with an icon + text. Color-blind users won't see the red.
+
+## Typography
+
+- **Minimum body size**: 16px on web; the platform default on mobile.
+- **Line height**: ≥ 1.5 (WCAG 1.4.12).
+- **Letter spacing**: ≥ 0.12em for body text.
+- **Don't disable user zoom** on mobile (`maximum-scale=1.0` in viewport meta is an a11y violation).
+- **RN: support Dynamic Type** — text uses `allowFontScaling={true}` (default); test at the largest accessibility setting.
+
+## Keyboard Navigation (WCAG 2.1)
+
+Every interactive element must be reachable + operable via keyboard alone.
+
+- **Tab order matches visual order** — DOM order is the default; avoid `tabindex` > 0.
+- **Visible focus indicator** — never `outline: none` without a replacement. Use a 2-3px outline OR `:focus-visible` for keyboard-only focus.
+- **Skip link** at the top of the page: "Skip to main content" — visible on focus.
+- **No keyboard traps** — user can always Tab/Esc out.
+- **Custom widgets** (autocomplete, tabs, accordion) — implement keyboard interactions per W3C ARIA APG patterns.
+
+```css
+/* Good visible focus */
+button:focus-visible,
+a:focus-visible,
+[role="button"]:focus-visible {
+  outline: 2px solid #2563eb;
+  outline-offset: 2px;
+}
+
+/* Skip link */
+.skip-link {
+  position: absolute;
+  left: -9999px;
+}
+.skip-link:focus {
+  left: 1rem;
+  top: 1rem;
+  z-index: 100;
+}
+```
+
+## Focus Management (WCAG 2.4.3, 3.2.2)
+
+When the UI changes, move focus deliberately:
+
+- **Modal opens** → focus first interactive element. Esc closes. Focus restored on close.
+- **Route change** → focus the new page's `<h1>` (or main landmark). Screen reader re-announces.
+- **Form submit error** → focus the first invalid field (or the error summary).
+- **Toast / alert appears** → use `role="status"` (polite) or `role="alert"` (assertive) — DON'T move focus unless interaction is required.
+
+For the full focus-trap implementation in React + RN, see [references/aria-and-focus.md](references/aria-and-focus.md).
+
+## Forms — Get These Right or You Lose Users
+
+Most accessibility failures are in forms. The fixes are simple:
+
+1. **Every input has a `<label>`** — or `aria-label` / `aria-labelledby` if visually hidden.
+2. **`htmlFor` matches `id`** so clicking the label focuses the input.
+3. **`required` attribute** + `aria-required="true"` (some screen readers don't announce HTML required).
+4. **Inline errors** with `aria-describedby` pointing to the error message + `aria-invalid="true"` on the input.
+5. **Submit error summary** at the top — `role="alert"`, focusable, links to each invalid field.
+6. **`autocomplete` attribute** for known fields (`name`, `email`, `tel`, `street-address`, `cc-number`, `current-password`, `new-password`, `one-time-code`).
+7. **Group related fields** with `<fieldset>` + `<legend>`.
+
+```tsx
+<label htmlFor="email">Email</label>
+<input
+  id="email"
+  type="email"
+  required
+  aria-required="true"
+  autoComplete="email"
+  aria-invalid={!!errors.email}
+  aria-describedby={errors.email ? 'email-error' : undefined}
+  {...register('email')}
+/>
+{errors.email && (
+  <span id="email-error" role="alert">{errors.email.message}</span>
+)}
+```
+
+## React Native — AccessibilityInfo Props
+
+RN uses `accessibility*` props on every component. The minimum:
+
+```tsx
+<Pressable
+  accessibilityRole="button"          // button | link | header | image | text | search | ...
+  accessibilityLabel="Save changes"   // what VoiceOver/TalkBack announces
+  accessibilityHint="Saves the form and returns to the previous screen"  // optional secondary
+  accessibilityState={{ disabled: isSaving }}
+  onPress={handleSave}>
+  <Text>Save</Text>
+</Pressable>
+```
+
+Other essentials:
+
+- **`accessibilityRole`** for non-`<Text>`/`<Pressable>` containers (header, list, none).
+- **`accessibilityLabel`** for icons and image-only buttons (otherwise SR reads nothing).
+- **`accessibilityElementsHidden={true}`** + **`importantForAccessibility="no-hide-descendants"`** to hide decorative views.
+- **`accessibilityLiveRegion="polite"`** (Android) / RN `AccessibilityInfo.announceForAccessibility(...)` (iOS) — for status updates.
+
+For the full RN-specific patterns including FlashList / form / modal / focus management, see [references/rn-accessibility.md](references/rn-accessibility.md).
+
+## Motion + Animation (WCAG 2.3.3)
+
+Some users get motion sickness from parallax, slide transitions, autoplay video. Respect `prefers-reduced-motion`.
+
+```css
+/* Disable transitions for users who request reduced motion */
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```
+
+```tsx
+// React Native
+import { AccessibilityInfo } from 'react-native';
+
+const [reduceMotion, setReduceMotion] = useState(false);
+useEffect(() => {
+  AccessibilityInfo.isReduceMotionEnabled().then(setReduceMotion);
+  const sub = AccessibilityInfo.addEventListener('reduceMotionChanged', setReduceMotion);
+  return () => sub.remove();
+}, []);
+
+// Then conditionally:
+const transition = reduceMotion ? { duration: 0 } : { duration: 250 };
+```
+
+Auto-play video: must have a way to pause/stop within 5 seconds (WCAG 2.2.2).
+
+## Screen Reader Testing — How
+
+You MUST test with a screen reader. Reading WCAG isn't enough.
+
+| Platform | Screen reader | Activation |
+|---|---|---|
+| macOS | VoiceOver | Cmd+F5 |
+| Windows | NVDA (free) | Ctrl+Alt+N after install |
+| iOS | VoiceOver | Settings → Accessibility → VoiceOver → On (or triple-press home/side) |
+| Android | TalkBack | Settings → Accessibility → TalkBack → On |
+| Chrome (dev) | ChromeVox | Extension |
+
+Test the critical flows: sign-in, add-to-cart / start-lesson, checkout / pay, settings, sign-out. If you can complete each flow eyes-closed using only the screen reader, the app is in good shape.
+
+For the testing protocol + per-flow checklist, see [references/screen-reader-testing.md](references/screen-reader-testing.md).
+
+## Automated Tooling
+
+Catch the easy wins automatically. None of these replace manual testing.
+
+- **axe-core** — runs in browser DevTools, in Playwright tests, in CI. The most thorough automated audit available.
+- **Lighthouse** — built into Chrome; lower fidelity than axe but gives a score.
+- **eslint-plugin-jsx-a11y** — catches anti-patterns at lint time (img without alt, click handler on non-interactive).
+- **eslint-plugin-react-native-a11y** — RN-specific lint rules.
+- **Playwright + @axe-core/playwright** — `await new AxeBuilder({ page }).analyze()` per critical page in CI.
+- **react-axe / @axe-core/react** — runs axe on every render in dev mode.
+
+```typescript
+// Playwright a11y test in CI
+import { test, expect } from '@playwright/test';
+import AxeBuilder from '@axe-core/playwright';
+
+test('home page is accessible', async ({ page }) => {
+  await page.goto('/');
+  const results = await new AxeBuilder({ page }).analyze();
+  expect(results.violations).toEqual([]);
+});
+```
+
+Fail the build on serious + critical violations.
+
+## Common a11y Failures (and Fixes)
+
+1. **`<div onClick>` instead of `<button>`** — use button.
+2. **Color-only error indicator** — add icon + text.
+3. **Missing alt on image** — `<img alt="...">` (or `alt=""` for decorative).
+4. **Modal opens, focus stays elsewhere** — focus first input on open.
+5. **Modal closes, focus disappears** — restore to the trigger.
+6. **No keyboard support for custom widget** — implement per ARIA APG.
+7. **Form input without label** — every input gets a `<label>`.
+8. **Error message only visible (not announced)** — use `aria-describedby` or `role="alert"`.
+9. **`outline: none`** — replace with `:focus-visible` styles.
+10. **`maximum-scale=1.0`** in viewport — remove.
+11. **Auto-play video / parallax without `prefers-reduced-motion`** — gate it.
+12. **Tab order doesn't match visual** — fix DOM order; avoid `tabindex>0`.
+13. **`tabindex="-1"` on something users need to reach** — remove.
+14. **Decorative icon without `aria-hidden="true"`** — SR reads "image".
+15. **RN button without `accessibilityLabel`** — SR reads nothing useful.
+16. **No skip link** — keyboard users tab through nav on every page.
+17. **Insufficient touch target** — WCAG 2.5.8 says min 24×24 CSS px (mobile usually wants 44×44).
+18. **No language attribute** on `<html>` — set `<html lang="en">`.
+19. **Page title same on every route** — set per page (`<title>` on web, `accessibilityViewIsModal` + announce on RN).
+
+## WCAG 2.2 — New AA Criteria (vs 2.1)
+
+WCAG 2.2 added 6 success criteria worth knowing:
+
+- **2.4.11 Focus Not Obscured (Min)** — focused element NOT entirely hidden by sticky header / cookie banner.
+- **2.4.12 Focus Not Obscured (Enh.)** — AAA — fully visible.
+- **2.5.7 Dragging Movements** — every drag has a non-drag alternative (e.g., re-order list also via long-press menu).
+- **2.5.8 Target Size (Minimum)** — 24×24 CSS px minimum (mobile patterns + density permitting).
+- **3.2.6 Consistent Help** — help link in same place across pages.
+- **3.3.7 Redundant Entry** — autofill prior info; don't make user re-type.
+- **3.3.8 Accessible Authentication** — no "type 4 random characters from your password" puzzles.
+- **3.3.9 Accessible Authentication (Enh.)** — AAA.
+
+Most apps already do these; check explicitly.
+
+## Pre-Launch a11y Checklist
+
+See [assets/a11y-checklist.md](assets/a11y-checklist.md). Each item is a concrete check; uncheck → fix or document waiver.
+
+## Source Material
+
+- *WCAG 2.2*: <https://www.w3.org/TR/WCAG22/>
+- *ARIA Authoring Practices Guide (APG)*: <https://www.w3.org/WAI/ARIA/apg/> — copy-paste patterns for combobox, tabs, etc.
+- *WebAIM*: <https://webaim.org/> — practical articles + free contrast checker.
+- *Inclusive Components* (Heydon Pickering) — book + blog with deep component patterns.
+- *axe-core docs*: <https://github.com/dequelabs/axe-core>
+- *Apple HIG — Accessibility*: <https://developer.apple.com/design/human-interface-guidelines/accessibility>
+- *Android Accessibility*: <https://developer.android.com/guide/topics/ui/accessibility>

core/skills/a11y/assets/a11y-checklist.md

@@ -0,0 +1,137 @@
+# Accessibility Pre-Launch Checklist (WCAG 2.2 AA)
+
+Run before each release. Each item is a concrete check; uncheck → fix or document waiver with reason + ETA.
+
+## Semantic Structure
+
+- [ ] Single `<h1>` per page; nested headings (h1 > h2 > h3) without skipping levels.
+- [ ] Landmark regions used (`<header>`, `<nav>`, `<main>`, `<footer>`, `<aside>`) on web.
+- [ ] React Native: `accessibilityRole="header"` on titles; `accessibilityRole="button"` on Pressables; `accessibilityRole="link"` on cross-app links.
+- [ ] Lists use `<ul>` / `<ol>`; nav menus use `<nav>` + `<ul>`.
+- [ ] No `<div onClick>` instead of `<button>` / `<Pressable>`.
+
+## Keyboard
+
+- [ ] Every interactive element reachable via Tab.
+- [ ] Tab order matches visual order.
+- [ ] No keyboard traps (can always Tab/Esc out).
+- [ ] Visible focus indicator on all focusable elements.
+- [ ] Skip link to main content (web).
+- [ ] Custom widgets (combobox, tabs, menu) follow ARIA APG keyboard pattern.
+- [ ] Modal traps focus; Esc closes; focus restored on close.
+- [ ] Touch target ≥ 24×24 CSS px (WCAG 2.5.8); mobile typically 44×44.
+
+## Color + Contrast
+
+- [ ] Body text contrast ≥ 4.5:1 on every background it appears on.
+- [ ] Large text (≥18pt or 14pt bold) ≥ 3:1.
+- [ ] UI components + meaningful graphics ≥ 3:1.
+- [ ] Focus indicator ≥ 3:1 against surrounding background.
+- [ ] No info conveyed by color alone (every red border has an icon + text).
+- [ ] Dark mode AND light mode both pass contrast checks.
+
+## Forms
+
+- [ ] Every input has a visible `<label>` or `accessibilityLabel`.
+- [ ] `htmlFor` matches `id`; clicking label focuses input.
+- [ ] `required` + `aria-required="true"` on required fields.
+- [ ] `autoComplete` set on known fields (`email`, `current-password`, `new-password`, `name`, `tel`, `street-address`, `cc-number`, `one-time-code`).
+- [ ] Inline error message: `aria-describedby` on input, `aria-invalid="true"`, `role="alert"` on the error.
+- [ ] Submit error: focus first invalid field OR error summary at top.
+- [ ] Field grouping with `<fieldset>` + `<legend>` where appropriate.
+- [ ] No CAPTCHAs without an accessible alternative (audio CAPTCHA / reCAPTCHA v3 / passkey).
+
+## Images + Media
+
+- [ ] Every `<img>` has `alt=""` (decorative) or descriptive `alt="..."`.
+- [ ] React Native `<Image>` decorative: `accessible={false}` + `accessibilityElementsHidden={true}`.
+- [ ] `<Image>` informative: `accessibilityLabel="..."`.
+- [ ] Video has captions OR is decorative + auto-pauses within 5 sec.
+- [ ] Audio has transcripts.
+- [ ] No autoplay video / audio (or muted + ≤ 5 sec).
+
+## Motion + Animation
+
+- [ ] `prefers-reduced-motion` media query respected (web).
+- [ ] React Native: check `AccessibilityInfo.isReduceMotionEnabled()` and disable / shorten animations.
+- [ ] No flashing > 3 times per second (seizure trigger).
+- [ ] Parallax / auto-scroll has stop control.
+
+## Modals + Dialogs
+
+- [ ] Use native `<dialog>` (web) or React Navigation modal preset (RN).
+- [ ] Focus moves to first interactive (or dialog itself) on open.
+- [ ] Focus trap inside; Esc / back button closes.
+- [ ] Focus returns to trigger on close.
+- [ ] `aria-labelledby` or `accessibilityLabel` on the dialog.
+- [ ] Backdrop click dismisses (or has documented reason not to).
+
+## Navigation
+
+- [ ] Page title set per route (`<title>` on web; React Navigation `headerTitle` or `accessibilityViewIsModal` + `announceForAccessibility` on RN).
+- [ ] Skip link at top (web).
+- [ ] Active nav item visually + programmatically marked (`aria-current="page"` or `accessibilityState={{ selected: true }}`).
+- [ ] Breadcrumb navigation (when used) marked with `aria-label="Breadcrumb"`.
+
+## Live Regions / Status
+
+- [ ] Async loading announced: `role="status"` (web) / `accessibilityLiveRegion="polite"` + `announceForAccessibility` (RN).
+- [ ] Errors announced: `role="alert"` (web) / `announceForAccessibility` (RN).
+- [ ] Toast notifications announced + auto-dismissed after enough time to read.
+
+## RN-Specific
+
+- [ ] `accessibilityRole` set on every Pressable / View used as a control.
+- [ ] `accessibilityLabel` on icon buttons.
+- [ ] `accessibilityState` reflects disabled / selected / busy / checked / expanded.
+- [ ] Decorative views: `accessibilityElementsHidden={true}` + `importantForAccessibility="no-hide-descendants"`.
+- [ ] Group cohesive content with `accessible={true}` + combined `accessibilityLabel`.
+- [ ] Focus management on route change + modal open via `AccessibilityInfo.setAccessibilityFocus`.
+- [ ] Dynamic Type tested at AX5; layout doesn't break.
+- [ ] `maxFontSizeMultiplier` set on tight UI elements.
+
+## Internationalization (if multi-language)
+
+- [ ] `<html lang="...">` set per page.
+- [ ] React Navigation header titles localized.
+- [ ] RTL support tested (Arabic / Hebrew / Persian if shipping).
+- [ ] Locale-aware date / number formatting (`Intl.NumberFormat` / `Intl.DateTimeFormat`).
+
+## Automated Tooling
+
+- [ ] `eslint-plugin-jsx-a11y` (web) / `eslint-plugin-react-native-a11y` (RN) passes.
+- [ ] Lighthouse accessibility score ≥ 95 on key pages.
+- [ ] axe-core passes (zero serious + critical violations) via Playwright integration test.
+- [ ] `react-axe` enabled in dev for every PR.
+
+## Manual Testing
+
+- [ ] **VoiceOver (iOS)** complete sign-in / browse / start-task / settings / sign-out flows.
+- [ ] **TalkBack (Android)** same flows.
+- [ ] **VoiceOver (macOS)** if web client.
+- [ ] **NVDA (Windows)** if web client.
+- [ ] **Keyboard-only** complete same flows on web (no mouse/trackpad).
+- [ ] **iOS Dynamic Type AX5** — layout doesn't break on critical screens.
+- [ ] **OS color filters** (Grayscale, Inverted Colors) tested on home screen.
+
+## Pre-Launch Smoke
+
+- [ ] All critical flows pass screen-reader test on iOS + Android.
+- [ ] axe-core CI step is green.
+- [ ] No serious / critical Lighthouse a11y violations.
+- [ ] Real-user accessibility tester (employee / consultant) runs the flows once.
+
+---
+
+If any box is unchecked, document the reason in a tracking issue. Accessibility bugs ship for the lifetime of the app version.
+
+## WCAG 2.2 — New Criteria (vs 2.1)
+
+Verify these explicitly:
+
+- [ ] **2.4.11 Focus Not Obscured (Min)** — focused element NOT entirely hidden by sticky header / cookie banner / floating buttons.
+- [ ] **2.5.7 Dragging Movements** — every drag has a non-drag alternative (e.g., re-order list also via long-press menu).
+- [ ] **2.5.8 Target Size (Min)** — 24×24 CSS px minimum.
+- [ ] **3.2.6 Consistent Help** — help link in same place across pages.
+- [ ] **3.3.7 Redundant Entry** — autofill prior info; don't make user re-type.
+- [ ] **3.3.8 Accessible Authentication** — no "type 4 random characters from your password" puzzles.

core/skills/a11y/references/aria-and-focus.md

@@ -0,0 +1,247 @@
+# ARIA Patterns + Focus Management
+
+The two areas where small mistakes cause big a11y failures. Both have correct patterns; both reward following them exactly.
+
+## The Three Rules of ARIA
+
+1. **Don't use ARIA**. Use semantic HTML (`<button>`, `<nav>`, `<main>`, `<dialog>`) first.
+2. **If you must, follow the W3C ARIA Authoring Practices Guide patterns exactly.** Don't invent.
+3. **Test with a screen reader.** ARIA is broken without verification.
+
+## Common Patterns — Use These Exactly
+
+### Disclosure Button (Show/Hide Section)
+
+```html
+<button
+  aria-expanded="false"
+  aria-controls="more-info">
+  More info
+</button>
+<div id="more-info" hidden>
+  Additional content
+</div>
+```
+
+JS toggles `aria-expanded` AND `hidden`. SR announces "expanded" / "collapsed".
+
+### Modal Dialog
+
+```html
+<dialog
+  open
+  aria-modal="true"
+  aria-labelledby="dlg-title"
+  aria-describedby="dlg-desc">
+  <h2 id="dlg-title">Confirm delete</h2>
+  <p id="dlg-desc">This action cannot be undone.</p>
+  <button>Cancel</button>
+  <button>Delete</button>
+</dialog>
+```
+
+The native `<dialog>` element handles modal semantics + Esc + backdrop click. Use it instead of div-with-overlay where possible.
+
+### Tabs (W3C APG pattern)
+
+```html
+<div role="tablist" aria-label="Account">
+  <button role="tab" aria-selected="true"  aria-controls="tab1-panel" id="tab1" tabindex="0">Profile</button>
+  <button role="tab" aria-selected="false" aria-controls="tab2-panel" id="tab2" tabindex="-1">Security</button>
+</div>
+<div role="tabpanel" id="tab1-panel" aria-labelledby="tab1">...</div>
+<div role="tabpanel" id="tab2-panel" aria-labelledby="tab2" hidden>...</div>
+```
+
+Keyboard:
+
+- **Tab** → moves into / out of the tablist.
+- **Arrow Left / Right** → moves between tabs (with `tabindex` rotation).
+- **Home / End** → first / last tab.
+- **Enter / Space** → activate (or auto-activate on focus, your choice — auto is more common in 2026).
+
+### Combobox (Autocomplete)
+
+This is the gnarliest. Use a library: `react-aria` (Adobe), `headlessui`, `radix-ui`. Don't roll your own.
+
+If you must, follow the APG combobox pattern exactly: <https://www.w3.org/WAI/ARIA/apg/patterns/combobox/>
+
+### Menu (Context Menu / Dropdown)
+
+```html
+<button
+  aria-haspopup="menu"
+  aria-expanded="false"
+  aria-controls="actions-menu">
+  Actions
+</button>
+<ul role="menu" id="actions-menu" hidden>
+  <li role="menuitem"><a href="/edit">Edit</a></li>
+  <li role="menuitem"><a href="/delete">Delete</a></li>
+</ul>
+```
+
+Keyboard: Down arrow opens; arrows navigate; Esc closes.
+
+### Live Regions
+
+For dynamic updates (toast, status change, search results count) without moving focus:
+
+```html
+<!-- Polite: SR finishes current sentence first. -->
+<div role="status" aria-live="polite">3 results found</div>
+
+<!-- Assertive: SR interrupts. Use sparingly — for errors/alerts. -->
+<div role="alert" aria-live="assertive">Failed to save</div>
+```
+
+The element MUST exist on initial render (empty); update its text content. Adding the element AND content at the same time is missed by some SR.
+
+### Loading States
+
+```html
+<button aria-busy="true" aria-describedby="status">Save</button>
+<span id="status" role="status" aria-live="polite">Saving…</span>
+```
+
+SR announces "Saving…" without losing focus.
+
+## Focus Management — Patterns
+
+### Modal Open / Close
+
+```typescript
+const previousFocus = useRef<HTMLElement | null>(null);
+const dialogRef = useRef<HTMLDialogElement>(null);
+
+function open() {
+  previousFocus.current = document.activeElement as HTMLElement;
+  dialogRef.current?.showModal();
+  // Focus the first interactive element OR the dialog itself.
+  const first = dialogRef.current?.querySelector<HTMLElement>(
+    'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
+  );
+  first?.focus();
+}
+
+function close() {
+  dialogRef.current?.close();
+  previousFocus.current?.focus();
+  previousFocus.current = null;
+}
+```
+
+Native `<dialog>` does Esc + backdrop dismiss for free. Use it.
+
+### Focus Trap
+
+In a modal, Tab + Shift+Tab must cycle within the dialog. Native `<dialog open>` handles this automatically. For custom overlays, use `focus-trap-react` or `react-focus-lock`.
+
+```tsx
+import FocusTrap from 'focus-trap-react';
+
+{isOpen && (
+  <FocusTrap focusTrapOptions={{ escapeDeactivates: true, onDeactivate: close }}>
+    <div role="dialog" aria-modal="true">
+      ...
+    </div>
+  </FocusTrap>
+)}
+```
+
+### Route Change
+
+In a SPA, the browser doesn't announce a navigation. Move focus to the new page:
+
+```tsx
+function Page({ title }: { title: string }) {
+  const h1Ref = useRef<HTMLHeadingElement>(null);
+  useEffect(() => {
+    h1Ref.current?.focus();
+  }, []);
+  return <h1 ref={h1Ref} tabIndex={-1}>{title}</h1>;
+}
+```
+
+`tabIndex={-1}` lets the element receive focus programmatically without entering the tab order.
+
+Or announce via live region:
+
+```tsx
+const { setAnnouncement } = useAnnouncer();
+useEffect(() => {
+  setAnnouncement(`Navigated to ${title}`);
+}, [title]);
+```
+
+### Form Submit Error
+
+```typescript
+async function onSubmit(data) {
+  try {
+    await submit(data);
+  } catch (err) {
+    setErrors(err.fields);
+    // Focus the first invalid field (or the error summary).
+    requestAnimationFrame(() => {
+      document.querySelector<HTMLElement>('[aria-invalid="true"]')?.focus();
+      // OR: errorSummaryRef.current?.focus();
+    });
+  }
+}
+```
+
+Use `requestAnimationFrame` so focus moves AFTER the DOM update.
+
+### Async Content Load
+
+```tsx
+{isLoading ? (
+  <p role="status" aria-live="polite">Loading lessons…</p>
+) : (
+  <ul>{...}</ul>
+)}
+```
+
+SR announces "Loading lessons…" without focus jump. When loaded, the list becomes available; user can navigate to it via headings.
+
+## React Native — Focus Management
+
+```tsx
+import { AccessibilityInfo, findNodeHandle, View } from 'react-native';
+
+const ref = useRef<View>(null);
+
+useEffect(() => {
+  if (isModalOpen) {
+    const reactTag = findNodeHandle(ref.current);
+    if (reactTag) AccessibilityInfo.setAccessibilityFocus(reactTag);
+  }
+}, [isModalOpen]);
+
+<View ref={ref} accessible={true} accessibilityLabel="Confirm delete">
+  ...
+</View>
+```
+
+For VoiceOver / TalkBack focus on a specific element after a UI change, `AccessibilityInfo.setAccessibilityFocus(reactTag)` is the API. Do it inside `requestAnimationFrame` or after `InteractionManager.runAfterInteractions`.
+
+## ARIA Don'ts
+
+1. **`role="button"` on a `<button>`** — redundant; remove.
+2. **`aria-label="Submit"`** on a button that has visible text "Submit" — redundant; remove.
+3. **`aria-hidden="true"`** on a focusable element — SR can't read but tab still lands → confused user. Either hide both or neither.
+4. **`tabindex` > 0** — breaks the natural tab order. Use 0 (in order) or -1 (programmatic only).
+5. **`role="presentation"`** + interactive children — strips semantics from the parent but children become unreachable.
+6. **Multiple `aria-live` regions** firing at once — they queue + interrupt each other.
+7. **`role="alert"` for non-urgent updates** — interrupts the SR; only for errors / time-sensitive.
+8. **Updating an `aria-live` element by replacing its DOM node** — SR misses the change. Update text content instead.
+
+## Source Material
+
+- *WAI-ARIA Authoring Practices Guide (APG)*: <https://www.w3.org/WAI/ARIA/apg/>
+- *Inclusive Components* (Heydon Pickering) — patterns for tabs, modals, menus.
+- *react-aria*: <https://react-spectrum.adobe.com/react-aria/> — battle-tested hooks.
+- *Headless UI*: <https://headlessui.com/> — pre-built unstyled accessible components.
+- *Radix UI*: <https://www.radix-ui.com/> — same idea, slightly different API.
+- *focus-trap-react*: <https://github.com/focus-trap/focus-trap-react>