> 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/phase13-session02-design-tokens-and-layout-shell/spec.md).

# Session Specification

**Session ID**: `phase13-session02-design-tokens-and-layout-shell` **Phase**: 13 - Public Website Foundation **Status**: Not Started **Created**: 2026-06-01 **Package**: public-website **Package Stack**: Astro/TypeScript

***

## 1. Session Overview

This session builds the Cyber-Tactical visual foundation and reusable page shell for the static `faction-os.com` website. Session 01 produced a minimal Astro workspace and a starter-safe `index.astro` with inline styles; this session replaces that throwaway page styling with shared design tokens, layouts, navigation, footer, section primitives, and system components that all later public website routes can reuse.

The work is intentionally foundational. It should make the website feel like a premium developer command surface without finishing the homepage, product pages, SEO plumbing, publishing templates, or asset pipeline. Later Phase 13 and Phase 14 sessions should be able to compose pages from this shell instead of rebuilding typography, spacing, focus states, navigation, or tactical background treatment.

The implementation must preserve the first-release product boundaries: static Astro output, no runtime analytics, no hosted form handling, no auth, no CMS, no React or Tailwind adoption, and no public claim that hosted identity, production-hosted validation, broad media readiness, or trusted erasure has been completed. The generated visual mockup referenced by website UX planning is not committed at `assets/showcase/factionos-website-mockup.png`, so current PRD, README, and UX documents are design guidance rather than a canonical image asset for this session.

***

## 2. Objectives

1. Add a shared global CSS foundation with reset rules, Cyber-Tactical color tokens, typography stacks, layout helpers, accessibility states, and reduced-motion guardrails.
2. Create shared Astro layouts and shell components for page chrome, skip links, header navigation, mobile navigation, footer, and section layout.
3. Create reusable system primitives for button links, panels, badges, metric strips, and accessible link/icon affordances.
4. Convert the starter home route to the shared shell and verify the result at desktop and mobile widths without text overlap, broken keyboard access, or continuous motion for reduced-motion users.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase13-session01-astro-scaffold-and-workspace-wiring` - Provides the `@factionos/public-website` Astro workspace, static output config, package scripts, root workspace registration, and passing build/typecheck baseline.

### Required Tools/Knowledge

* Astro component syntax, layouts, slots, scoped styles, and global CSS imports.
* CSS custom properties, responsive grid/flex layouts, focus states, `prefers-reduced-motion`, and accessible navigation patterns.
* npm workspace commands and repository Biome formatting/linting conventions.
* Current public website guidance in `public-website/README_public-website.md`, `public-website/build-site-plan.md`, and `public-website/website_ux.md`.

### Environment Requirements

* Use Node.js `26.2.0+` and npm `11.16.0`, matching `.nvmrc`, root engines, and package metadata.
* The default shell currently reports Node.js `v24.14.0` and npm `10.5.1`; implementation commands should prepend `/home/aiwithapex/.nvm/versions/node/v26.2.0/bin` to `PATH` or record the exact blocker before claiming validation.
* No network access should be required unless the implementation deliberately changes package dependencies or introduces a documented font-loading request.

***

## 4. Scope

### In Scope (MVP)

* Visitors can see a consistent FactionOS website shell - Create shared header, mobile navigation, footer, skip link, and main content landmarks.
* Maintainers can reuse a Cyber-Tactical visual system - Add global tokens for Space Black, Navy Obsidian, transparent Obsidian, Cyber Cyan, Hyper Purple, Matrix Green, Crimson Laser, Ice White, and Tactical Slate.
* Page builders can compose responsive sections - Add full-width band and unframed section primitives with constrained inner content instead of using decorative page-section cards.
* Keyboard and assistive-technology users can navigate the shell - Implement visible focus rings, reachable skip links, accessible external links, and clear mobile navigation controls.
* Reduced-motion users retain static clarity - Disable continuous scanner or pulse effects under `prefers-reduced-motion: reduce` while preserving borders, labels, and state indicators.
* Later website sessions can reuse components - Create button, badge, panel, and metric primitives with stable dimensions and no reliance on color alone.
* Font planning is privacy-conscious - Define the required display, body, and code font stacks and avoid third-party font requests by default unless the request is explicitly documented as temporary.

### Out of Scope (Deferred)

* Final homepage, product, features, how-it-works, security, or content copy - *Reason: Phase 14 and Phase 15 own production page content.*
* Canonical metadata, Open Graph, Twitter cards, RSS, robots, manifest, and structured data plumbing - *Reason: Session 03 owns SEO and static site plumbing.*
* Blog/news collections, seed posts, and publishing templates - *Reason: Session 04 owns typed content collections.*
* Brand/showcase image promotion, Open Graph fallback media, and press assets - *Reason: Session 05 owns asset provenance and media prep.*
* Tailwind, React, shadcn/ui, server rendering, CMS adapters, hosted forms, auth, or runtime analytics - *Reason: These are first-release non-goals.*
* Decorative page sections implemented as floating cards - *Reason: Sections must be full-width bands or unframed layouts; cards are reserved for repeated items and framed tools.*

***

## 5. Technical Approach

### Architecture

Keep the implementation local to `public-website/`. Add `src/styles/global.css` as the single shared reset, token, typography, focus, layout, motion, and accessibility foundation. `BaseLayout.astro` should import that stylesheet and provide the document-level frame, while `Shell.astro` composes skip link, header, main content, footer, and any reduced-motion-safe decorative layers.

Create navigation components under `src/components/navigation/`, layout components under `src/components/layout/`, system primitives under `src/components/system/`, and simple navigation data under `src/data/`. `index.astro` should stop owning inline CSS and should render through the shared layout/shell so future pages inherit the same chrome and visual rules.

Use CSS and Astro components first. If the mobile navigation needs a small browser script, keep it local, dependency-free, and explicit about state reset on close, route re-entry, and viewport changes. Do not add third-party UI, icon, animation, or font packages in this session unless a concrete blocker is documented and the dependency remains local to `public-website`.

### Design Patterns

* Static-first Astro shell: Shared layouts produce static HTML and CSS without server adapters or client frameworks.
* Token-driven styling: CSS custom properties make later page work consistent without duplicating literal colors and spacing values.
* Progressive disclosure for motion: Decorative scanline, glow, and status treatment are optional layers over readable static content.
* Accessible navigation by default: Native links and buttons, visible focus, skip links, external link text, and mobile state reset prevent shell-level UX regressions.
* No-overclaim copy boundary: Shared footer and shell copy must point to demo and docs without implying hosted identity, analytics capture, production validation, formal certification, or broad erasure guarantees.

### Technology Stack

* Astro `6.4.2` in static output mode.
* `@astrojs/mdx` `6.0.1`, `@astrojs/sitemap` `3.7.3`, and `@astrojs/rss` `4.0.18` already available for later sessions.
* TypeScript `5.9.3` through `astro sync && tsc --noEmit`.
* Vanilla Astro components, scoped component CSS, and shared global CSS.
* No Tailwind, React, shadcn/ui, CMS adapter, server adapter, hosted analytics, or hosted form dependency.

***

## 6. Deliverables

### Files to Create

| File                                                              | Purpose                                                                                       | Est. Lines |
| ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ---------- |
| `public-website/src/styles/global.css`                            | Reset, tokens, typography stacks, layout helpers, focus states, motion, and responsive rules. | \~360      |
| `public-website/src/data/navigation.ts`                           | Shared navigation groups and external demo/docs destinations.                                 | \~80       |
| `public-website/src/layouts/BaseLayout.astro`                     | Document-level Astro layout with global stylesheet import and main slot.                      | \~110      |
| `public-website/src/layouts/ContentLayout.astro`                  | Standard content/page layout built on the shared shell.                                       | \~90       |
| `public-website/src/layouts/LegalLayout.astro`                    | Policy/legal page layout with review-state affordances.                                       | \~80       |
| `public-website/src/components/layout/Shell.astro`                | Shared page chrome composition.                                                               | \~120      |
| `public-website/src/components/layout/Section.astro`              | Full-width band and unframed section primitive.                                               | \~100      |
| `public-website/src/components/navigation/SkipLink.astro`         | Keyboard skip link component.                                                                 | \~35       |
| `public-website/src/components/navigation/Header.astro`           | Route-aware desktop header and primary navigation.                                            | \~140      |
| `public-website/src/components/navigation/MobileNavigation.astro` | Accessible mobile navigation control and panel.                                               | \~130      |
| `public-website/src/components/navigation/Footer.astro`           | Shared footer link groups and boundary copy.                                                  | \~130      |
| `public-website/src/components/system/ButtonLink.astro`           | Link-style button primitive with variants and external affordance.                            | \~110      |
| `public-website/src/components/system/Badge.astro`                | Status badge primitive with text-visible state.                                               | \~70       |
| `public-website/src/components/system/Panel.astro`                | Framed repeated-item/tool primitive, not a page-section wrapper.                              | \~90       |
| `public-website/src/components/system/MetricStrip.astro`          | Responsive labeled metric strip primitive.                                                    | \~110      |

### Files to Modify

| File                                                                                          | Changes                                                                                                                   | Est. Lines |
| --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `public-website/src/pages/index.astro`                                                        | Replace inline starter CSS and direct HTML shell with shared layout and primitives.                                       | \~80       |
| `.spec_system/specs/phase13-session02-design-tokens-and-layout-shell/implementation-notes.md` | Record implementation decisions, validation evidence, and any font-loading or environment blockers during implementation. | \~120      |

***

## 7. Success Criteria

### Functional Requirements

* [ ] `public-website/src/styles/global.css` defines the required Cyber-Tactical palette, typography stacks, focus rings, layout helpers, and reduced-motion behavior.
* [ ] `index.astro` renders through the shared layout/shell and no longer owns page-level inline CSS.
* [ ] Header, mobile navigation, footer, and skip link are keyboard reachable.
* [ ] Demo and docs links are explicit, accessible, and clearly external.
* [ ] Sections use full-width bands or unframed constrained layouts, not decorative floating page-section cards.
* [ ] System primitives are reusable without introducing React, Tailwind, shadcn/ui, icon packages, or animation packages.

### Testing Requirements

* [ ] `npm --workspace @factionos/public-website run typecheck` passes under Node.js `26.2.0+`, or the exact environment blocker is recorded.
* [ ] `npm --workspace @factionos/public-website run build` passes under Node.js `26.2.0+`, or the exact environment blocker is recorded.
* [ ] Focus order, skip link, desktop navigation, mobile navigation, and external links are manually smoke-tested.
* [ ] Desktop and mobile browser smoke confirms no obvious text overlap, clipping, or inaccessible shell controls.

### Non-Functional Requirements

* [ ] Body text contrast meets at least the planned `4.5:1` target against the dark backgrounds.
* [ ] Continuous decorative motion is disabled for reduced-motion users while static state clarity remains visible.
* [ ] The site remains static-output only with no analytics, hosted forms, auth, CMS, server rendering, hosted identity, or production-hosted validation claim.
* [ ] Font loading does not introduce an unreviewed third-party request; any temporary external font request is documented.

### Quality Gates

* [ ] All new or modified files in this session are ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code follows project conventions and package-local Astro style.
* [ ] Root Biome formatting/linting is not regressed for touched files.

***

## 8. Implementation Notes

### Key Considerations

* The committed website mockup image referenced by `website_ux.md` is absent, so use text requirements from PRD, README, build plan, and UX spec as the source of truth for this session.
* `public-website/website_ux.md` is pre-existing UTF-8 planning material. New session outputs and new implementation files should remain ASCII-only.
* Session 03 will add SEO components and central metadata; leave clean integration points without duplicating that scope.
* Session 05 will handle brand/showcase media provenance; do not promote existing images through this layout shell.
* The current default shell runtime is below the repo baseline; validation evidence must use the available Node.js `26.2.0` path.

### Potential Challenges

* Mobile navigation state drift: Keep open/closed state explicit and reset it when the panel closes, a link is activated, or the viewport returns to the desktop layout.
* One-note palette risk: Use cyan, purple, green, red, slate, and ice-white accents intentionally so the design does not collapse into only dark blue/purple gradients.
* Decorative overuse: Tactical grids, scanlines, and glows should support the command-surface feel without becoming unreadable or essential to meaning.
* Font privacy: Prefer local font names plus system fallbacks unless self-hosted files are added in a later asset/performance session.

### Relevant Considerations

* \[P03] **Stable docs are the current contract**: Use current README, docs, PRD, and package sources instead of historical examples or archived PRD material.
* \[P07] **Hosted services ship as disabled-default guardrails only**: Shared shell and footer copy must not imply active hosted auth, storage, analytics, push, remote access, or public replay hosting.
* \[P04] **Asset provenance gate remains active**: Do not promote brand, showcase, generated draft, unknown, or historical media as release-ready in this shell.
* \[P08] **Release-candidate evidence is claim-scoped**: Local website build and browser smoke are not production-hosted validation or formal accessibility certification.
* \[P02-apps/web] **Responsive and accessibility debt**: Treat focus, mobile layout, reduced motion, contrast, and no-overlap checks as first-class tasks.

### Behavioral Quality Focus

Checklist active: Yes

Top behavioral risks for this session:

* Mobile navigation could remain open, trap focus poorly, or fail to reset when users activate a link or revisit the shell.
* Decorative motion could continue for reduced-motion users or become the only indicator of system state.
* External demo/docs links could be visually unclear, inaccessible, or imply hosted behavior that the product does not claim.
* Responsive text and labels could overlap controls at mobile widths if fixed dimensions are not constrained carefully.

***

## 9. Testing Strategy

### Unit Tests

* No dedicated unit test runner is expected for these static Astro shell components in this session.
* Typecheck should cover Astro component props and TypeScript navigation data.

### Integration Tests

* Run `npm --workspace @factionos/public-website run typecheck`.
* Run `npm --workspace @factionos/public-website run build`.
* Run focused Biome format/lint checks for touched website files.

### Manual Testing

* Start the Astro dev server and inspect the home route at desktop and mobile widths.
* Keyboard through skip link, header navigation, mobile navigation, CTA links, and footer links.
* Confirm mobile navigation can open, close, activate a link, and reopen without stale state.
* Verify demo/docs links remain external and accessible.

### Edge Cases

* `prefers-reduced-motion: reduce` disables scanner/pulse motion while keeping static borders and status labels visible.
* Long labels wrap without overlapping neighboring controls.
* External links remain understandable when icon or decorative affordances are unavailable.
* Browser support without JavaScript still leaves core navigation links reachable, or a clear no-JavaScript fallback is present.

***

## 10. Dependencies

### External Libraries

* None new planned.

### Other Sessions

* **Depends on**: `phase13-session01-astro-scaffold-and-workspace-wiring`
* **Depended by**: `phase13-session03-seo-metadata-and-static-site-plumbing`, `phase13-session04-content-collections-and-publishing-templates`, `phase13-session05-asset-pipeline-and-brand-media-prep`, and Phase 14 page implementation sessions.

***

## 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/phase13-session02-design-tokens-and-layout-shell/spec.md?ask=<question>&goal=<endgoal>
```

`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.