> 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/public-website/docs/archive-docs_public-website/website_ux.md). # Website UX And Visual System This document describes the current FactionOS public website UX, visual language, accessibility posture, and motion rules. It is no longer a planning mockup note; it documents the implemented static Astro website. ## UX Goals The website should make a technical visitor understand the product quickly: * FactionOS is mission control for AI coding agents. * The default product posture is local-first. * The public website is static and does not collect visitor telemetry. * Demo and docs are separate destinations. * Product surfaces are concrete: cockpit, hooks, CLI, protocol, optional War Room, outbound adapters, and synthetic demo. The site should feel like a premium developer cockpit rather than a generic SaaS landing page. ## Product Experience Principles | Principle | Implementation | | ------------------------ | ------------------------------------------------------------------------------------------------------------------ | | Show product behavior | Static cockpit, battlefield, terminal, pipeline, feature matrix, and status panels show product concepts directly. | | Keep boundaries visible | Pages state what is local, optional, synthetic, static, pre-review, or no-claim. | | Prefer concrete copy | Copy describes hooks, mission state, approvals, timelines, replay, outbound adapters, and local data classes. | | Preserve privacy posture | No analytics, hosted forms, storage writes, cookies, or runtime network calls are part of the first-release site. | | Keep navigation direct | Header, mobile navigation, footer, demo, docs, and mailto actions are explicit and accessible. | ## Visual Identity The implemented style uses a cyber-tactical dark system: * dark neutral backgrounds * cyan, green, purple, warning, and critical state accents * crisp borders and bounded panels * terminal-like readouts * product-interface mockups * restrained static effects and reduced-motion fallbacks The dominant visual impression should be tactical command surface, not marketing template. ## Global Styling Global CSS lives in `src/styles/global.css` and owns: * reset and base layout rules * color tokens * typography tokens * spacing and radius tokens * focus states * responsive wrapping helpers * reduced-motion rules * shared decorative treatments Component CSS should remain scoped unless the style is a true global primitive. ## Typography The first-release site uses local/system font stacks. It does not load remote font providers. This preserves the static privacy boundary and avoids third party font requests. Future self-hosted brand fonts are deferred until source, license, byte budget, fallback behavior, and privacy review are recorded. ## Components Core layout and system components: * `BaseLayout.astro` * `ContentLayout.astro` * `LegalLayout.astro` * `PostLayout.astro` * `Shell.astro` * `Section.astro` * `Header.astro` * `MobileNavigation.astro` * `Footer.astro` * `SkipLink.astro` * `ButtonLink.astro` * `Badge.astro` * `Panel.astro` * `MetricStrip.astro` Marketing and page-specific components live under `src/components/marketing/`. Publishing components live under `src/components/content/`. ## Homepage UX The homepage first viewport must keep these visible: * FactionOS brand signal. * Product category: mission control for AI coding agents. * Static terminal/cockpit preview. * Demo CTA. * Docs CTA. * Static/no-collection boundary. Implemented homepage sections include: * hero cockpit * live status panel * battlefield preview * three-pillar deck * hook-to-cockpit loop * security boundary callout * latest blog/news preview * final CTA All readouts are deterministic static samples, not live telemetry. ## Product And Technical Pages `/product` explains the product surface map: * web cockpit * hook ingest * CLI * protocol * optional War Room * outbound adapters * static demo `/features` gives the feature inventory: * cockpit navigation * live roster * mission feed * battlefield map * mission detail * replay * approvals * file/tool timelines * prompt lifecycle * diagnostics * settings * orchestration deck * subagent lineage * outbound adapters * export * audit trail `/how-it-works` explains the pipeline: ``` Claude Code hooks / Codex CLI hooks / compatible producers -> JSON payloads -> local event ingest -> local server state -> WebSocket stream -> web cockpit -> optional outbound adapters or optional War Room ``` The website describes this pipeline; it does not execute it. ## Trust And Conversion Pages Use-case pages route four audiences: * engineering teams * AI platform teams * founders * power users Trust pages include: * `/security` * `/faq` * `/roadmap` * `/legal/*` Company and conversion pages include: * `/investors` * `/about` * `/contact` * `/press` These pages must stay conservative. Do not add unsupported hosted-service, commercial, legal, or certification claims. ## Motion Motion is decorative and should not be necessary for comprehension. Rules: * Continuous effects must respect `prefers-reduced-motion`. * Animated showcase media must have a static fallback where used. * Hover/focus transitions should be short and non-essential. * Do not add motion that causes layout shift or obscures content. * Do not add scroll-jacking or auto-playing interaction flows. `OptimizedMedia.astro` supports a reduced-motion fallback for media entries with a `fallbackKey`. ## Accessibility Rules The current site is designed around: * semantic `header`, `nav`, `main`, and `footer` * skip link to `#main-content` * one visible `h1` per page * readable heading order * visible focus states * accessible labels for nav, external links, controls, and media * non-color-only status copy * responsive text wrapping * reduced-motion support Legal and content pages use layouts that keep the `h1`, review state, and body structure consistent. ## Responsive Rules Validated target viewports: * 360px mobile * 768px tablet * 1280px desktop * 1600px wide desktop Implementation rules: * Grids collapse cleanly to one column on mobile. * Text uses standard relative sizing, not viewport-width font scaling. * Long words, code-like strings, buttons, and nav labels must wrap or fit. * Product previews should preserve shape without clipping important labels. * Footer and mobile navigation must remain reachable and keyboard-usable. ## Image UX Visible page media should use `OptimizedMedia.astro` unless there is a clear reason not to. Image requirements: * non-empty alt text * bounded responsive widths * lazy loading unless first-viewport priority is justified * reduced-motion fallback for animated showcase media * provenance or conditional status visible where needed * no press download link unless the file is launch-ready ## Content Tone Use: * specific product nouns * local-first boundary language * static/synthetic/optional labels * clear demo/docs/contact actions * concise technical explanations Avoid: * generic AI productivity claims * unverifiable metrics * hidden hosted-service implications * "certified", "compliant", or "production validated" language without proof * claims that prompts, paths, source files, credentials, replay data, or terminal output are uploaded by default ## UX Regression Checklist Run this after major layout, route, or content changes: * Header navigation works on desktop. * Mobile navigation opens, focuses a menu link, and closes with Escape. * Skip link receives focus first and moves to main content. * Demo and docs CTAs use the approved external destinations. * No horizontal overflow at 360px and 768px. * No text overlaps or spills out of buttons/panels. * Images load with useful alt text. * Reduced-motion fallback appears for animated showcase media. * Legal pages remain visibly pre-review. * Static/no-collection copy remains accurate. Then run: ```bash npm --workspace @factionos/public-website run typecheck npm --workspace @factionos/public-website run build npm --workspace @factionos/public-website run check:links ``` --- # 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/public-website/docs/archive-docs_public-website/website_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.