feat(a11y): WCAG 2.1 AA scanning, baseline ratchet, and remediation

.claude/skills/a11y-review/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: a11y-review
+description: Accessibility (WCAG 2.1 AA) review of UI changes - keyboard operation, accessible names/roles/states, focus management, announcements, and the repo's a11y gates. Use before finishing any change that adds or modifies interactive UI, when asked to review a branch or PR for accessibility, or when a user reports a keyboard or screen reader problem.
+---
+
+# Accessibility review
+
+Jetstream targets WCAG 2.1 AA (program docs in `docs/accessibility/`). This skill is the review
+pass that the 2026 audit and code review used; run it on the current diff before calling UI work
+done, or on the files the user names.
+
+## Scope
+
+- Default scope is `git diff --name-only main...HEAD` plus uncommitted changes; the user may
+  narrow it to files or an area. Only `.tsx` files that render UI (and their specs) matter.
+- **Read each file in full**, not just the hunk: the defect is usually in how the changed element
+  interacts with the rest of the component (a role on the parent, a handler on the row).
+- Check `docs/accessibility/audit-2026/findings.md` ("Still open after the review") before
+  reporting so known, deliberately-open items are not re-raised.
+
+## Checklist
+
+Walk every interactive element in scope and answer each question. "Interactive" includes anything
+with an `onClick`, `onKeyDown`, `href`, `tabIndex`, or an ARIA widget role.
+
+1. **Name, role, state.** Does it have an accessible name that matches the visible text (icon-only
+   buttons need `title` or `aria-label`; the name must include the visible label - WCAG 2.5.3)?
+   Is the role native (`<button>`, `<a href>`) or a correct ARIA widget role on a focusable element?
+   Are `aria-expanded`, `aria-selected`, `aria-checked`, `aria-pressed`, `aria-current`,
+   `aria-invalid`, `aria-describedby` present where the state exists visually? Is anything
+   decorative (`Icon` next to text) hidden rather than named?
+2. **Keyboard.** Can it be reached with Tab (or with arrow keys inside a composite) and operated
+   with Enter/Space? Do lists, grids, trees, tabs, menus, and radio groups use a single tab stop
+   with arrow keys, Home/End, and type-ahead where the APG pattern has it? Is there any trap
+   (Monaco editors are the deliberate exception, with the documented Ctrl+M escape)?
+3. **Focus management.** When a control unmounts on click (Remove -> Keep/Confirm, Save/Undo,
+   delete row, close panel), where does focus go? It must land on the replacement control, the
+   nearest sensible sibling, or the trigger - never on `body`. Dialogs and popovers must trap and
+   return focus (`Modal`, `Popover`, `FloatingFocusManager` do this; custom panels must too).
+   Route changes must not steal focus except after a user-initiated navigation.
+4. **Announcements.** Are status changes a screen reader must hear (load progress, results count,
+   save confirmation, validation summary, "copied") rendered inside a live region? Are errors
+   announced assertively and success/progress politely? Does the live region exist before the
+   message arrives (a region mounted with text is not announced)?
+5. **Disabled and busy.** A control that disables itself while its own action runs must stay
+   focusable (`ariaDisabledButtonProps`) so focus is not dropped and the reason is announced;
+   native `disabled` is fine for controls gated by other state. Long operations expose
+   `aria-busy` or a status message, not just a spinner.
+6. **Forms.** Every input has a `<label for>` or `aria-labelledby` that points at an existing id;
+   help text and errors are linked with `aria-describedby`; required and invalid states are in
+   ARIA, not only in colour; error summaries move focus or are announced.
+7. **Layering.** Escape closes only the top-most layer (popover inside a modal, editor inside a
+   grid cell). Anything that handles Escape goes through `useEscapeToCloseLayer`.
+8. **Visual (what code can show).** Text and focus rings are not removed with `outline: none`;
+   information is not carried by colour alone; the layout tolerates 200% zoom / 320px reflow
+   (no fixed pixel heights around text).
+9. **Tests.** Interactive `libs/ui` components have an `axeScan()` assertion in their spec;
+   keyboard behaviour that was hand-rolled has a unit test; new routes have an
+   `a11y-baseline.json` entry.
+
+## Shared primitives to reach for
+
+| Need                                                   | Use                                                                                           |
+| ------------------------------------------------------ | --------------------------------------------------------------------------------------------- |
+| Keep a self-disabling button focusable                 | `ariaDisabledButtonProps` (`libs/ui/src/lib/form/button/aria-disabled-button.utils.ts`)       |
+| Announce a status string                               | `AssistiveStatus` (polite region), `useAnnouncer` (imperative), `ScopedNotification` (banner) |
+| Escape closes this layer only                          | `useEscapeToCloseLayer` / `EscapeLayerPropagationContext`                                     |
+| Single-tab-stop list with row-level extras             | `List` (roving tabindex, `focusListEntryRow`), `Tabs`, `Accordion`, `Tree`                    |
+| Filter input that hands off to the list with ArrowDown | `SearchInput` + `List` (see `SobjectFieldList`)                                               |
+| Combobox / picklist                                    | `Combobox`, `Picklist` (ARIA 1.2 pattern; focus moves to the option)                          |
+| Modal / popover / dropdown menu                        | `Modal`, `Popover`, `DropDown` (focus trap, return focus, Escape)                             |
+| Data grid keyboard model                               | `data-table/grid/keyboard/useGridKeyboardNavigation.ts`                                       |
+| Skip link, focus main on navigation                    | `SkipToContent`, `FocusMainContentOnRouteChange`                                              |
+| Unit-level axe assertion                               | `axeScan(container)` from `@jetstream/test-utils`                                             |
+
+Reference implementations to copy from: `libs/ui/src/lib/modal/Modal.tsx`, `popover/Popover.tsx`,
+`form/dropdown/DropDown.tsx`, `list/List.tsx`, `tabs/Tabs.tsx`, and the grid under `data-table/grid/`.
+
+## Gates to run
+
+```bash
+pnpm lint                         # jsx-a11y rules at `error` (never demote one)
+pnpm a11y:lint-ratchet            # no new warn-tier jsx-a11y hits, axeScan() in new libs/ui specs, every route baselined
+pnpm nx run ui:test -- <spec>     # unit specs with axeScan()
+pnpm e2e:local a11y               # axe sweep of every route + interactive states against a11y-baseline.json
+```
+
+When a fix drops a lint hit, run `pnpm a11y:lint-ratchet --update` so the baseline shrinks with it.
+Growth of either baseline needs `--allow-growth` and a line in the findings log.
+
+## Report format
+
+One line per finding, most severe first, then the verified-OK list and anything not exercised:
+
+```
+[P1|P2|P3] path/to/File.tsx:123 - claim - who hits it and how (keyboard / VoiceOver / zoom) - fix
+```
+
+- **P1**: cannot be completed with a keyboard or a screen reader (trap, unnamed control, lost focus,
+  unannounced error, inaccessible required step).
+- **P2**: works but wrong or confusing (misleading name, missing state, duplicate announcement,
+  focus lands somewhere surprising).
+- **P3**: polish and consistency.
+
+Only report what the code proves. If a behaviour depends on runtime layout or a screen reader
+quirk, say it is untested rather than guessing.
+
+## Landing fixes
+
+Fix P1 and P2 findings in the same change unless the user asks for a report only. On a branch
+with atomic commits, land a fix as `git commit --fixup=<sha>` against the commit that introduced
+the defect and leave the autosquash to the author; a fix for a pre-existing gap is a normal commit
+with a `fix(<scope>):` subject that says what a user could not do before. Add or extend a spec for
+every keyboard or focus behaviour you change, and run `pnpm format` and `pnpm organize-imports`
+on touched files.

.github/copilot-instructions.md

@@ -18,3 +18,4 @@ Jetstream is a private Nx monorepo (React 19 + Vite web app, Express/Prisma API,
 - UI is hand-built — this repo does NOT use `@salesforce/design-system-react`. Prefer SLDS CSS classes; use Emotion `css` where needed. State is jotai atoms.
 - Always use curly braces on `if` statements. Prefer verbose variable names (except `i` for index); avoid single-letter names.
 - Tests are Vitest, co-located in `__tests__/*.spec.ts`. Migrations are created with the Prisma CLI only.
+- The product targets **WCAG 2.1 AA** (see `docs/accessibility/`). In UI changes, flag missing accessible names, keyboard operability gaps, focus-management regressions, and missing `aria-live` for async status. Interactive `libs/ui` components should carry an `axeScan()` assertion (`@jetstream/test-utils`) in their spec — reference pattern: `libs/ui/src/lib/modal/__tests__/Modal.spec.tsx`.

.github/workflows/ci.yml

@@ -84,6 +84,11 @@ jobs:
       - name: Lint
         run: pnpm lint
 
+      # Fails on new warn-tier jsx-a11y hits, new libs/ui specs without axeScan(), and new routes
+      # without an axe baseline entry (scripts/a11y-lint-ratchet.mjs).
+      - name: Accessibility lint ratchet
+        run: pnpm a11y:lint-ratchet
+
   # Build application
   build-and-test:
     runs-on: ubuntu-latest
@@ -245,7 +250,9 @@ jobs:
         id: setup
         uses: ./.github/actions/setup-e2e
         with:
-          affected-projects: api|jetstream
+          # jetstream-e2e is listed so a change that only touches the suite itself (a spec, the a11y
+          # baseline, the shared page objects) still runs it — api/jetstream alone would skip those.
+          affected-projects: api|jetstream|jetstream-e2e
           suite-name: E2E
 
       # build:ci compiles all nine apps; E2E only reaches three of them. api/src/main.ts statically
@@ -288,6 +295,19 @@ jobs:
           retention-days: 1
           if-no-files-found: ignore
 
+      # Raw axe-core scan results from the a11y specs — evidence artifacts for the accessibility
+      # conformance report (VPAT) and inputs to scripts/a11y-merge-baseline.mjs.
+      - name: Upload a11y scan results
+        if: always() && steps.setup.outputs.should_run == 'true'
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: a11y-results-${{ matrix.shardIndex }}
+          path: apps/jetstream-e2e/a11y-results
+          retention-days: 30
+          # Only the shard(s) that ran an a11y spec produce results, so an empty shard is normal here;
+          # merge-e2e-reports fails the run if NO shard produced any.
+          if-no-files-found: ignore
+
   # Playwright's _electron support needs a real BrowserWindow, which a headless GitHub-hosted
   # runner has no display server for — xvfb-run provides a virtual one. Single job, single worker
   # (no sharding, unlike e2e-shard): Electron launches are heavier than browser contexts and there's
@@ -419,6 +439,23 @@ jobs:
           pattern: blob-report-*
           merge-multiple: true
 
+      - name: Download a11y scan results
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          path: all-a11y-results
+          pattern: a11y-results-*
+          merge-multiple: true
+
+      # The a11y specs land on whichever shards Playwright assigns them to, so a shard without results
+      # is normal. What must never pass silently is the suite running with NO shard producing any —
+      # that means the a11y specs were skipped or broken and the ratchet did not run.
+      - name: Check a11y scan results exist
+        run: |
+          if [ -n "$(ls -A all-blob-reports 2>/dev/null)" ] && [ -z "$(ls -A all-a11y-results 2>/dev/null)" ]; then
+            echo "::error::E2E ran but no a11y scan results were produced — the a11y specs did not run"
+            exit 1
+          fi
+
       # The E2E job exits successfully without producing reports when the affected-guard skips it,
       # so an empty download here is expected rather than an error.
       #

.gitignore

@@ -61,6 +61,8 @@ package-lock.json
 **/playwright-report
 **/playwright-summary.json
 **/playwright/.cache
+# axe-core scan evidence (VPAT inputs) — generated by the a11y E2E specs and scripts/a11y-scan-urls.mjs
+**/a11y-results
 
 .nx/cache
 .nx/workspace-data

.husky/pre-commit

@@ -28,3 +28,11 @@ pnpm exec oxlint --quiet . || {
   echo "Lint errors found. Run 'pnpm lint:fix' to auto-fix what can be fixed."
   exit 1
 }
+
+# Accessibility ratchet: new warn-tier jsx-a11y hits, new libs/ui specs without axeScan(), and new
+# routes without an axe baseline entry (scripts/a11y-lint-ratchet.mjs).
+pnpm a11y:lint-ratchet || {
+  echo ""
+  echo "Accessibility ratchet failed. See the messages above, or use 'git commit --no-verify' to bypass."
+  exit 1
+}

.oxlintrc.json

@@ -103,16 +103,33 @@
     // unicorn/no-new-array, unicorn/no-single-promise-in-promise-methods,
     // unicorn/no-useless-fallback-in-spread, unicorn/no-useless-length-check.
 
-    // Accessibility was advisory before the migration (Nx's React preset reports these as
-    // warnings, and only the two React apps opted into the wider set). Keeping that posture.
-    "jsx-a11y/autocomplete-valid": "warn",
+    // Accessibility ratchet (docs/accessibility/README.md): each rule is promoted from `warn` to
+    // `error` once its violation count reaches zero — see the lint census in
+    // docs/accessibility/audit-2026/findings.md for current counts. Never demote a promoted rule.
+    "jsx-a11y/anchor-ambiguous-text": "error",
+    "jsx-a11y/autocomplete-valid": "error",
     "jsx-a11y/click-events-have-key-events": "warn",
-    "jsx-a11y/control-has-associated-label": "warn",
-    "jsx-a11y/interactive-supports-focus": "warn",
-    "jsx-a11y/label-has-associated-control": "warn",
+    // depth: SLDS blueprints nest a control's text several levels deep (li > div.slds-media >
+    // span.slds-media__body > span), beyond the default depth of 2
+    "jsx-a11y/control-has-associated-label": ["warn", { "depth": 5 }],
+    "jsx-a11y/interactive-supports-focus": "error",
+    // depth: the SLDS toggle's second <label> wraps the input plus the on/off state text two levels down
+    "jsx-a11y/label-has-associated-control": ["error", { "depth": 3 }],
     "jsx-a11y/no-noninteractive-element-interactions": "warn",
-    "jsx-a11y/no-noninteractive-element-to-interactive-role": "warn",
-    "jsx-a11y/no-redundant-roles": "warn",
+    // The allowlist mirrors eslint-plugin-jsx-a11y's recommended config: APG composite widgets are
+    // built from list markup (ul[role=listbox] > li[role=option], role=tree/treeitem, role=tablist/tab)
+    "jsx-a11y/no-noninteractive-element-to-interactive-role": [
+      "warn",
+      {
+        "ul": ["listbox", "menu", "menubar", "radiogroup", "tablist", "tree", "treegrid"],
+        "ol": ["listbox", "menu", "menubar", "radiogroup", "tablist", "tree", "treegrid"],
+        "li": ["menuitem", "menuitemradio", "menuitemcheckbox", "option", "row", "tab", "treeitem"],
+        "table": ["grid"],
+        "td": ["gridcell"],
+        "fieldset": ["radiogroup", "presentation"]
+      }
+    ],
+    "jsx-a11y/no-redundant-roles": "error",
     "jsx-a11y/no-static-element-interactions": "warn",
 
     // Focus placement in modals/popovers is deliberate (StepUpAuthModal, grid filter inputs, etc.).

CLAUDE.md

@@ -54,6 +54,15 @@ This project does NOT use `@salesforce/design-system-react`, all components were
 
 Prefer using Salesforce lightning design system CSS classes when applicable, but can use `import { css } from '@emotion/react'` where needed.
 
+## Accessibility
+
+The product targets WCAG 2.1 AA — program docs, findings log, and the conformance report live in `docs/accessibility/`. Run the `/a11y-review` skill on any change that adds or modifies interactive UI before calling it done.
+
+- New or changed interactive UI must be keyboard operable with correct ARIA (names, roles, states) and managed focus: when a control unmounts on activation, move focus to its replacement or the trigger, never let it fall to `body`. Reference implementations: `libs/ui/src/lib/modal/Modal.tsx`, `popover/Popover.tsx`, `form/dropdown/DropDown.tsx`, `list/List.tsx`, and the grid under `data-table/grid/`.
+- Use the shared primitives instead of hand-rolling: `ariaDisabledButtonProps` for a control that disables itself, `AssistiveStatus` / `useAnnouncer` / `ScopedNotification` for status a screen reader must hear, `useEscapeToCloseLayer` for anything Escape closes, and the roving-tabindex composites (`List`, `Tabs`, `Accordion`, `Tree`, the grid) for long collections — never a tab stop per row.
+- Add an `axeScan()` assertion (from `@jetstream/test-utils`) to specs for interactive `libs/ui` components — see `libs/ui/src/lib/modal/__tests__/Modal.spec.tsx`.
+- `pnpm a11y:lint-ratchet` runs in pre-commit and CI. It fails on any new `warn`-tier `jsx-a11y` hit (per file and rule, baselined in `tools/oxlint/jsx-a11y-baseline.json`), a new `libs/ui` spec without `axeScan()`, and a new `APP_ROUTES` entry without an `a11y-baseline.json` key. `--update` shrinks the baseline; growth needs `--allow-growth` plus a findings-log entry. E2E axe scans in `apps/jetstream-e2e/src/tests/a11y/` ratchet the same way, and `jsx-a11y` rules are never demoted from `error`.
+
 ## Testing Approach
 
 - Unit tests with Vitest (co-located with source files, but in a `__tests__` folder example: `__tests__/*.spec.ts`)