docs-site: one visual system, richer pages and automatic dark theme

[omrsamer]

Summary

Gives the GitHub Pages site (docs-site/) one visual system and a richer look, in the spirit of the animated, card-based reference the team liked: shared primitives replace four button systems and about twenty card variants; every page, including the 19 rendered README and doc pages and the 404 page, now opens with the same dark header; Home gets a centred hero with a four-stage journey strip, persona cards, an HTML capability stack and a four-column footer; the data-heavy pages gain a posture heat-map, a comparison table with stage columns, a workshop track matrix, steppers, a policy summary and a diagram lightbox; and the site follows the operating system's dark mode automatically. Nothing outside docs-site/ changed.

The contract from PR #34 still holds: no backend, no runtime network requests, no external assets or fonts, no analytics, no storage, no raw HTML. WCAG 2.2 AA is checked by axe on every route in light and dark, prefers-reduced-motion is respected everywhere, and layout shift stays at 0.

What changed

Design system (foundation)

• Semantic tokens in tokens.css (--color-surface, --color-band, --color-link, --color-accent, --color-focus, text scale, --radius-pill, --shadow-card). The raw palette is used only inside tokens.css.
• Shared primitives with unit tests: Button, Card, SectionHeading, Section, ChipNav, NumberedSteps, StatTile and FactStat, Sources, StageJourney, HeaderGlow. Every page module was migrated onto them and the duplicate CSS was deleted.
• PageHeader gained align, variant="compact", breadcrumbs, hue and a static gradient backdrop that every header now shows by default.

Pages

• Home: centred hero over the constellation with a gradient accent and the journey strip; project tiles with stage icons and facts whose caveats sit behind a "Why this figure" disclosure; five persona cards; the capability stack (five layers, ten capabilities, four posture dots each with a text alternative, linking into the posture matrix); a four-column footer.
• Start: steppers with stage-coloured counters for every quickstart; the comparison table with stage-coloured columns, icons and a card view below 640 px; FAQ as a chip nav plus cards; first-deploy stat row in the Get started header.
• Projects: accent cards on the index; stat tiles, steppers, card lists and stretched-link cards on the project pages; a track x module matrix for the Workshop; a "policies at a glance" grid with Deployed and Not deployed badges.
• Concepts and Reference: posture heat-map (tint per posture, icon and text kept in every cell, stage column rules); four planes and governed flows as HTML diagrams; a diagram lightbox (native <dialog>) on every figure; the Workshop LLM Gateway diagram added to the Architecture page with its source; glossary letters and support-envelope jumps as chip navs; limitation cards with stage accents.
• Doc pages: compact dark header with breadcrumbs, project stage, source path and actions; a CSS-only reading progress bar; a back-to-top link; card pager. 404 uses the same header and buttons.

Dark theme

• color-scheme: light dark and a prefers-color-scheme: dark remap of the semantic tokens only. No toggle, nothing stored. index.html carries color-scheme and two theme-color metas; validate_static.py checks the meta on every page.

Guardrails

• designLint.test.ts scans every CSS module for hex literals, white, rgba(, 999px, raw palette backgrounds and button-like classes.
• structure.spec.ts: one dark header with the single h1 on every route, icon plus text in every posture cell, the capability stack's dots and text alternatives, the journey strip order, the doc-page progress bar.
• New desktop-dark and mobile-dark Playwright projects run the axe sweep, reflow, structure and motion checks with the OS preference set to dark.
• screenshots.spec.ts (opt-in) captures a curated route list in every project for review.

Verification

• npm run typecheck, npm run lint (zero warnings), npm test (984 tests, design lint included), npm run build (37 pages prerendered), npm run validate:static (now also checks the colour-scheme meta), npm run audit (0 vulnerabilities).
• npm run test:browser: 421 passed, 0 failed, across four projects (desktop, mobile, desktop-dark, mobile-dark): axe sweep of every route in both colour schemes, structure, motion, reflow at 320/390/1100/1440, behaviour and content specs. The 34 skips are the opt-in screenshot spec and viewport-conditional cases.
• Lighthouse (mobile emulation, local preview), light and dark: Home performance 97, accessibility 100, best practices 100, SEO 100, CLS 0; Blueprint project page 97 / 100 / 100 / 100, CLS 0; Blueprint README 96 / 100 / 100 / 100, CLS 0. The Workshop project page scores 84 on performance because its hero is a 384 KB PNG owned by the workshop folder; this PR does not change repository assets.
• Constellation chunk still about 3 KB gzipped; main bundle 153 KB gzipped (was 146 KB).
• Every page reviewed as full-page screenshots at 1440 and 390 in light and dark; no console errors, no horizontal overflow, one h1 per page, no heading level skips.

One measurement fix outside the plan: the header entrance animation from PR #36 started at opacity 0, and Chrome never reports content first painted at opacity 0 as a Largest Contentful Paint candidate (the compositor-driven fade triggers no new paint record). On pages whose hero fills the mobile viewport Lighthouse therefore reported no LCP and a performance score of 0. The entrance is now a rise without a fade, and every page reports an LCP again.

🤖 Generated with Claude Code