> 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/prd/prd_ux.md). # FactionOS UX Requirements This is the canonical UX requirements source for FactionOS. The stable docs-facing entry point `docs/PRD_UX.md` is a symlink to this file. The UX goal is a dense, local-first command cockpit: fast to scan, safe for sensitive developer data, clear about current runtime state, and responsive enough for supported desktop and mobile browser validation without pretending to be a hosted collaboration product. ## UX Status Vocabulary | Status | Meaning | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Shipped | Current source implements the UX behavior. | | Phase 02 | Current phase must refine or complete the UX behavior. | | Phase 03 | Completed local orchestration UX subset, with later hosted and executor surfaces deferred. | | Phase 04 | Completed media and audio/visual UX subset, with conditional media and later hosted/mobile surfaces deferred. | | Phase 05 | Completed optional War Room Worker UX subset, with later hosted identity, collaboration expansion, mobile certification, and erasure deferred. | | Phase 06 | Completed collaboration, isolation, mobile, and accessibility UX subset with local browser evidence and later hosted/certification/erasure work deferred. | | Phase 07 | Completed hosted-services and analytics guardrail UX subset as scoped local or disabled/unavailable copy; production-hosted validation, certification, and trusted erasure were routed to Phase 08 release hardening. | | Phase 08 | Release closeout UX evidence is complete and no-overclaim by default: local browser gates may pass while production-hosted deployment, hosted identity, formal certification, broad media readiness, and full trusted erasure remain no-claim unless explicitly proven in the release-candidate record. | | Deferred | Later phase owns the UX behavior. | | Excluded | UX must avoid implying the behavior exists. | | Evidence only | Historical UX material can inform gaps but is not authority. | ## UX Principles * Keep the cockpit operational, dense, and scan-friendly. * Prefer current runtime state over marketing copy or aspirational labels. * Make every state-mutating action explicit, reversible where practical, and protected against accidental duplicate actions. * Present local-first privacy boundaries at the point where data could leave the browser, local server, or local filesystem. * Preserve keyboard, pointer, screen-reader, and reduced-motion access for interactive surfaces. * Show clear failure paths instead of blank panels, infinite spinners, or generic errors. ## UX Requirement Structure Phase 02 implementation sessions must use these sections as the routing model: 1. Cockpit shell and navigation. 2. Hero roster, hero detail, and selection. 3. Mission log, mission detail, tags, and timeline. 4. Battlefield interaction and state visualization. 5. Overlays and global commands. 6. Permission and plan context. 7. Settings, notifications, replay, export, and scan UX. 8. Local orchestration controls. 9. Media and audio/visual experience. 10. Public demo experience. 11. Responsive, accessibility, and reduced-motion requirements. 12. Deferred and excluded UX. Phase 02 closeout evidence on 2026-05-29 validates the supported app and public demo desktop/mobile browser surfaces. The evidence includes nonzero battlefield dimensions, screenshots, browser guard assertions, fallback art states, public demo offline reload after one online visit, and a fixed small-viewport public demo header overlap. This is scoped product-surface validation, not a full WCAG certification or hosted collaboration validation. Phase 04 closeout evidence on 2026-05-29 validates the media and audio/visual subset on supported local app and public-demo browser projects. It covers failed image fallbacks, reduced-motion battlefield state, opt-in or gesture-compatible audio visible equivalents, public-demo speech/music failure paths, offline shell reload after one online visit, and browser guard assertions. This remains scoped media UX validation, not full WCAG certification, mobile certification, hosted collaboration validation, or production-hosted validation. Phase 05 closeout evidence on 2026-05-30 validates the optional War Room Worker UX subset on supported local app desktop/mobile browser projects. It covers disabled, diagnostics, join, pending, create, approved, connected, reconnecting, unavailable, and redacted remote-context states. This remains scoped local-browser validation, not full WCAG certification, mobile certification, hosted collaboration validation, trusted identity validation, or production-hosted app validation. Phase 06 Session 01 defines the collaboration, isolation, mobile, and accessibility UX baseline in `.spec_system/archive/phases/phase_06/collaboration_isolation_safety_baseline.md` and `.spec_system/archive/phases/phase_06/mobile_accessibility_acceptance_checklist.md`. Later UX changes must keep optional Worker transfer, local-only fallback, unavailable execution, hosted deferrals, and non-erasure wording visible. Phase 06 closeout evidence on 2026-05-30 validates the collaboration, isolation, and mobile UX subset on local app desktop/mobile Playwright projects. It covers room-local authority copy, redacted remote context, reconnect, leave/reset, unavailable Worker states, local orchestration, isolation posture, reduced motion, no-overlap checks, long-text wrapping, and mobile workpad reachability. This is scoped local-browser evidence with a local server and mocked or same-origin Worker paths. It is not full WCAG certification, physical-device mobile certification, hosted identity proof, hosted collaboration validation, production-hosted app validation, analytics validation, remote execution validation, public replay hosting validation, or trusted erasure. Phase 07 Session 01 creates documentation-only UX guardrails for hosted identity, analytics consent, public replay hosting, push, remote access, operator diagnostics, browser-visible config, local-only fallback, and unavailable states. Later Phase 07 UX work must keep hosted surfaces disabled or unavailable until consent, minimization, redaction, authorization, visible failure states, tests, and docs exist. Session 01 does not add hosted account UX, analytics dashboards, push delivery, public replay hosting, remote access, production-hosted validation, certification, or trusted erasure. Phase 07 Session 05 adds passive analytics status UX in Settings. The drawer may show disabled, unavailable, consent-required, opted-out, or ready guardrail copy and must revalidate on open. It must not add a tracking control, dashboard link, recorder, heatmap, session replay inspector, server ingestion claim, or account-backed consent store. Config values, website ids, API keys, or room authority are not consent, and opt-out must remain dominant over config and prior consent. Phase 07 Session 06 keeps push and remote-access UX local-only or unavailable: browser notifications stay opt-in and local, with no push subscription, VAPID, backend delivery, remote access, or tunnel UX presented as active. Phase 07 Session 07 closes out the phase. All hosted, analytics, push, remote-access, and operator-diagnostic UX described above is validated only as scoped local or disabled/unavailable guardrail copy. It is not hosted identity proof, analytics ingestion, push delivery, public replay hosting, production-hosted app validation, mobile certification, WCAG certification, or trusted erasure. Phase 08 Session 08 records local release-candidate evidence while those claims remain no-claim unless a release record proves them. ## Interaction Requirements * Primary interactions must expose native or platform-compatible controls: buttons for actions, radiogroups for exclusive modes, toggles or checkboxes for binary settings, text inputs for roots or filters, and dialogs for overlays. * Modal and drawer surfaces must have an accessible name, close affordance, Escape dismissal where implemented, and focus behavior that does not trap the user in a broken state. * Global commands must not steal input while the user is typing in form fields or editable content. * Selection state must remain synchronized across battlefield, roster, detail, and mission context. ## Visual Requirements * The cockpit should feel like an operations console, not a landing page. * Battlefield art must stay behind readable DOM labels, rings, buttons, and status treatment. * Product state should be visible through stable labels, chips, rings, badges, tables, and overlays instead of depending on color alone. * Quarantined historical media must not appear as current product art. ## Motion Requirements * Animations must communicate state without being required to understand state. * Reduced-motion settings and `prefers-reduced-motion` handling must keep equivalent static labels, colors, and state indicators visible. * Replays and achievement bursts must avoid feedback loops or duplicate state capture. ## Responsive Requirements * The cockpit must keep critical content reachable on desktop and mobile browser widths. * Text must not overlap controls, cards, labels, preceding content, or following content. * The 2D battlefield must maintain nonzero dimensions and a stable 16:9 board presentation where possible. ## Accessibility Requirements * Interactive controls need accessible names and visible focus states. * Dialogs and overlays need `role="dialog"` or equivalent semantics when they behave as modal surfaces. * Toggle groups need explicit selected state through `aria-pressed`, `aria-checked`, or native control state. * Data visualizations need text captions, labels, or summaries that communicate the same decision-making information. ## Cockpit Shell And Navigation UX * The first viewport must show the cockpit itself, not a marketing landing page. * The battlefield remains the central visual anchor, with mission and roster context close enough to support repeated scanning. * Rail content must scroll inside stable regions without pushing the entire cockpit into an unusable state on desktop. * Mobile layouts may stack, but the battlefield, mission list, roster, and critical controls must remain reachable without overlapping text or controls. * Connection state and local-server unavailability must be visible through status treatment and actionable copy. * Settings, keyboard help, command palette, heatmap, standings, leaderboard, tool usage, mission complexity, trophy room, and replay must be discoverable from stable controls or keyboard routes. ## Hero, Mission, Permission, And Plan UX * Hero selection must be consistent across battlefield tokens, roster cards, hero detail, and mission context. * Hero cards must provide compact state, active mission, metrics, and specialization cues suitable for quick comparison. * Hero detail must prioritize current work, recent history, and meaningful rollups over raw event dumps. * Mission rows must be keyboard-activatable controls, not inert rows that only work with a pointer. * Mission filters must make active filter state visible and reversible. * Mission detail must distinguish prompt summary, tool steps, timing, state, token/cost estimates, and failure information. * Permission and plan dialogs must show requester, action, rationale, expiration or pending state, and visible accept/reject outcomes. * If a permission or plan response is already resolved, the UI must not invite duplicate decisions. ## Battlefield UX * Battlefield hero tokens must be native buttons with accessible names that include hero name, faction, state, and active mission context when available. * Selected token state must use `aria-pressed` or equivalent state semantics. * Clicking empty board space may clear selection, but it must not interfere with token activation. * The board must provide a readable fallback background if the image fails. * Hero art failures must fall back to readable initials or another visible state treatment. * State rings, pings, labels, halos, and count badges must remain legible over the generated background. * Reduced motion must disable nonessential looping motion while keeping static labels, state colors, and selection treatment. * Achievement bursts must not block interaction, must be bounded, and must not become the only indicator of achievement state. ## Overlay And Global Command UX * Command palette results must use listbox/option semantics or equivalent keyboard behavior and must keep the active result visible. * Keyboard shortcuts must be grouped by workflow and must not override normal typing in inputs or editable content. * Heatmap, standings, leaderboard, tool usage, mission complexity, and trophy overlays must present ranked or grouped data with clear active metric state. * Visualization overlays must expose captions, table labels, or `aria-label` summaries so color or chart geometry is not the only information channel. * Overlay close buttons need explicit accessible labels. * Deep links or command routes into overlays must reset transient state after the intended open transition. ## Settings, Replay, Export, Notifications, And Scan UX * Settings controls must use recognizable controls: toggles for binary settings, radiogroups for theme, buttons for commands, and inputs for scan root values. * Analytics status in Settings must be passive copy only. It should distinguish disabled default, unavailable config, consent required, opt-out, and ready guardrail state without implying event capture, a dashboard, recorder, heatmap, session replay, server ingestion, or trusted erasure. * Notification controls must explain unsupported, default, denied, and granted browser permission states at the point of action. * Test notification actions must report blocked, throttled, denied, unsupported, or delivered outcomes through visible feedback. * Replay panel must show an understandable time axis, replay window controls, replay status, clear action, and failure handling for malformed shared links. * Shared replay links must communicate that replay data is redacted and local to the URL fragment, not uploaded. * Export UI must make CSV/JSON choice and local-server dependency clear and must surface failures without exposing raw payloads. * Scan UX must require an explicit root, explain approved-root restrictions, report start, success, issue count, and failure, and avoid leaking broad absolute-path detail in shared surfaces. ## Local Orchestration UX * Phase 03 orchestration controls now appear for the shipped local contracts only. Planned, typed-only, unsupported, stubbed, separate-surface, deferred, excluded, and evidence-only behavior must not be presented as available current UX. * Task queue and agent template controls must expose local pending, active, completed, rejected, unavailable, and failed states without implying hosted queues or remote workers. * Subagent lineage controls must show parent-child mission relationships where data exists and must degrade to clear missing or unavailable states when IDs are absent or malformed. * Guarded action controls must show requester, action family, rationale, expiry, pending state, decision state, unavailable state, failure state, and duplicate-decision protection. * Web controls must preserve keyboard, pointer, screen-reader, and reduced-motion access, with visible labels for destructive or sensitive local actions. * CLI diagnostics UX must summarize queue, template, lineage, guarded-action, hook, listener, and spool health without exposing raw prompts, command bodies, terminal output, tokens, broad absolute paths, transcripts, or raw state file contents. * Session 07 browser evidence validates the orchestration panel on desktop and mobile with local REST snapshots, empty lineage state, unavailable action state, local-only copy, and browser guard assertions. It is not full WCAG, hosted collaboration, or production-hosted validation. ## War Room UX * The War Room panel must keep shipped-versus-planned status explicit. Current web-to-Worker federation is available only as optional, redacted external transfer through a configured Worker URL; it must not imply hosted identity, hosted storage, analytics, public replay hosting, remote execution, or trusted erasure. * The web UX must expose local-only, unavailable, create, join, pending, approved, rejected, connected, reconnecting, caught-up, disconnected, and left states without blank panels. * Missing Worker URL, Worker downtime, room not found, room full, rate-limited requests, failed socket upgrade, stale approval, duplicate decision, rejected join, reconnect failure, and catch-up failure must produce visible bounded feedback. * Leader approval, rejection, reconnect, disconnect, and leave controls must guard duplicate actions while in flight and revalidate state on re-entry. * Participant names, colors, roles, and online flags are display metadata, not hosted identity or account proof. * Federated cockpit events must be compact and redacted. UI copy must not imply prompts, file contents, command bodies, terminal output, transcripts, secrets, broad paths, exports, replay buffers, media drafts, or scan payloads are safe to transfer. * Keyboard, pointer, and screen-reader users must be able to create or join a room, review pending participants, approve or reject a request, understand unavailable states, reconnect, disconnect, and leave the room. * Phase 06 collaboration UX changes must keep remote context visually separate from local hero, mission, queue, guarded-action, replay, export, notification, settings, adapter, scan, archive, memory, and media source-of-truth state. * Phase 06 closeout validates these states with local browser evidence only. Future hosted identity, hosted storage, analytics, public replay hosting, production-hosted validation, mobile or WCAG certification, and trusted erasure must remain later-phase UX claims until dedicated evidence exists. ## Phase 08 Release UX Gates * Phase 08 Session 01 baseline artifacts define UX release claim gates for local-first mode, optional Worker federation, hosted identity, hosted storage, analytics, public replay, push, remote access, trusted erasure, certification, production-hosted validation, media readiness, and legacy deletion. * Local erasure UX must use preview, explicit confirmation, progress, completed, partial-failure, unsupported, and verification states. Reset, leave, uninstall, diagnostics recovery, or browser-only cleanup must not be labeled trusted erasure. * Hosted identity UX must remain planned or unavailable unless a later session ships account flow, consent, revocation, authorization, audit, tests, docs, and local-only fallback. Worker authority and participant metadata must stay room-local and non-account-backed. * Mobile and accessibility evidence must name the surfaces, viewport classes, input methods, focus paths, labels, reduced-motion behavior, contrast, and text-fit criteria it covers. Automated evidence must not be described as formal WCAG certification or physical-device certification without matching proof. * Phase 08 Session 06 evidence lives in `.spec_system/archive/phases/phase_08/mobile_accessibility_certification_evidence.md`. It covers local Playwright app/public-demo desktop and mobile projects, focused component regressions, browser guard helpers, screenshot retention slots, and manual-review status. It is local browser and component evidence only, not formal WCAG certification, physical-device certification, third-party audit evidence, or production-hosted validation. * Production-hosted UX claims require deployed app, public-demo, or Worker evidence from Phase 08 Session 05. Local, mocked, same-origin, or browser-only evidence remains useful regression evidence, not deployed validation. * Decommission and media UX copy must keep historical material and conditional media candidate-only until Session 07 records approval and reruns affected gates. * Phase 08 Session 08 release-candidate evidence lives in `.spec_system/archive/phases/phase_08/release_candidate_validation_record.md`. It records passing local app and public-demo desktop/mobile Playwright evidence separately from deployed hosted smoke. The local browser evidence may support local UX regression confidence, but it must not be described as formal certification, physical-device validation, hosted identity proof, production-hosted validation, broad media readiness, or full trusted unified erasure. ## Media And Audio/Visual UX * Current battlefield art, portrait images, brand media, showcase media, public demo speech, and public demo music must be presented as current only where stable docs and the Phase 04 media matrix identify approved or conditional use. * Phase 04 closeout makes only the battlefield background and hero standee records release-ready. Portraits, brand, showcase, public-demo speech, public-demo music, generated references, and generated drafts must retain visible conditional or non-release blocker context in docs and UI copy. * Media loading, unavailable media, failed audio playback, denied browser playback, missing assets, and unsupported formats need visible states rather than silent failure. * Audio must never be required to understand product state. Voice lines, SFX, alerts, celebration audio, and music need captions, labels, toast feedback, static state, or another visible equivalent. * Browser audio must be opt-in or gesture-compatible and must expose stopped, playing, blocked, unavailable, and failed states through accessible controls. * Large or optional media should be lazy-loaded unless a documented public-demo service-worker decision explicitly precaches it. * Quarantined `EXAMPLES/` media must not appear as current product art, audio, screenshot evidence, or generated-media source input. * First-draft generated media from fal.ai, ElevenLabs, or later providers must be reviewed as non-runtime drafts first; runtime UI may reference it only after catalog, fallback, accessibility, privacy, and performance gates pass. * Full app audio remains synthetic Web Audio only. File-backed voice lines, SFX, alerts, celebration audio, music, HUD art, achievement icons, optional video, and expanded battlefield variants stay planned or deferred until a later UX scope validates source, rights, labels, captions, fallbacks, responsive behavior, and privacy. ## Public Demo UX * The public demo must open into the usable demo experience after its entry gesture and must remain understandable without a local server. * Demo copy must clearly distinguish synthetic data from real local sessions. * Demo battlefield behavior, visible state, and asset treatment must stay aligned with the full app when Phase 02 changes the battlefield contract. * Demo audio and music controls must remain opt-in or gesture-compatible with browser autoplay policies. * Demo media provenance, cache behavior, captions or visible equivalents, and lazy-loading decisions must remain documented before release. * Offline support must be validated after one online visit whenever the service worker precache list changes. Phase 04 closeout currently validates the demo shell cache version `factionos-demo-v9`. * Demo limitations must avoid implying War Room federation, real hooks, LLM endpoints, plan workpad, or persistent server state are available in the static artifact. ## Responsive, Accessibility, And Reduced-Motion Acceptance * Supported desktop and mobile viewport checks must verify nonzero battlefield dimensions, no overlapping text, reachable controls, and readable labels. * All interactive icon-only controls must have accessible names. * Button text and labels must fit within containers or wrap cleanly. * Focus order must allow a keyboard user to move through main shell controls, panel controls, overlays, and close actions. * Reduced-motion mode must be validated for battlefield states, command palette transitions, replay, achievement bursts, and any new animation. * Error states must be visible in the UI and testable without relying on console output. * Phase 06 mobile and accessibility changes must satisfy `.spec_system/archive/phases/phase_06/mobile_accessibility_acceptance_checklist.md` before validation closeout. * Phase 06 closeout evidence satisfies the local desktop/mobile acceptance checklist for changed surfaces, including the Plan Workpad mobile overflow fix found by Playwright, while formal certification remains out of scope. ## Deferred And Excluded UX * Do not present hosted account, hosted persistence, public replay hosting, or analytics dashboards as available current product UX. * Do not present analytics config, website ids, API keys, provider labels, or room-local authority as analytics consent. Settings may show passive disabled, unavailable, consent-required, or opted-out status only until a later session ships active capture with consent and payload evidence. * Do not present future push, remote access, hosted diagnostics, Supabase, Umami, VAPID, Cloudflare Tunnel, or hosted config placeholders as active UX until the owning Phase 07 session validates disablement, consent, minimization, redaction, authorization, and local-only fallback. * Do not present optional War Room federation as hosted collaboration, account-backed identity, mobile-certified collaboration, public replay hosting, analytics, remote execution, or trusted erasure. The Phase 05 UX must continue to preserve local-only and Worker-unavailable states. * Do not present inbound chat commands, generic webhook commands, remote execution, Docker isolation, hosted queues, shared queues, or public orchestration sharing as shipped Phase 03 UX. * Do not present guarded-action approval, diagnostics cleanup, leave, reset, or local recovery as execution or trusted erasure. * Do not present `EXAMPLES/` media, historical reports, or legacy build output as current product examples. --- # 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/prd/prd_ux.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.