Eve library

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

Guide

Revision 1

On this page

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.