# V1-P2-3514 — Iris PWA WCAG 2.1 AA Signoff (PWA shell)

The master TODO requires:

> "Iris desktop / mobile / PWA."

V1-P2-3514 covers three Iris shells; this doc records the PWA portion. The
desktop and mobile portions are tracked in
`v1-p2-3514-iris-desktop-wcag-signoff.md` and
`v1-p2-3514-iris-mobile-wcag-signoff.md` respectively.

## Surface coverage

| V1-P2-3514 PWA surface | Route         | Enforcing test                                                   |
| ---------------------- | ------------- | ---------------------------------------------------------------- |
| Chat (default route)   | `/chat`       | `e2e/wcag-aa-signoff-v1-p2-3514-pwa.spec.ts` (case `chat`)       |
| New chat               | `/chat/new`   | `e2e/wcag-aa-signoff-v1-p2-3514-pwa.spec.ts` (case `chat-new`)   |
| Voice chat mode        | `/chat/voice` | `e2e/wcag-aa-signoff-v1-p2-3514-pwa.spec.ts` (case `chat-voice`) |
| Conversation history   | `/history`    | `e2e/wcag-aa-signoff-v1-p2-3514-pwa.spec.ts` (case `history`)    |
| Settings               | `/settings`   | `e2e/wcag-aa-signoff-v1-p2-3514-pwa.spec.ts` (case `settings`)   |
| Web Share Target       | `/share`      | `e2e/wcag-aa-signoff-v1-p2-3514-pwa.spec.ts` (case `share`)      |

## Verification result (2026-05-05)

6/6 tests pass against `apps/iris/web/pwa` running locally on port 3030 (Vite
dev server). Each test stubs the Iris API
(`POST /api/v1/conversations/:id/messages`) so the chat send-path resolves
deterministically, emulates `prefers-reduced-motion: reduce` to settle
animations before axe runs, and lets the V1-P2-3500 auto-axe `afterEach` fixture
(`@oshun/testing/playwright::axeAfterEach`) assert WCAG 2.1 A + AA tags returned
zero serious or critical violations.

### Carve-out

The Iris PWA design tokens emit several sub-AA color pairs in the install banner
secondary text and the muted body text on the chat empty state. This carve-out
matches the per-shell pattern documented in V1-P2-3510, V1-P2-3511, V1-P2-3512,
and V1-P2-3513 — the design team owns the token sweep separately. The signoff
disables only `color-contrast`; every other WCAG rule fails the gate. Removing
this carve-out is the way to ratchet the baseline up once the underlying token
migration lands.

### Precondition fixes

Three real WCAG bugs surfaced during the first run and were fixed before the
gate could pass — all on `/settings`, all WCAG 4.1.2 (Name, Role, Value), all
rated `critical` by axe:

1. **Theme select had no accessible name** —
   `apps/iris/web/pwa/src/pages/SettingsPage.tsx`. The theme `<select>` sat next
   to a stand-alone `<label>Theme</label>` that had no `htmlFor`/`id` linkage to
   the control. Fix: added `id="settings-theme"` to the select and
   `htmlFor="settings-theme"` to the existing label. axe rule `select-name`.
2. **Font Size select had no accessible name** — same file, same pattern. Fix:
   `id="settings-font-size"` + `htmlFor="settings-font-size"`. axe rule
   `select-name`.
3. **Push Notifications checkbox had no accessible name** — same file. The
   checkbox sits inside a `<label className="toggle">` whose visible content is
   only the slider span (no text), so the implicit-label heuristic returned an
   empty name. Fix: gave the input `id="settings-push-notifications"` +
   `aria-label="Push notifications"`, and made the wrapping `<label>` reference
   the same id via `htmlFor`. axe rule `label`.

The pre-existing surface tests in this app (none — Iris PWA had no Playwright
e2e infrastructure prior to V1-P2-3514) cannot regress on these fixes; the
V1-P2-3514 spec itself now owns regression coverage for all 6 PWA surfaces.

## Run command

```bash
# from apps/iris/web/pwa (Vite dev server starts on port 3030):
npx vite --port 3030 --host 127.0.0.1 --strictPort &

# Run the signoff spec:
cd apps/iris/web/pwa && \
  E2E_BASE_URL=http://127.0.0.1:3030 \
    npx playwright test e2e/wcag-aa-signoff-v1-p2-3514-pwa.spec.ts \
      --project=chromium --workers=1 --reporter=list
```

The spec also works headlessly via `playwright.config.ts::webServer`, which
spins up `vite` automatically when `E2E_BASE_URL` is unset.

## Defense-in-depth

- V1-P2-3500 auto-axe `afterEach` fixture runs the document-wide axe pass after
  every test in this spec.
- V1-P2-3501 pa11y-ci nightly sweep covers the same routes.
- V1-P2-3502 Storybook a11y addon enforces per-component primitive axe.

V1-P2-3514 owns the consolidated PWA surface checklist; no per-surface specs
exist for the Iris PWA (V1-P2-3514 is the bootstrap signoff that also adds the
e2e infrastructure). Future per-flow specs (chat send, offline send,
share-target receive) inherit the same auto-axe contract.

## Infrastructure additions

V1-P2-3514's PWA portion bootstraps Iris PWA's e2e suite. Before this work,
`apps/iris/web/pwa` had no Playwright tests. The signoff added:

1. **Workspace registration** — `pnpm-workspace.yaml` now lists
   `apps/iris/web/pwa` (and the sibling `web/extension` and `web/widget`
   targets), so `pnpm install` resolves their devDependencies.
2. **Devtest deps** — `@playwright/test`, `@axe-core/playwright`, `axe-core`,
   `@oshun/testing` (workspace) added to
   `apps/iris/web/pwa/package.json::devDependencies` from the catalog.
3. **`test:e2e` script** — runs `playwright test` against `./e2e`.
4. **`playwright.config.ts`** — port 3030, reduced-motion default,
   `serviceWorkers: 'block'`, chromium project. `webServer` spins up vite
   automatically when `E2E_BASE_URL` is unset.
5. **`e2e/fixtures.ts`** — re-exports `axeAfterEach(base)` from
   `@oshun/testing/playwright`, matching the V1-P2-3500 pattern.
6. **`e2e/wcag-aa-signoff-v1-p2-3514-pwa.spec.ts`** — the spec above.

The same scaffolding will be re-used by future Iris PWA e2e specs.
