Eve library

V1-P2-3514 — Iris Desktop WCAG 2.1 AA Signoff (desktop 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 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.