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

The master TODO requires:

> "Iris desktop / mobile / PWA."

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

## Surface coverage

| V1-P2-3514 desktop surface     | State                                   | Enforcing test                                                                      |
| ------------------------------ | --------------------------------------- | ----------------------------------------------------------------------------------- |
| Main shell with sidebar open   | TitleBar + Sidebar + ChatView           | `e2e/wcag-aa-signoff-v1-p2-3514-desktop.spec.ts` (case `main-shell-sidebar-open`)   |
| Main shell with sidebar closed | TitleBar + ChatView (sidebar collapsed) | `e2e/wcag-aa-signoff-v1-p2-3514-desktop.spec.ts` (case `main-shell-sidebar-closed`) |
| Preferences modal              | Open atop the main shell                | `e2e/wcag-aa-signoff-v1-p2-3514-desktop.spec.ts` (case `preferences-modal`)         |
| About modal                    | Open atop the main shell                | `e2e/wcag-aa-signoff-v1-p2-3514-desktop.spec.ts` (case `about-modal`)               |

## Verification result (2026-05-05)

4/4 tests pass against `apps/iris/desktop` running locally on port 1430 (Vite
dev server). Each test injects a Tauri 2.0 IPC stub via `page.addInitScript`
(see `e2e/support/tauri-mock.ts`) before navigation, emulates
`prefers-reduced-motion: reduce`, 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.

### Tauri IPC mock

The Iris desktop shell normally talks to a Rust backend via Tauri 2.0's
`@tauri-apps/api/core::invoke` and `@tauri-apps/api/event::listen`. In the
dev-mode browser those APIs read `window.__TAURI_INTERNALS__` at module load and
reject if it is undefined — the App's bootstrap `useEffect` chain
(`get_app_info`, `get_preferences`, `get_conversation_history`) silently fails
and the chat surface re-renders forever in its loading state. The mock at
`apps/iris/desktop/e2e/support/tauri-mock.ts` installs a minimal
`window.__TAURI_INTERNALS__` shape with deterministic responses for the four
boot commands and the optional commands the modals call (`update_preferences`,
`clear_history`, `send_message`, `capture_screenshot`). Event listeners are
no-ops returning a synchronous unlisten so the React `useEffect` cleanup runs
cleanly.

### Carve-out

Iris Desktop shares the V1-P2-3510..3513 cohort's color-token sub-AA pairs. 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 Iris
design tokens land.

### Precondition fixes

One real UX/a11y bug surfaced and was fixed before the gate could pass:

1. **About modal had no in-DOM trigger** — `apps/iris/desktop/src/App.tsx` wired
   `setShowAbout(true)` to a Tauri `show-about` event emitted by the OS-level
   menu. With no in-DOM trigger, keyboard users who never reach the OS menu (and
   assistive-tech users on Linux/Wayland where the system menu may be absent)
   had no path to the About surface. The
   `apps/iris/desktop/src/components/Sidebar.tsx` footer used to host only the
   Preferences button; the fix adds an "About" button next to it that calls a
   new `onShowAbout` prop, plumbed from `App.tsx` via `setShowAbout(true)`. The
   footer SVG icons additionally received `aria-hidden="true"` so axe doesn't
   double-count them as missing accessible names while their parent buttons own
   the visible label.

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

## Run command

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

# Run the signoff spec:
cd apps/iris/desktop && \
  E2E_BASE_URL=http://127.0.0.1:1430 \
    npx playwright test e2e/wcag-aa-signoff-v1-p2-3514-desktop.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 desktop surface checklist; no per-surface specs
exist for the Iris desktop shell (V1-P2-3514 is the bootstrap signoff that also
adds the e2e infrastructure).

## Infrastructure additions

Before this work, `apps/iris/desktop` had no Playwright tests. The signoff
added:

1. **Devtest deps** — `@playwright/test`, `@axe-core/playwright`, `axe-core`,
   `@oshun/testing` (workspace) added to
   `apps/iris/desktop/package.json::devDependencies` from the catalog.
2. **`test:e2e` script** — runs `playwright test` against `./e2e`.
3. **`playwright.config.ts`** — port 1430, reduced-motion default,
   `serviceWorkers: 'block'`, chromium project. `webServer` spins up vite
   automatically when `E2E_BASE_URL` is unset.
4. **`e2e/fixtures.ts`** — re-exports `axeAfterEach(base)` from
   `@oshun/testing/playwright`, matching the V1-P2-3500 pattern.
5. **`e2e/support/tauri-mock.ts`** — Tauri 2.0 IPC mock script (above).
6. **`e2e/wcag-aa-signoff-v1-p2-3514-desktop.spec.ts`** — the spec.
7. **`tsconfig.json`** path mapping for `@oshun/testing/playwright` so
   Playwright's TS loader resolves the workspace symlink without tripping ESM
   exports resolution. (Same fix landed in PWA tsconfig.)

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