> 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/design-intelligence-2026-07-05.md). # FactionOS Public Website Design Intelligence Date: 2026-07-05 Scope: design strategy, brand system, homepage blueprint, component system, tokens, copy direction, and implementation prompt for `https://faction-os.com/`. ## 1. Executive Design Verdict Recommended: make FactionOS feel like a premium tactical strategy game command center for AI-agent work. The site should open on an epic, product-like command table: agent lanes, mission objectives, replay rails, threat markers, approval gates, and local-first boundary signals. Animation, motion, unique effects, and distinctive type are not optional polish; they are part of the brand thesis. The gaming feel should come from interface language, cinematic motion, and an ownable command-HUD visual system, not fantasy art, weapon imagery, or decorative sci-fi noise. The conversion job is to make engineers believe, within the first viewport, that FactionOS turns chaotic multi-agent coding sessions into something observable, steerable, reviewable, and locally controlled. ## 2. Inputs, Assumptions, and Confidence Provided: * Existing FactionOS extraction docs under `docs/astro/sites/factionos-public-website/content/`. * Rendered homepage, product, features, how-it-works, security, use-case, contact, blog, and news snapshots. * Archived source components and CSS for the current Astro site. * User direction: "the website really should have an epic gaming feel to it while maintaining its relationship to ai agentics." * Follow-up direction: animation, motion, unique effects, and unique fonts should be a clear part of the design direction. * Approved cinematic hero asset bundle: [grounded-hero-02-room-cockpit / Veo 3.1 Fast](https://github.com/AI-with-Apex-VIP/factionos/tree/main/tmp/factionos-public-website-assets/cinematic-hero/generated/grounded-hero-02-room-cockpit/delivery/veo31-fast/README_delivery-veo31-fast.md). * Acquired media manifest: [acquired-media-asset-manifest-2026-07-05.md](https://github.com/AI-with-Apex-VIP/factionos/tree/main/public-website/acquired-media-asset-manifest-2026-07-05.md). * Live staged asset pack: `../../../../../tmp/factionos-public-website-assets/`. Observed: * Product description: "Local-first mission control for observing, steering, and coordinating AI coding agents across real development work." * Current site already uses command, cockpit, mission, battlefield, local-first, static sample, and boundary language. * Current CSS uses dark tactical colors, cyan/purple/green/crimson accents, Rajdhani/Outfit/JetBrains Mono, panels, terminal surfaces, status rings, and synthetic cockpit UI. * Current public website posture is static Astro output with no hosted forms, analytics, browser storage writes, runtime fetch, WebSocket, or visitor data collection in the first-release scan. * Asset inventory drift exists across the reviewed materials: the acquired markdown manifest records `117` staged files, the older JSON checksum manifest records `83`, and the live staging folder currently contains `128` files because the Veo delivery bundle has been added. Treat the live folder plus the delivery `SHA256SUMS.txt` as the implementation source of truth. Missing: * Final logo source files beyond the archived square brand mark reference. * Customer proof, product screenshots from a live install, pricing, install funnel details, OSS/community status, and launch-stage GTM decision. * Whether the site should push demo, docs, download, waitlist, or contact as the primary commercial action long term. Assumptions: * Primary page type: B2B/dev-tool homepage. * Primary conversion action for this pass: open the synthetic demo, then read docs. Secondary action: contact for partnership, security, investor, or product discussion. * Target audience: serious AI-assisted developers, engineering team leads, founders, AI platform teams, and power users running Claude Code, Codex CLI, or similar local agents. * Positioning: technical, premium, agentic, local-first, early-category, opinionated. * Visual ambition: very high. The current design should evolve from "cyber dashboard" into "cinematic strategy HUD for agent work," with a distinctive type system, an ownable hero animation, and motion/effects that make agentic state feel alive without slowing first paint. Confidence: high for direction and structure, medium for conversion priorities until product packaging and customer proof are finalized. ## 3. Archetype and Conversion Model Primary archetype: B2B SaaS / dev tool. Secondary archetypes: app/product UI and high-trust technical infrastructure. Audience state of mind: * They already know AI coding agents are powerful. * They are worried about invisible background work, lost intent, parallel session sprawl, unsafe automation, noisy logs, and sensitive local context. * They want more control without adopting a hosted control plane by default. Trust burden: high. The product touches prompts, local paths, command status, file activity, agent sessions, replay, adapters, and review states. The page must say exactly what does and does not leave the machine. Proof burden: high. "Mission control" is a strong claim. The site needs visible product-like proof early: agent lanes, review checkpoints, trace timeline, event contract, replay rail, and demo path. Primary conversion action: * Short term: Open Demo. * Secondary: Read Docs. * Tertiary: Contact. Emotional job: * Make agent work feel commandable, not mysterious. * Make the visitor feel like the operator of a powerful system, not a passenger watching terminal output. Functional job: * Explain what FactionOS is, how it works, what surfaces exist, what stays local, what is optional, and why the product category matters. ## 4. Research Summary Research sources used: * FactionOS current content and archived source under this docs folder. * Cursor: * Devin: * Devin Desktop: * OpenAI Codex: * Claude Code: * GitHub Copilot: * Amp: * LangSmith Observability: * Langfuse: * Braintrust: * Coralogix Code Agents Observability: * Cline: * Aider: * OpenCode: * Continue: and * Tabnine: Strong contenders analyzed: | Brand | Category | Observed CTA pattern | Observed top message | Useful pattern for FactionOS | | ------------- | ----------------------------------- | ----------------------------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | Cursor | AI coding agent | Download, get started, request demo | Coding agent for ambitious software | Product UI appears immediately; agent tasks are made visual; enterprise trust follows product proof. | | Devin Desktop | Agent command center / IDE | Download, sign up | Manage local and cloud agents from one surface | Strong direct fit: "agent fleet" management, kanban/session board, agent state labels. | | Devin | Autonomous software engineer | Try, download, contact sales | AI software engineer for serious teams | Enterprise case study and tool integrations create proof, but FactionOS should not overclaim customer outcomes. | | OpenAI Codex | AI coding partner | Explore Codex for work | Build and ship with AI | "Command center for agentic coding" and multi-agent workflows validate FactionOS category language. | | Claude Code | Agentic coding tool | Download, docs, sales | Agent that reads code, edits files, runs commands | Clear surface list: terminal, IDE, web, Slack. FactionOS needs similarly clear surfaces. | | Amp | Frontier coding agent | Get started, install | Built for leading models | Strong CLI-first confidence and changelog freshness. FactionOS can borrow freshness, not minimalism. | | LangSmith | AI agent observability | Start building, get demo | Know what agents are doing | Observability category language is direct: visibility, traces, SDK/framework integration. | | Langfuse | Open-source AI engineering platform | Start free, docs, demo | Trace and evaluate AI agents | Proof density: OSS/community stats, docs, changelog, self-hosting. | | Braintrust | AI observability/evals | Start building, talk to engineer | Ship quality AI at scale | Strong problem framing: AI fails differently, so you need a new observability layer. | | Coralogix | Code-agent observability | Get a demo, docs | Turn AI coding into measurable performance | Enterprise "usage, cost, code impact" framing helps FactionOS explain ROI without fake metrics. | | Cline | Open-source coding agent | Get started, docs/GitHub | Open coding agent | Strong developer trust from open-source, installs, stars, provider choice, and approval control. | | OpenCode | Open-source coding agent | Download, docs | Open-source AI coding agent | Privacy-first, multi-session, any-model positioning is relevant to FactionOS. | Contrast examples: | Brand | Why it is a contrast example | What FactionOS should avoid | | --------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | Aider | Credible terminal tool with sparse, older-feeling homepage structure. | Relying on terminal copy and OSS stats alone; FactionOS needs a more cinematic product surface. | | Continue current site | Transitional acquisition page, not a full product homepage. | Letting announcement or docs language replace product clarity. | | Generic observability pages | Often enterprise-polished but visually interchangeable. | Becoming another dark dashboard with logo strips, generic traces, and vague "visibility" copy. | Key observed patterns: * Winners show the product surface early, often above the fold or immediately after the hero. * AI coding tools increasingly sell "agent management," "parallel workflows," and "command center" rather than just autocomplete. * Observability tools lead with "know what your agents are doing," traces, evals, quality, cost, and control. * Developer tools use direct CTAs: download, install, start building, read docs, get demo. * Trust proof appears quickly for mature products: logos, customer stories, OSS stats, docs, pricing, security, audit controls. * Changelog, docs, and release freshness matter in this category because agents and models evolve quickly. Surprising finding: * The strongest competitors validate FactionOS' "mission control" framing, but few own the gaming/strategy-HUD aesthetic. That is the opportunity: FactionOS can become visually memorable by translating agent work into mission state, lanes, objectives, replay, and tactical decisions. ## 5. Winning Structure Map | Section pattern | Frequency among strong examples | Recommendation for FactionOS | | -------------------------------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | Product/outcome hero with immediate CTA | Universal | Must-have. Make the hero a command-table thesis, not just a headline. | | Product UI preview or video near top | Universal | Must-have. Show synthetic but product-like agent lanes and mission state. | | Docs/get started path | Universal | Must-have. Developers need a concrete next step. | | Capability groups/features | Universal | Must-have. Organize by operator job: observe, coordinate, review, contain. | | Security/privacy/control | Majority | Must-have for FactionOS. Put it after product proof, not as a disclaimer wall. | | Integrations/provider surfaces | Majority | Strong recommendation. Name Claude Code, Codex CLI, compatible producers, adapters. | | Customer logos/case studies | Majority for mature brands | Missing for FactionOS. Replace temporarily with proof-of-work, docs, demo, route parity, local boundary clarity. | | Changelog/blog/release freshness | Majority | Strong recommendation. Keep field notes visible but secondary. | | Pricing/contact sales | Split | Optional until packaging exists. Use contact intent routing instead. | | OSS/community stats | Split | Use only if true and current. Do not invent stars, users, or installs. | | Playable mission map | Missing opportunity | Use as FactionOS' signature differentiator. | | Explicit "rules of engagement" privacy model | Missing opportunity | Translate privacy boundaries into a game-like command contract. | Order logic: 1. Establish the category and fantasy: "mission control for AI coding agents." 2. Prove it visually with a command-table surface. 3. Explain how agent events become visible state. 4. Show the operator jobs the product supports. 5. State local-first controls and transfer boundaries. 6. Route by audience and next action. 7. Close with demo/docs/contact. Do this, not that: * Do: show a cinematic mission board that is clearly labeled synthetic. * Do not: lead with a long privacy caveat before the visitor understands the product. * Do: use gaming as an interface metaphor. * Do not: use soldiers, weapons, explosions, generic space art, or lore that obscures the product. * Do: keep every dramatic visual tied to an agentic concept: agents, lanes, objectives, traces, approvals, replay, handoff. * Do not: create neon decoration that could belong to any cyberpunk SaaS page. ## 6. Brand Guidelines ### Logo Guidance Observed: * Current header uses a square "FOS" mark and the FactionOS wordmark. * Archived hero references a square brand mark asset. Recommended logo direction: * Primary lockup: square faction insignia plus FactionOS wordmark. * Icon-only mark: angular tile, shield, or command-node geometry. It should feel like a game faction emblem and a developer-tool app icon at the same time. * Wordmark: wide, confident, engineered. Rajdhani or a custom condensed geometric sans can work if spacing is disciplined. * Clear space: at least one mark width around the icon; one cap-height around the wordmark. * Minimum size: icon no smaller than 32px in UI; wordmark no smaller than 112px wide. * Background pairings: obsidian, armory panel, or image/video areas with a dark scrim. Avoid placing cyan mark directly on bright cyan effects. * Unacceptable usage: stretched mark, glowing mark as decoration, low-contrast mark, weaponized/military insignia, or fantasy guild styling. ### Color Palette Use a dark command-room palette, but keep it from becoming one-note dark blue by mixing steel neutrals, cyan, green, amber, violet, and crimson in clear roles. | Token | HEX | RGB | Role | Emotional purpose | | -------------- | --------- | ------------- | --------------------------------- | --------------------------------------------- | | Void Black | `#07090F` | 7, 9, 15 | Page background | Deep game-menu atmosphere, maximum contrast. | | Obsidian Navy | `#0D121C` | 13, 18, 28 | Hero and section base | Technical depth without pure black harshness. | | Armory Panel | `#171E2A` | 23, 30, 42 | Cards, panels, HUD surfaces | Solid product UI foundation. | | Gunmetal Line | `#344154` | 52, 65, 84 | Borders, dividers | Industrial structure, scan-friendly grouping. | | Ice Text | `#F4F8FF` | 244, 248, 255 | Primary text | High confidence, WCAG-safe text. | | Tactical Slate | `#A9B4C3` | 169, 180, 195 | Secondary text | Calm technical readability. | | Reactor Cyan | `#18E8FF` | 24, 232, 255 | Primary CTA, focus, active lanes | Live system energy. | | Squad Green | `#23D77B` | 35, 215, 123 | Success, ready, local-first | Safe, ready, operator-approved. | | Signal Amber | `#F4B942` | 244, 185, 66 | Warnings, static sample labels | Caution without panic. | | Rift Violet | `#8B5CF6` | 139, 92, 246 | Review, queued, secondary CTA | Agentic/advanced state. Use sparingly. | | Critical Red | `#F0445E` | 240, 68, 94 | Risk, blocked, destructive states | Real risk and claim boundaries. | Usage ratios: * 70% Void/Obsidian backgrounds. * 18% Armory/Gunmetal structure. * 7% Ice/Slate text. * 5% accent states combined. Contrast guidance: * Body text on Obsidian must use Ice Text or Tactical Slate at AA contrast. * Reactor Cyan should not be used for long body text; reserve for UI state, links, active rings, focus, and CTAs. * Signal Amber and Critical Red need dark backgrounds and text labels, never color-only meaning. * Violet should never become the dominant brand color. ### Typography Recommended font roles: * Primary display: Oxanium, 700-800. Use for the hero lockup, section titles, mission labels, stat numerals, and command-table headings. The staged variable file supports `200 800`; do not request 900 unless a separate cut is later acquired. Oxanium has a squared game-UI feel without tipping into novelty. * Secondary display/UI: Rajdhani, 600-700. Use for compact HUD labels, nav, cards, badges, and dense command surfaces. This preserves continuity with the current site while giving the hero a more ownable face. * Body: Outfit, 400-650 from the staged asset pack. Use for readable product explanation. Geist remains a possible later upgrade only if a new font file is acquired and measured. * Mono/data: JetBrains Mono, 500-800. Use for terminal, event IDs, status badges, schema labels, coordinates. * Optional cinematic accent: Orbitron only for tiny HUD labels, route codes, or logo-adjacent marks. Do not set paragraphs or major headings in this face. Typeface implementation: * Self-host fonts. Do not depend on render-blocking third-party font delivery. * Use `font-display: swap` and preload only the two critical first-viewport font files. * Recommended production stack from the staged assets: Oxanium 700/800, Rajdhani 600/700, Outfit 400/500/650, JetBrains Mono 500/700. * If performance budget gets tight, keep Oxanium, Outfit, and JetBrains Mono; drop Rajdhani first. * Do not use default Inter-only SaaS typography. The type system must feel like FactionOS before any color or logo is visible. Type scale: | Role | Desktop | Mobile | Weight | Line height | Notes | | ------------- | ------- | ------- | ------- | ----------- | -------------------------------------------------------- | | H1 | 80-96px | 44-56px | 800 | 0.92-1.0 | Short and iconic. Avoid wrapping into more than 3 lines. | | Hero subtitle | 30-38px | 24-28px | 700/800 | 1.08 | Explain the category. | | H2 | 48-60px | 32-40px | 800 | 1.02 | Section thesis. | | H3 | 24-28px | 20-24px | 700 | 1.15 | Component headings. | | Body | 16-18px | 16px | 400/500 | 1.6-1.75 | Keep dense but readable. | | Small/UI | 13-14px | 12-13px | 600/700 | 1.35 | Buttons, badges, labels. | | Data/mono | 12-15px | 12-14px | 650/800 | 1.45 | Console and event rows. | Typography rules: * Use sentence case for readable labels. * Use uppercase only for compact HUD labels and badges. * Keep letter spacing at 0 unless an all-caps mono label needs slight tracking. * Do not scale font size with viewport width alone; use clamp values with hard min/max. * Make text fit all panels. Long labels should wrap cleanly, not shrink into illegibility. * Give the H1 a custom treatment: tight stacked words, bracket/corner framing, or a subtle inline coordinate mark. The unique type moment belongs in the hero, not in every heading. ### Voice and Tone Personality traits: * Commanding, not macho. * Technical, not academic. * Cinematic, not theatrical. * Precise, not timid. * Local-first and privacy-literate, not vague. Writing style: * Short declarative headlines. * Plain verbs: watch, steer, replay, approve, contain, inspect. * Specific nouns: agents, missions, lanes, hooks, snapshots, approvals, adapters, replay, local server. * Avoid hollow AI hype: revolutionary, magical, autonomous workforce, guaranteed, omniscient, zero-risk. * Avoid over-militarized language: kill chain, target, weaponize, enemy, battlefield dominance. CTA language: * Primary: Open Demo. * Secondary: Read Docs. * Contextual: Inspect Product Map, Follow Hook Flow, Review Security Boundary, Contact FactionOS. * Avoid: Learn More as the only repeated CTA. Tone by context: * Homepage: cinematic and clear. * Product/service pages: concrete surface maps. * Security: plain boundaries, no borrowed assurance. * Docs: exact setup language. * Contact: route intent cleanly. * Error states: state what failed and what to do next. ### Imagery and Graphics Recommended visual system: * Signature image/motion: a full-width strategy-game command table showing three to five agent lanes moving across a mission map. * Approved hero media for this pass: [grounded-hero-02-room-cockpit / Veo 3.1 Fast](https://github.com/AI-with-Apex-VIP/factionos/tree/main/tmp/factionos-public-website-assets/cinematic-hero/generated/grounded-hero-02-room-cockpit/delivery/veo31-fast/README_delivery-veo31-fast.md). Use it as the poster-first cinematic command-room plate, with semantic page copy and CTAs over the dark copy-safe zone. * Product mockups: crisp cockpit UI, not blurry screenshots. Use synthetic data until real captures are approved. * Gaming references: tactical map, party/squad roster, objective tracker, replay timeline, minimap, status rings, cooldown/queue bars, command console. * AI-agent references: hook event, prompt lifecycle, tool request, file touch, validation gate, approval, outbound adapter, local snapshot. * Motion: scanlines, lane progress, event pulses, map panning, replay scrub, hover magnification on mission nodes. * Reduced motion: static poster frame with all information present. * Icon style: 1.75px to 2px stroke, angular, technical, Lucide-compatible where possible. Avoid: * Stock photos of developers. * Generic robots, brains, magic sparkles, gradient blobs, blurred orbs. * FPS/war imagery, explosions, soldiers, guns, skulls, or dystopian scenes. * Fake customer dashboards or fake live telemetry. * Product UI so small that it reads as decoration. ### Acquired Asset Usage Map Staging source root: `../../../../../tmp/factionos-public-website-assets/`. Do not promote the whole staging folder. Promote only the assets listed as production use, keep provenance and QA files out of the public build, and preserve the generated media READMEs in project docs or implementation notes when the site workspace is created. Reviewed sources: * Asset manifest doc: [acquired-media-asset-manifest-2026-07-05.md](https://github.com/AI-with-Apex-VIP/factionos/tree/main/public-website/acquired-media-asset-manifest-2026-07-05.md). * Top-level staging README: `README_factionos-public-website-assets.md`. * Hero delivery README: `cinematic-hero/generated/grounded-hero-02-room-cockpit/delivery/veo31-fast/README_delivery-veo31-fast.md`. * Category READMEs for brand, fonts, HUD icons, social images, synthetic data, and grounded hero sources. Production asset map: | Asset source | Production use | Promote to eventual Astro site | Notes | | ---------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `brand/factionos-lockup.svg` | Header navigation, footer, hero brand lockup if a full wordmark is needed. | `src/assets/brand/factionos-lockup.svg` or an inline Astro/SVG component. | Provisional. The wordmark is live SVG text; outline it before publishing a public brand-download kit. | | `brand/factionos-mark.svg` | Full-color command-node mark for hero, nav compact state, feature seals, and social source composition. | `src/assets/brand/factionos-mark.svg`. | Use on obsidian/armory backgrounds with restrained glow only from CSS state, not baked decoration. | | `brand/factionos-mark-mono.svg` | Single-color mark for masks, currentColor UI use, favicons, footer/legal surfaces, and compact command badges. | `src/assets/brand/factionos-mark-mono.svg` and derived `public/favicon.svg` if approved. | Good for state-color inheritance; do not use as repeated decorative wallpaper. | | `brand/factionos-app-icon.svg` | App/PWA icon source and square social/avatar fallback. | `public/icons/factionos-app-icon.svg`; derive raster favicon/PWA sizes during implementation. | Source asset only until final icon export sizes are generated. | | `fonts/woff2/oxanium-latin-wght-normal.woff2` | H1, section titles, mission labels, stat numerals, and command-table headings. | `public/fonts/factionos/oxanium-latin-wght-normal.woff2`. | Critical above the fold; preload with `font-display: swap`. | | `fonts/woff2/outfit-latin-wght-normal.woff2` | Body copy, long-form explanations, FAQ, footer, and readable product prose. | `public/fonts/factionos/outfit-latin-wght-normal.woff2`. | Critical above the fold; preload with Oxanium. | | `fonts/woff2/rajdhani-latin-700-normal.woff2` and `rajdhani-latin-600-normal.woff2` | Dense HUD labels, nav, badges, capability cards, command chips, and compact panel headings. | `public/fonts/factionos/`. | Rajdhani 800 is not staged; use 700 for strong HUD labels and 600 for smaller UI. Do not preload unless measured as first-viewport critical. | | `fonts/woff2/jetbrains-mono-latin-wght-normal.woff2` | Event rows, route IDs, status chips, code/protocol snippets, and accessible data tables. | `public/fonts/factionos/jetbrains-mono-latin-wght-normal.woff2`. | Do not preload unless the final hero renders mono data labels above the fold and performance allows it. | | `fonts/woff2/orbitron-latin-wght-normal.woff2` | Optional tiny accent for route codes, logo-adjacent marks, or rare cinematic HUD labels. | Promote only if used: `public/fonts/factionos/orbitron-latin-wght-normal.woff2`. | Default decision: do not promote. Oxanium/Rajdhani already carry the identity. | | `fonts/font-face.css` and `fonts/preload-snippet.html` | Implementation references for global CSS and `` font preload. | Merge into site global CSS/layout head; do not ship as standalone content. | Keep licenses and Fontsource metadata in docs or asset provenance, not in the public route tree unless required. | | `cinematic-hero/generated/grounded-hero-02-room-cockpit/delivery/veo31-fast/public/hero/*.mp4` and `*.webm` | Section 1 cinematic command hero video sources. | `public/hero/factionos-grounded-hero-02-room-cockpit.av1.mp4`, `.vp9.webm`, `.h264.mp4`. | Preferred launch bundle. 1920x824, 5s, 24fps, audio stripped, about 3.25 MB combined. No `autoplay`; start only when in view and motion is allowed. | | `cinematic-hero/generated/grounded-hero-02-room-cockpit/delivery/veo31-fast/src/assets/hero/*poster.avif` and `*poster.webp` | Hero first paint, video poster, and reduced-motion still. | `src/assets/hero/factionos-grounded-hero-02-room-cockpit-poster.avif` and `.webp`. | Import AVIF through Astro assets and preload it for the first viewport. WebP is fallback. | | `cinematic-hero/generated/grounded-hero-02-room-cockpit/delivery/veo31-fast/SHA256SUMS.txt` | Copy verification during implementation. | Keep in implementation notes or docs; not a public asset. | Use after copying delivery files out of `tmp`. | | `cinematic-hero/generated/grounded-hero-02-room-cockpit/delivery/veo31-fast/preview.html` and `qa/*` | Local visual QA: loop, crop, contact sheet, seam preview. | Do not promote into the public site. | Use before launch QA only. | | `cinematic-hero/grounded-v2/*.png` | Art-direction reference and future still/video rerender source candidates. | Do not promote for this first pass. | `02-room-cockpit` is the selected source for the approved video. `01`, `03`, and `04` remain alternatives for future A/B or redesign work. | | `cinematic-hero/factionos-cinematic-hero-*-source.png` | Older cinematic source candidates. | Do not promote. | Keep as historical source material only. | | `cinematic-hero/generated/grounded-hero-02-room-cockpit/processed/veo31-fast/*` | Provider working set behind the delivery bundle. | Do not promote when using the packaged delivery files. | Useful if delivery must be regenerated or audited. | | `cinematic-hero/generated/grounded-hero-02-room-cockpit/processed/seedance20/*` | Alternate smaller, subtler hero variant. | Promote only if explicitly choosing Seedance instead of Veo. | Do not ship both provider sets unless A/B testing is explicitly planned. | | `cinematic-hero/generated/grounded-hero-02-room-cockpit/raw/*` and `metadata/*` | Generation provenance, prompts, provider records, request summaries, and failed-call evidence. | Keep in docs/provenance only; never public runtime. | Useful for auditability and future generation work. | | `hud-icons/*.svg` | Custom currentColor command-HUD icons across mission map, feature cards, flow diagrams, rules, routes, and CTAs. | `src/icons/hud/` or inline Astro SVG components. | Replace individual icons with Lucide equivalents only when the standard icon communicates the same job as clearly. | | `synthetic-data/mission-state.json` | Deterministic data source for hero, mission board, replay rail, provider examples, and accessible list/table fallbacks. | `src/data/factionos/mission-state.json` or equivalent typed data module. | Keep visible label: "Synthetic demo data. No visitor telemetry." One data source should drive both animated UI and accessibility fallback. | | `social/og-default.svg`, `.png`, `.webp` | Default/homepage social preview. | Source in `src/assets/social/`; final generated output in `public/og/og-default.png` or `.webp`. | Regenerate launch rasters after final fonts are wired. Current PNG/WebP are previews. | | `social/og-product.svg`, `.png`, `.webp` | Product, features, demo, and how-it-works social preview. | Same social pipeline as default. | Keep copy aligned with product surface, not fake telemetry. | | `social/og-security.svg`, `.png`, `.webp` | Security, rules-of-engagement, privacy/boundary social preview. | Same social pipeline as default. | Use boundary language and avoid compliance claims. | | `social/og-docs.svg`, `.png`, `.webp` | Docs, blog/news, field notes, changelog, and technical reference social preview. | Same social pipeline as default. | Regenerate after font pipeline is final. | | `manifests/asset-manifest.json` | Original checksum and byte-size reference for the staged pack. | Do not promote into site runtime. | It records an older 83-file view and does not cover the current delivery bundle; use it only as provenance. | | `README_*.md`, `licenses/*`, `metadata/*` | Implementation provenance, licenses, generation records, and staging notes. | Keep in docs or implementation handoff. | These are not public page assets. | HUD icon placement: | Icon | Primary UI use | | ----------------------- | ------------------------------------------------------------------ | | `agent-node.svg` | Agent lane cards, mission map nodes, role routes. | | `hook-event.svg` | Hook-To-Cockpit Flow, event timeline, signal relay rows. | | `approval-gate.svg` | Review checkpoint, optional exit gates, Rules Of Engagement. | | `replay-marker.svg` | Mission Board Product Proof, replay rail, Field Notes. | | `local-boundary.svg` | Local-first badges, Rules Of Engagement, provider boundary labels. | | `risk-marker.svg` | Operator Problem, risk/warning states, blocked data classes. | | `adapter.svg` | Provider And Adapter Surface, outbound destinations. | | `mission-objective.svg` | Hero objective panel, capability deck, final command CTA. | | `status-ring.svg` | Hero state rings, mission board status, health/ready indicators. | | `operator-command.svg` | Primary command affordances, final CTA console, operator route. | Section-to-asset mapping: | Section | Required assets | Optional/support assets | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- | | 1. Cinematic Command Hero | Veo delivery video sources; AVIF/WebP poster; `factionos-lockup.svg` or `factionos-mark.svg`; Oxanium, Outfit, Rajdhani; `mission-state.json`; `mission-objective.svg`, `agent-node.svg`, `status-ring.svg`, `operator-command.svg`. | `risk-marker.svg`, `approval-gate.svg`, `local-boundary.svg`; `preview.html` and `qa/*` for QA only. | | 2. The Operator Problem | `risk-marker.svg`, `hook-event.svg`, JetBrains Mono for log fragments. | `mission-state.json` rows can power before/after examples if labels stay synthetic. | | 3. Mission Board Product Proof | `mission-state.json`; `agent-node.svg`, `status-ring.svg`, `replay-marker.svg`, `approval-gate.svg`, `risk-marker.svg`, `mission-objective.svg`. | Use hero poster as faint background texture only if it does not reduce inspectability. | | 4. Hook-To-Cockpit Flow | `hook-event.svg`, `adapter.svg`, `local-boundary.svg`, `approval-gate.svg`; JetBrains Mono for protocol snippets. | `mission-state.json` event types for examples. | | 5. Capability Deck | HUD icon set: `agent-node`, `mission-objective`, `approval-gate`, `local-boundary`, `adapter`, `risk-marker`. | `status-ring.svg` for active/ready capability state. | | 6. Rules Of Engagement | `local-boundary.svg`, `risk-marker.svg`, `approval-gate.svg`; `mission-state.json` for sample sensitive data classes. | `status-ring.svg` for default/optional/blocked/no-claim chips. | | 7. Role Routes | `operator-command.svg`, `agent-node.svg`, `mission-objective.svg`. | Role cards can reuse the mark as a tiny route seal, not a repeated decoration. | | 8. Provider And Adapter Surface | `adapter.svg`, `hook-event.svg`, `local-boundary.svg`; JetBrains Mono protocol labels. | `approval-gate.svg` for optional exits. | | 9. Field Notes And Roadmap | `replay-marker.svg`, `mission-objective.svg`; `og-docs` social source for related pages. | No hero video reuse unless a specific article needs it. | | 10. Final Command CTA | `factionos-mark.svg` or mono mark; `operator-command.svg`; Oxanium/Rajdhani CTA labels. | `status-ring.svg` for command-ready affordance. | | Global SEO/social | `og-default`, `og-product`, `og-security`, `og-docs`; brand mark; final font pipeline. | Regenerate social rasters after fonts are in the actual site build. | ### Motion And Effects System Motion thesis: FactionOS should feel alive because agent state is alive. Animation should make work legible: a hook event arrives, a lane advances, a review gate opens, a risk marker warns, and an operator command changes the board. The signature effect is not "neon movement"; it is a cinematic mission system waking up and continuously explaining agentic work. Signature hero effect: Mission Boot Sequence. Approved motion plate: * Use the Veo 3.1 Fast `grounded-hero-02-room-cockpit` bundle as the production hero media for the first implementation pass: [delivery README](https://github.com/AI-with-Apex-VIP/factionos/tree/main/tmp/factionos-public-website-assets/cinematic-hero/generated/grounded-hero-02-room-cockpit/delivery/veo31-fast/README_delivery-veo31-fast.md). * The plate carries the command-room signature effect: a cyan mission core / HUD emitter waking the cockpit. Preserve the dark left-side copy-safe region and keep all H1, body copy, CTAs, badges, and synthetic labels as real HTML. * Delivery properties: `1920x824`, `5s`, `24fps`, audio stripped, AV1/VP9/H.264 sources totaling about `3.25 MB`, AVIF poster about `64 KB`. 1. Cold start: the command grid fades in from black, coordinate ticks calibrate, and the FactionOS mark resolves with a restrained cyan edge-light. 2. Agent deployment: three to five agent lanes enter the mission board as distinct nodes with role labels such as Plan, Build, Review, Risk, and Operator. 3. Event ingestion: a hook event flashes on the timeline, draws a line to the active lane, and updates the objective state. 4. Review checkpoint: a violet or amber gate pauses one lane, showing that the human operator remains in control. 5. Command ready: the Open Demo CTA becomes active after the board settles. Hero timing: * Total perceived boot: 900-1400ms, then settle. * No important text waits for animation. Copy and CTAs should be readable immediately. * The hero can loop subtle state changes every 10-16 seconds, but must not feel like a loading screen. * Respect `prefers-reduced-motion` with a static poster state and no loss of information. Unique effect palette: * Tactical scan: a thin mask-driven scan passes over the map only when state changes. * Route trace: SVG or canvas line draws between event source, agent node, and review gate. * State pulse: one-ring pulse for active/ready/warning states, never constant throbbing. * Parallax command layers: background grid, agent lanes, and event rail move at slightly different depths on pointer or scroll, capped to a few pixels. * Replay scrub: timeline hover/focus highlights the related mission node and route. * Holographic edge: panels get a thin cyan or amber corner bevel, not a fuzzy glow. * Terminal flicker: extremely subtle line reveal for event rows; avoid noisy CRT filters. Scroll choreography: * Section entrances should feel like loading a new command deck: grid lines resolve, headings lock into place, and data rows populate in short groups. * Use staggered reveal only for structured lists where order matters: pipeline steps, event rows, rules of engagement, and role routes. * Do not animate every card the same way. The page should have one cinematic language, not a preset reveal on everything. Kinetic-scroll adaptations: * Operator doctrine reveal: choose one short, high-value paragraph in Operator Problem or Rules Of Engagement for a character-by-character scroll opacity reveal. Split text into words and glyphs, keep words unbroken, map glyph opacity from 0.2 to 1, expose the full text with `aria-label`, and render normal full-opacity text under `prefers-reduced-motion`. Use it for doctrine copy, not dense documentation. * Signal relay rows: add one narrow, product-specific counter-panning rail of hook events, adapter names, status chips, or mini snapshots between the hero and product proof, or inside Mission Board Product Proof if it helps continuity. Rows pan in opposite directions on scroll, but source content must stay semantic, synthetic-labeled, and readable when motion is off. Use posters/static tiles first; lazy attach any video sources near the viewport and pause off-screen. * Mission stack cards: where the page needs deeper proof, let Capability Deck or Mission Board Product Proof use sticky-stacking panels that scale subtly as the next panel takes focus. The pattern must work for any card count, avoid nested cards, and collapse to a simple ordered stack on mobile before content gets compressed. * Magnetic treatment: reserve magnetic hover for one hero object only, such as the command core or active mission node. Disable under reduced motion and do not magnetize cards, nav, or every CTA. * Constraint: these are FactionOS state primitives, not portfolio cosplay. Each kinetic move must explain agent state, operator choice, replay, or local boundary. Microinteractions: * Hover/focus on an agent lane highlights its route, objective, and latest event. * Hover/focus on a boundary chip reveals "default," "optional," "blocked," or "no claim" detail. * CTA hover can create a command-confirmation sweep, but it must remain fast and readable. * Keyboard focus states should be as visually intentional as hover states. Implementation guidance: * Prefer CSS transforms, opacity, SVG stroke-dashoffset, and lightweight canvas for the mission map. * Use Three.js only if a true 3D command table is being built; if used, keep it full-bleed or unframed, load lazily/idle after the poster, and pause off-screen. * For this production pass, use the approved pre-rendered AVIF/WebP poster plus optimized Veo video bundle. CSS/SVG/canvas motion can add route traces or state labels, but must not replace the API-generated cinematic plate. First paint must be poster-first. * Pause animation with `IntersectionObserver` when off-screen. * Keep motion independent of layout: animation must not resize panels, shift text, or change grid dimensions. * No continuous CPU-heavy particle fields, noise shaders, or decorative background loops. Performance budget: * First viewport must have a meaningful static command poster before any client JavaScript runs. * JS for optional hero interactivity should be code-split and idle/lazy hydrated. * Respect Core Web Vitals: no main-thread jank, no layout shift, no blocking font waterfall. * Reduced-motion mode must still look intentionally designed, not broken or empty. ### Spacing and Layout Layout philosophy: * Dense command surfaces inside broad cinematic bands. * Strong grid discipline: 12-column desktop, 6-column tablet, single-column mobile. * Containers: 1180px standard, 1440px wide command surfaces. * Section padding: 80-112px desktop, 48-72px tablet, 40-56px mobile. * Card radius: 4-8px for HUD panels. Avoid pillowy SaaS cards. * Borders: 1px gunmetal lines with state-colored accents. * Shadows: dark elevation plus subtle state glow, never blurry decorative halos. * Sticky header: compact, glassy, low height; primary CTAs always visible on desktop. * Mobile: hero becomes stacked command briefing, then horizontally scroll-safe mission board or simplified lane stack. ## 7. Design Language Translation Design thesis: FactionOS should feel like a AAA strategy-game command center meets serious local-first developer infrastructure. It should avoid generic cyberpunk SaaS and instead make AI-agent work feel like an operator-led mission: lanes, objectives, replay, approvals, diagnostics, and explicit transfer rules. Typography should be distinctive enough to read as FactionOS before the logo appears; color should encode real state; layout should behave like a command surface; and motion should reveal agent state rather than decorate the page. The visitor should believe "I can control parallel AI coding agents without surrendering my local context" before being asked to open the demo or read the docs. Load-bearing design decisions: 1. Strategy-game command table as the hero, not a split text/card SaaS hero. 2. Agent lanes as squads: plan, build, review, risk, and operator. 3. State colors with semantic meaning: cyan active, green ready/local, amber warning/static, violet review/queued, red blocked/risk. 4. Product proof before privacy detail. The boundary is visible early but not allowed to bury the product promise. 5. HUD components that are real information architecture: objective tracker, event stream, replay rail, approval gates, adapter exits. 6. Local-first trust as "rules of engagement": what starts local, what can exit, what never leaves by default. 7. Cinematic motion in one orchestrated system: mission boot sequence, route tracing, lane pulses, event ingestion, and replay scrub. No scattered animation confetti. 8. Unique type as a product signal: Oxanium-led hero/display typography, Rajdhani HUD UI, JetBrains Mono data rails, and a custom H1 treatment. 9. Effects with jobs: scan, pulse, parallax, and line-draw effects must explain state changes, never just decorate empty space. ## 8. Recommended Page Blueprint ### Section 1 - Cinematic Command Hero Priority: Must-have. Purpose: Establish FactionOS as the command surface for AI-agent development work. User question answered: What is this, and why should I care in five seconds? Headline formula: `Mission control for [AI coding agents / parallel agent work].` Recommended content: * Brand mark. * One-line category statement. * Short body: "Watch parallel agent work, keep intent visible, and steer implementation from a local-first cockpit." * Primary CTA: Open Demo. * Secondary CTA: Read Docs. * Compact posture badges: Local-first, Synthetic demo, No website telemetry. Visual direction: * Full-bleed or wide command-table scene. * Production media starts from the approved Veo bundle: [grounded-hero-02-room-cockpit delivery](https://github.com/AI-with-Apex-VIP/factionos/tree/main/tmp/factionos-public-website-assets/cinematic-hero/generated/grounded-hero-02-room-cockpit/delivery/veo31-fast/README_delivery-veo31-fast.md). * Agent lanes move across a tactical grid. * Objective panel on left, event rail on right, map center, status badges below. * Product-like UI must be first-viewport signal. Proof: * Synthetic sample label. * Explicit "no live visitor telemetry" microcopy. * Demo and docs links. Layout: * Desktop: cinematic map surface spans 60-70% of viewport width, copy integrated as command briefing overlay, not in a floating marketing card. * Mobile: compact briefing first, then a simplified vertical mission board with three lane cards. Interaction: * Initial boot sequence resolves in 900-1400ms: grid resolves, agent nodes pulse once, event rail populates. * Hover/focus on agent lane reveals state and boundary. * Reduced motion uses a static rendered frame. Why this belongs here: * Strong competitors show product UI immediately. FactionOS' differentiator is the game-HUD translation of agent work. Do this, not that: * Do: "Agent A is planning, Agent B is ready for review, risk gate is warning." * Do not: show abstract neon shapes that do not teach the product. ### Section 2 - The Operator Problem Priority: Strong recommendation. Purpose: Name the pain before feature listing. User question answered: What breaks when I run multiple AI coding agents? Headline formula: `Agent work disappears fast. Operators need state.` Recommended content: * Three pressure points: terminal scrollback, parallel session drift, hidden risk/approval moments. * One concise paragraph connecting pain to FactionOS. Visual direction: * Three "before" strips: raw terminal noise, lost objective, risky tool action. * Each resolves into a FactionOS state label. CTA: * Secondary link to How It Works. Proof: * Use real workflow classes from current content: hook events, prompt lifecycle, file touches, validation gates. Layout: * Three-column desktop, stacked mobile. Interaction: * Hover transforms raw log fragment into structured mission state. Why this belongs here: * It gives emotional reason for the command table without relying on hype. Do this, not that: * Do: make the category problem concrete. * Do not: claim AI agents are unsafe in general or promise full automation safety. ### Section 3 - Mission Board Product Proof Priority: Must-have. Purpose: Show what the cockpit makes visible. User question answered: What would I actually see? Headline formula: `Watch the mission, not the scrollback.` Recommended content: * Agent roster. * Mission objective. * Status ring. * Trace rail. * Event stream. * Approval checkpoint. * Replay marker. Visual direction: * Large interactive cockpit surface. This can reuse and upgrade current `BattlefieldPreview`, `HeroCockpit`, and `LiveStatusPanel` concepts. CTA: * Open Demo. Proof: * Label synthetic data clearly. * Use deterministic sample rows. Layout: * Wide, immersive band. * Avoid putting cards inside cards. Use unframed panels on a single command surface. Interaction: * Scrub event timeline; selecting a trace highlights related lane and objective. Why this belongs here: * Developer-tool winners convert with visible product proof before long feature copy. Do this, not that: * Do: make screenshots inspectable. * Do not: hide UI behind a tiny decorative mockup. ### Section 4 - Hook-To-Cockpit Flow Priority: Must-have. Purpose: Explain the agentic system architecture. User question answered: How does agent work become cockpit state? Headline formula: `From hook event to operator view.` Recommended content: * Claude Code hooks. * Codex CLI hooks. * Compatible producers. * Protocol JSON. * Local `/event`. * Local server snapshot. * WebSocket to cockpit. * Optional adapters. * Optional War Room. Visual direction: * Horizontal pipeline on desktop, vertical route on mobile. * Each node has input, output, boundary. * Use "gate" styling for optional exits. CTA: * Read Docs. Proof: * Current how-it-works content already has exact flow and no-claim boundaries. Interaction: * Focus/hover reveals input/output/boundary panel. * Optional exits use amber/violet, not green. Why this belongs here: * This anchors the gaming metaphor in real agentic architecture. Do this, not that: * Do: show clear local-to-optional transfer path. * Do not: imply the website itself runs hooks or opens runtime streams. ### Section 5 - Capability Deck Priority: Must-have. Purpose: Convert product surface into buyer-understandable capabilities. User question answered: What jobs does FactionOS help with? Headline formula: `Observe. Coordinate. Review. Contain.` Recommended content: * Observe: lifecycle, file/tool timeline, diagnostics. * Coordinate: missions, lanes, roster, subagent lineage. * Review: approvals, replay, validation gates. * Contain: local-first defaults, redaction, explicit adapters. * Export: handoff/audit output when needed. Visual direction: * Five tactical loadout tiles. Each tile has icon, state color, "operator job," and "boundary." CTA: * Inspect Features. Proof: * Link to product and features pages. Interaction: * Tile hover changes map overlay behind it. Why this belongs here: * Winners include feature groups, but FactionOS should group by operator job rather than generic feature categories. Do this, not that: * Do: "Review risky moments before work proceeds." * Do not: "AI-powered productivity platform." ### Section 6 - Rules Of Engagement Priority: Must-have. Purpose: State the local-first trust model in memorable form. User question answered: What leaves my machine? Headline formula: `Local by default. External by command.` Recommended content: * What starts local. * What the website does not collect. * What optional exits exist. * What is explicitly no-claim. * Sensitive payload classes: prompts, paths, terminal output, credentials, replay, code. Visual direction: * Game rules panel or mission contract. * "Default," "Optional," "Blocked," and "No claim" labels. CTA: * Review Security. Proof: * Cite static site scan posture from extraction report: no hosted forms, analytics/tracker snippets, runtime fetch/WebSocket/EventSource/beacon/storage/cookie writes in current built output. Interaction: * Expandable data classes. * Color-coded boundary chips with text labels. Why this belongs here: * Security is central, but it should feel like command discipline, not a legal disclaimer dump. Do this, not that: * Do: name sensitive classes. * Do not: claim certification, compliance, or trusted erasure without evidence. ### Section 7 - Role Routes Priority: Strong recommendation. Purpose: Help different audiences identify their path. User question answered: Is this for me? Recommended content: * Engineering teams. * AI platform teams. * Founders. * Power users. Visual direction: * Squad selection screen. Each role has mission brief, active pain, recommended route. CTA: * Open relevant use case. Proof: * Use existing use-case pages and exact content boundaries. Interaction: * Keyboard-accessible segmented control or cards. Why this belongs here: * Mature competitors segment enterprise/individual/team journeys. Do this, not that: * Do: make audience choice quick. * Do not: create generic persona cards with stock portraits. ### Section 8 - Provider And Adapter Surface Priority: Strong recommendation. Purpose: Clarify ecosystem relationship. User question answered: Does it work with my agents and tools? Recommended content: * Claude Code hooks. * Codex CLI hooks. * Compatible producers. * Discord, Telegram, HTTPS outbound adapters as optional. * War Room as optional. Visual direction: * Tactical equipment bay: sources on left, local core center, optional exits right. CTA: * Follow Hook Flow. Proof: * Make compatibility contract-based. Avoid implying universal provider support. Interaction: * Toggle source, see event type examples. Why this belongs here: * Competitors increasingly win by surfacing cross-tool workflow. Do this, not that: * Do: "compatible producers can follow the event contract." * Do not: "works with every agent" unless proven. ### Section 9 - Field Notes And Roadmap Priority: Strong recommendation. Purpose: Show product momentum without fake metrics. User question answered: Is this alive and thoughtfully built? Recommended content: * Latest blog. * Latest news/changelog. * Roadmap themes. Visual direction: * Mission log, patch notes, or campaign journal. CTA: * Read Field Notes. Proof: * Current content collections and RSS. Why this belongs here: * Fast-moving agentic tooling needs freshness signals. Do this, not that: * Do: show dates and concise summaries. * Do not: claim traction without evidence. ### Section 10 - Final Command CTA Priority: Must-have. Purpose: Close with the two practical next actions. User question answered: What should I do next? Headline formula: `Open the demo. Keep the docs close.` Recommended content: * Open Demo. * Read Docs. * Contact if needed. * Boundary: demo and docs are separate public destinations. Visual direction: * Final command console with two large actions and destination labels. Interaction: * CTA hover shows destination and posture. Why this belongs here: * Developer tools need a concrete next step, not a vague "learn more." Do this, not that: * Do: label external destinations. * Do not: bury CTAs under paragraph-heavy copy. ## 9. Component System Navigation: * Role: global wayfinding. * Anatomy: mark, wordmark, Product, Features, How It Works, Use Cases, Security, Blog/News, Demo, Docs. * States: active, hover, focus, external. * Accessibility: keyboard focus visible; external links labeled. * Mobile: drawer or full-screen command menu with Demo/Docs pinned. Command Hero: * Role: thesis and conversion. * Anatomy: briefing copy, CTA cluster, posture chips, mission map, event rail. * Production asset: [grounded-hero-02-room-cockpit / Veo 3.1 Fast](https://github.com/AI-with-Apex-VIP/factionos/tree/main/tmp/factionos-public-website-assets/cinematic-hero/generated/grounded-hero-02-room-cockpit/delivery/veo31-fast/README_delivery-veo31-fast.md). * States: booting, active, reduced-motion. * Mobile: briefing plus lane stack. Cinematic Motion Layer: * Role: shared animation system for the command-table experience. * Anatomy: boot controller, scan sweep, route trace, state pulse, section reveal, replay highlight, reduced-motion poster state. * States: idle, booting, active, selected, paused off-screen, reduced-motion. * Spacing/layout: must not alter document flow or component dimensions. * Accessibility: no essential information conveyed by motion alone; all states have text labels. * Performance: use CSS/SVG/canvas transforms and opacity first; lazy hydrate optional interactivity; pause loops when off-screen. Mission Map: * Role: signature visual proof. * Anatomy: grid, coordinates, agent nodes, route lines, risk markers, objective panel, legend. * States: active, queued, ready, warning, blocked. * Accessibility: text table or list equivalent for map state. Agent Lane Card: * Role: show one agent/workstream. * Anatomy: ID, role, objective, status, progress, next checkpoint, boundary tag. * States: planning, building, reviewing, blocked, ready. Event Timeline / Replay Rail: * Role: make agent history inspectable. * Anatomy: timestamp, event type, source, output, boundary, related lane. * States: selected, warning, complete. * Accessibility: ordered list semantics. Rule Panel: * Role: local-first trust model. * Anatomy: default, optional, blocked, no-claim columns. * States: expanded/collapsed. CTA Buttons: * Primary: cyan border/glow, solid dark fill, mono label. * Secondary: violet or gunmetal. * Warning/external: amber label chip. * States: hover sheen, focus ring, disabled only when action unavailable. Feature Cards: * Role: capability grouping. * Anatomy: icon, operator job, capability bullets, boundary chip. * Avoid nested cards. Role Route Cards: * Role: audience routing. * Anatomy: role, mission brief, pain, next page. * State: hover/focus reveals recommended route. FAQ Accordion: * Role: answer objections without bloating homepage. * Anatomy: question, concise answer, link to FAQ/security/docs. * Accessibility: button semantics, aria-expanded. Footer: * Role: complete route and trust surface. * Anatomy: product, resources, company, legal, external destinations, RSS. ## 10. Design Tokens ```yaml tokens: colors: background: void: "#07090F" obsidian: "#0D121C" band: "#101827" surface: panel: "#171E2A" panelRaised: "#202838" console: "#05070C" text: primary: "#F4F8FF" secondary: "#A9B4C3" muted: "#728197" inverse: "#071017" border: default: "#344154" subtle: "rgba(52, 65, 84, 0.54)" active: "rgba(24, 232, 255, 0.62)" primary: cyan: "#18E8FF" cyanSoft: "rgba(24, 232, 255, 0.12)" secondary: violet: "#8B5CF6" violetSoft: "rgba(139, 92, 246, 0.12)" accent: green: "#23D77B" amber: "#F4B942" red: "#F0445E" success: "#23D77B" warning: "#F4B942" danger: "#F0445E" typography: fontHeading: "Oxanium, Rajdhani, 'Arial Narrow', 'Segoe UI', system-ui, sans-serif" fontUi: "Rajdhani, Oxanium, 'Segoe UI', system-ui, sans-serif" fontBody: "Outfit, Inter, ui-sans-serif, system-ui, sans-serif" fontMono: "'JetBrains Mono', 'SFMono-Regular', Consolas, monospace" weights: regular: 400 medium: 550 semibold: 650 bold: 800 black: 800 sizes: h1: "clamp(2.75rem, 7vw, 6rem)" h2: "clamp(2rem, 4.6vw, 3.75rem)" h3: "clamp(1.3rem, 2.3vw, 1.75rem)" body: "1rem" lede: "clamp(1.05rem, 1.4vw, 1.18rem)" ui: "0.875rem" code: "0.8125rem" lineHeights: tight: 0.96 heading: 1.05 body: 1.65 data: 1.45 letterSpacing: default: "0" hud: "0.04em" spacing: 1: "0.25rem" 2: "0.5rem" 3: "0.75rem" 4: "1rem" 5: "1.25rem" 6: "1.5rem" 8: "2rem" 10: "2.5rem" 12: "3rem" 16: "4rem" 20: "5rem" 24: "6rem" radius: xs: "2px" sm: "4px" md: "8px" lg: "12px" shadows: panel: "0 24px 70px rgba(0, 0, 0, 0.42)" cyan: "0 0 24px rgba(24, 232, 255, 0.18)" green: "0 0 20px rgba(35, 215, 123, 0.16)" warning: "0 0 20px rgba(244, 185, 66, 0.14)" motion: boot: "1100ms" fast: "140ms" standard: "220ms" cinematic: "760ms" sectionReveal: "520ms" routeTrace: "680ms" pulse: "1600ms" mapLoop: "12000ms" easingOut: "cubic-bezier(0.16, 1, 0.3, 1)" easingStandard: "cubic-bezier(0.25, 0.8, 0.25, 1)" effects: scanOpacity: "0.10" glowSoft: "0 0 24px rgba(24, 232, 255, 0.18)" bevelLine: "linear-gradient(135deg, rgba(24,232,255,0.72), transparent 28%, rgba(244,185,66,0.42))" parallaxMax: "8px" routeWidth: "1.5px" gridSize: "88px" breakpoints: sm: "640px" md: "900px" lg: "1120px" xl: "1440px" ``` Useful CSS variables: ```css :root { color-scheme: dark; --color-bg: #07090f; --color-bg-elevated: #0d121c; --color-panel: #171e2a; --color-line: #344154; --color-text: #f4f8ff; --color-muted: #a9b4c3; --color-cyan: #18e8ff; --color-green: #23d77b; --color-amber: #f4b942; --color-violet: #8b5cf6; --color-red: #f0445e; --font-display: Oxanium, Rajdhani, "Arial Narrow", "Segoe UI", system-ui, sans-serif; --font-ui: Rajdhani, Oxanium, "Segoe UI", system-ui, sans-serif; --font-body: Outfit, Inter, ui-sans-serif, system-ui, sans-serif; --font-code: "JetBrains Mono", "SFMono-Regular", Consolas, monospace; --radius-panel: 8px; --line: 1px solid var(--color-line); --ease-out: cubic-bezier(0.16, 1, 0.3, 1); --motion-boot: 1100ms; --motion-route-trace: 680ms; --motion-section-reveal: 520ms; --effect-parallax-max: 8px; --effect-grid-size: 88px; } ``` ## 11. Copy and CTA Matrix Hero message options: * `Mission control for AI coding agents.` * `Run the agents. Keep command.` * `A local-first cockpit for parallel agent work.` * `Turn agent sessions into missions you can inspect, replay, and steer.` Primary CTA labels: * Open Demo. * Inspect Demo. * Launch Synthetic Demo. Secondary CTA labels: * Read Docs. * Follow Hook Flow. * Review Security. * Inspect Product Map. Trust language: * `Local-first by default.` * `External signals are deliberate.` * `Synthetic demo data, clearly labeled.` * `No website telemetry in the current static release.` * `Optional adapters stay optional.` Words to use: * mission, cockpit, operator, agent lanes, trace, event, replay, approval, checkpoint, local server, boundary, adapter, review, handoff, protocol, diagnostics. Words to avoid: * magical, autonomous workforce, omniscient, unstoppable, zero-risk, weaponized, battlefield dominance, guaranteed compliance, fully secure, AI revolution. Section copy formulas: * Problem: `When [agent work pattern] happens, [operator risk] follows. FactionOS turns it into [visible state].` * Feature: `[Operator job] without [common failure].` * Security: `[Data class] stays [boundary] unless [explicit action].` * CTA: `[Action] the [surface], then [next developer step].` ## 12. Anti-Patterns Weaker competitor and category anti-patterns: * Sparse terminal-only page that makes the product feel like a script instead of a command surface. * Generic enterprise observability page with interchangeable traces and logo rows. * Heavy security disclaimers before the user understands the product. * Abstract gradients and neon blobs standing in for product proof. * Overclaiming "live" or "real-time" on a static public page. * Fake customer logos, invented metrics, or implied production validation. * Using game aesthetics as costume rather than information architecture. FactionOS must avoid: * Becoming all dark blue/cyan with no semantic contrast. * Letting "battlefield" language become violent or militarized. * Hiding local-first trust behind legal copy. * Showing sample data without labels. * Turning every panel into a card inside another card. * Using oversized hero text inside compact UI panels. * Making UI text too small to inspect. Do this, not that: * Do: "Local by default. External by command." * Not: "Enterprise-grade secure AI." * Do: "Replay a bounded local event sequence." * Not: "See everything your agents do." * Do: "Compatible producers can follow the event contract." * Not: "Works with every AI agent." * Do: "Open the synthetic demo." * Not: "Launch live cockpit" from the public static site. ## 13. Final Builder Prompt Build or redesign the FactionOS public homepage as a cinematic, high-performance Astro static page for a local-first AI coding-agent command product. Project summary: FactionOS is local-first mission control for observing, steering, and coordinating AI coding agents across real development work. The audience is serious developers, engineering teams, AI platform teams, founders, and power users running tools like Claude Code, Codex CLI, and compatible local agent workflows. The primary conversion is Open Demo; secondary is Read Docs; tertiary is Contact. Visual direction: Create a premium tactical strategy-game command center, not a generic SaaS page. The hero should feel like a AAA strategy-game HUD translated into a real developer tool: mission map, agent lanes, objective tracker, replay rail, approval gates, risk markers, status rings, local event stream, and command-console labels. Use gaming UI as information architecture. The page must include beautiful animation, cinematic motion, unique effects, and distinctive fonts as core brand material. Avoid fantasy art, shooter/military imagery, robots, generic AI brains, stock photos, blurred gradient blobs, and fake live telemetry. Approved hero asset: Use the `grounded-hero-02-room-cockpit` Veo 3.1 Fast bundle as the production cinematic hero plate: [delivery README](https://github.com/AI-with-Apex-VIP/factionos/tree/main/tmp/factionos-public-website-assets/cinematic-hero/generated/grounded-hero-02-room-cockpit/delivery/veo31-fast/README_delivery-veo31-fast.md). Install the videos from `public/hero` and posters from `src/assets/hero`, preload the AVIF poster, and start video playback only when the hero is in view and motion is allowed. Preserve the left-side copy-safe zone and keep all page copy, CTAs, badges, and accessibility equivalents as semantic HTML. Asset promotion: Promote only selected assets from `tmp/factionos-public-website-assets/`. Use `brand/factionos-lockup.svg`, `factionos-mark.svg`, `factionos-mark-mono.svg`, and `factionos-app-icon.svg` for navigation, favicon/PWA derivations, footer, and social source composition. Promote fonts to `public/fonts/factionos/`: Oxanium variable, Outfit variable, Rajdhani 600/700, JetBrains Mono variable, and only promote Orbitron if a tiny accent is actually used. Merge `fonts/font-face.css` into global CSS and preload only Oxanium plus Outfit by default. Promote `hud-icons/*.svg` into `src/icons/hud/` or inline components for mission, hook, approval, replay, boundary, risk, adapter, objective, status, and operator states. Promote `synthetic-data/mission-state.json` into the site data layer and keep the visible "Synthetic demo data. No visitor telemetry." label wherever it drives UI. Use `social/og-default`, `og-product`, `og-security`, and `og-docs` as source templates, but regenerate final rasters after fonts are wired. Keep raw videos, processed provider comparison files, metadata, QA previews, checksums, manifests, licenses, and READMEs out of the public runtime unless they are deliberately linked as documentation. Brand rules: Use a dark command-room palette: Void Black `#07090F`, Obsidian `#0D121C`, Armory Panel `#171E2A`, Gunmetal Line `#344154`, Ice Text `#F4F8FF`, Tactical Slate `#A9B4C3`, Reactor Cyan `#18E8FF`, Squad Green `#23D77B`, Signal Amber `#F4B942`, Rift Violet `#8B5CF6`, Critical Red `#F0445E`. Accent colors must encode real state. Use Oxanium for the signature display voice, Rajdhani for dense HUD/UI labels, Outfit for body copy, and JetBrains Mono for terminal/data labels. Self-host fonts, preload only critical first-viewport font files, and use `font-display: swap`. Card radius should be 4-8px. Borders and glows should be restrained. Page structure: 1. Cinematic Command Hero: integrated command briefing plus wide strategy-map product surface. Headline: "Mission control for AI coding agents." CTAs: Open Demo, Read Docs. Badges: Local-first, Synthetic demo, No website telemetry. 2. Operator Problem: explain terminal scrollback, parallel session drift, and hidden risk moments. 3. Mission Board Product Proof: large synthetic cockpit with agent roster, mission objective, trace rail, event stream, approval checkpoint, replay marker. 4. Hook-To-Cockpit Flow: Claude Code hooks, Codex CLI hooks, compatible producers, protocol JSON, local `/event`, server snapshot, WebSocket cockpit, optional adapters, optional War Room. 5. Capability Deck: Observe, Coordinate, Review, Contain, Export. 6. Rules Of Engagement: local-first boundary, optional exits, blocked sensitive classes, no-claim limits. 7. Role Routes: engineering teams, AI platform teams, founders, power users. 8. Provider And Adapter Surface: sources, local core, optional outbound destinations. 9. Field Notes And Roadmap: latest blog/news and roadmap themes. 10. Final Command CTA: Open Demo, Read Docs, Contact. Component requirements: * Sticky navigation with product/docs/demo actions and external labels. * Full-width command hero with accessible text equivalent for map state. * Mission map component with agent nodes, route lines, objective panel, legend, status colors, and reduced-motion static state. * Agent lane card with role, objective, status, progress, next checkpoint, boundary tag. * Event timeline/replay rail as an ordered list. * Rule panel for default/optional/blocked/no-claim states. * Capability cards grouped by operator job. * Role route cards. * CTA buttons with primary, secondary, ghost, warning/external states. * Footer with product, resources, company, legal, RSS, demo, docs. Copy direction: Use precise command language: watch, steer, replay, approve, contain, inspect. Avoid hype. Do not claim live telemetry, hosted account behavior, universal provider support, production validation, certification, or trusted erasure unless evidence exists. Keep the boundary visible but concise. Responsive behavior: Desktop gets the cinematic command table. Tablet stacks the briefing and map. Mobile shows the command briefing first, then a simplified vertical mission lane stack and readable event list. No text overlap. No layout shifts when labels wrap. Accessibility: Meet WCAG 2.2 AA. Do not rely on color alone. Every status color needs a text label. Maintain visible focus. External links require labels. Motion must respect `prefers-reduced-motion`. The synthetic mission map needs an accessible list/table equivalent. Interaction requirements: Use one orchestrated motion system: Mission Boot Sequence, route tracing, lane pulses, event rail updates, replay scrub, and selected trace highlight. The boot sequence should resolve in roughly 900-1400ms and then settle. The approved Veo plate supplies the cinematic command-room movement; any CSS/SVG/canvas layer should explain state on top of it, not replace it. Add section choreography that feels like loading command decks: grid lines resolve, headings lock in, and ordered data rows populate in short groups. Adapt kinetic-scroll primitives tastefully: one character-by-character operator doctrine reveal, one optional counter-panning signal relay of real product-state tiles, subtle sticky-stacking proof panels where they clarify sequencing, and a single magnetic hero object. Keep motion GPU-friendly with transforms, opacity, SVG stroke-dashoffset, lightweight canvas, or poster-first video where appropriate. Pause off-screen. Provide static fallbacks. Do not scatter unrelated hover effects. Anti-patterns: No generic split hero with text on one side and a decorative card on the other. No fake live customer telemetry. No stock developer photos. No robots/AI brains. No gradient blobs/orbs. No nested cards. No all-purple or all-cyan theme. No invented metrics or logos. No military violence aesthetics. ## 14. Final QA Checklist * The first viewport clearly says FactionOS is mission control for AI coding agents. * The gaming feel is visible through useful HUD/product UI, not decoration. * The typography feels distinctive: Oxanium-led display, HUD UI labels, readable body, and mono data rails are all intentionally applied. * The hero has a signature motion/effects moment: mission boot, route trace, lane pulse, event ingestion, or replay scrub. * Any kinetic-scroll-inspired effect maps to FactionOS state or operator choice, has a reduced-motion equivalent, and does not introduce portfolio-style decoration. * Motion reveals agentic state and operator control; it is not generic reveal animation. * Effects have restraint and purpose: no noisy particles, constant throbbing, heavy shader loops, or decorative animation that does not explain product state. * The hero includes a product-like command surface, not a generic abstract visual. * Approved hero bundle is wired poster-first, with AV1/VP9/H.264 sources, reduced-motion poster fallback, and in-view-only playback. * The acquired asset usage map has been followed: only selected production assets are promoted, delivery files are verified with `SHA256SUMS.txt`, and no `tmp/` paths are referenced by the built site. * Raw provider outputs, processed comparison files, metadata, QA previews, manifests, licenses, and staging READMEs are kept out of public runtime unless deliberately published as documentation. * Social rasters are regenerated after the final site font pipeline is wired. * Demo data is labeled synthetic wherever needed. * No copy implies the public static website opens WebSockets, reads local state, collects prompts, or hosts replay. * CTAs are concrete: Open Demo, Read Docs, Contact. * Security boundaries are specific and not overclaimed. * Agentic architecture is understandable from hook event to cockpit. * State colors have text labels and pass contrast. * Mobile text and UI do not overlap. * Reduced motion is fully useful. * Off-screen animations pause, and first paint has a meaningful static command-poster state. * Visual assets are inspectable and relevant. * Customer metrics, awards, and claims are omitted unless verified. * The page can be built as static Astro output on Cloudflare Pages. --- # 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/design-intelligence-2026-07-05.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.