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:
- 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 nohtmlFor/idlinkage to the control. Fix: addedid="settings-theme"to the select andhtmlFor="settings-theme"to the existing label. axe ruleselect-name. - Font Size select had no accessible name — same file, same pattern. Fix:
id="settings-font-size"+htmlFor="settings-font-size". axe ruleselect-name. - 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 inputid="settings-push-notifications"+aria-label="Push notifications", and made the wrapping<label>reference the same id viahtmlFor. axe rulelabel.
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#
# 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
afterEachfixture 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:
- Workspace registration —
pnpm-workspace.yamlnow listsapps/iris/web/pwa(and the siblingweb/extensionandweb/widgettargets), sopnpm installresolves their devDependencies. - Devtest deps —
@playwright/test,@axe-core/playwright,axe-core,@oshun/testing(workspace) added toapps/iris/web/pwa/package.json::devDependenciesfrom the catalog. test:e2escript — runsplaywright testagainst./e2e.playwright.config.ts— port 3030, reduced-motion default,serviceWorkers: 'block', chromium project.webServerspins up vite automatically whenE2E_BASE_URLis unset.e2e/fixtures.ts— re-exportsaxeAfterEach(base)from@oshun/testing/playwright, matching the V1-P2-3500 pattern.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.