> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/sessions/phase08-session06-mobile-and-accessibility-certification-evidence/spec.md). # Session Specification **Session ID**: `phase08-session06-mobile-and-accessibility-certification-evidence` **Phase**: 08 - Release Hardening and Legacy Decommission **Status**: Complete **Created**: 2026-05-31 **Completed**: 2026-05-31 **Package**: apps/web **Package Stack**: TypeScript, React 18, Vite, Tailwind, Zustand, Vitest, Playwright app/public-demo browser projects, and release evidence docs *** ## 1. Session Overview This session produces release-grade mobile and accessibility evidence for the web cockpit and public demo surfaces that Phase 08 intends to claim. Sessions 01 through 05 established the release claim gates, trusted erasure contracts and controls, Worker room-state erasure boundaries, hosted identity no-claim wording, and production-hosted smoke validation. The next unresolved release risk is certification wording: existing Phase 06 evidence proves local browser behavior, but it is not formal WCAG certification, physical-device certification, or production-hosted validation. The work defines supported viewport, browser, input, reduced-motion, focus, dialog, screen-reader-label, contrast, text-fit, and fallback criteria. It then extends browser evidence for cockpit, War Room, settings, replay, export, scan, notifications, local erasure, public demo, and release-critical overlays. Any blocking issues found during evidence collection should be fixed narrowly in the owning web or public-demo surface. The output is evidence, not a broad redesign. Stable docs must clearly distinguish automated Playwright evidence, focused component tests, manual review, production-hosted smoke, and formal certification status. If no manual or third-party audit is performed, the release must make no formal WCAG or mobile-device certification claim. *** ## 2. Objectives 1. Define the Phase 08 mobile and accessibility release evidence criteria for supported app and public-demo surfaces. 2. Add or extend automated browser evidence for mobile, desktop, keyboard, focus, dialog, reduced-motion, text-fit, contrast, fallback, and no-overlap behavior. 3. Apply focused fixes for any release-critical overlap, unreachable control, missing label, focus return, reduced-motion, or fallback blocker found by the evidence pass. 4. Update UX PRD, release docs, web README, public-demo validation docs, and Phase 08 evidence notes without claiming formal certification beyond available proof. *** ## 3. Prerequisites ### Required Sessions * [x] `phase08-session01-release-requirements-and-risk-baseline` - provides certification claim gates, evidence vocabulary, no-overclaim wording, and S0806 routing. * [x] `phase08-session02-unified-erasure-contract-and-inventory` - provides unsupported-claim vocabulary that evidence docs must not reinterpret as trusted erasure. * [x] `phase08-session03-local-erasure-runtime-and-controls` - provides local/browser erasure controls that this session must include in web evidence without broad erasure overclaiming. * [x] `phase08-session04-war-room-and-hosted-identity-release-gate` - provides Worker erasure and hosted identity no-claim boundaries that War Room mobile evidence must preserve. * [x] `phase08-session05-production-hosted-validation-and-deploy-smoke` - provides production-hosted smoke evidence boundaries that must remain separate from local browser mobile/accessibility evidence. ### Required Tools/Knowledge * Phase 06 mobile/accessibility checklist: `.spec_system/archive/phases/phase_06/mobile_accessibility_acceptance_checklist.md`. * Current Playwright browser projects in `playwright.config.ts` and existing evidence tests in `tests/e2e/`. * Browser guard helpers in `tests/e2e/support/browserGuards.ts`. * Web package README and component/test patterns in `apps/web/README_web.md` and `apps/web/tests/`. * Public demo validation docs under `public-demo/docs_public-demo/`. * Phase 08 routing and risk artifacts in `.spec_system/PRD/phase_08/`. ### Environment Requirements * Node 20+ and npm workspaces installed. * Playwright browsers installed for the local environment. * Local app and public-demo e2e servers available through the existing Playwright `webServer` configuration. * No hosted auth, hosted storage, analytics capture, push delivery, remote access, Cloudflare Tunnel, provider credentials, or real executors required. *** ## 4. Scope ### In Scope (MVP) * Maintainer can cite a source-controlled evidence artifact that declares supported app and public-demo surfaces, viewport classes, browser projects, input methods, focus/dialog requirements, reduced-motion behavior, text-fit/overflow requirements, contrast review expectations, fallback states, automated evidence, and manual/formal certification limits. * Web cockpit release surfaces have automated desktop/mobile evidence for battlefield, mission rail, roster, title bar, settings, replay, export, scan, notifications, local erasure, War Room, command palette, keyboard shortcuts, and key overlays. * Public demo release surfaces have automated desktop/mobile evidence for splash, cockpit, battlefield, roster, mission log, music/voice visible equivalents, reduced motion, offline shell, synthetic-data limitations, and no local-server or War Room overclaiming. * Browser guard helpers can detect no horizontal overflow, focus visibility, element overlap, privacy leaks, service-worker readiness, text clipping, and contrast-critical visible text failures where feasible. * Targeted fixes are added only for release-critical evidence blockers found during the session. * UX PRD, release guide, web README, public-demo validation docs, and Phase 08 evidence notes distinguish automated evidence, manual review, local browser evidence, production-hosted smoke, and formal certification status. ### Out of Scope (Deferred) * Formal WCAG certification, VPAT creation, or third-party accessibility audit - *Reason: this session can record evidence only unless matching manual or third-party material exists.* * Physical-device mobile certification - *Reason: local browser projects and mobile emulation are not physical-device lab results.* * Broad visual redesign - *Reason: the phase owns release hardening, not product reskinning.* * Hosted auth, hosted storage, analytics capture, public replay hosting, Web Push, remote access, Cloudflare Tunnel, hosted diagnostic agents, or real executors - *Reason: all remain disabled, unavailable, planned, or out of scope unless a later scoped session activates them.* * Production-hosted validation claims - *Reason: Session 05 owns deployed smoke; this session owns mobile/accessibility evidence.* * Legacy evidence deletion or media promotion - *Reason: Session 07 owns decommission and media release gates.* *** ## 5. Technical Approach ### Architecture Extend the existing Playwright evidence path instead of creating a separate test runner. The current root `playwright.config.ts` already starts the local server, web app, and path-prefixed public demo, and it runs app/public-demo desktop and mobile projects. Add release evidence checks to the existing `tests/e2e/app.e2e.ts`, `tests/e2e/public-demo.e2e.ts`, and `tests/e2e/support/browserGuards.ts` surfaces so screenshots, browser guards, focus assertions, reduced-motion assertions, offline checks, and viewport projects remain centralized. Use focused React/Vitest tests in `apps/web/tests/MobileAccessibility.test.tsx` for component-level semantics that are cheaper and more deterministic than full browser paths: region labels, dialog naming, focus return, local-only copy, duplicate-action guard state, remote context labels, and no-overclaim wording. Add implementation fixes only where tests or screenshots expose a release blocker. Record an evidence artifact under `.spec_system/PRD/phase_08/` with the criteria, commands, evidence classes, screenshots/test outputs to retain, manual review checklist, exclusions, and residual risks. Documentation updates should make the same boundaries visible in release and package-facing docs. ### Design Patterns * Evidence-first hardening: extend assertions and screenshots before changing UI so fixes are tied to observed release blockers. * Native semantics: prefer buttons, inputs, labels, dialogs, aria state, focus return, and visible text equivalents over custom interaction contracts. * Local-first no-overclaim wording: every evidence note separates local browser validation from production-hosted validation, hosted identity, analytics, push, remote access, and trusted erasure. * Focused remediation: fix only release-critical overlap, focus, label, reduced-motion, fallback, or text-fit failures found during this pass. * Sanitized evidence: screenshots and docs must not expose raw prompts, paths, commands, tokens, room payloads, exports, logs, backups, replay buffers, or diagnostics. ### Technology Stack * React 18 and TypeScript in `apps/web`. * Tailwind and existing CSS in `apps/web/src/index.css`. * Zustand stores for settings, game state, War Room, and local erasure. * Vitest and Testing Library for focused component tests. * Playwright projects `app-desktop`, `app-mobile`, `public-demo-desktop`, and `public-demo-mobile`. * Markdown PRD, release, README, and public-demo validation docs. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `.spec_system/PRD/phase_08/mobile_accessibility_certification_evidence.md` | Phase 08 evidence criteria, command record, screenshots/manual review checklist, certification boundary, residual risks, and Session 08 handoff | \~180 | ### Files to Modify | File | Changes | Est. Lines | | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `tests/e2e/support/browserGuards.ts` | Add reusable text-fit, clipping, contrast-critical, and accessible-name evidence helpers where feasible | \~140 | | `tests/e2e/app.e2e.ts` | Add or extend release evidence for cockpit, settings, replay, export, scan, notifications, local erasure, War Room, focus, overlays, reduced motion, no-overlap, and screenshots | \~260 | | `tests/e2e/public-demo.e2e.ts` | Add or extend release evidence for splash, cockpit, mobile layout, audio visible equivalents, reduced motion, offline shell, synthetic limitations, and no-overclaim copy | \~180 | | `apps/web/tests/MobileAccessibility.test.tsx` | Add focused component regressions for labels, focus return, duplicate-action guard copy, local-only copy, and no-overclaim wording | \~180 | | `apps/web/src/components/Layout.tsx` | Apply targeted layout/text-fit fixes if evidence exposes release-critical reachability or overlap blockers | \~40 | | `apps/web/src/components/TitleBar.tsx` | Apply targeted control-label, touch target, focus, or text-fit fixes if evidence exposes blockers | \~40 | | `apps/web/src/components/SettingsDrawer.tsx` | Apply targeted settings, scan, notification, hosted analytics, or state re-entry fixes if evidence exposes blockers | \~60 | | `apps/web/src/components/ReplayPanel.tsx` | Apply targeted replay focus, malformed-link, empty-state, or local-fragment copy fixes if evidence exposes blockers | \~50 | | `apps/web/src/components/LocalErasurePanel.tsx` | Apply targeted local erasure wording, duplicate-trigger, focus, or state-reset fixes if evidence exposes blockers | \~60 | | `apps/web/src/components/WarRoomPanel.tsx` | Apply targeted War Room mobile, focus, duplicate-trigger, or no-overclaim fixes if evidence exposes blockers | \~70 | | `public-demo/index.html` | Apply targeted demo mobile, accessible-name, reduced-motion, visible-equivalent, or no-overclaim fixes if evidence exposes blockers | \~80 | | `.spec_system/PRD/PRD_UX.md` | Update UX evidence boundaries for Phase 08 Session 06 and no formal certification claim | \~80 | | `docs/release.md` | Add Session 06 evidence commands, supported coverage, certification no-claim wording, and residual risks | \~80 | | `apps/web/README_web.md` | Document release mobile/accessibility evidence boundaries for the web app | \~60 | | `public-demo/docs_public-demo/validation.md` | Add Session 06 public-demo evidence expectations and certification no-overclaim wording | \~70 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Supported app and public-demo release surfaces are usable on declared desktop and mobile viewport classes without incoherent overlap, unreachable critical actions, or horizontal overflow. * [ ] Dialogs, drawers, keyboard routes, focus return, visible focus, labels, reduced-motion states, and fallback states have automated release evidence or explicit manual review notes. * [ ] Local erasure, War Room, replay, export, scan, notifications, hosted guardrail copy, and public-demo limitations remain visible without implying hosted identity, production-hosted validation, analytics capture, push delivery, remote access, formal certification, or trusted unified erasure. * [ ] Evidence artifact records commands, evidence classes, screenshots to retain, unsupported claims, and residual risks. * [ ] Docs do not overclaim formal WCAG certification, physical-device certification, production-hosted validation, hosted identity, or trusted erasure. ### Testing Requirements * [ ] Focused `apps/web` mobile/accessibility component tests pass. * [ ] App desktop and app mobile Playwright evidence passes. * [ ] Public demo desktop and public demo mobile Playwright evidence passes. * [ ] Manual screenshot review is recorded or explicitly listed as not performed with no formal certification claim. ### Non-Functional Requirements * [ ] Core local-first workflows still work without hosted accounts, Cloudflare credentials, analytics, push, remote access, provider keys, tunnels, or real executors. * [ ] Browser-visible and tracked evidence does not expose raw prompts, file contents, commands, terminal output, tokens, local paths, room payloads, exports, logs, backups, replay buffers, scan payloads, diagnostics, provider output, or quarantined historical content. * [ ] Release wording distinguishes automated evidence from formal certification. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] `npm run format:check` or focused Biome check passes for changed code. * [ ] Focused Vitest and Playwright commands pass or blockers are recorded. * [ ] `git diff --check` passes. *** ## 8. Implementation Notes ### Key Considerations * The current Phase 06 evidence is strong local browser evidence, not formal certification. * Existing Playwright tests already cover the app and public demo desktop/mobile projects; this session should broaden release-critical assertions rather than duplicating runner setup. * Production-hosted smoke from Session 05 is a separate evidence class. Do not cite local mobile evidence as deployed app validation. * Public demo remains a standalone synthetic artifact and must not import workspace packages or imply local-server, War Room, hosted replay, or LLM endpoint behavior. * Local erasure controls from Session 03 and Worker erasure controls from Session 04 must remain scoped; mobile evidence must not call leave/reset or local cleanup trusted erasure unless the unified workflow evidence supports that exact claim. ### Potential Challenges * Browser evidence can be flaky if screenshots depend on active animations: mitigate with reduced-motion paths, stable selectors, deterministic seeded state, and `animations: "disabled"` screenshots. * Contrast evidence can be hard to automate completely: mitigate with automated checks for critical visible text where feasible and explicit manual review notes for remaining coverage. * Broad cockpit surfaces can make this session too large: keep fixes scoped to release-critical blockers and record nonblocking polish as residual risk for Session 08 or later work. * Long labels and mobile drawers can create layout shifts: use stable dimensions, wrapping/truncation, no horizontal overflow assertions, and focused screenshots. * Certification language can drift in docs: update release and UX docs with exact no-overclaim wording and test grep-sensitive language during implementation. ### Relevant Considerations * \[P02-apps/web] **Responsive and accessibility debt**: this session directly addresses mobile, focus return, dialog semantics, reduced motion, contrast, and accessibility validation for release-critical web surfaces. * \[P07] **Phase complete is not release complete**: this is a release evidence session, but Session 08 still owns final release-candidate closeout. * \[P07] **Redaction is boundary-specific**: screenshots, test output, and docs must avoid raw sensitive data and use bounded labels, counts, states, and evidence paths. * \[P03] **Stable docs are the current contract**: UX PRD, release docs, web README, and public-demo validation docs must state exactly what evidence supports. * \[P02] **Do not confuse browser validation with production-hosted validation**: local Playwright app/public-demo evidence is not deployed app or production-hosted proof. * \[Security] **P06-S07-HOSTED-IDENTITY**: War Room mobile evidence must keep room-local authority separate from hosted account identity. * \[Security] **P06-S07-ERASURE**: local reset, browser cleanup, Worker leave/reset, and focused erasure controls must not be overclaimed as full trusted erasure. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Evidence could pass while release docs overclaim formal WCAG or mobile-device certification. * Mobile controls could be visible but unreachable by keyboard, focus, or touch. * Dialogs, drawers, and reopenable panels could retain stale state or lose focus return after close/reopen. * Local erasure, War Room, hosted guardrail, replay, export, scan, or notification copy could imply hosted identity, production validation, analytics capture, push delivery, remote access, or trusted erasure. * Screenshots or test diagnostics could expose sensitive local values if guards are not applied consistently. *** ## 9. Testing Strategy ### Unit Tests * Extend `apps/web/tests/MobileAccessibility.test.tsx` for region labels, visible focus, dialog naming, focus return, local-only copy, duplicate-action guards, remote context labels, reduced-motion static state, and no-overclaim wording. * Add targeted component tests for any web component fixed during evidence gathering. ### Integration Tests * Extend `tests/e2e/app.e2e.ts` with release evidence across app desktop/mobile projects for cockpit, War Room, settings, replay, export, scan, notifications, local erasure, overlays, reduced motion, no-overlap, text-fit, and privacy-safe visible text. * Extend `tests/e2e/public-demo.e2e.ts` with release evidence across public-demo desktop/mobile projects for splash, cockpit, battlefield, audio visible equivalents, offline shell, mobile layout, keyboard reachability, reduced motion, and synthetic/no-server limitation copy. * Reuse `tests/e2e/support/browserGuards.ts` for no page errors, no console errors, no failed local requests, no failed local assets, no privacy leaks, overflow checks, focus visibility, service-worker readiness, and screenshots. ### Manual Testing * Review retained Playwright screenshots for desktop and mobile app/public-demo surfaces. * Record whether any keyboard-only, screen-reader-label, contrast, or physical-device checks were manually performed. * If no manual or third-party audit is performed, record that formal WCAG/mobile certification is not claimed. ### Edge Cases * Very long participant names, room codes, Worker URLs, diagnostics, mission titles, hero names, and error messages. * Reduced-motion mode with battlefield state, replay, overlays, reconnect, toast, achievement, speech, and music behavior. * Offline local server or unavailable Worker state. * Denied, unsupported, default, and granted browser notification permission states. * Malformed replay links and local fragment cleanup. * Local erasure dry-run, confirmation, partial-failure, and no-claim text. * Public demo service-worker offline reload after one successful online visit. * Mobile viewport with stacked rails, long labels, fixed toasts, dialogs, and bottom rail. *** ## 10. Dependencies ### External Libraries * `@playwright/test`: existing root e2e runner. * `vitest` and Testing Library: existing focused web test stack. * React 18, Vite, Tailwind, and Zustand in `apps/web`. ### Other Sessions * **Depends on**: `phase08-session01-release-requirements-and-risk-baseline`, `phase08-session02-unified-erasure-contract-and-inventory`, `phase08-session03-local-erasure-runtime-and-controls`, `phase08-session04-war-room-and-hosted-identity-release-gate`, `phase08-session05-production-hosted-validation-and-deploy-smoke` * **Depended by**: `phase08-session07-legacy-evidence-decommission-and-media-release-gate`, `phase08-session08-release-candidate-validation-and-documentation-closeout` *** ## Next Steps Run the implement workflow step to begin AI-led implementation. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/sessions/phase08-session06-mobile-and-accessibility-certification-evidence/spec.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.