> 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/phase16-session01-responsive-and-accessibility-hardening/spec.md). # Session Specification **Session ID**: `phase16-session01-responsive-and-accessibility-hardening` **Phase**: 16 - Quality, Deployment, And Launch Handoff **Status**: Not Started **Created**: 2026-06-02 **Package**: public-website **Package Stack**: Astro/TypeScript *** ## 1. Session Overview This session opens Phase 16 by hardening the static FactionOS public website for responsive behavior and accessibility before performance, automated gates, deployment, and launch handoff work begin. Phases 13-15 completed the Astro foundation, homepage, product story, trust pages, publishing surfaces, company pages, roadmap, FAQ, legal pages, and cross-link consistency pass. The next step is to verify that the complete first-release website works cleanly across mobile, tablet, desktop, wide desktop, keyboard, focus, contrast, semantic landmark, heading, mockup, and reduced-motion contexts. The work matters because Phase 16 should make the already-built website safe to launch at `https://faction-os.com/` without adding product surface area. The site must remain static, privacy-preserving, and separate from the zero-install demo and GitBook documentation while still being usable by keyboard users, small-screen users, screen-reader users, and users who request reduced motion. Implementation stays within `public-website` and the session evidence files. It should fix concrete responsive and accessibility defects found during the audit and record any remaining launch blockers. It must not add analytics, trackers, hosted forms, CMS behavior, auth, server-rendered website routes, runtime personalization, third-party embeds, or unsupported hosted-service claims. *** ## 2. Objectives 1. Audit all first-release routes at 360px, 768px, 1280px, and 1440px or wider, then fix overlap, clipping, unstable layout, and long-text overflow defects. 2. Verify and harden semantic landmarks, skip link behavior, one `h1` per page, ordered heading levels, and accessible names for links and controls. 3. Verify and harden keyboard-visible focus, mobile navigation behavior, CTA reachability, contrast, non-color-only state, and product mockup semantics. 4. Verify that `prefers-reduced-motion` disables continuous motion while preserving equivalent static labels, state, and product context. *** ## 3. Prerequisites ### Required Sessions * [x] `phase13-session01-astro-scaffold-and-workspace-wiring` through `phase13-session05-asset-pipeline-and-brand-media-prep` - static Astro workspace, layout shell, metadata, content collections, and media pipeline exist. * [x] `phase14-session01-hero-cockpit-and-primary-ctas` through `phase14-session05-features-and-how-it-works-pages` - homepage, product, feature, and how-it-works surfaces exist. * [x] `phase15-session01-use-cases-hub-and-role-pages` through `phase15-session06-cross-linking-and-copy-consistency-pass` - trust, publishing, company, contact, press, roadmap, FAQ, legal, and route/link consistency work is complete. ### Required Tools/Knowledge * Astro 6 static routes, layouts, scoped component styles, and content collections. * Existing `BaseLayout`, `Shell`, `Header`, `MobileNavigation`, `Footer`, marketing components, system primitives, and global CSS patterns. * Current route, CTA, and external destination constants in `public-website/src/data/site.ts` and `public-website/src/data/navigation.ts`. * Current no-claim boundaries from `.spec_system/CONSIDERATIONS.md` and `.spec_system/SECURITY-COMPLIANCE.md`. * Browser inspection at 360px, 768px, 1280px, and 1440px or wider. ### Environment Requirements * Node.js 26.2.0 or newer. * npm workspace commands available from the repository root. * Local website dev or preview server can run with `npm --workspace @factionos/public-website run dev` or `npm --workspace @factionos/public-website run preview`. * Package validation commands available: `npm --workspace @factionos/public-website run typecheck`, `npm --workspace @factionos/public-website run build`, and `npm --workspace @factionos/public-website run check:links`. *** ## 4. Scope ### In Scope (MVP) * Visitors can use all first-release routes at 360px, 768px, 1280px, and 1440px or wider without incoherent text overlap, clipping, horizontal spilling, or unstable layout. * Visitors can use header links, mobile navigation, footer links, CTAs, blog/news cards, legal pages, and route indexes with keyboard-visible focus and logical focus order. * Visitors using assistive technology receive semantic `header`, `nav`, `main`, and `footer` landmarks, working skip-link behavior, one `h1` per page, ordered heading levels, and useful accessible names. * Visitors can distinguish state without relying on color alone. * Visitors can read body text at contrast of at least `4.5:1`. * Visitors can understand product mockups through semantic HTML, useful alt text, nearby explanatory text, or accessible labels. * Visitors with `prefers-reduced-motion` do not receive continuous motion while static state labels and product context remain visible. * Long labels, legal copy, URLs, code-like content, and route names use wrapping rules such as `word-wrap: break-word;` and `overflow-wrap: break-word;` where needed. * Manual QA notes record checked routes, viewports, accessibility passes, fixes, and any launch blockers. ### Out of Scope (Deferred) * Formal WCAG certification - *Reason: this session performs launch hardening, not a third-party certification process.* * Third-party accessibility audit - *Reason: no external audit is required for this session scope.* * Deep performance optimization - *Reason: Phase 16 Session 02 owns performance and image optimization.* * Automated build-gate expansion - *Reason: Phase 16 Session 03 owns automated checks and build gates.* * Cloudflare Pages deployment setup - *Reason: Phase 16 Session 04 owns the deployment path.* * New pages, product features, hosted forms, analytics, auth, CMS, server rendering, runtime personalization, or third-party embeds - *Reason: Phase 16 hardens the existing static website for launch.* *** ## 5. Technical Approach ### Architecture Start with a route and component inventory so the audit covers the full first-release surface instead of only the homepage. Use the existing static Astro package structure: layout primitives handle landmarks and document structure, navigation components handle keyboard and mobile behavior, global CSS handles shared focus, wrapping, contrast, and reduced-motion rules, and marketing/content components handle route-specific mockups and proof panels. Responsive fixes should prefer stable constraints, intrinsic sizing, grid fallbacks, flex wrapping, and content wrapping over viewport-width font scaling or one-off overflow hiding. Accessibility fixes should use native HTML where possible, explicit labels where needed, visible focus treatment, semantic headings, and reduced-motion media queries. Keep the current static privacy boundary intact: no runtime analytics, no hosted form submission, no client-side collection, and no external transfer beyond explicit demo/docs/mailto links. Manual QA evidence should be recorded in the session implementation notes while the final validation workflow will own the formal validation record. If a defect cannot be fixed inside the session window, record it as a launch blocker with route, viewport, reproduction notes, and reason. ### Design Patterns * Shared responsive primitives: Fix repeated overlap and wrapping issues in global CSS or shared components before touching individual routes. * Semantic Astro layouts: Keep page landmarks, skip links, and heading flow in layout components where the route structure is shared. * Native interaction first: Use links and buttons with visible focus instead of script-only interaction surfaces. * Static equivalent for motion: Preserve labels, state chips, and summaries when continuous motion is disabled. * Registry-backed media semantics: Use the existing media registry and `OptimizedMedia.astro` pattern for alt text, dimensions, and provenance. * Evidence-led fixes: Audit, fix, and record route/viewport evidence in the session notes instead of making broad unverified rewrites. ### Technology Stack * Astro 6.4.2 static output. * TypeScript 5.9.3. * Node.js 26.2.0 or newer. * npm workspaces. * Existing Biome formatting/linting, Astro typecheck, package build, and package link checker. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ---------- | | `.spec_system/specs/phase16-session01-responsive-and-accessibility-hardening/implementation-notes.md` | Manual route, viewport, keyboard, contrast, heading, reduced-motion, and fix evidence recorded during implementation | \~160 | ### Files to Modify | File | Changes | Est. Lines | | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------ | ---------- | | `public-website/src/styles/global.css` | Shared wrapping, focus, contrast, reduced-motion, and responsive layout fixes | \~160 | | `public-website/src/layouts/BaseLayout.astro` | Landmark, skip-link, document structure, and main-content checks if needed | \~40 | | `public-website/src/components/navigation/SkipLink.astro` | Skip-link visibility and target behavior if needed | \~25 | | `public-website/src/components/navigation/Header.astro` | Desktop navigation focus, labels, wrapping, and current-link treatment | \~70 | | `public-website/src/components/navigation/MobileNavigation.astro` | Keyboard operation, state reset, labels, focus, and small-screen reachability | \~90 | | `public-website/src/components/navigation/Footer.astro` | Footer link wrapping, contrast, labels, and keyboard focus behavior | \~60 | | `public-website/src/layouts/ContentLayout.astro` | Content page heading flow, long-text wrapping, and route body semantics | \~45 | | `public-website/src/layouts/LegalLayout.astro` | Legal page heading flow, long-copy wrapping, and review-marker reachability | \~45 | | `public-website/src/layouts/PostLayout.astro` | Blog/news article heading flow, metadata semantics, and content wrapping | \~45 | | `public-website/src/components/system/ButtonLink.astro` | CTA accessible names, external labels, focus, and wrapping behavior | \~45 | | `public-website/src/components/content/PostCard.astro` | Blog/news card keyboard, focus, heading, and long-title behavior | \~45 | | `public-website/src/components/marketing/HeroCockpit.astro` | Homepage mockup semantics, labels, focus order, and reduced-motion behavior | \~90 | | `public-website/src/components/marketing/BattlefieldPreview.astro` | Battlefield preview labels, non-color-only state, fallback text, and motion behavior | \~90 | | `public-website/src/components/marketing/ProductProofPanels.astro` | Product mockup semantics, contrast, and static-sample labeling | \~70 | | `public-website/src/components/marketing/TerminalWindow.astro` | Code-like content wrapping, labels, and reduced-motion handling | \~45 | *** ## 7. Success Criteria ### Functional Requirements * [ ] No incoherent overlap, clipping, or horizontal spilling remains at 360px, 768px, 1280px, or 1440px or wider on first-release routes. * [ ] Header, mobile navigation, footer, CTAs, blog/news cards, and legal pages are reachable and usable with keyboard input. * [ ] Visible focus states are present for all links and controls. * [ ] `header`, `nav`, `main`, and `footer` landmarks are present where appropriate. * [ ] Skip link moves focus to the main content target. * [ ] Each page has one `h1` and ordered heading levels. * [ ] External links, icon-only controls, preview controls, and mobile navigation controls have useful accessible names. * [ ] Body text contrast is at least `4.5:1`. * [ ] State is not conveyed by color alone. * [ ] Product mockups have useful semantics, alt text, or nearby explanatory text. * [ ] `prefers-reduced-motion` disables continuous motion and preserves equivalent static context. ### Testing Requirements * [ ] `npm --workspace @factionos/public-website run typecheck` passes. * [ ] `npm --workspace @factionos/public-website run build` passes. * [ ] `npm --workspace @factionos/public-website run check:links` passes. * [ ] Manual QA covers 360px, 768px, 1280px, and 1440px or wider. * [ ] Manual keyboard, heading, landmark, focus, contrast, mockup semantics, and reduced-motion checks are recorded. ### Non-Functional Requirements * [ ] Public website remains static Astro output with no server adapter. * [ ] No new production dependencies are added. * [ ] No analytics, trackers, cookies, hosted forms, WebSockets, EventSource, runtime data collection, auth, CMS adapter, or third-party embed is introduced. * [ ] Existing no-claim boundaries for hosted identity, trusted erasure, production-hosted validation, and broad media readiness remain intact. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] No route, CTA, or external destination drift is introduced. * [ ] Launch blockers found during the pass are fixed or explicitly recorded. *** ## 8. Implementation Notes ### Key Considerations * Phase 16 should harden existing pages; avoid adding new content surfaces or product claims. * Route contract drift remains a launch risk, so navigation, links, and route labels should keep using shared data where practical. * Static website privacy boundaries remain active: no analytics by default, no hosted form submission, and no third-party runtime transfer. * Website media claims remain scoped. Use existing optimized media and provenance-backed patterns; do not promote conditional media by implication. ### Potential Challenges * Broad route coverage can exceed the session window: start from shared components and record unfixed route-specific defects as launch blockers. * Visual mockups may convey state through color or motion: add static labels, nearby explanations, and reduced-motion alternatives. * Mobile navigation may pass visually but fail keyboard operation: verify open, focus, activation, close, and re-entry behavior. * Long legal, route, or code-like strings can overflow at 360px: use shared wrapping rules before one-off route patches. ### Relevant Considerations * \[P15-public-website] **Route contract drift is a launch risk**: Keep route labels, navigation, content links, and the built-site checker aligned while hardening responsive/accessibility behavior. * \[P16-public-website] **Launch hardening is still ahead**: This session is the responsive/accessibility pass before performance, build gates, deployment, and launch evidence. * \[P13-public-website] **Static Astro boundary is intentional**: Keep the public website separate from `apps/web`, `public-demo`, and GitBook docs with no server adapter, React, Tailwind, CMS, auth, hosted forms, or analytics by default. * \[P13-public-website] **Registry-backed media is the website pattern**: Use centralized image semantics and fallback behavior where media components are involved. * \[P08] **Release evidence is claim-scoped**: Local accessibility and responsive evidence is not formal WCAG certification or production-hosted validation. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Mobile navigation, CTAs, and cards appear usable by pointer but fail keyboard focus, activation, close, or re-entry behavior. * Responsive fixes hide overflow instead of preserving readable text and reachable controls at mobile widths. * Motion, color, or decorative mockup imagery becomes the only way to understand state. * Static website changes accidentally add data collection, external transfer, or unsupported hosted-service claims. *** ## 9. Testing Strategy ### Unit Tests * No new unit tests are required for the MVP unless implementation adds or changes TypeScript helpers. If helper logic changes, add focused tests near the helper or extend the existing deterministic link checker coverage. ### Integration Tests * Run `npm --workspace @factionos/public-website run typecheck`. * Run `npm --workspace @factionos/public-website run build`. * Run `npm --workspace @factionos/public-website run check:links`. ### Manual Testing * Start a local dev or preview server and check home, product, features, how-it-works, use-cases, use-case detail pages, security, blog index, blog detail, news index, news detail, investors, about, contact, press, roadmap, FAQ, legal hub, privacy, terms, and acceptable-use routes. * Check each representative route at 360px, 768px, 1280px, and 1440px or wider. * Verify keyboard operation for header navigation, mobile navigation, footer links, CTAs, blog/news cards, legal links, and preview controls. * Verify reduced-motion behavior with browser emulation or OS preference. ### Edge Cases * Very long blog/news titles, legal labels, route names, URLs, and code-like terminal text. * Mobile navigation opened, closed, and reopened after route changes or focus movement. * External demo/docs/mailto links with visible labels and accessible names. * Product mockup image failure or reduced-motion state. * Users who rely on focus indicators, high zoom, narrow viewport, or color-blind perception. *** ## 10. Dependencies ### External Libraries * None new. Use the existing Astro, TypeScript, Sharp, and npm workspace dependency set. ### Other Sessions * **Depends on**: Phases 13, 14, and 15 completed. * **Depended by**: `phase16-session02-performance-and-image-optimization`, `phase16-session03-automated-checks-and-build-gates`, `phase16-session04-cloudflare-pages-deployment-path`, and `phase16-session05-launch-review-and-documentation-handoff`. *** ## 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/phase16-session01-responsive-and-accessibility-hardening/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.