> 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/phase21-session06-responsive-layout-and-accessibility-pass/spec.md). # Session Specification **Session ID**: `phase21-session06-responsive-layout-and-accessibility-pass` **Phase**: 21 - Bottom Rail Focused Surface Expansion **Status**: Not Started **Created**: 2026-06-29 **Package**: apps/web **Package Stack**: TypeScript *** ## 1. Session Overview This session hardens the focused bottom-rail surfaces after Sessions 01 through 05 delivered the shared expansion state, same-instance host, Orchestration Command Center path, overlay layering, and Quest Board / War Room parity. The next product gap is practical usability across desktop and small browser viewports: expanded Quest Board, Orchestration, and War Room must be framed, reachable, scrollable where needed, keyboard-operable, and recoverable without clipping or overlapping controls. The work stays in `apps/web` and focuses on the shared host, shell layout, focused-surface tests, and browser evidence. It does not redesign unrelated cockpit panels, add new product capabilities, change backend orchestration semantics, or claim formal accessibility or mobile certification. The session is next because Phase 21 Session 07 is final regression and documentation, and the analyzer reports Sessions 01 through 05 complete while Session 06 remains the earliest unfinished executable session. *** ## 2. Objectives 1. Make the shared bottom-rail focused host size safely on small and desktop viewports without cockpit-grid clipping. 2. Preserve compact bottom-rail usability when no surface is expanded. 3. Harden dialog accessibility for labels, focus movement, focus containment, close controls, Escape, and scroll behavior. 4. Add focused automated and browser-visible evidence for Quest Board, Orchestration, and War Room expanded surfaces. *** ## 3. Prerequisites ### Required Sessions * [x] `phase21-session01-expansion-state-foundation` - Provides transient `expandedBottomRailSurfaceId` state. * [x] `phase21-session02-shared-expansion-host` - Provides the same-instance `BottomRailExpansionHost`. * [x] `phase21-session03-orchestration-command-center-expansion` - Provides Orchestration Command Center focused-surface behavior. * [x] `phase21-session04-shortcut-and-overlay-layering` - Provides layered Escape behavior through `overlayLayers`. * [x] `phase21-session05-quest-board-and-war-room-parity` - Provides Quest Board and War Room focused-surface parity. ### Required Tools Or Knowledge * React, TypeScript, Zustand, Tailwind utilities, Testing Library, Vitest, and Playwright. * Existing focused bottom-rail host in `apps/web/src/components/BottomRailExpansionHost.tsx`. * Existing cockpit shell layout in `apps/web/src/App.tsx` and `apps/web/src/components/Layout.tsx`. * Existing browser guard helpers in `tests/e2e/support/browserGuards.ts`. ### Environment Requirements * Local checkout with npm dependencies installed. * Local web app and e2e web servers can run through the existing npm and Playwright scripts. * No hosted credentials, Worker deployment credentials, provider keys, production environment, or formal accessibility audit tooling is required. *** ## 4. Scope ### In Scope (MVP) * A cockpit user can expand Quest Board, Orchestration, and War Room at desktop and small browser widths without the focused surface being clipped by the cockpit grid. * A keyboard user can enter the expanded surface, reach primary panel controls, close by explicit close control or Escape, and return focus to the opener. * Expanded surfaces contain scrollable panel content where needed while the background cockpit stays visually and behaviorally secondary. * Compact Quest Board, Orchestration, and War Room remain usable in the bottom rail when no panel is expanded. * Existing loading, offline, unavailable, local-only, and no-claim copy remains product-facing and visible. * Browser evidence records at least one desktop viewport and one small/mobile viewport for the three expanded surfaces. ### Out Of Scope (Deferred) * Full formal WCAG or mobile certification - Reason: this session creates practical local browser evidence only. * New mobile navigation systems - Reason: Phase 21 is scoped to bottom-rail focused surfaces. * New Quest Board, Orchestration, or War Room domain features - Reason: Sessions 03 and 05 already covered feature parity. * Backend execution, Worker protocol, hosted identity, production-hosted validation, trusted unified erasure, or remote execution changes - Reason: those are explicit no-claim boundaries outside this presentation pass. * Stable documentation closeout - Reason: Session 07 owns final docs and phase regression handoff. *** ## 5. Technical Approach ### Architecture Keep `BottomRailExpansionHost` as the single shared focused-surface contract. Tune the expanded wrapper so it uses viewport-safe inset, width, height, max-height, and overflow rules independent of the cockpit grid. Keep the child panel mounted once and make only the host presentation change between compact and focused states. Add lifecycle-scoped scroll containment and focus containment to the host while an expanded surface is active. The host should restore all acquired document/body state on close or unmount, and Escape should continue respecting higher overlay layers from `overlayLayers`. Use existing shell wrappers in `App.tsx` and `Layout.tsx` to keep compact bottom rail dimensions stable. Add tests in the same places where focused-surface behavior is already covered: host unit tests, shell integration tests, mobile accessibility tests, and the app Playwright suite with existing browser guard helpers. ### Design Patterns * Same-instance promotion: expand the existing mounted panel; do not render a duplicate Quest Board, Orchestration, or War Room tree. * Lifecycle cleanup: any document/body scroll lock or event listener is acquired only while a surface is expanded and released on close or unmount. * Accessible modal contract: expanded surfaces expose a dialog name, close control, focus restoration, keyboard dismissal, and contained tab order. * Practical browser proof: use automated viewport checks and screenshots as scoped evidence without implying formal certification. *** ## 6. Deliverables ### Files To Create | File | Purpose | Est. Lines | | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ---------- | | `.spec_system/specs/phase21-session06-responsive-layout-and-accessibility-pass/browser-verification.md` | Record desktop and small viewport browser evidence, screenshots, limitations, and no-certification boundary. | \~90 | ### Files To Modify | File | Changes | Est. Lines | | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `apps/web/src/components/BottomRailExpansionHost.tsx` | Tune viewport-safe focused sizing, scroll containment, focus containment, and cleanup behavior. | \~120 | | `apps/web/src/App.tsx` | Adjust bottom-rail host and shell classes so compact and focused modes keep stable dimensions. | \~40 | | `apps/web/src/components/Layout.tsx` | Refine bottom-rail grid overflow and small/desktop layout constraints only where needed. | \~30 | | `apps/web/src/index.css` | Add or refine shared focused-surface, scroll, or text-fit utilities used by the host. | \~40 | | `apps/web/tests/BottomRailExpansionHost.test.tsx` | Cover viewport-safe classes, scroll-lock cleanup, focus containment, and Escape behavior. | \~120 | | `apps/web/tests/CockpitShell.test.tsx` | Cover all three focused surfaces for accessible dialog behavior, compact fallback, and state preservation under layout changes. | \~150 | | `apps/web/tests/MobileAccessibility.test.tsx` | Add practical accessibility checks for focused bottom-rail labels, touch targets, focus return, and no certification copy. | \~120 | | `tests/e2e/app.e2e.ts` | Add desktop/mobile browser checks for expanded Quest Board, Orchestration, and War Room sizing, text fit, overlap, and screenshots. | \~160 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Expanded Quest Board, Orchestration, and War Room are visible within the viewport and not clipped by the cockpit grid at the tested desktop and small viewports. * [ ] Expanded panel content remains scrollable where needed without exposing an unusable blank, overlapped, or unreachable region. * [ ] Compact bottom rail remains usable with all three panels mounted once when no surface is expanded. * [ ] Close button, backdrop close, and Escape close return focus to the opener for all three surfaces. * [ ] Tab navigation stays inside the expanded surface during normal keyboard navigation while it is modal. ### Testing Requirements * [ ] `BottomRailExpansionHost` tests cover scroll lock cleanup, focus containment, sizing classes, and higher-layer Escape behavior. * [ ] `CockpitShell` and `MobileAccessibility` tests cover the three real shell surfaces and practical accessibility expectations. * [ ] App Playwright coverage records desktop and small viewport checks for all three expanded surfaces. * [ ] Focused Vitest, Playwright app projects, and web typecheck complete. ### Non-Functional Requirements * [ ] No duplicate Quest Board, Orchestration, or War Room panel tree is introduced. * [ ] No hosted identity, hosted collaboration safety, production-hosted validation, trusted erasure, formal WCAG, formal mobile certification, or remote execution claim is introduced. * [ ] Broad UI rows and screenshots do not expose raw prompts, command bodies, terminal output, file contents, diffs, Worker authority tokens, request bodies, secrets, replay buffers, exports, scan payloads, or broad absolute paths. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] Primary user-facing surfaces contain product-facing copy only. *** ## 8. Implementation Notes ### Working Assumptions * `apps/web` is the package context: the analyzer marks Session 06 as `apps/web`, the Phase 21 PRD identifies the relevant implementation under `apps/web`, and all deliverables touch web shell, component, CSS, test, or app e2e files. * Browser evidence can be implemented as Playwright coverage plus a session-local `browser-verification.md`: the Session 06 stub allows browser evidence or documented local verification, and the repo already uses Playwright app desktop/mobile projects plus browser guard screenshot attachments for scoped local browser evidence. * Formal certification remains out of scope: the master PRD, UX PRD, security record, and Session 06 stub all distinguish local browser accessibility evidence from full WCAG or mobile certification. ### Key Considerations * The current host already uses fixed positioning, a backdrop, dialog semantics, focus restore, guarded compact clicks, and higher-layer Escape checks; this session should harden those contracts rather than replace the architecture. * `Layout.tsx` currently uses a constrained desktop bottom row and a stacked small-viewport grid; compact mode must remain stable and scrollable after focused-mode changes. * Orchestration contains the largest focused surface, including Command Center tabs and nested drawers, so sizing and focus behavior must account for deeper content than Quest Board or War Room. * Browser checks should use product-facing surfaces and existing guard helpers instead of adding debug UI. ### Potential Challenges * Happy DOM cannot measure real layout; component tests should assert classes, focus behavior, and state while Playwright owns viewport geometry, overlap, and text-fit evidence. * Body scroll locking can leak if cleanup is tied only to one close path; cleanup must run on close, Escape, backdrop, one-surface-to-another transitions, and unmount. * Focus containment can conflict with nested overlays; higher overlay layers should keep Escape ordering and focus behavior intact. ### Relevant Considerations * \[P20] **Release evidence is the execution claim source**: Record local browser evidence before Session 06 is treated as complete. * \[P20] **Do not add action verbs before evidence**: Keep any UI label tied to already implemented focused-surface behavior. * \[P20] **Broad privacy gates are release-critical**: Browser evidence and visible text checks must not leak raw commands, output, diffs, file contents, tokens, secrets, provider payloads, or broad paths. * \[P03] **Stable docs are the current contract**: Defer stable docs updates to Session 07, but do not create behavior that would contradict the current no-claim boundaries. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Expanded surfaces look modal but allow focus to move behind them. * Body or cockpit scroll lock remains active after close or one-surface-to-another transitions. * Small viewport users cannot reach close controls or bottom content because the surface clips instead of scrolling. * Browser evidence accidentally broadens practical local accessibility checks into formal certification language. *** ## 9. Testing Strategy ### Unit Tests * Update `apps/web/tests/BottomRailExpansionHost.test.tsx` for focus containment, document/body scroll cleanup, expanded sizing classes, and higher-layer Escape behavior. * Update `apps/web/tests/CockpitShell.test.tsx` for real Quest Board, Orchestration, and War Room expanded-surface accessibility and compact-mode preservation. * Update `apps/web/tests/MobileAccessibility.test.tsx` for focused bottom-rail labels, close controls, focus return, and no formal certification copy. ### Integration Tests * Extend `tests/e2e/app.e2e.ts` to open Quest Board, Orchestration, and War Room in both app desktop and app mobile projects. * Use existing browser guard helpers for size, overlap, visible-text fit, privacy-safe text, and screenshot attachments. ### Runtime Verification * Run focused Vitest targets for `BottomRailExpansionHost`, `CockpitShell`, `MobileAccessibility`, `OrchestrationPanel`, `QuestBoard`, and `WarRoomPanel`. * Run `npm run typecheck --workspace @factionos/web`. * Run Playwright app desktop and app mobile coverage for the updated app e2e checks. ### Edge Cases * Close and reopen a focused surface after a background click opener and after the explicit focus button opener. * Press Tab and Shift+Tab from the first and last focusable controls in the expanded surface. * Open a higher overlay from expanded Orchestration and verify Escape does not close the parent surface first. * Switch directly from one expanded bottom-rail surface to another and verify scroll lock and focus state do not leak. * Verify no formal certification, hosted identity, trusted erasure, production-hosted, or remote execution claim appears in changed product surfaces. *** ## 10. Dependencies ### Other Sessions * Depends on: `phase21-session01-expansion-state-foundation`, `phase21-session02-shared-expansion-host`, `phase21-session03-orchestration-command-center-expansion`, `phase21-session04-shortcut-and-overlay-layering`, `phase21-session05-quest-board-and-war-room-parity` * Depended by: `phase21-session07-final-regression-and-documentation` *** ## Next Steps Run the `implement` workflow step to begin 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/phase21-session06-responsive-layout-and-accessibility-pass/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.