diff --git a/docs-site/.gitignore b/docs-site/.gitignore
index 344275f..b68deb4 100644
--- a/docs-site/.gitignore
+++ b/docs-site/.gitignore
@@ -29,6 +29,7 @@ Thumbs.db
 # Test artifacts
 test-results/
 playwright-report/
+screenshots/
 
 # Python bytecode from scripts/validate_static.py
 __pycache__/
diff --git a/docs-site/README.md b/docs-site/README.md
index 7f51ad4..c0776cf 100644
--- a/docs-site/README.md
+++ b/docs-site/README.md
@@ -122,6 +122,18 @@ The Home hero band carries an ambient constellation drawn on a `<canvas>`: drift
 - **Atlas SVG.** `assets/repository-atlas-journey.svg` draws itself on load (hub, project cards, shared-capability links, then each journey line with its arrowhead) through a `<style>` block inside the SVG, so it also animates when embedded with `<img>`. Every rule sits behind `prefers-reduced-motion: no-preference`; the file contains no script.
 - **Tests.** `tests/browser/motion.spec.ts` checks the running, paused and static states, the pause control, layout shift, the chunk size budget, and that no keyframe animation runs under reduced motion.
 
+## Design system
+
+Every page is built from a small set of shared primitives in `src/components/`, and every colour comes from a semantic token in `src/styles/tokens.css`. That is what keeps the pages consistent and what makes the dark theme a token remap rather than a second stylesheet.
+
+- **Tokens.** Surfaces and roles (`--color-surface`, `--color-surface-sunken`, `--color-band`, `--color-link`, `--color-accent`, `--color-on-accent`, `--color-focus`, `--focus-ring`, `--color-overlay-hover`), text scale (`--text-xs` to `--text-lg`), `--label-tracking`, `--radius-pill`, `--shadow-card`. The raw palette (`--color-cloud`, `--color-mist`, `--color-midnight`) is for tokens.css only. Three breakpoints: 640, 1024 and 1280 px.
+- **Primitives.** `Button` (primary, secondary, ghost; renders a router link, an external link or a button), `Card` (plain, stage accent or tinted; `interactive` adds the hover lift, `reveal` the scroll rise), `SectionHeading` and `Section` (one heading rhythm, left or centred), `ChipNav` (section navigation, jump links, letter navigation), `NumberedSteps` (stage-coloured counters with an optional connector), `StatTile` and `FactStat` (a fact with its source and an optional collapsed caveat), `Sources`, `StageJourney` (the four stages as linked pills), `HeaderGlow` (the static gradient behind every page header).
+- **Page headers.** `PageHeader` renders the single dark band per page: `align="center"` on Home, `variant="compact"` on document pages, a `hue` for the glow, and a `backdrop` slot (Home passes the constellation). Every route, including rendered READMEs and the 404 page, uses it, so every page has exactly one h1 inside one dark header.
+- **Dark theme.** `tokens.css` sets `color-scheme: light dark` and remaps the semantic tokens under `@media (prefers-color-scheme: dark)`. There is no toggle and nothing is stored: the site follows the operating system. `index.html` carries `color-scheme` and two `theme-color` metas, and `validate_static.py` checks the meta on every prerendered page.
+- **Design lint.** `src/styles/designLint.test.ts` scans every CSS module and fails on hex literals, the `white` keyword, `rgba(`, `999px`, raw palette backgrounds and button-like class names outside `Button.module.css`. Run it with `DESIGN_LINT=1 npm test`.
+- **Browser structure checks.** `tests/browser/structure.spec.ts` asserts one dark page header with the single h1 on every route, icon plus text in every posture cell, the text alternative behind the Home capability dots, and the doc-page progress bar. The `desktop-dark` and `mobile-dark` Playwright projects run the axe sweep, reflow and structure checks with the OS preference set to dark.
+- **Screenshots.** `SCREENSHOTS=1 SHOT_DIR=/tmp/shots npx playwright test screenshots` captures a curated route list in every project (light and dark, desktop and mobile) for review; the files are not a gate and are git-ignored.
+
 ## Validation
 
 Before committing:
diff --git a/docs-site/index.html b/docs-site/index.html
index 55489bb..c2329a1 100644
--- a/docs-site/index.html
+++ b/docs-site/index.html
@@ -4,7 +4,9 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <meta name="description" content="AI Agent Factory: enterprise agentic AI samples for AWS with Amazon Bedrock and Amazon Bedrock AgentCore" />
-    <meta name="theme-color" content="#0B1220" />
+    <meta name="color-scheme" content="light dark" />
+    <meta name="theme-color" media="(prefers-color-scheme: light)" content="#0B1220" />
+    <meta name="theme-color" media="(prefers-color-scheme: dark)" content="#070B14" />
     <title>AI Agent Factory</title>
     <link rel="icon" type="image/svg+xml" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'%3E%3Crect width='32' height='32' rx='6' fill='%230B1220'/%3E%3Cpath d='M8 16h16M16 8v16' stroke='%232563EB' stroke-width='3' stroke-linecap='round'/%3E%3C/svg%3E" />
     <!-- hash-shim -->
diff --git a/docs-site/package.json b/docs-site/package.json
index 669ef06..fecca8a 100644
--- a/docs-site/package.json
+++ b/docs-site/package.json
@@ -12,8 +12,8 @@
     "preview": "vite preview",
     "lint": "eslint . --ext ts,tsx,mjs --report-unused-disable-directives --max-warnings 0",
     "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.node.json && tsc --noEmit -p tests/tsconfig.json",
-    "test": "vitest run",
-    "test:watch": "vitest",
+    "test": "DESIGN_LINT=1 vitest run",
+    "test:watch": "DESIGN_LINT=1 vitest",
     "validate:static": "python3 scripts/validate_static.py",
     "audit": "npm audit --audit-level=high",
     "audit:prod": "npm audit --omit=dev --audit-level=high",
diff --git a/docs-site/playwright.config.ts b/docs-site/playwright.config.ts
index 0720652..748e3b3 100644
--- a/docs-site/playwright.config.ts
+++ b/docs-site/playwright.config.ts
@@ -48,5 +48,17 @@ export default defineConfig({
       name: 'desktop',
       use: { ...devices['Desktop Chrome'], viewport: { width: 1440, height: 900 } },
     },
+    // Dark theme sweeps: the same axe, reflow, structure and motion checks with the OS
+    // preference set to dark, so every route is contrast-checked in both schemes.
+    {
+      name: 'desktop-dark',
+      testMatch: /(a11y|reflow|structure|motion|screenshots)\.spec\.ts$/,
+      use: { ...devices['Desktop Chrome'], viewport: { width: 1440, height: 900 }, colorScheme: 'dark' },
+    },
+    {
+      name: 'mobile-dark',
+      testMatch: /(a11y|reflow|structure|screenshots)\.spec\.ts$/,
+      use: { ...devices['Desktop Chrome'], viewport: { width: 390, height: 844 }, colorScheme: 'dark' },
+    },
   ],
 });
diff --git a/docs-site/scripts/validate_static.py b/docs-site/scripts/validate_static.py
index bfea34e..5e4cb9f 100644
--- a/docs-site/scripts/validate_static.py
+++ b/docs-site/scripts/validate_static.py
@@ -93,6 +93,11 @@
 TITLE_PATTERN = re.compile(r"<title[^>]*>(.*?)</title>", re.IGNORECASE | re.DOTALL)
 CANONICAL_PATTERN = re.compile(r"<link[^>]+rel=[\"']canonical[\"']", re.IGNORECASE)
 OG_TITLE_PATTERN = re.compile(r"<meta[^>]+property=[\"']og:title[\"']", re.IGNORECASE)
+COLOR_SCHEME_PATTERN = re.compile(
+    r"<meta[^>]+name=[\"']color-scheme[\"'][^>]+content=[\"']light dark[\"']"
+    r"|<meta[^>]+content=[\"']light dark[\"'][^>]+name=[\"']color-scheme[\"']",
+    re.IGNORECASE,
+)
 NOINDEX_PATTERN = re.compile(
     r"<meta[^>]+name=[\"']robots[\"'][^>]+content=[\"'][^\"']*noindex"
     r"|<meta[^>]+content=[\"'][^\"']*noindex[^\"']*[\"'][^>]+name=[\"']robots[\"']",
@@ -360,6 +365,8 @@ def validate_prerender() -> None:
         if not is_stub:
             if not OG_TITLE_PATTERN.search(head):
                 fail(f"{relative} is missing <meta property=\"og:title\">")
+            if not COLOR_SCHEME_PATTERN.search(head):
+                fail(f"{relative} is missing <meta name=\"color-scheme\" content=\"light dark\"> (dark theme support)")
             continue
 
         # Outside the sitemap only the known redirect stubs may exist, and each must send the
diff --git a/docs-site/src/components/BackToTop.module.css b/docs-site/src/components/BackToTop.module.css
new file mode 100644
index 0000000..a23cd62
--- /dev/null
+++ b/docs-site/src/components/BackToTop.module.css
@@ -0,0 +1,57 @@
+/* Card-like pill fixed bottom-right. Sits under the site header (z 100) and the
+   reading progress bar (z 101). */
+.top {
+  position: fixed;
+  right: var(--space-4);
+  bottom: var(--space-4);
+  z-index: 99;
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-2);
+  min-height: 2.75rem;
+  min-width: 2.75rem;
+  padding: 0 var(--space-4);
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-pill);
+  background: var(--color-surface);
+  color: var(--color-text-primary);
+  box-shadow: var(--shadow-lg);
+  font-size: var(--text-sm);
+  font-weight: 600;
+  line-height: 1.2;
+  text-decoration: none;
+}
+
+.top:hover {
+  border-color: var(--color-link);
+  color: var(--color-link-hover);
+  text-decoration: none;
+}
+
+.top:focus-visible {
+  outline: var(--focus-ring);
+  outline-offset: 2px;
+}
+
+/* Slide in from below the viewport over the first 40vh of scroll. Translate only: the
+   link keeps full contrast at every scroll position. Outside this support and for
+   reduced-motion readers the link is simply visible. */
+@supports (animation-timeline: scroll()) {
+  @media (prefers-reduced-motion: no-preference) {
+    .top {
+      animation: back-to-top-rise linear both;
+      animation-timeline: scroll(root block);
+      animation-range: 0 40vh;
+    }
+  }
+}
+
+@keyframes back-to-top-rise {
+  from {
+    translate: 0 calc(100% + var(--space-6));
+  }
+
+  to {
+    translate: 0 0;
+  }
+}
diff --git a/docs-site/src/components/BackToTop.test.tsx b/docs-site/src/components/BackToTop.test.tsx
new file mode 100644
index 0000000..7637e76
--- /dev/null
+++ b/docs-site/src/components/BackToTop.test.tsx
@@ -0,0 +1,12 @@
+import { render, screen } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+import { BackToTop } from './BackToTop';
+
+describe('BackToTop', () => {
+  it('renders a visibly labelled link to the main landmark', () => {
+    render(<BackToTop />);
+    const link = screen.getByRole('link', { name: 'Back to top' });
+    expect(link).toHaveAttribute('href', '#main-content');
+    expect(link.querySelector('svg')).toHaveAttribute('aria-hidden', 'true');
+  });
+});
diff --git a/docs-site/src/components/BackToTop.tsx b/docs-site/src/components/BackToTop.tsx
new file mode 100644
index 0000000..02e4675
--- /dev/null
+++ b/docs-site/src/components/BackToTop.tsx
@@ -0,0 +1,18 @@
+import { ArrowUp } from 'lucide-react';
+import styles from './BackToTop.module.css';
+
+/**
+ * "Back to top" link for long documents, fixed bottom-right. It targets the main
+ * landmark (`#main-content` in Layout), so activating it both scrolls to the top and
+ * moves focus to the start of the page. In browsers with scroll-driven animations it
+ * slides in from below the viewport during the first 40vh of scrolling (translate only,
+ * never opacity, so its contrast is constant); elsewhere it is simply visible.
+ */
+export function BackToTop() {
+  return (
+    <a href="#main-content" className={styles.top} data-back-to-top>
+      <ArrowUp size={16} aria-hidden="true" />
+      Back to top
+    </a>
+  );
+}
diff --git a/docs-site/src/components/Breadcrumbs.module.css b/docs-site/src/components/Breadcrumbs.module.css
index 434eaca..b971902 100644
--- a/docs-site/src/components/Breadcrumbs.module.css
+++ b/docs-site/src/components/Breadcrumbs.module.css
@@ -1,6 +1,8 @@
+/* Breadcrumb trail. It renders inside the page header's `.on-dark` band, where
+   `--color-text-primary` and `--color-text-secondary` are already remapped to the
+   light set, so only semantic tokens are used here and nothing is hard-coded. */
 .nav {
-  font-size: 0.875rem;
-  margin-bottom: var(--space-4);
+  font-size: var(--text-sm);
 }
 
 .list {
@@ -20,6 +22,7 @@
 .link {
   color: var(--color-text-secondary);
   text-decoration: underline;
+  text-decoration-thickness: from-font;
   text-underline-offset: 0.15em;
   display: inline-flex;
   align-items: center;
@@ -30,6 +33,11 @@
   color: var(--color-text-primary);
 }
 
+.link:focus-visible {
+  outline: var(--focus-ring);
+  outline-offset: 2px;
+}
+
 .current {
   color: var(--color-text-primary);
   font-weight: 500;
diff --git a/docs-site/src/components/Button.module.css b/docs-site/src/components/Button.module.css
new file mode 100644
index 0000000..6c09ca2
--- /dev/null
+++ b/docs-site/src/components/Button.module.css
@@ -0,0 +1,111 @@
+/* The site's single button style. Variants and sizes are data attributes so tests
+   and pages never depend on hashed class names. Colours are tokens only, which is
+   what makes the same button work on light surfaces, inside `.on-dark` bands and
+   in the dark theme. */
+.button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: var(--space-2);
+  min-height: 2.75rem;
+  padding: 0 var(--space-5);
+  border: 1px solid transparent;
+  border-radius: var(--radius-md);
+  font: inherit;
+  font-size: var(--text-base);
+  font-weight: 600;
+  line-height: 1.2;
+  text-decoration: none;
+  cursor: pointer;
+  transition:
+    background-color var(--transition-fast),
+    color var(--transition-fast),
+    border-color var(--transition-fast),
+    translate var(--transition-fast);
+}
+
+.button:hover {
+  text-decoration: none;
+}
+
+.button:focus-visible {
+  outline: var(--focus-ring);
+  outline-offset: 2px;
+}
+
+.button[data-size='sm'] {
+  min-height: 2rem;
+  padding: 0 var(--space-3);
+  font-size: var(--text-sm);
+}
+
+.button[data-size='lg'] {
+  min-height: 3rem;
+  padding: 0 var(--space-6);
+  font-size: 1.0625rem;
+}
+
+/* Primary: accent fill on every surface. */
+.button[data-variant='primary'] {
+  background: var(--color-accent);
+  color: var(--color-on-accent);
+}
+
+.button[data-variant='primary']:hover {
+  background: var(--color-blue-hover);
+  color: var(--color-on-accent);
+}
+
+/* Secondary: outline in the current text colour, so it adapts to dark bands by inheritance. */
+.button[data-variant='secondary'] {
+  background: transparent;
+  color: var(--color-text-primary);
+  border-color: currentColor;
+}
+
+.button[data-variant='secondary']:hover {
+  background: var(--color-overlay-hover);
+  color: var(--color-text-primary);
+}
+
+/* Ghost: link-coloured text, no border, quiet hover. */
+.button[data-variant='ghost'] {
+  background: transparent;
+  color: var(--color-link);
+  padding-inline: var(--space-3);
+}
+
+.button[data-variant='ghost']:hover {
+  background: var(--color-overlay-hover);
+  color: var(--color-link-hover);
+  text-decoration: underline;
+}
+
+.icon {
+  display: inline-flex;
+  flex-shrink: 0;
+}
+
+.icon > svg {
+  display: block;
+}
+
+.label {
+  min-width: 0;
+}
+
+/* Micro-interactions: pointer devices only, never under reduced motion. */
+@media (hover: hover) and (prefers-reduced-motion: no-preference) {
+  .iconEnd {
+    transition: translate var(--transition-fast);
+  }
+
+  .button:hover .iconEnd,
+  .button:focus-visible .iconEnd {
+    translate: 2px 0;
+  }
+
+  .button:active {
+    translate: 0 1px;
+  }
+}
diff --git a/docs-site/src/components/Button.test.tsx b/docs-site/src/components/Button.test.tsx
new file mode 100644
index 0000000..a5b2da7
--- /dev/null
+++ b/docs-site/src/components/Button.test.tsx
@@ -0,0 +1,55 @@
+import { fireEvent, render, screen } from '@testing-library/react';
+import { ArrowRight } from 'lucide-react';
+import { MemoryRouter } from 'react-router-dom';
+import { describe, expect, it, vi } from 'vitest';
+import { Button } from './Button';
+
+describe('Button', () => {
+  it('renders a router link with variant and size data attributes', () => {
+    render(
+      <MemoryRouter>
+        <Button to="/start/" variant="secondary" size="lg" iconEnd={<ArrowRight />}>
+          Get started
+        </Button>
+      </MemoryRouter>,
+    );
+    const link = screen.getByRole('link', { name: 'Get started' });
+    expect(link).toHaveAttribute('href', '/start/');
+    expect(link).toHaveAttribute('data-variant', 'secondary');
+    expect(link).toHaveAttribute('data-size', 'lg');
+    expect(link.querySelector('[data-icon-end]')).toHaveAttribute('aria-hidden', 'true');
+  });
+
+  it('renders an external anchor that opens in a new tab and says so', () => {
+    render(
+      <Button href="https://github.com/aws-samples/sample-ai-agent-factory" external>
+        Source on GitHub
+      </Button>,
+    );
+    const link = screen.getByRole('link', { name: 'Source on GitHub (opens in new tab)' });
+    expect(link).toHaveAttribute('target', '_blank');
+    expect(link).toHaveAttribute('rel', 'noopener noreferrer');
+    expect(link).toHaveAttribute('data-variant', 'primary');
+  });
+
+  it('renders a plain anchor for in-page fragments', () => {
+    render(<Button href="#quickstart">Quickstart</Button>);
+    const link = screen.getByRole('link', { name: 'Quickstart' });
+    expect(link).toHaveAttribute('href', '#quickstart');
+    expect(link).not.toHaveAttribute('target');
+  });
+
+  it('renders a real button that defaults to type="button" and forwards clicks', () => {
+    const onClick = vi.fn();
+    render(
+      <Button variant="ghost" onClick={onClick} aria-pressed="false">
+        Pause
+      </Button>,
+    );
+    const button = screen.getByRole('button', { name: 'Pause' });
+    expect(button).toHaveAttribute('type', 'button');
+    expect(button).toHaveAttribute('aria-pressed', 'false');
+    fireEvent.click(button);
+    expect(onClick).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/docs-site/src/components/Button.tsx b/docs-site/src/components/Button.tsx
new file mode 100644
index 0000000..b3b9d8d
--- /dev/null
+++ b/docs-site/src/components/Button.tsx
@@ -0,0 +1,102 @@
+import type { AnchorHTMLAttributes, ButtonHTMLAttributes, ReactNode } from 'react';
+import { Link, type LinkProps } from 'react-router-dom';
+import { ExternalLink } from './ExternalLink';
+import styles from './Button.module.css';
+
+export type ButtonVariant = 'primary' | 'secondary' | 'ghost';
+export type ButtonSize = 'sm' | 'md' | 'lg';
+
+interface BaseProps {
+  variant?: ButtonVariant;
+  size?: ButtonSize;
+  /** Decorative icon before the label (rendered aria-hidden). */
+  iconStart?: ReactNode;
+  /** Decorative icon after the label (rendered aria-hidden); nudges on hover. */
+  iconEnd?: ReactNode;
+  className?: string;
+  children: ReactNode;
+}
+
+/** Internal navigation via react-router. */
+type AsLink = BaseProps & { to: string; href?: never } & Omit<LinkProps, 'to' | 'className' | 'children'>;
+/** Plain anchor: in-page fragment, or an external URL when `external` is set (opens in a new tab). */
+type AsAnchor = BaseProps & {
+  href: string;
+  to?: never;
+  external?: boolean;
+} & Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'href' | 'className' | 'children' | 'target' | 'rel'>;
+/** Real button. */
+type AsButton = BaseProps & { to?: never; href?: never } & Omit<
+    ButtonHTMLAttributes<HTMLButtonElement>,
+    'className' | 'children'
+  >;
+
+export type ButtonProps = AsLink | AsAnchor | AsButton;
+
+/**
+ * The one button style for the site. Renders a react-router `Link` when `to` is
+ * given, an anchor (wrapped in `ExternalLink` when `external`) when `href` is
+ * given, and a `<button>` otherwise. Colours come from tokens, so the same
+ * markup works inside `.on-dark` containers without extra props.
+ */
+export function Button(props: ButtonProps) {
+  const { variant = 'primary', size = 'md', iconStart, iconEnd, className, children } = props;
+  const classes = [styles.button, className].filter(Boolean).join(' ');
+  const data = { 'data-variant': variant, 'data-size': size } as const;
+  const content = (
+    <>
+      {iconStart && (
+        <span className={styles.icon} aria-hidden="true">
+          {iconStart}
+        </span>
+      )}
+      <span className={styles.label}>{children}</span>
+      {iconEnd && (
+        <span className={`${styles.icon} ${styles.iconEnd}`} data-icon-end aria-hidden="true">
+          {iconEnd}
+        </span>
+      )}
+    </>
+  );
+
+  if ('to' in props && props.to !== undefined) {
+    const { to, ...rest } = withoutBase(props);
+    return (
+      <Link {...rest} {...data} to={to} className={classes}>
+        {content}
+      </Link>
+    );
+  }
+
+  if ('href' in props && props.href !== undefined) {
+    const { href, external, ...rest } = withoutBase(props);
+    if (external) {
+      return (
+        <ExternalLink {...rest} {...data} href={href} className={classes} iconSize={16} hideIcon={Boolean(iconEnd)}>
+          {content}
+        </ExternalLink>
+      );
+    }
+    return (
+      <a {...rest} {...data} href={href} className={classes}>
+        {content}
+      </a>
+    );
+  }
+
+  const { type, ...rest } = withoutBase(props);
+  return (
+    <button {...rest} {...data} type={type ?? 'button'} className={classes}>
+      {content}
+    </button>
+  );
+}
+
+const BASE_KEYS = ['variant', 'size', 'iconStart', 'iconEnd', 'className', 'children'] as const;
+
+/** Drop the presentational props so the rest can spread onto the rendered element. */
+function withoutBase<T extends BaseProps>(props: T): Omit<T, (typeof BASE_KEYS)[number]> {
+  const rest = { ...props } as Record<string, unknown>;
+  for (const key of BASE_KEYS) delete rest[key];
+  return rest as Omit<T, (typeof BASE_KEYS)[number]>;
+}
diff --git a/docs-site/src/components/Card.module.css b/docs-site/src/components/Card.module.css
new file mode 100644
index 0000000..c349a1d
--- /dev/null
+++ b/docs-site/src/components/Card.module.css
@@ -0,0 +1,113 @@
+/* The site's single card surface. Variants and padding are data attributes. */
+.card {
+  position: relative;
+  background: var(--color-surface);
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-lg);
+  box-shadow: var(--shadow-card);
+  min-width: 0;
+}
+
+.card[data-padding='sm'] {
+  padding: var(--space-3) var(--space-4);
+}
+
+.card[data-padding='md'] {
+  padding: var(--space-5);
+}
+
+.card[data-padding='lg'] {
+  padding: var(--space-6);
+}
+
+/* Stage accent: a 4 px top rule in the stage hue. */
+.card[data-variant='accent'] {
+  border-top: 4px solid var(--card-accent, var(--color-border));
+}
+
+.card[data-stage='learn'] {
+  --card-accent: var(--stage-learn-tint);
+  --stage-color: var(--stage-learn);
+}
+
+.card[data-stage='build'] {
+  --card-accent: var(--stage-build-tint);
+  --stage-color: var(--stage-build);
+}
+
+.card[data-stage='govern'] {
+  --card-accent: var(--stage-govern-tint);
+  --stage-color: var(--stage-govern);
+}
+
+.card[data-stage='scale'] {
+  --card-accent: var(--stage-scale-tint);
+  --stage-color: var(--stage-scale);
+}
+
+/* Tinted: soft surface with a left rule, for contract and checklist boxes. */
+.card[data-variant='tinted'] {
+  background: var(--card-tint-bg);
+  border-color: transparent;
+  border-left: 4px solid var(--card-tint-rule);
+  box-shadow: none;
+}
+
+.card[data-tint='amber'] {
+  --card-tint-bg: var(--tint-amber);
+  --card-tint-rule: var(--stage-learn-tint);
+  --card-tint-heading: var(--tint-heading-amber);
+}
+
+.card[data-tint='green'] {
+  --card-tint-bg: var(--tint-green);
+  --card-tint-rule: var(--stage-build-tint);
+  --card-tint-heading: var(--tint-heading-green);
+}
+
+.card[data-tint='violet'] {
+  --card-tint-bg: var(--tint-violet);
+  --card-tint-rule: var(--stage-govern-tint);
+  --card-tint-heading: var(--tint-heading-violet);
+}
+
+.card[data-tint='blue'] {
+  --card-tint-bg: var(--tint-blue);
+  --card-tint-rule: var(--stage-scale-tint);
+  --card-tint-heading: var(--tint-heading-blue);
+}
+
+.card[data-variant='tinted'] :is(h2, h3, h4) {
+  color: var(--card-tint-heading);
+}
+
+/* Interactive cards: the border picks up the link colour on hover; the lift itself
+   comes from the shared [data-lift] rule in tokens.css. */
+.card[data-lift] {
+  transition:
+    border-color var(--transition-normal),
+    translate var(--transition-normal),
+    box-shadow var(--transition-normal);
+}
+
+.card[data-lift]:hover,
+.card[data-lift]:focus-within {
+  border-color: var(--color-link);
+}
+
+/* One inner link can stretch over the whole card. */
+.card [data-stretch]::after {
+  content: '';
+  position: absolute;
+  inset: 0;
+  border-radius: inherit;
+}
+
+.card [data-stretch]:focus-visible {
+  outline: none;
+}
+
+.card:has([data-stretch]:focus-visible) {
+  outline: var(--focus-ring);
+  outline-offset: 2px;
+}
diff --git a/docs-site/src/components/Card.test.tsx b/docs-site/src/components/Card.test.tsx
new file mode 100644
index 0000000..0fc8965
--- /dev/null
+++ b/docs-site/src/components/Card.test.tsx
@@ -0,0 +1,37 @@
+import { render, screen } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+import { Card } from './Card';
+
+describe('Card', () => {
+  it('renders a plain div card with medium padding by default', () => {
+    render(<Card>Body</Card>);
+    const card = screen.getByText('Body');
+    expect(card.tagName).toBe('DIV');
+    expect(card).toHaveAttribute('data-card');
+    expect(card).toHaveAttribute('data-variant', 'plain');
+    expect(card).toHaveAttribute('data-padding', 'md');
+    expect(card).not.toHaveAttribute('data-lift');
+    expect(card).not.toHaveAttribute('data-reveal');
+  });
+
+  it('renders the requested element with stage accent, lift and reveal', () => {
+    render(
+      <ul>
+        <Card as="li" variant="accent" stage="govern" interactive reveal padding="sm" aria-label="MCP Gateway">
+          Content
+        </Card>
+      </ul>,
+    );
+    const card = screen.getByRole('listitem', { name: 'MCP Gateway' });
+    expect(card).toHaveAttribute('data-variant', 'accent');
+    expect(card).toHaveAttribute('data-stage', 'govern');
+    expect(card).toHaveAttribute('data-lift', '');
+    expect(card).toHaveAttribute('data-reveal', '');
+    expect(card).toHaveAttribute('data-padding', 'sm');
+  });
+
+  it('defaults the tinted variant to the blue tint', () => {
+    render(<Card variant="tinted">Note</Card>);
+    expect(screen.getByText('Note')).toHaveAttribute('data-tint', 'blue');
+  });
+});
diff --git a/docs-site/src/components/Card.tsx b/docs-site/src/components/Card.tsx
new file mode 100644
index 0000000..a81ec59
--- /dev/null
+++ b/docs-site/src/components/Card.tsx
@@ -0,0 +1,58 @@
+import type { HTMLAttributes, ReactNode } from 'react';
+import type { JourneyStage } from '../content/data';
+import styles from './Card.module.css';
+
+export type CardTint = 'amber' | 'green' | 'violet' | 'blue';
+
+export interface CardProps extends Omit<HTMLAttributes<HTMLElement>, 'className' | 'children'> {
+  /** Element to render; list items and articles keep their semantics. */
+  as?: 'div' | 'li' | 'article' | 'section';
+  /** plain: bordered surface; accent: 4 px stage-coloured top border; tinted: soft tint with a left rule. */
+  variant?: 'plain' | 'accent' | 'tinted';
+  /** Stage for the accent variant (also exposed as data-stage for badges inside). */
+  stage?: JourneyStage;
+  /** Tint for the tinted variant. */
+  tint?: CardTint;
+  /** Hover lift and link-coloured border; use when the whole card or its main link is clickable. */
+  interactive?: boolean;
+  /** Rise into place on scroll (progressive enhancement, see tokens.css). */
+  reveal?: boolean;
+  padding?: 'sm' | 'md' | 'lg';
+  className?: string;
+  children: ReactNode;
+}
+
+/**
+ * The one card surface for the site: one radius, one border, a resting shadow.
+ * Pages add their own inner layout through `className`; the card owns only the box.
+ * A single inner link marked `data-stretch` makes the whole card clickable while
+ * keeping one accessible link.
+ */
+export function Card({
+  as: Tag = 'div',
+  variant = 'plain',
+  stage,
+  tint,
+  interactive = false,
+  reveal = false,
+  padding = 'md',
+  className,
+  children,
+  ...rest
+}: CardProps) {
+  return (
+    <Tag
+      {...rest}
+      className={[styles.card, className].filter(Boolean).join(' ')}
+      data-card
+      data-variant={variant}
+      data-padding={padding}
+      data-stage={stage}
+      data-tint={variant === 'tinted' ? (tint ?? 'blue') : undefined}
+      data-lift={interactive ? '' : undefined}
+      data-reveal={reveal ? '' : undefined}
+    >
+      {children}
+    </Tag>
+  );
+}
diff --git a/docs-site/src/components/ChipNav.module.css b/docs-site/src/components/ChipNav.module.css
new file mode 100644
index 0000000..adbe115
--- /dev/null
+++ b/docs-site/src/components/ChipNav.module.css
@@ -0,0 +1,98 @@
+.nav {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--space-2);
+  margin: var(--space-4) 0;
+  min-width: 0;
+}
+
+.nav[data-sticky] {
+  position: sticky;
+  top: var(--header-height);
+  z-index: 5;
+  margin: 0;
+  padding: var(--space-2) 0;
+  background: var(--color-bg-primary);
+}
+
+.lead {
+  font-size: var(--text-sm);
+  font-weight: 600;
+  color: var(--color-text-secondary);
+  margin-right: var(--space-1);
+}
+
+.chips {
+  list-style: none;
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--space-2);
+  position: relative;
+  min-width: 0;
+  max-width: 100%;
+}
+
+/* Below 640 px the scroll variant forms one row that scrolls inside the list. */
+.nav[data-overflow='scroll'] .chips {
+  flex-wrap: nowrap;
+  overflow-x: auto;
+  padding-bottom: var(--space-1);
+  scrollbar-width: thin;
+}
+
+@media (min-width: 640px) {
+  .nav[data-overflow='scroll'] .chips {
+    flex-wrap: wrap;
+    overflow: visible;
+    padding-bottom: 0;
+  }
+}
+
+.chip {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-2);
+  min-height: 2rem;
+  padding: var(--space-1) var(--space-3);
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-pill);
+  background: var(--color-surface);
+  color: var(--color-text-primary);
+  font-size: var(--text-sm);
+  font-weight: 500;
+  text-decoration: none;
+  white-space: nowrap;
+  transition:
+    border-color var(--transition-fast),
+    color var(--transition-fast);
+}
+
+.nav[data-size='sm'] .chip {
+  min-height: var(--target-min);
+  min-width: var(--target-min);
+  padding: 0 var(--space-2);
+  font-size: var(--text-xs);
+  font-weight: 600;
+}
+
+.chip:hover {
+  color: var(--color-link-hover);
+  border-color: var(--color-link);
+  text-decoration: underline;
+}
+
+.chip:focus-visible {
+  outline: var(--focus-ring);
+  outline-offset: 2px;
+}
+
+.chip[aria-current='page'] {
+  color: var(--color-link-hover);
+  border-color: var(--color-link);
+  font-weight: 600;
+}
+
+.badge {
+  display: inline-flex;
+}
diff --git a/docs-site/src/components/ChipNav.test.tsx b/docs-site/src/components/ChipNav.test.tsx
new file mode 100644
index 0000000..e8d6e65
--- /dev/null
+++ b/docs-site/src/components/ChipNav.test.tsx
@@ -0,0 +1,40 @@
+import { render, screen } from '@testing-library/react';
+import { MemoryRouter } from 'react-router-dom';
+import { describe, expect, it } from 'vitest';
+import { ChipNav } from './ChipNav';
+
+describe('ChipNav', () => {
+  it('marks the current page among router items and renders plain anchors for fragments', () => {
+    render(
+      <MemoryRouter initialEntries={['/concepts/architecture']}>
+        <ChipNav
+          label="Concepts section"
+          lead="In this section:"
+          items={[
+            { label: 'Agent Factory', to: '/concepts/agent-factory/' },
+            { label: 'Architecture', to: '/concepts/architecture/' },
+            { label: 'Diagrams', href: '#diagrams' },
+          ]}
+        />
+      </MemoryRouter>,
+    );
+    const nav = screen.getByRole('navigation', { name: 'Concepts section' });
+    expect(nav).toHaveTextContent('In this section:');
+    expect(nav).toHaveAttribute('data-overflow', 'scroll');
+    expect(screen.getByRole('link', { name: 'Architecture' })).toHaveAttribute('aria-current', 'page');
+    expect(screen.getByRole('link', { name: 'Agent Factory' })).not.toHaveAttribute('aria-current');
+    expect(screen.getByRole('link', { name: 'Diagrams' })).toHaveAttribute('href', '#diagrams');
+  });
+
+  it('exposes sticky and size as data attributes', () => {
+    render(
+      <MemoryRouter>
+        <ChipNav label="Letters" size="sm" sticky overflow="wrap" items={[{ label: 'A', href: '#a' }]} />
+      </MemoryRouter>,
+    );
+    const nav = screen.getByRole('navigation', { name: 'Letters' });
+    expect(nav).toHaveAttribute('data-sticky', '');
+    expect(nav).toHaveAttribute('data-size', 'sm');
+    expect(nav).toHaveAttribute('data-overflow', 'wrap');
+  });
+});
diff --git a/docs-site/src/components/ChipNav.tsx b/docs-site/src/components/ChipNav.tsx
new file mode 100644
index 0000000..f274300
--- /dev/null
+++ b/docs-site/src/components/ChipNav.tsx
@@ -0,0 +1,74 @@
+import type { ReactNode } from 'react';
+import { Link, useLocation } from 'react-router-dom';
+import styles from './ChipNav.module.css';
+
+export interface ChipNavItem {
+  label: ReactNode;
+  /** Site path (react-router); the current page is marked with aria-current. */
+  to?: string;
+  /** In-page fragment ("#quickstart") or other plain href. */
+  href?: string;
+  /** Optional decoration before the label, for example an outline stage badge. */
+  badge?: ReactNode;
+}
+
+export interface ChipNavProps {
+  /** Accessible name of the nav landmark. Required: several chip navs can share a page. */
+  label: string;
+  /** Visible lead text before the chips, for example "Jump to:". */
+  lead?: ReactNode;
+  items: ChipNavItem[];
+  /** scroll: one row that scrolls below 640 px and wraps above; wrap: always wraps. */
+  overflow?: 'scroll' | 'wrap';
+  size?: 'sm' | 'md';
+  /** Stick under the site header while the section scrolls (letter navs, long pages). */
+  sticky?: boolean;
+  className?: string;
+}
+
+const normalise = (path: string) => path.replace(/\/+$/, '') || '/';
+
+/**
+ * The site's one chip rail: section navigation, in-page jump links and letter
+ * navigation all render through it. Items with `to` mark the current page.
+ */
+export function ChipNav({ label, lead, items, overflow = 'scroll', size = 'md', sticky = false, className }: ChipNavProps) {
+  const { pathname } = useLocation();
+  const current = normalise(pathname);
+  return (
+    <nav
+      aria-label={label}
+      className={[styles.nav, className].filter(Boolean).join(' ')}
+      data-chip-nav
+      data-overflow={overflow}
+      data-size={size}
+      data-sticky={sticky ? '' : undefined}
+    >
+      {lead && <span className={styles.lead}>{lead}</span>}
+      <ul className={styles.chips}>
+        {items.map((item, index) => {
+          const key = item.to ?? item.href ?? String(index);
+          const inner = (
+            <>
+              {item.badge && <span className={styles.badge}>{item.badge}</span>}
+              <span>{item.label}</span>
+            </>
+          );
+          return (
+            <li key={key}>
+              {item.to ? (
+                <Link to={item.to} className={styles.chip} aria-current={normalise(item.to) === current ? 'page' : undefined}>
+                  {inner}
+                </Link>
+              ) : (
+                <a href={item.href} className={styles.chip}>
+                  {inner}
+                </a>
+              )}
+            </li>
+          );
+        })}
+      </ul>
+    </nav>
+  );
+}
diff --git a/docs-site/src/components/CodeBlock.module.css b/docs-site/src/components/CodeBlock.module.css
index 35b1299..66ab0f7 100644
--- a/docs-site/src/components/CodeBlock.module.css
+++ b/docs-site/src/components/CodeBlock.module.css
@@ -2,7 +2,7 @@
   position: relative;
   margin: var(--space-4) 0;
   border-radius: var(--radius-md);
-  background: var(--color-midnight);
+  background: var(--color-band);
   color: var(--color-cloud);
   overflow: hidden;
 }
@@ -13,7 +13,7 @@
   justify-content: space-between;
   gap: var(--space-2);
   padding: var(--space-1) var(--space-2) var(--space-1) var(--space-4);
-  background: var(--color-midnight-light);
+  background: var(--color-band-raised);
   font-size: 0.75rem;
 }
 
@@ -36,7 +36,7 @@
 }
 
 .copy:hover {
-  background: rgba(255, 255, 255, 0.12);
+  background: var(--color-overlay-strong);
 }
 
 .copy:focus-visible {
diff --git a/docs-site/src/components/Constellation.module.css b/docs-site/src/components/Constellation.module.css
index eb852b6..c42cce6 100644
--- a/docs-site/src/components/Constellation.module.css
+++ b/docs-site/src/components/Constellation.module.css
@@ -1,5 +1,6 @@
-/* Fills PageHeader's backdrop slot. The header band keeps its own midnight background, so the
-   canvas only adds the constellation on top; without JavaScript nothing here exists. */
+/* Fills PageHeader's backdrop slot. The header band keeps its own background, so the canvas only
+   adds the constellation on top; without JavaScript nothing here exists. Colours are semantic
+   tokens resolved inside the header's `.on-dark` scope. */
 .root {
   position: absolute;
   inset: 0;
@@ -12,14 +13,14 @@
   height: 100%;
 }
 
-/* Bottom 40 percent fades back to midnight so the actions row and lead stay readable. */
+/* Bottom 40 percent fades back to the band colour so the actions row and lead stay readable. */
 .fade {
   position: absolute;
   left: 0;
   right: 0;
   bottom: 0;
   height: 40%;
-  background: linear-gradient(to bottom, rgba(11, 18, 32, 0), var(--color-midnight));
+  background: linear-gradient(to bottom, transparent, var(--color-band));
 }
 
 /* The WCAG 2.2.2 pause control: bottom-right, inside the band's padding so it never overlaps
@@ -33,10 +34,10 @@
   gap: var(--space-1);
   min-height: 28px;
   padding: 0 var(--space-3);
-  border: 1px solid rgba(245, 247, 251, 0.35);
-  border-radius: 999px;
-  background: rgba(11, 18, 32, 0.85);
-  color: var(--color-cloud);
+  border: 1px solid color-mix(in srgb, var(--color-text-primary) 35%, transparent);
+  border-radius: var(--radius-pill);
+  background: color-mix(in srgb, var(--color-band) 85%, transparent);
+  color: var(--color-text-primary);
   font: inherit;
   font-size: 0.8125rem;
   font-weight: 600;
@@ -50,12 +51,12 @@
 }
 
 .toggle:hover {
-  border-color: var(--color-cloud);
-  background: var(--color-midnight-light);
+  border-color: var(--color-text-primary);
+  background: var(--color-band-raised);
 }
 
 .toggle:focus-visible {
-  outline: 2px solid var(--color-cloud);
+  outline: var(--focus-ring);
   outline-offset: 2px;
 }
 
diff --git a/docs-site/src/components/Constellation.tsx b/docs-site/src/components/Constellation.tsx
index 31f4765..65503bd 100644
--- a/docs-site/src/components/Constellation.tsx
+++ b/docs-site/src/components/Constellation.tsx
@@ -40,14 +40,26 @@ function isLowPower(): boolean {
   return (typeof cores === 'number' && cores <= 4) || window.innerWidth < 640;
 }
 
-/** Bounding box of the hero copy column relative to the backdrop, so drawing under the text can be dimmed. */
+/** Padding (CSS px) added around the copy block so the dimmed area clears the text comfortably. */
+const COPY_MARGIN = 16;
+
+/**
+ * Bounding box of the header's copy block (the element wrapping the h1), relative to the backdrop,
+ * so drawing under the text can be dimmed. Measured from the DOM rather than assumed, so it follows
+ * the block wherever the header places it (left column or centred).
+ */
 function measureCopyRegion(root: HTMLElement): Rect | null {
-  const heading = root.parentElement?.querySelector('h1');
-  const copy = heading?.parentElement;
+  const header = root.closest<HTMLElement>('[data-page-header]') ?? root.parentElement?.parentElement ?? null;
+  const copy = header?.querySelector<HTMLElement>('[data-copy]') ?? header?.querySelector('h1')?.parentElement ?? null;
   if (!copy) return null;
   const rootRect = root.getBoundingClientRect();
   const copyRect = copy.getBoundingClientRect();
-  return { x: copyRect.left - rootRect.left, y: copyRect.top - rootRect.top, width: copyRect.width, height: copyRect.height };
+  return {
+    x: copyRect.left - rootRect.left - COPY_MARGIN,
+    y: copyRect.top - rootRect.top - COPY_MARGIN,
+    width: copyRect.width + COPY_MARGIN * 2,
+    height: copyRect.height + COPY_MARGIN * 2,
+  };
 }
 
 /** Whether the animation should run given the visitor's choice and their motion preference. */
diff --git a/docs-site/src/components/DocPage.module.css b/docs-site/src/components/DocPage.module.css
index ea34307..3aa974a 100644
--- a/docs-site/src/components/DocPage.module.css
+++ b/docs-site/src/components/DocPage.module.css
@@ -1,8 +1,16 @@
 .page {
-  padding-top: var(--space-6);
+  padding-top: var(--space-8);
   padding-bottom: var(--section-padding-y);
 }
 
+/* Source path in the header lead: monospace, wraps anywhere so long repository paths
+   never widen the band at narrow widths. Inherits the lead's on-dark colour. */
+.sourcePath {
+  font-family: var(--font-mono);
+  font-size: 0.9em;
+  overflow-wrap: anywhere;
+}
+
 .layout,
 .layoutNoSidebar {
   display: grid;
@@ -76,9 +84,9 @@
   min-height: 36px;
   padding: var(--space-1) var(--space-3);
   border: 1px solid var(--color-border);
-  border-radius: 999px;
+  border-radius: var(--radius-pill);
   color: var(--color-text-secondary);
-  background: var(--color-bg-secondary);
+  background: var(--color-surface);
   white-space: nowrap;
   text-decoration: none;
 }
@@ -89,8 +97,8 @@
 }
 
 .sidebarLink[aria-current='page'] {
-  color: var(--color-blue-hover);
-  border-color: var(--color-blue);
+  color: var(--color-link-hover);
+  border-color: var(--color-link);
   font-weight: 600;
 }
 
@@ -122,7 +130,7 @@
   }
 
   .sidebarLink[aria-current='page'] {
-    border-left-color: var(--color-blue);
+    border-left-color: var(--color-link);
   }
 }
 
@@ -131,15 +139,6 @@
   min-width: 0;
 }
 
-.header {
-  margin-bottom: var(--space-6);
-}
-
-.source {
-  margin-top: var(--space-2);
-  font-size: 0.875rem;
-}
-
 .body {
   line-height: 1.7;
 }
@@ -201,7 +200,7 @@
   border-top: 1px solid var(--color-border);
 }
 
-/* Previous / next */
+/* Previous / next: two interactive cards, each stretched over by its single link. */
 .pager {
   display: grid;
   grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
@@ -211,26 +210,32 @@
   border-top: 1px solid var(--color-border);
 }
 
+.pagerCard {
+  display: flex;
+  min-height: 48px;
+}
+
 .pagerLink {
   display: flex;
+  flex: 1;
   align-items: center;
   gap: var(--space-2);
   min-width: 0;
   overflow-wrap: anywhere;
-  min-height: 48px;
-  padding: var(--space-3);
-  border: 1px solid var(--color-border);
-  border-radius: var(--radius-md);
   color: var(--color-text-primary);
-  background: var(--color-bg-secondary);
   text-decoration: none;
 }
 
 .pagerLink:hover {
-  border-color: var(--color-blue);
+  color: var(--color-text-primary);
   text-decoration: underline;
 }
 
+/* Long labels must not squeeze the arrow. */
+.pagerLink > svg {
+  flex-shrink: 0;
+}
+
 .pagerNext {
   justify-content: flex-end;
   text-align: right;
@@ -238,9 +243,9 @@
 
 .pagerLabel {
   display: block;
-  font-size: 0.75rem;
+  font-size: var(--text-xs);
   text-transform: uppercase;
-  letter-spacing: 0.04em;
+  letter-spacing: var(--label-tracking);
   color: var(--color-text-secondary);
 }
 
@@ -257,14 +262,14 @@
     top: calc(var(--header-height) + var(--space-4));
     max-height: calc(100vh - var(--header-height) - var(--space-8));
     overflow-y: auto;
-    font-size: 0.875rem;
+    font-size: var(--text-sm);
   }
 }
 
 .tocHeading {
-  font-size: 0.75rem;
+  font-size: var(--text-xs);
   text-transform: uppercase;
-  letter-spacing: 0.06em;
+  letter-spacing: var(--label-tracking);
   color: var(--color-text-secondary);
   margin-bottom: var(--space-2);
 }
diff --git a/docs-site/src/components/DocPage.tsx b/docs-site/src/components/DocPage.tsx
index f0d7d2e..611c579 100644
--- a/docs-site/src/components/DocPage.tsx
+++ b/docs-site/src/components/DocPage.tsx
@@ -1,15 +1,21 @@
+import type { ReactNode } from 'react';
 import { Link } from 'react-router-dom';
 import { ArrowLeft, ArrowRight } from 'lucide-react';
-import { getProjectById } from '../content/data';
+import { getProjectById, type JourneyStage, type Project } from '../content/data';
 import { docsForProject, type DocEntry } from '../content/docs';
 import { docLabel, docTitle } from '../docs/docModules';
 import type { DocModule } from '../docs/types';
-import { blob } from '../content/links';
+import { blob, ISSUES_URL } from '../content/links';
 import { PATHS, projectPath } from '../paths';
+import { BackToTop } from './BackToTop';
 import { Breadcrumbs, type Crumb } from './Breadcrumbs';
-import { ExternalLink } from './ExternalLink';
+import { Button } from './Button';
+import { Card } from './Card';
+import type { HeaderHue } from './HeaderGlow';
 import { mdxComponents } from './mdxComponents';
+import { PageHeader } from './PageHeader';
 import { PageMeta } from './PageMeta';
+import { ReadingProgress } from './ReadingProgress';
 import styles from './DocPage.module.css';
 
 export interface DocPageProps {
@@ -17,10 +23,53 @@ export interface DocPageProps {
   mod: DocModule;
 }
 
+/** What the compact header shows for one document kind. */
+interface HeaderPlan {
+  eyebrow: string;
+  stage?: JourneyStage;
+  hue?: HeaderHue;
+  /** Secondary actions after "View source on GitHub". */
+  extraActions: ReactNode;
+}
+
+/**
+ * Header copy per DocEntry kind. Every kind keeps the "View source on GitHub" action;
+ * README and doc pages add a ghost link back to the project page, and the repository-level
+ * CONTRIBUTING page adds "Report an issue" instead of a project link.
+ */
+function headerPlan(entry: DocEntry, project: Project | undefined): HeaderPlan {
+  const projectLink = project ? (
+    <Button variant="ghost" size="sm" to={projectPath(project.id)}>
+      Project page
+    </Button>
+  ) : null;
+  switch (entry.kind) {
+    case 'readme':
+      return { eyebrow: 'README', stage: project?.stage, extraActions: projectLink };
+    case 'doc':
+      return { eyebrow: `${project?.shortName ?? 'Project'} docs`, stage: project?.stage, extraActions: projectLink };
+    case 'changelog':
+      return { eyebrow: 'Changelog', stage: project?.stage, extraActions: null };
+    case 'connector':
+      return { eyebrow: 'Connector', stage: project?.stage ?? 'govern', extraActions: null };
+    case 'contributing':
+      return {
+        eyebrow: 'Repository',
+        hue: 'slate',
+        extraActions: (
+          <Button variant="ghost" size="sm" href={ISSUES_URL} external>
+            Report an issue
+          </Button>
+        ),
+      };
+  }
+}
+
 /**
- * Page shell for a rendered repository Markdown file: breadcrumbs, project
- * sidebar, h1 from the file's own title, source link, TOC rail, MDX body and
- * previous/next links within the project.
+ * Page shell for a rendered repository Markdown file: a compact dark header band
+ * (breadcrumbs, kind eyebrow, stage badge, the file's own h1 title, source path and
+ * actions), a reading progress bar, the project sidebar, TOC rail, MDX body,
+ * previous/next cards within the project and a back-to-top link.
  */
 export function DocPage({ entry, mod }: DocPageProps) {
   const title = docTitle(entry);
@@ -31,6 +80,7 @@ export function DocPage({ entry, mod }: DocPageProps) {
   const next = index >= 0 && index < siblings.length - 1 ? siblings[index + 1] : undefined;
   const Content = mod.default;
   const toc = mod.toc ?? [];
+  const plan = headerPlan(entry, project);
 
   const crumbs: Crumb[] = [{ label: 'Home', to: PATHS.home }];
   if (project) {
@@ -45,85 +95,109 @@ export function DocPage({ entry, mod }: DocPageProps) {
     ? `${title}. Rendered from ${entry.sourcePath} in the ${project.shortName} project of the AI Agent Factory repository.`
     : `${title}. Rendered from ${entry.sourcePath} in the AI Agent Factory repository.`;
 
+  const actions = (
+    <>
+      <Button variant="secondary" size="sm" href={blob(entry.sourcePath)} external>
+        View source on GitHub
+      </Button>
+      {plan.extraActions}
+    </>
+  );
+
   return (
-    <div className={`container ${styles.page}`}>
+    <>
       <PageMeta title={pageTitle} description={description} />
-      <Breadcrumbs items={crumbs} />
-      <div className={siblings.length > 1 ? styles.layout : styles.layoutNoSidebar}>
-        {siblings.length > 1 && project && (
-          <nav aria-label={`${project.shortName} documentation`} className={styles.sidebar}>
-            <ul className={styles.sidebarList}>
-              {siblings.map((doc) => (
-                <li key={doc.id}>
-                  <Link
-                    to={doc.route}
-                    className={styles.sidebarLink}
-                    aria-current={doc.id === entry.id ? 'page' : undefined}
-                  >
-                    {docLabel(doc)}
-                  </Link>
-                </li>
-              ))}
-            </ul>
-          </nav>
-        )}
-
-        {toc.length > 0 && (
-          <nav aria-labelledby="doc-toc-heading" className={styles.toc}>
-            <h2 id="doc-toc-heading" className={styles.tocHeading}>
-              On this page
-            </h2>
-            <ul className={styles.tocList}>
-              {toc.map((item) => (
-                <li key={item.id} className={item.depth === 3 ? styles.tocNested : undefined}>
-                  <a href={`#${item.id}`} className={styles.tocLink}>
-                    {item.text}
-                  </a>
-                </li>
-              ))}
-            </ul>
-          </nav>
-        )}
+      <PageHeader
+        variant="compact"
+        breadcrumbs={<Breadcrumbs items={crumbs} />}
+        eyebrow={plan.eyebrow}
+        stage={plan.stage}
+        hue={plan.hue}
+        title={title}
+        lead={
+          <>
+            Rendered from <span className={styles.sourcePath}>{entry.sourcePath}</span>
+          </>
+        }
+        actions={actions}
+      />
+      <ReadingProgress />
 
-        <article className={styles.article}>
-          <header className={styles.header}>
-            <h1>{title}</h1>
-            <p className={styles.source}>
-              <ExternalLink href={blob(entry.sourcePath)}>View source on GitHub</ExternalLink>
-            </p>
-          </header>
-
-          <div className={styles.body}>
-            <Content components={mdxComponents} />
-          </div>
+      <div className={`container ${styles.page}`}>
+        <div className={siblings.length > 1 ? styles.layout : styles.layoutNoSidebar}>
+          {siblings.length > 1 && project && (
+            <nav aria-label={`${project.shortName} documentation`} className={styles.sidebar}>
+              <ul className={styles.sidebarList}>
+                {siblings.map((doc) => (
+                  <li key={doc.id}>
+                    <Link
+                      to={doc.route}
+                      className={styles.sidebarLink}
+                      aria-current={doc.id === entry.id ? 'page' : undefined}
+                    >
+                      {docLabel(doc)}
+                    </Link>
+                  </li>
+                ))}
+              </ul>
+            </nav>
+          )}
 
-          {(previous || next) && (
-            <nav aria-label="Previous and next documents" className={styles.pager}>
-              {previous ? (
-                <Link to={previous.route} className={styles.pagerLink} rel="prev">
-                  <ArrowLeft size={16} aria-hidden="true" />
-                  <span>
-                    <span className={styles.pagerLabel}>Previous</span>
-                    {docLabel(previous)}
-                  </span>
-                </Link>
-              ) : (
-                <span />
-              )}
-              {next && (
-                <Link to={next.route} className={`${styles.pagerLink} ${styles.pagerNext}`} rel="next">
-                  <span>
-                    <span className={styles.pagerLabel}>Next</span>
-                    {docLabel(next)}
-                  </span>
-                  <ArrowRight size={16} aria-hidden="true" />
-                </Link>
-              )}
+          {toc.length > 0 && (
+            <nav aria-labelledby="doc-toc-heading" className={styles.toc}>
+              <h2 id="doc-toc-heading" className={styles.tocHeading}>
+                On this page
+              </h2>
+              <ul className={styles.tocList}>
+                {toc.map((item) => (
+                  <li key={item.id} className={item.depth === 3 ? styles.tocNested : undefined}>
+                    <a href={`#${item.id}`} className={styles.tocLink}>
+                      {item.text}
+                    </a>
+                  </li>
+                ))}
+              </ul>
             </nav>
           )}
-        </article>
 
+          <article className={styles.article}>
+            <div className={styles.body}>
+              <Content components={mdxComponents} />
+            </div>
+
+            {(previous || next) && (
+              <nav aria-label="Previous and next documents" className={styles.pager}>
+                {previous ? (
+                  <Card interactive padding="sm" className={styles.pagerCard}>
+                    <Link to={previous.route} className={styles.pagerLink} rel="prev" data-stretch>
+                      <ArrowLeft size={16} aria-hidden="true" />
+                      <span>
+                        <span className={styles.pagerLabel}>Previous</span>
+                        {docLabel(previous)}
+                      </span>
+                    </Link>
+                  </Card>
+                ) : (
+                  <span />
+                )}
+                {next && (
+                  <Card interactive padding="sm" className={styles.pagerCard}>
+                    <Link to={next.route} className={`${styles.pagerLink} ${styles.pagerNext}`} rel="next" data-stretch>
+                      <span>
+                        <span className={styles.pagerLabel}>Next</span>
+                        {docLabel(next)}
+                      </span>
+                      <ArrowRight size={16} aria-hidden="true" />
+                    </Link>
+                  </Card>
+                )}
+              </nav>
+            )}
+          </article>
+        </div>
       </div>
-    </div>
+
+      <BackToTop />
+    </>
   );
 }
diff --git a/docs-site/src/components/FactsTable.module.css b/docs-site/src/components/FactsTable.module.css
index efa2565..e6bb257 100644
--- a/docs-site/src/components/FactsTable.module.css
+++ b/docs-site/src/components/FactsTable.module.css
@@ -34,7 +34,7 @@
 }
 
 .table thead th {
-  background: var(--color-cloud);
+  background: var(--color-surface-sunken);
 }
 
 .table tbody th {
diff --git a/docs-site/src/components/Figure.module.css b/docs-site/src/components/Figure.module.css
index 705f890..9e553c3 100644
--- a/docs-site/src/components/Figure.module.css
+++ b/docs-site/src/components/Figure.module.css
@@ -1,9 +1,18 @@
 .figure {
   margin: var(--space-6) 0;
   padding: var(--space-4);
-  background: var(--color-bg-secondary);
+  background: var(--color-surface);
   border: 1px solid var(--color-border);
   border-radius: var(--radius-lg);
+  box-shadow: var(--shadow-card);
+}
+
+/* Only the image sits on the white panel: raster diagrams have white interiors, so the
+   panel keeps them framed in the dark theme while caption and controls stay on the surface. */
+.panel {
+  padding: var(--space-2);
+  background: var(--color-figure-panel);
+  border-radius: var(--radius-md);
 }
 
 .figure img {
@@ -12,7 +21,64 @@
 
 .caption {
   margin-top: var(--space-3);
-  font-size: 0.875rem;
+  font-size: var(--text-sm);
   color: var(--color-text-secondary);
   text-align: center;
 }
+
+/* Links inside the secondary-coloured caption need more than colour. */
+.caption a {
+  text-decoration: underline;
+  text-underline-offset: 0.15em;
+}
+
+.actions {
+  display: flex;
+  justify-content: center;
+  margin-top: var(--space-2);
+}
+
+/* Lightbox: a native modal dialog. No padding on the box itself, so a click that lands on
+   the element (not on the bar or the image) is a backdrop click. The global reset zeroes
+   margins, so the UA's centring margin is restored here. */
+.dialog {
+  margin: auto;
+  width: fit-content;
+  max-width: calc(100vw - var(--space-8));
+  max-height: calc(100vh - var(--space-8));
+  padding: 0;
+  overflow: auto;
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-lg);
+  background: var(--color-surface);
+  color: var(--color-text-primary);
+  box-shadow: var(--shadow-lg);
+}
+
+.dialog::backdrop {
+  background: color-mix(in srgb, var(--color-band) 72%, transparent);
+}
+
+.dialogBar {
+  position: sticky;
+  top: 0;
+  left: 0;
+  z-index: 1;
+  display: flex;
+  justify-content: flex-end;
+  padding: var(--space-2);
+  background: var(--color-surface);
+  border-bottom: 1px solid var(--color-border);
+}
+
+.dialogBody {
+  padding: var(--space-4);
+  background: var(--color-figure-panel);
+}
+
+/* The whole point of the dialog: the image at its natural width, scrolled inside the box. */
+.fullImage {
+  display: block;
+  max-width: none;
+  height: auto;
+}
diff --git a/docs-site/src/components/Figure.test.tsx b/docs-site/src/components/Figure.test.tsx
new file mode 100644
index 0000000..485f2c4
--- /dev/null
+++ b/docs-site/src/components/Figure.test.tsx
@@ -0,0 +1,107 @@
+import { act, fireEvent, render, screen } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { Figure } from './Figure';
+
+/**
+ * jsdom has no `showModal`/`close` on HTMLDialogElement. The polyfill mirrors the
+ * browser contract the component relies on: `open` toggles and `close()` fires a
+ * `close` event on the element.
+ */
+function polyfillDialog() {
+  const proto = HTMLDialogElement.prototype as HTMLDialogElement & { showModal: () => void; close: () => void };
+  const showModal = vi.fn(function (this: HTMLDialogElement) {
+    this.setAttribute('open', '');
+  });
+  const close = vi.fn(function (this: HTMLDialogElement) {
+    this.removeAttribute('open');
+    this.dispatchEvent(new Event('close'));
+  });
+  Object.defineProperty(proto, 'showModal', { value: showModal, configurable: true, writable: true });
+  Object.defineProperty(proto, 'close', { value: close, configurable: true, writable: true });
+  return { showModal, close };
+}
+
+describe('Figure lightbox', () => {
+  let polyfill: ReturnType<typeof polyfillDialog>;
+
+  beforeEach(() => {
+    polyfill = polyfillDialog();
+    document.body.style.overflow = '';
+  });
+
+  afterEach(() => {
+    document.body.style.overflow = '';
+  });
+
+  function renderFigure() {
+    return render(
+      <Figure
+        src="/diagram.png"
+        alt="A diagram"
+        width={800}
+        height={600}
+        caption={<strong>Figure 1.</strong>}
+        download={{ href: 'https://example.com/diagram.drawio', label: 'Open the source' }}
+      />,
+    );
+  }
+
+  it('renders the dialog closed, without a second image, and keeps the download link', () => {
+    renderFigure();
+    const dialog = document.querySelector('dialog');
+    expect(dialog).not.toBeNull();
+    expect(dialog).not.toHaveAttribute('open');
+    expect(screen.getAllByRole('img', { hidden: true })).toHaveLength(1);
+    expect(screen.getByRole('link', { name: /open the source/i })).toHaveAttribute('href', 'https://example.com/diagram.drawio');
+    expect(document.body.style.overflow).toBe('');
+  });
+
+  it('opens as a modal with the same image at natural size, locks scroll, and closes via the Close button', () => {
+    renderFigure();
+    const opener = screen.getByRole('button', { name: /open full size/i });
+    fireEvent.click(opener);
+
+    const dialog = document.querySelector('dialog') as HTMLDialogElement;
+    expect(polyfill.showModal).toHaveBeenCalledTimes(1);
+    expect(dialog).toHaveAttribute('open');
+    expect(document.body.style.overflow).toBe('hidden');
+
+    const images = dialog.querySelectorAll('img');
+    expect(images).toHaveLength(1);
+    expect(images[0]).toHaveAttribute('alt', 'A diagram');
+    expect(images[0]).toHaveAttribute('width', '800');
+
+    fireEvent.click(screen.getByRole('button', { name: /^close$/i }));
+    expect(polyfill.close).toHaveBeenCalledTimes(1);
+    expect(dialog).not.toHaveAttribute('open');
+    expect(document.body.style.overflow).toBe('');
+    expect(opener).toHaveFocus();
+  });
+
+  it('closes on a backdrop click but not on a click inside the content, and returns focus', () => {
+    renderFigure();
+    const opener = screen.getByRole('button', { name: /open full size/i });
+    fireEvent.click(opener);
+    const dialog = document.querySelector('dialog') as HTMLDialogElement;
+
+    fireEvent.click(dialog.querySelector('img') as HTMLImageElement);
+    expect(dialog).toHaveAttribute('open');
+
+    fireEvent.click(dialog);
+    expect(dialog).not.toHaveAttribute('open');
+    expect(opener).toHaveFocus();
+  });
+
+  it('restores focus and scroll when the browser closes the dialog itself (Escape)', () => {
+    renderFigure();
+    const opener = screen.getByRole('button', { name: /open full size/i });
+    fireEvent.click(opener);
+    const dialog = document.querySelector('dialog') as HTMLDialogElement;
+    (dialog.querySelector('button') as HTMLButtonElement).focus();
+
+    // Escape makes the browser run close(): the element loses `open` and fires `close`.
+    act(() => dialog.close());
+    expect(document.body.style.overflow).toBe('');
+    expect(opener).toHaveFocus();
+  });
+});
diff --git a/docs-site/src/components/Figure.tsx b/docs-site/src/components/Figure.tsx
index 0617236..b1872d2 100644
--- a/docs-site/src/components/Figure.tsx
+++ b/docs-site/src/components/Figure.tsx
@@ -1,4 +1,6 @@
-import type { ReactNode } from 'react';
+import { useCallback, useEffect, useId, useRef, useState, type MouseEvent, type ReactNode } from 'react';
+import { Maximize2, X } from 'lucide-react';
+import { Button } from './Button';
 import { DocImage, type ImageFetchPriority, type ImageLoading } from './DocImage';
 import { ExternalLink } from './ExternalLink';
 import styles from './Figure.module.css';
@@ -18,12 +20,65 @@ export interface FigureProps {
   className?: string;
 }
 
-/** Image with a visible caption and an optional source download link. */
+/**
+ * Image with a visible caption, an optional source download link and an "Open full
+ * size" control. The control opens a native `<dialog>` (modal, so focus stays inside
+ * and Escape closes it) that shows the same image at its natural width inside a
+ * scrollable panel. The dialog is closed by default, so prerendered pages never
+ * carry it open; body scroll is locked while it is open and focus returns to the
+ * opener on close.
+ */
 export function Figure({ src, alt, caption, width, height, download, loading, fetchPriority, className }: FigureProps) {
+  const captionId = useId();
+  const dialogRef = useRef<HTMLDialogElement>(null);
+  /* `Button` does not forward refs; the opener is found inside this wrapper when focus returns. */
+  const actionsRef = useRef<HTMLDivElement>(null);
+  const [open, setOpen] = useState(false);
+
+  useEffect(() => {
+    const dialog = dialogRef.current;
+    if (!open || !dialog) return;
+    if (!dialog.open) {
+      if (typeof dialog.showModal === 'function') dialog.showModal();
+      else dialog.setAttribute('open', '');
+    }
+    const previousOverflow = document.body.style.overflow;
+    document.body.style.overflow = 'hidden';
+    return () => {
+      document.body.style.overflow = previousOverflow;
+    };
+  }, [open]);
+
+  const close = useCallback(() => {
+    const dialog = dialogRef.current;
+    if (!dialog) return;
+    if (typeof dialog.close === 'function') dialog.close();
+    else {
+      dialog.removeAttribute('open');
+      dialog.dispatchEvent(new Event('close'));
+    }
+  }, []);
+
+  /** Fired by the browser after Escape, the Close button or a backdrop click. */
+  const handleClose = useCallback(() => {
+    setOpen(false);
+    actionsRef.current?.querySelector('button')?.focus();
+  }, []);
+
+  /** The dialog box has no padding of its own, so a click on the element itself is a backdrop click. */
+  const handleBackdropClick = useCallback(
+    (event: MouseEvent<HTMLDialogElement>) => {
+      if (event.target === event.currentTarget) close();
+    },
+    [close],
+  );
+
   return (
-    <figure className={[styles.figure, className].filter(Boolean).join(' ')}>
-      <DocImage src={src} alt={alt} width={width} height={height} loading={loading} fetchPriority={fetchPriority} />
-      <figcaption className={styles.caption}>
+    <figure className={[styles.figure, className].filter(Boolean).join(' ')} data-figure>
+      <div className={styles.panel}>
+        <DocImage src={src} alt={alt} width={width} height={height} loading={loading} fetchPriority={fetchPriority} />
+      </div>
+      <figcaption id={captionId} className={styles.caption}>
         {caption}
         {download && (
           <>
@@ -32,6 +87,38 @@ export function Figure({ src, alt, caption, width, height, download, loading, fe
           </>
         )}
       </figcaption>
+      <div className={styles.actions} ref={actionsRef}>
+        <Button
+          variant="ghost"
+          size="sm"
+          iconStart={<Maximize2 size={16} />}
+          aria-describedby={captionId}
+          aria-haspopup="dialog"
+          onClick={() => setOpen(true)}
+          data-figure-open
+        >
+          Open full size
+        </Button>
+      </div>
+      <dialog
+        ref={dialogRef}
+        className={styles.dialog}
+        aria-labelledby={captionId}
+        onClose={handleClose}
+        onClick={handleBackdropClick}
+        data-figure-dialog
+      >
+        <div className={styles.dialogBar}>
+          <Button variant="secondary" size="sm" iconStart={<X size={16} />} onClick={close} data-figure-close>
+            Close
+          </Button>
+        </div>
+        {open && (
+          <div className={styles.dialogBody}>
+            <img src={src} alt={alt} width={width} height={height} decoding="async" className={styles.fullImage} />
+          </div>
+        )}
+      </dialog>
     </figure>
   );
 }
diff --git a/docs-site/src/components/FlowStrip.module.css b/docs-site/src/components/FlowStrip.module.css
new file mode 100644
index 0000000..9c0507e
--- /dev/null
+++ b/docs-site/src/components/FlowStrip.module.css
@@ -0,0 +1,69 @@
+.strip {
+  min-width: 0;
+}
+
+.strip[data-stage='learn'] {
+  --stage-color: var(--stage-learn);
+}
+
+.strip[data-stage='build'] {
+  --stage-color: var(--stage-build);
+}
+
+.strip[data-stage='govern'] {
+  --stage-color: var(--stage-govern);
+}
+
+.strip[data-stage='scale'] {
+  --stage-color: var(--stage-scale);
+}
+
+.list {
+  list-style: none;
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(min(15rem, 100%), 1fr));
+  gap: var(--space-3);
+  margin: 0;
+  padding: 0;
+}
+
+.step {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-1);
+}
+
+.index {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 1.5rem;
+  height: 1.5rem;
+  border-radius: var(--radius-pill);
+  background: var(--stage-color, var(--color-text-primary));
+  color: var(--stage-fill-text);
+  font-size: var(--text-xs);
+  font-weight: 700;
+  /* Transparent border so forced-colors mode still draws the circle. */
+  border: 1px solid transparent;
+}
+
+.name {
+  font-weight: 600;
+}
+
+.detail {
+  font-size: var(--text-sm);
+  color: var(--color-text-secondary);
+}
+
+.source {
+  margin-top: auto;
+  padding-top: var(--space-1);
+}
+
+.caption {
+  margin-top: var(--space-3);
+  font-size: var(--text-sm);
+  color: var(--color-text-secondary);
+}
diff --git a/docs-site/src/components/FlowStrip.tsx b/docs-site/src/components/FlowStrip.tsx
new file mode 100644
index 0000000..b6bb3a2
--- /dev/null
+++ b/docs-site/src/components/FlowStrip.tsx
@@ -0,0 +1,52 @@
+import type { ReactNode } from 'react';
+import type { JourneyStage } from '../content/data';
+import type { Source } from '../content/facts';
+import { Card } from './Card';
+import { SmallSource } from './Sources';
+import styles from './FlowStrip.module.css';
+
+export interface FlowStripItem {
+  id: string;
+  /** Step or flow name, shown in bold. */
+  name: string;
+  /** One or two sentences under the name. */
+  detail: string;
+  /** Optional source for this item, rendered as a small "source" link. */
+  source?: Source;
+}
+
+export interface FlowStripProps {
+  items: FlowStripItem[];
+  /** Colours the index circles. */
+  stage: JourneyStage;
+  /** Accessible name of the list, for example "Four governed flows". */
+  label: string;
+  /** Optional caption under the strip (sources, a note). */
+  caption?: ReactNode;
+  className?: string;
+}
+
+/**
+ * A numbered strip of small cards: an HTML rendering of a flow or request path.
+ * Index circles take the stage colour; the number is decorative because the list
+ * itself is ordered.
+ */
+export function FlowStrip({ items, stage, label, caption, className }: FlowStripProps) {
+  return (
+    <div className={[styles.strip, className].filter(Boolean).join(' ')} data-flow-strip data-stage={stage}>
+      <ol className={styles.list} aria-label={label}>
+        {items.map((item, index) => (
+          <Card as="li" key={item.id} padding="sm" className={styles.step}>
+            <span className={styles.index} aria-hidden="true">
+              {index + 1}
+            </span>
+            <span className={styles.name}>{item.name}</span>
+            <span className={styles.detail}>{item.detail}</span>
+            {item.source && <SmallSource source={item.source} context={item.name} className={styles.source} />}
+          </Card>
+        ))}
+      </ol>
+      {caption && <p className={styles.caption}>{caption}</p>}
+    </div>
+  );
+}
diff --git a/docs-site/src/components/HeaderGlow.module.css b/docs-site/src/components/HeaderGlow.module.css
new file mode 100644
index 0000000..78c9009
--- /dev/null
+++ b/docs-site/src/components/HeaderGlow.module.css
@@ -0,0 +1,49 @@
+/* Two radial glows in the section hue plus a dotted grid, all translucent through
+   color-mix so the band colour underneath (and the dark theme) shows through.
+   Browsers without color-mix simply show the plain band. */
+.glow {
+  position: absolute;
+  inset: 0;
+  pointer-events: none;
+  --glow-hue: var(--stage-scale-tint);
+  --glow-a: color-mix(in srgb, var(--glow-hue) 22%, transparent);
+  --glow-b: color-mix(in srgb, var(--glow-hue) 12%, transparent);
+  --glow-dot: color-mix(in srgb, var(--color-cloud) 9%, transparent);
+  background-image:
+    radial-gradient(55% 90% at 100% 0%, var(--glow-a), transparent 65%),
+    radial-gradient(45% 70% at 0% 100%, var(--glow-b), transparent 65%),
+    radial-gradient(circle at 1px 1px, var(--glow-dot) 1px, transparent 1.6px);
+  background-size:
+    100% 100%,
+    100% 100%,
+    40px 40px;
+  background-repeat: no-repeat, no-repeat, repeat;
+  /* Fade the grid out towards the copy so text sits on a calm surface. */
+  mask-image: linear-gradient(to right, color-mix(in srgb, black 55%, transparent), black 60%);
+}
+
+.glow[data-hue='learn'] {
+  --glow-hue: var(--stage-learn-tint);
+}
+
+.glow[data-hue='build'] {
+  --glow-hue: var(--stage-build-tint);
+}
+
+.glow[data-hue='govern'] {
+  --glow-hue: var(--stage-govern-tint);
+}
+
+.glow[data-hue='scale'] {
+  --glow-hue: var(--stage-scale-tint);
+}
+
+.glow[data-hue='slate'] {
+  --glow-hue: var(--color-slate);
+}
+
+@media (forced-colors: active) {
+  .glow {
+    display: none;
+  }
+}
diff --git a/docs-site/src/components/HeaderGlow.tsx b/docs-site/src/components/HeaderGlow.tsx
new file mode 100644
index 0000000..c91850b
--- /dev/null
+++ b/docs-site/src/components/HeaderGlow.tsx
@@ -0,0 +1,13 @@
+import type { JourneyStage } from '../content/data';
+import styles from './HeaderGlow.module.css';
+
+export type HeaderHue = JourneyStage | 'slate';
+
+/**
+ * Static, CSS-only backdrop for page headers: two soft radial glows in a section
+ * hue and the faint 40 px dotted grid used by the Atlas diagram. No JavaScript, no
+ * motion, `pointer-events: none`; it only gives the dark band some depth.
+ */
+export function HeaderGlow({ hue = 'scale' }: { hue?: HeaderHue }) {
+  return <div className={styles.glow} data-hue={hue} aria-hidden="true" />;
+}
diff --git a/docs-site/src/components/Layout.module.css b/docs-site/src/components/Layout.module.css
index 442501b..5b4a75d 100644
--- a/docs-site/src/components/Layout.module.css
+++ b/docs-site/src/components/Layout.module.css
@@ -4,7 +4,7 @@
   position: sticky;
   top: 0;
   z-index: 100;
-  background: var(--color-bg-secondary);
+  background: var(--color-surface);
   border-bottom: 1px solid var(--color-border);
   height: var(--header-height);
 }
@@ -39,7 +39,7 @@
 }
 
 .logoIcon {
-  color: var(--color-blue);
+  color: var(--color-link);
 }
 
 .logoText {
@@ -101,18 +101,18 @@
 
 .navLink:hover {
   color: var(--color-text-primary);
-  background: var(--color-mist);
+  background: var(--color-overlay-hover);
   text-decoration: none;
 }
 
 .navLink.active {
-  color: var(--color-blue-hover);
-  box-shadow: inset 0 -2px 0 var(--color-blue);
+  color: var(--color-link-hover);
+  box-shadow: inset 0 -2px 0 var(--color-link);
   border-radius: var(--radius-md) var(--radius-md) 0 0;
 }
 
 .navLink:focus-visible {
-  outline: 2px solid var(--color-blue);
+  outline: var(--focus-ring);
   outline-offset: 2px;
 }
 
@@ -136,7 +136,7 @@
   min-width: 200px;
   margin-top: var(--space-1);
   padding: var(--space-2);
-  background: var(--color-bg-secondary);
+  background: var(--color-surface);
   border: 1px solid var(--color-border);
   border-radius: var(--radius-lg);
   box-shadow: var(--shadow-lg);
@@ -158,13 +158,13 @@
 
 .dropdownLink:hover {
   color: var(--color-text-primary);
-  background: var(--color-mist);
+  background: var(--color-overlay-hover);
   text-decoration: none;
 }
 
 .dropdownLink.active {
-  color: var(--color-blue-hover);
-  background: rgba(37, 99, 235, 0.1);
+  color: var(--color-link-hover);
+  background: color-mix(in srgb, var(--color-link) 10%, transparent);
   font-weight: 600;
 }
 
@@ -187,7 +187,7 @@
 
 .githubLink:hover {
   color: var(--color-text-primary);
-  background: var(--color-mist);
+  background: var(--color-overlay-hover);
   text-decoration: none;
 }
 
@@ -238,11 +238,11 @@
 }
 
 .mobileMenuButton:hover {
-  background: var(--color-mist);
+  background: var(--color-overlay-hover);
 }
 
 .mobileMenuButton:focus-visible {
-  outline: 2px solid var(--color-blue);
+  outline: var(--focus-ring);
   outline-offset: 2px;
 }
 
@@ -259,7 +259,7 @@
   left: 0;
   right: 0;
   bottom: 0;
-  background: var(--color-bg-secondary);
+  background: var(--color-surface);
   overflow-y: auto;
   z-index: 90;
 }
@@ -281,11 +281,11 @@
 }
 
 .mobileClose:hover {
-  background: var(--color-mist);
+  background: var(--color-overlay-hover);
 }
 
 .mobileClose:focus-visible {
-  outline: 2px solid var(--color-blue);
+  outline: var(--focus-ring);
   outline-offset: 2px;
 }
 
@@ -309,12 +309,12 @@
 }
 
 .mobileNavLink:hover {
-  background: var(--color-mist);
+  background: var(--color-overlay-hover);
   text-decoration: none;
 }
 
 .mobileNavLink[aria-current='page'] {
-  color: var(--color-blue-hover);
+  color: var(--color-link-hover);
   font-weight: 600;
 }
 
@@ -344,34 +344,118 @@
   width: 100%;
 }
 
-/* Footer */
+/* Footer: four link columns from the content model, then the repository links, the
+   disclaimer and the build stamp. Colours are semantic tokens resolved inside `.on-dark`. */
 .footer {
-  background: var(--color-midnight);
-  padding: var(--space-8) 0;
+  background: var(--color-band);
+  border-top: 1px solid var(--color-band-raised);
+  padding: var(--space-10) 0 var(--space-8);
 }
 
 .footerContent {
   max-width: var(--max-width);
   margin: 0 auto;
   padding: 0 var(--page-padding-x);
-  display: flex;
-  flex-direction: column;
+  display: grid;
+  gap: var(--space-8);
+}
+
+.footerNav {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr);
   gap: var(--space-6);
 }
 
-@media (min-width: 768px) {
-  .footerContent {
-    flex-direction: row;
-    flex-wrap: wrap;
-    justify-content: space-between;
-    align-items: flex-start;
+@media (min-width: 640px) {
+  .footerNav {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+}
+
+@media (min-width: 1024px) {
+  .footerNav {
+    grid-template-columns: repeat(4, minmax(0, 1fr));
+  }
+}
+
+.footerColumn {
+  min-width: 0;
+}
+
+.footerHeading {
+  margin: 0 0 var(--space-2);
+  font-size: var(--text-xs);
+  font-weight: 700;
+  letter-spacing: var(--label-tracking);
+  text-transform: uppercase;
+  line-height: 1.25;
+}
+
+.footer .footerHeadingLink {
+  display: inline-flex;
+  align-items: center;
+  min-height: var(--target-min);
+  color: var(--color-text-primary);
+  text-decoration: none;
+}
+
+.footer .footerHeadingLink:hover {
+  color: var(--color-text-primary);
+  text-decoration: underline;
+  text-underline-offset: 0.15em;
+}
+
+.footerColumnLinks {
+  list-style: none;
+  display: grid;
+  gap: var(--space-1);
+}
+
+.footer .footerNavLink {
+  display: inline-flex;
+  align-items: center;
+  min-height: var(--target-min);
+  font-size: var(--text-sm);
+  color: var(--color-text-secondary);
+  text-decoration: none;
+  transition: color var(--transition-fast);
+}
+
+.footer .footerNavLink:hover {
+  color: var(--color-text-primary);
+  text-decoration: underline;
+  text-underline-offset: 0.15em;
+}
+
+.footer .footerHeadingLink:focus-visible,
+.footer .footerNavLink:focus-visible,
+.footer .footerLink:focus-visible {
+  outline: var(--focus-ring);
+  outline-offset: 2px;
+}
+
+.footerMeta {
+  display: grid;
+  gap: var(--space-4);
+  padding-top: var(--space-6);
+  border-top: 1px solid var(--color-band-raised);
+}
+
+@media (min-width: 1024px) {
+  .footerMeta {
+    grid-template-columns: minmax(0, 1fr) auto;
+    align-items: start;
+  }
+
+  .buildStamp {
+    grid-column: 1 / -1;
   }
 }
 
 .footerText {
-  max-width: 600px;
-  font-size: 0.875rem;
-  color: var(--color-mist);
+  max-width: 60ch;
+  font-size: var(--text-sm);
+  color: var(--color-text-secondary);
 }
 
 .footerLinks {
@@ -385,29 +469,23 @@
   display: inline-flex;
   align-items: center;
   min-height: var(--target-min);
-  font-size: 0.875rem;
-  color: var(--color-mist);
+  font-size: var(--text-sm);
+  color: var(--color-text-secondary);
   text-decoration: underline;
   text-underline-offset: 0.15em;
   transition: color var(--transition-fast);
 }
 
 .footer .footerLink:hover {
-  color: var(--color-cloud);
-}
-
-.footer .footerLink:focus-visible {
-  outline: 2px solid var(--color-cloud);
-  outline-offset: 2px;
+  color: var(--color-text-primary);
 }
 
 .buildStamp {
-  flex-basis: 100%;
-  font-size: 0.75rem;
-  color: var(--color-text-inverse-muted);
+  font-size: var(--text-xs);
+  color: var(--color-text-secondary);
 }
 
 .sha {
-  background: var(--color-midnight-light);
-  color: var(--color-mist);
+  background: var(--color-band-raised);
+  color: var(--color-text-primary);
 }
diff --git a/docs-site/src/components/Layout.tsx b/docs-site/src/components/Layout.tsx
index 9d11c3a..be5ef4c 100644
--- a/docs-site/src/components/Layout.tsx
+++ b/docs-site/src/components/Layout.tsx
@@ -2,6 +2,7 @@ import { useCallback, useEffect, useRef, useState, type FocusEvent, type MouseEv
 import { flushSync } from 'react-dom';
 import { Link, Outlet, useLocation } from 'react-router-dom';
 import { ChevronDown, Github, Hexagon, Menu, X } from 'lucide-react';
+import { navigation, type NavItem } from '../content/data';
 import { ISSUES_URL, REPO_URL, VULN_REPORT_URL } from '../content/links';
 import { siteNav } from '../nav';
 import { PATHS } from '../paths';
@@ -10,6 +11,26 @@ import { HomeLink } from './HomeLink';
 import { RouteChange } from './RouteChange';
 import styles from './Layout.module.css';
 
+/**
+ * The Start section has a single entry in the main navigation, so the footer lists
+ * its five pages here (same labels as the Start section chip nav).
+ */
+const START_LINKS: NavItem[] = [
+  { path: PATHS.start, label: 'Get started' },
+  { path: PATHS.whichProject, label: 'Which project fits?' },
+  { path: PATHS.prerequisites, label: 'Prerequisites' },
+  { path: PATHS.costsAndCleanup, label: 'Costs and cleanup' },
+  { path: PATHS.faq, label: 'FAQ' },
+];
+
+/** Footer columns: one per top-level navigation entry, each with at least one link. */
+const FOOTER_COLUMNS = navigation
+  .map((item) => ({
+    ...item,
+    children: item.children && item.children.length > 0 ? item.children : item.path === PATHS.start ? START_LINKS : [],
+  }))
+  .filter((item) => item.children.length > 0);
+
 const MOBILE_MENU_ID = 'mobile-menu';
 const NEW_ISSUE_URL = `${ISSUES_URL}/new`;
 
@@ -303,36 +324,58 @@ export function Layout() {
 
       <footer className={`${styles.footer} on-dark`} {...inertWhenMenuOpen}>
         <div className={styles.footerContent}>
-          <p className={styles.footerText}>
-            This is sample code released under the MIT-0 License, not an AWS service. Review the architecture,
-            security posture, and costs before you use it.
-          </p>
-          <ul className={styles.footerLinks} aria-label="Footer links">
-            <li>
-              <ExternalLink href={REPO_URL} className={styles.footerLink}>
-                Repository
-              </ExternalLink>
-            </li>
-            <li>
-              <Link to={PATHS.contributing} className={styles.footerLink}>
-                Contributing
-              </Link>
-            </li>
-            <li>
-              <ExternalLink href={NEW_ISSUE_URL} className={styles.footerLink}>
-                Report an issue
-              </ExternalLink>
-            </li>
-            <li>
-              <ExternalLink href={VULN_REPORT_URL} className={styles.footerLink}>
-                Security reporting
-              </ExternalLink>
-            </li>
-          </ul>
-          <p className={styles.buildStamp}>
-            Built from <code className={styles.sha}>{__BUILD_SHA__}</code> on{' '}
-            <time dateTime={__BUILD_DATE__}>{__BUILD_DATE__}</time>
-          </p>
+          <nav className={styles.footerNav} aria-label="Footer navigation">
+            {FOOTER_COLUMNS.map((item) => (
+              <div key={item.path} className={styles.footerColumn}>
+                <h2 className={styles.footerHeading}>
+                  <Link to={item.path} className={styles.footerHeadingLink}>
+                    {item.label}
+                  </Link>
+                </h2>
+                <ul className={styles.footerColumnLinks}>
+                  {item.children.map((child) => (
+                    <li key={child.path}>
+                      <Link to={child.path} className={styles.footerNavLink}>
+                        {child.label}
+                      </Link>
+                    </li>
+                  ))}
+                </ul>
+              </div>
+            ))}
+          </nav>
+          <div className={styles.footerMeta}>
+            <p className={styles.footerText}>
+              This is sample code released under the MIT-0 License, not an AWS service. Review the architecture,
+              security posture, and costs before you use it.
+            </p>
+            <ul className={styles.footerLinks} aria-label="Footer links">
+              <li>
+                <ExternalLink href={REPO_URL} className={styles.footerLink}>
+                  Repository
+                </ExternalLink>
+              </li>
+              <li>
+                <Link to={PATHS.contributing} className={styles.footerLink}>
+                  Contributing
+                </Link>
+              </li>
+              <li>
+                <ExternalLink href={NEW_ISSUE_URL} className={styles.footerLink}>
+                  Report an issue
+                </ExternalLink>
+              </li>
+              <li>
+                <ExternalLink href={VULN_REPORT_URL} className={styles.footerLink}>
+                  Security reporting
+                </ExternalLink>
+              </li>
+            </ul>
+            <p className={styles.buildStamp}>
+              Built from <code className={styles.sha}>{__BUILD_SHA__}</code> on{' '}
+              <time dateTime={__BUILD_DATE__}>{__BUILD_DATE__}</time>
+            </p>
+          </div>
         </div>
       </footer>
     </>
diff --git a/docs-site/src/components/NumberedSteps.module.css b/docs-site/src/components/NumberedSteps.module.css
new file mode 100644
index 0000000..8f0b894
--- /dev/null
+++ b/docs-site/src/components/NumberedSteps.module.css
@@ -0,0 +1,84 @@
+.steps {
+  --step-size: 1.75rem;
+  --step-gap: var(--space-6);
+  list-style: none;
+  counter-reset: step;
+  display: grid;
+  gap: var(--step-gap);
+  margin: var(--space-4) 0;
+  padding: 0;
+}
+
+.steps[data-dense] {
+  --step-gap: var(--space-3);
+}
+
+.steps[data-stage='learn'] {
+  --stage-color: var(--stage-learn);
+}
+
+.steps[data-stage='build'] {
+  --stage-color: var(--stage-build);
+}
+
+.steps[data-stage='govern'] {
+  --stage-color: var(--stage-govern);
+}
+
+.steps[data-stage='scale'] {
+  --stage-color: var(--stage-scale);
+}
+
+.item {
+  position: relative;
+  padding-left: calc(var(--step-size) + var(--space-3));
+  counter-increment: step;
+  min-width: 0;
+}
+
+.item::before {
+  content: counter(step);
+  position: absolute;
+  left: 0;
+  top: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: var(--step-size);
+  height: var(--step-size);
+  border-radius: var(--radius-pill);
+  background: var(--stage-color, var(--color-text-primary));
+  color: var(--stage-fill-text);
+  font-size: var(--text-sm);
+  font-weight: 700;
+  line-height: 1;
+  /* Transparent border so forced-colors mode still draws the circle. */
+  border: 1px solid transparent;
+}
+
+/* Connector line between counters. */
+.steps[data-connector] .item:not(:last-child)::after {
+  content: '';
+  position: absolute;
+  left: calc(var(--step-size) / 2 - 1px);
+  top: calc(var(--step-size) + var(--space-1));
+  bottom: calc(-1 * var(--step-gap) + var(--space-1));
+  width: 2px;
+  background: var(--color-border);
+}
+
+.title {
+  min-height: var(--step-size);
+  display: flex;
+  align-items: center;
+  font-weight: 600;
+  line-height: 1.35;
+}
+
+.body {
+  margin-top: var(--space-2);
+}
+
+.body > * + * {
+  margin-top: var(--space-2);
+}
diff --git a/docs-site/src/components/NumberedSteps.test.tsx b/docs-site/src/components/NumberedSteps.test.tsx
new file mode 100644
index 0000000..9ce0119
--- /dev/null
+++ b/docs-site/src/components/NumberedSteps.test.tsx
@@ -0,0 +1,34 @@
+import { render, screen } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+import { NumberedSteps } from './NumberedSteps';
+
+describe('NumberedSteps', () => {
+  it('renders an ordered list whose items keep native semantics', () => {
+    render(
+      <NumberedSteps stage="build" connector aria-label="Deploy steps">
+        <NumberedSteps.Item title="Clone the repository">
+          <p>Folder names are exact.</p>
+        </NumberedSteps.Item>
+        <NumberedSteps.Item title="Deploy" />
+      </NumberedSteps>,
+    );
+    const list = screen.getByRole('list', { name: 'Deploy steps' });
+    expect(list.tagName).toBe('OL');
+    expect(list).toHaveAttribute('data-stage', 'build');
+    expect(list).toHaveAttribute('data-connector', '');
+    expect(screen.getAllByRole('listitem')).toHaveLength(2);
+    expect(screen.getByText('Clone the repository')).toBeInTheDocument();
+    expect(screen.getByText('Folder names are exact.')).toBeInTheDocument();
+  });
+
+  it('continues numbering from start via a CSS counter reset', () => {
+    render(
+      <NumberedSteps start={4} dense>
+        <NumberedSteps.Item title="Fourth" />
+      </NumberedSteps>,
+    );
+    const list = screen.getByRole('list');
+    expect(list).toHaveStyle({ counterReset: 'step 3' });
+    expect(list).toHaveAttribute('data-dense', '');
+  });
+});
diff --git a/docs-site/src/components/NumberedSteps.tsx b/docs-site/src/components/NumberedSteps.tsx
new file mode 100644
index 0000000..a6a95b6
--- /dev/null
+++ b/docs-site/src/components/NumberedSteps.tsx
@@ -0,0 +1,65 @@
+import type { CSSProperties, HTMLAttributes, ReactNode } from 'react';
+import type { JourneyStage } from '../content/data';
+import styles from './NumberedSteps.module.css';
+
+export interface NumberedStepsProps extends Omit<HTMLAttributes<HTMLOListElement>, 'className' | 'children'> {
+  /** Colours the counter circles; defaults to the text colour. */
+  stage?: JourneyStage;
+  /** First number (for a list that continues another). */
+  start?: number;
+  /** Draw a vertical line between the counters. */
+  connector?: boolean;
+  /** Tighter spacing for short lists (module lists, policy lists). */
+  dense?: boolean;
+  className?: string;
+  children: ReactNode;
+}
+
+/**
+ * Ordered list with stage-coloured counter circles. The number is drawn with a CSS
+ * counter on `::before`, so screen readers announce the list position once, from
+ * the `<ol>` itself. Use `NumberedSteps.Item` for each step.
+ */
+export function NumberedSteps({
+  stage,
+  start,
+  connector = false,
+  dense = false,
+  className,
+  children,
+  ...rest
+}: NumberedStepsProps) {
+  const style = start && start > 1 ? ({ counterReset: `step ${start - 1}` } as CSSProperties) : undefined;
+  return (
+    <ol
+      {...rest}
+      className={[styles.steps, className].filter(Boolean).join(' ')}
+      style={style}
+      data-numbered-steps
+      data-stage={stage}
+      data-connector={connector ? '' : undefined}
+      data-dense={dense ? '' : undefined}
+    >
+      {children}
+    </ol>
+  );
+}
+
+export interface NumberedStepItemProps extends Omit<HTMLAttributes<HTMLLIElement>, 'className' | 'children' | 'title'> {
+  /** Step title, rendered in bold beside the counter. */
+  title: ReactNode;
+  /** Body: notes, code blocks, links. */
+  children?: ReactNode;
+  className?: string;
+}
+
+function Item({ title, children, className, ...rest }: NumberedStepItemProps) {
+  return (
+    <li {...rest} className={[styles.item, className].filter(Boolean).join(' ')}>
+      <div className={styles.title}>{title}</div>
+      {children && <div className={styles.body}>{children}</div>}
+    </li>
+  );
+}
+
+NumberedSteps.Item = Item;
diff --git a/docs-site/src/components/PageHeader.module.css b/docs-site/src/components/PageHeader.module.css
index 582f27f..6a18dc6 100644
--- a/docs-site/src/components/PageHeader.module.css
+++ b/docs-site/src/components/PageHeader.module.css
@@ -1,11 +1,57 @@
 .header {
   position: relative;
   overflow: hidden;
-  background: var(--color-midnight);
+  background: var(--color-band);
   color: var(--color-text-inverse);
   padding: var(--section-padding-y) 0;
 }
 
+/* Compact band for document pages: tighter padding, smaller title. */
+.header[data-variant='compact'] {
+  padding: var(--space-8) 0;
+}
+
+.header[data-variant='compact'] .title {
+  font-size: var(--font-size-h2);
+}
+
+.header[data-variant='compact'] .lead {
+  margin-top: var(--space-2);
+  font-size: var(--text-base);
+}
+
+.header[data-variant='compact'] .actions {
+  margin-top: var(--space-4);
+}
+
+/* Centred copy (Home). */
+.header[data-align='center'] .copy {
+  text-align: center;
+  margin-inline: auto;
+  max-width: 60rem;
+}
+
+.header[data-align='center'] .title {
+  max-width: none;
+}
+
+.header[data-align='center'] .lead {
+  margin-inline: auto;
+}
+
+.header[data-align='center'] .actions,
+.header[data-align='center'] .meta {
+  justify-content: center;
+}
+
+.header[data-align='center'] .meta {
+  display: flex;
+}
+
+.breadcrumbs {
+  margin-bottom: var(--space-3);
+}
+
 /* Decorative layer behind the copy; empty (and invisible) unless a page passes `backdrop`. */
 .backdrop {
   position: absolute;
@@ -28,9 +74,9 @@
 
 .eyebrow {
   margin: 0 0 var(--space-2);
-  font-size: 0.875rem;
+  font-size: var(--text-sm);
   font-weight: 600;
-  letter-spacing: 0.08em;
+  letter-spacing: var(--label-tracking);
   text-transform: uppercase;
   color: var(--color-text-inverse-muted);
 }
@@ -48,7 +94,7 @@
 .lead {
   margin: var(--space-4) 0 0;
   max-width: 65ch;
-  font-size: 1.125rem;
+  font-size: var(--text-lg);
   line-height: 1.6;
   color: var(--color-text-inverse-muted);
 }
@@ -79,17 +125,18 @@
   }
 }
 
-/* Entrance: fade in and rise 12px, once, title first then the rest 60ms apart. Only inside the
-   no-preference query so reduced-motion visitors (and no-JavaScript renders) see the final state
-   straight away; opacity and transform never affect layout. */
+/* Entrance: rise 12px, once, title first then the rest 60ms apart. A rise without a fade:
+   content painted at opacity 0 is never reported as a Largest Contentful Paint candidate
+   (the compositor-driven fade triggers no new paint record), which made Lighthouse report
+   no LCP at all on pages whose hero fills the viewport. Only inside the no-preference query
+   so reduced-motion visitors (and no-JavaScript renders) see the final state straight away;
+   a transform never affects layout or contrast. */
 @keyframes header-rise {
   from {
-    opacity: 0;
     transform: translateY(12px);
   }
 
   to {
-    opacity: 1;
     transform: none;
   }
 }
diff --git a/docs-site/src/components/PageHeader.test.tsx b/docs-site/src/components/PageHeader.test.tsx
index 173288f..565dcf3 100644
--- a/docs-site/src/components/PageHeader.test.tsx
+++ b/docs-site/src/components/PageHeader.test.tsx
@@ -46,4 +46,22 @@ describe('PageHeader', () => {
     expect(container.querySelector('p')).toBeNull();
     expect(container.querySelector('[data-stage]')).toBeNull();
   });
+
+  it('renders a static glow backdrop by default and exposes align and variant', () => {
+    const { container } = render(<PageHeader title="Docs" stage="govern" align="center" variant="compact" />);
+    const header = container.querySelector('[data-page-header]');
+    expect(header).toHaveAttribute('data-align', 'center');
+    expect(header).toHaveAttribute('data-variant', 'compact');
+    expect(container.querySelector('[data-hue="govern"]')).toHaveAttribute('aria-hidden', 'true');
+  });
+
+  it('replaces the default glow when a backdrop is passed and renders breadcrumbs first', () => {
+    const { container } = render(
+      <PageHeader title="Home" backdrop={<canvas data-testid="canvas" />} breadcrumbs={<nav aria-label="Breadcrumb">Home</nav>} />,
+    );
+    expect(container.querySelector('[data-hue]')).toBeNull();
+    expect(screen.getByTestId('canvas')).toBeInTheDocument();
+    const copy = screen.getByRole('heading', { level: 1 }).parentElement!;
+    expect(copy.firstElementChild).toContainElement(screen.getByRole('navigation', { name: 'Breadcrumb' }));
+  });
 });
diff --git a/docs-site/src/components/PageHeader.tsx b/docs-site/src/components/PageHeader.tsx
index bd7b543..b4b3c5b 100644
--- a/docs-site/src/components/PageHeader.tsx
+++ b/docs-site/src/components/PageHeader.tsx
@@ -1,6 +1,7 @@
 import type { ReactNode } from 'react';
 import type { JourneyStage } from '../content/data';
 import { STAGE_LABELS } from '../stage';
+import { HeaderGlow, type HeaderHue } from './HeaderGlow';
 import { StageBadge } from './StageBadge';
 import styles from './PageHeader.module.css';
 
@@ -28,6 +29,14 @@ export interface PageHeaderProps {
    *  off. Only interactive descendants that opt back into pointer events (the pause control) are
    *  reachable. */
   backdrop?: ReactNode;
+  /** Hue of the default gradient backdrop when no `backdrop` is passed. Defaults to the stage, else blue. */
+  hue?: HeaderHue;
+  /** start: copy left-aligned (every hub page); center: copy centred (Home). */
+  align?: 'start' | 'center';
+  /** default: full band; compact: tighter band with a smaller title (doc pages). */
+  variant?: 'default' | 'compact';
+  /** Breadcrumb trail rendered above the eyebrow, on the band. */
+  breadcrumbs?: ReactNode;
   className?: string;
 }
 
@@ -36,7 +45,7 @@ export interface PageHeaderProps {
  * optional meta row (fact chips), optional actions row and optional figure slot. It is the only dark band a page
  * needs; sections below it sit on the light surface. Pages still render <PageMeta>.
  *
- * On load the eyebrow, badge, title, lead, meta, actions and figure fade in and rise 12px with a
+ * On load the eyebrow, badge, title, lead, meta, actions and figure rise 12px with a
  * short stagger (title first). The animation is CSS-only, applies inside
  * `@media (prefers-reduced-motion: no-preference)` and runs once, so reduced-motion visitors and
  * no-JavaScript renders see the final state immediately and nothing shifts layout.
@@ -51,14 +60,25 @@ export function PageHeader({
   actions,
   figure,
   backdrop,
+  hue,
+  align = 'start',
+  variant = 'default',
+  breadcrumbs,
   className,
 }: PageHeaderProps) {
   const innerClass = [styles.inner, figure ? styles.hasFigure : undefined].filter(Boolean).join(' ');
+  const glowHue: HeaderHue = hue ?? stage ?? 'scale';
   return (
-    <header className={[styles.header, 'on-dark', className].filter(Boolean).join(' ')}>
-      {backdrop !== undefined && <div className={styles.backdrop}>{backdrop}</div>}
+    <header
+      className={[styles.header, 'on-dark', className].filter(Boolean).join(' ')}
+      data-page-header
+      data-align={align}
+      data-variant={variant}
+    >
+      <div className={styles.backdrop}>{backdrop !== undefined ? backdrop : <HeaderGlow hue={glowHue} />}</div>
       <div className={`container ${innerClass}`}>
-        <div className={styles.copy}>
+        <div className={styles.copy} data-copy>
+          {breadcrumbs && <div className={styles.breadcrumbs}>{breadcrumbs}</div>}
           {eyebrow && <p className={styles.eyebrow}>{eyebrow}</p>}
           {stage && (
             <StageBadge stage={stage} label={stageLabel ?? STAGE_LABELS[stage]} className={styles.badge} />
diff --git a/docs-site/src/components/ReadingProgress.module.css b/docs-site/src/components/ReadingProgress.module.css
new file mode 100644
index 0000000..6e87d6d
--- /dev/null
+++ b/docs-site/src/components/ReadingProgress.module.css
@@ -0,0 +1,38 @@
+/* Fixed under the sticky site header, above it in stacking order so the bar is never
+   hidden behind the header's bottom border. Transform-only, so it never takes layout
+   space (CLS 0) and never overlaps text. */
+.progress {
+  position: fixed;
+  top: var(--header-height);
+  left: 0;
+  width: 100%;
+  height: 3px;
+  background: var(--color-link);
+  transform-origin: 0 50%;
+  scale: 0 1;
+  z-index: 101;
+  pointer-events: none;
+  display: none;
+}
+
+/* Progressive enhancement: shown only where scroll-driven animations exist and motion is
+   welcome. Without either, the bar stays display: none. */
+@supports (animation-timeline: scroll()) {
+  @media (prefers-reduced-motion: no-preference) {
+    .progress {
+      display: block;
+      animation: doc-progress linear both;
+      animation-timeline: scroll(root block);
+    }
+  }
+}
+
+@keyframes doc-progress {
+  from {
+    scale: 0 1;
+  }
+
+  to {
+    scale: 1 1;
+  }
+}
diff --git a/docs-site/src/components/ReadingProgress.test.tsx b/docs-site/src/components/ReadingProgress.test.tsx
new file mode 100644
index 0000000..fd716b2
--- /dev/null
+++ b/docs-site/src/components/ReadingProgress.test.tsx
@@ -0,0 +1,13 @@
+import { render } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+import { ReadingProgress } from './ReadingProgress';
+
+describe('ReadingProgress', () => {
+  it('renders a decorative bar hidden from assistive technology', () => {
+    const { container } = render(<ReadingProgress />);
+    const bar = container.querySelector('[data-reading-progress]');
+    expect(bar).not.toBeNull();
+    expect(bar).toHaveAttribute('aria-hidden', 'true');
+    expect(bar?.textContent).toBe('');
+  });
+});
diff --git a/docs-site/src/components/ReadingProgress.tsx b/docs-site/src/components/ReadingProgress.tsx
new file mode 100644
index 0000000..6568369
--- /dev/null
+++ b/docs-site/src/components/ReadingProgress.tsx
@@ -0,0 +1,12 @@
+import styles from './ReadingProgress.module.css';
+
+/**
+ * Reading progress bar for long documents: a 3 px rule fixed under the site header that
+ * fills from left to right as the page scrolls. CSS scroll-driven animation only, no
+ * JavaScript and no layout impact (fixed, transform-only), hidden unless the browser
+ * supports `animation-timeline: scroll()` and the reader has not asked for reduced motion.
+ * Decorative, so it is hidden from assistive technology.
+ */
+export function ReadingProgress() {
+  return <div className={styles.progress} aria-hidden="true" data-reading-progress />;
+}
diff --git a/docs-site/src/components/ResponsiveTable.module.css b/docs-site/src/components/ResponsiveTable.module.css
index 08bc72a..7f9652c 100644
--- a/docs-site/src/components/ResponsiveTable.module.css
+++ b/docs-site/src/components/ResponsiveTable.module.css
@@ -27,7 +27,7 @@
 }
 
 .table th {
-  background: var(--color-cloud);
+  background: var(--color-surface-sunken);
   font-weight: 600;
 }
 
diff --git a/docs-site/src/components/Section.module.css b/docs-site/src/components/Section.module.css
new file mode 100644
index 0000000..11be82b
--- /dev/null
+++ b/docs-site/src/components/Section.module.css
@@ -0,0 +1,24 @@
+.section {
+  padding: var(--space-10) 0;
+  border-top: 1px solid var(--color-border);
+  /* In-page links land below the sticky header. */
+  scroll-margin-top: calc(var(--header-height) + var(--space-4));
+}
+
+.section[data-flush],
+.section:first-child {
+  border-top: 0;
+  padding-top: var(--space-4);
+}
+
+.section h3 {
+  margin: var(--space-6) 0 var(--space-3);
+}
+
+.section p + p,
+.section p + ul,
+.section p + ol,
+.section ul + p,
+.section ol + p {
+  margin-top: var(--space-3);
+}
diff --git a/docs-site/src/components/Section.tsx b/docs-site/src/components/Section.tsx
new file mode 100644
index 0000000..93b4964
--- /dev/null
+++ b/docs-site/src/components/Section.tsx
@@ -0,0 +1,38 @@
+import type { ReactNode } from 'react';
+import { SectionHeading, type SectionHeadingProps } from './SectionHeading';
+import styles from './Section.module.css';
+
+export interface SectionProps {
+  /** Fragment id; the heading gets `${id}-heading` and labels the region. */
+  id: string;
+  title: ReactNode;
+  eyebrow?: SectionHeadingProps['eyebrow'];
+  lead?: SectionHeadingProps['lead'];
+  badge?: SectionHeadingProps['badge'];
+  actions?: SectionHeadingProps['actions'];
+  align?: SectionHeadingProps['align'];
+  /** Remove the top rule (first section under a header or a chip nav). */
+  flush?: boolean;
+  className?: string;
+  children: ReactNode;
+}
+
+/**
+ * A page section with one heading rhythm: top rule, consistent padding, an h2
+ * from `SectionHeading`, and `scroll-margin-top` so in-page links land below the
+ * sticky site header.
+ */
+export function Section({ id, title, eyebrow, lead, badge, actions, align, flush = false, className, children }: SectionProps) {
+  const headingId = `${id}-heading`;
+  return (
+    <section
+      id={id}
+      className={[styles.section, className].filter(Boolean).join(' ')}
+      aria-labelledby={headingId}
+      data-flush={flush ? '' : undefined}
+    >
+      <SectionHeading id={headingId} title={title} eyebrow={eyebrow} lead={lead} badge={badge} actions={actions} align={align} />
+      {children}
+    </section>
+  );
+}
diff --git a/docs-site/src/components/SectionHeading.module.css b/docs-site/src/components/SectionHeading.module.css
new file mode 100644
index 0000000..8cd7092
--- /dev/null
+++ b/docs-site/src/components/SectionHeading.module.css
@@ -0,0 +1,59 @@
+.heading {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: flex-end;
+  justify-content: space-between;
+  gap: var(--space-3) var(--space-6);
+  margin-bottom: var(--space-6);
+}
+
+.text {
+  max-width: 72ch;
+  min-width: 0;
+}
+
+.heading[data-align='center'] {
+  justify-content: center;
+  text-align: center;
+}
+
+.heading[data-align='center'] .text {
+  margin-inline: auto;
+}
+
+.eyebrow {
+  margin-bottom: var(--space-2);
+  font-size: var(--text-xs);
+  font-weight: 700;
+  letter-spacing: var(--label-tracking);
+  text-transform: uppercase;
+  color: var(--color-text-secondary);
+}
+
+.title {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--space-2) var(--space-3);
+}
+
+.heading[data-align='center'] .title {
+  justify-content: center;
+}
+
+.badge {
+  display: inline-flex;
+}
+
+.lead {
+  margin-top: var(--space-3);
+  font-size: var(--text-lg);
+  line-height: 1.5;
+  color: var(--color-text-secondary);
+}
+
+.actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--space-2);
+}
diff --git a/docs-site/src/components/SectionHeading.test.tsx b/docs-site/src/components/SectionHeading.test.tsx
new file mode 100644
index 0000000..454a1fc
--- /dev/null
+++ b/docs-site/src/components/SectionHeading.test.tsx
@@ -0,0 +1,34 @@
+import { render, screen } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+import { Section } from './Section';
+import { SectionHeading } from './SectionHeading';
+
+describe('SectionHeading', () => {
+  it('renders eyebrow, heading level, lead and alignment', () => {
+    render(<SectionHeading id="pick" eyebrow="Projects" title="Pick a project" lead="Four samples." align="center" />);
+    const heading = screen.getByRole('heading', { level: 2, name: 'Pick a project' });
+    expect(heading).toHaveAttribute('id', 'pick');
+    expect(screen.getByText('Projects')).toBeInTheDocument();
+    expect(screen.getByText('Four samples.')).toBeInTheDocument();
+    expect(heading.closest('[data-section-heading]')).toHaveAttribute('data-align', 'center');
+  });
+
+  it('renders an h3 with a badge inside the heading', () => {
+    render(<SectionHeading level={3} title="Workshop" badge={<span>1. Learn</span>} />);
+    expect(screen.getByRole('heading', { level: 3 })).toHaveTextContent('1. LearnWorkshop');
+  });
+});
+
+describe('Section', () => {
+  it('labels the region with its heading', () => {
+    render(
+      <Section id="quickstart" title="Quickstart" flush>
+        <p>Steps</p>
+      </Section>,
+    );
+    const region = screen.getByRole('region', { name: 'Quickstart' });
+    expect(region).toHaveAttribute('id', 'quickstart');
+    expect(region).toHaveAttribute('data-flush', '');
+    expect(screen.getByRole('heading', { level: 2 })).toHaveAttribute('id', 'quickstart-heading');
+  });
+});
diff --git a/docs-site/src/components/SectionHeading.tsx b/docs-site/src/components/SectionHeading.tsx
new file mode 100644
index 0000000..56aafb6
--- /dev/null
+++ b/docs-site/src/components/SectionHeading.tsx
@@ -0,0 +1,50 @@
+import type { ReactNode } from 'react';
+import styles from './SectionHeading.module.css';
+
+export interface SectionHeadingProps {
+  /** Id for the heading element, used by `aria-labelledby` on the enclosing section. */
+  id?: string;
+  /** Small uppercase label above the title. */
+  eyebrow?: ReactNode;
+  title: ReactNode;
+  level?: 2 | 3;
+  /** One or two sentences under the title, in secondary text. */
+  lead?: ReactNode;
+  align?: 'start' | 'center';
+  /** Badge rendered before the title text, inside the heading (for project headings). */
+  badge?: ReactNode;
+  /** Links or buttons aligned to the end of the heading row. */
+  actions?: ReactNode;
+  className?: string;
+}
+
+/**
+ * One heading rhythm for every section: optional eyebrow, the heading, an optional
+ * lead and optional actions. Home centres its headings; everything else starts left.
+ */
+export function SectionHeading({
+  id,
+  eyebrow,
+  title,
+  level = 2,
+  lead,
+  align = 'start',
+  badge,
+  actions,
+  className,
+}: SectionHeadingProps) {
+  const Heading = level === 3 ? 'h3' : 'h2';
+  return (
+    <div className={[styles.heading, className].filter(Boolean).join(' ')} data-align={align} data-section-heading>
+      <div className={styles.text}>
+        {eyebrow && <p className={styles.eyebrow}>{eyebrow}</p>}
+        <Heading id={id} className={styles.title}>
+          {badge && <span className={styles.badge}>{badge}</span>}
+          <span>{title}</span>
+        </Heading>
+        {lead && <p className={styles.lead}>{lead}</p>}
+      </div>
+      {actions && <div className={styles.actions}>{actions}</div>}
+    </div>
+  );
+}
diff --git a/docs-site/src/components/SectionNav.module.css b/docs-site/src/components/SectionNav.module.css
deleted file mode 100644
index b44e9ce..0000000
--- a/docs-site/src/components/SectionNav.module.css
+++ /dev/null
@@ -1,66 +0,0 @@
-/* Mirrors the Start section rail (.jump / .chips / .chip in src/pages/start/start.module.css). */
-.nav {
-  display: flex;
-  flex-wrap: wrap;
-  align-items: center;
-  gap: var(--space-2);
-  margin: var(--space-4) 0;
-  min-width: 0;
-}
-
-.label {
-  font-size: 0.875rem;
-  font-weight: 600;
-  color: var(--color-text-secondary);
-  margin-right: var(--space-1);
-}
-
-/* Below 640px the chips form one row that scrolls inside the list. */
-.chips {
-  list-style: none;
-  display: flex;
-  flex-wrap: nowrap;
-  gap: var(--space-2);
-  position: relative;
-  min-width: 0;
-  max-width: 100%;
-  overflow-x: auto;
-  padding-bottom: var(--space-1);
-  scrollbar-width: thin;
-}
-
-@media (min-width: 640px) {
-  .chips {
-    flex-wrap: wrap;
-    overflow: visible;
-    padding-bottom: 0;
-  }
-}
-
-.chip {
-  display: inline-flex;
-  align-items: center;
-  gap: var(--space-1);
-  min-height: 32px;
-  padding: var(--space-1) var(--space-3);
-  border: 1px solid var(--color-border);
-  border-radius: 999px;
-  background: var(--color-bg-secondary);
-  color: var(--color-text-primary);
-  font-size: 0.875rem;
-  font-weight: 500;
-  text-decoration: none;
-  white-space: nowrap;
-}
-
-.chip:hover {
-  color: var(--color-blue-hover);
-  border-color: var(--color-blue);
-  text-decoration: underline;
-}
-
-.chip[aria-current='page'] {
-  color: var(--color-blue-hover);
-  border-color: var(--color-blue);
-  font-weight: 600;
-}
diff --git a/docs-site/src/components/SectionNav.tsx b/docs-site/src/components/SectionNav.tsx
index 3475782..22ff21d 100644
--- a/docs-site/src/components/SectionNav.tsx
+++ b/docs-site/src/components/SectionNav.tsx
@@ -1,5 +1,4 @@
-import { Link, useLocation } from 'react-router-dom';
-import styles from './SectionNav.module.css';
+import { ChipNav } from './ChipNav';
 
 export interface SectionNavItem {
   label: string;
@@ -14,28 +13,10 @@ export interface SectionNavProps {
   className?: string;
 }
 
-const normalise = (path: string) => path.replace(/\/+$/, '') || '/';
-
 /**
- * "In this section" chip rail linking the pages of one hub section. The current
- * page is marked with aria-current. Below 640px the chips scroll horizontally
- * inside the list; from 640px they wrap. Styled like the Start section's rail.
+ * "In this section" chip rail linking the pages of one hub section. A thin wrapper
+ * over `ChipNav`, which marks the current page with aria-current.
  */
 export function SectionNav({ label = 'In this section', items, className }: SectionNavProps) {
-  const { pathname } = useLocation();
-  const current = normalise(pathname);
-  return (
-    <nav aria-label={label} className={[styles.nav, className].filter(Boolean).join(' ')}>
-      <span className={styles.label}>In this section:</span>
-      <ul className={styles.chips}>
-        {items.map(({ to, label: itemLabel }) => (
-          <li key={to}>
-            <Link to={to} className={styles.chip} aria-current={normalise(to) === current ? 'page' : undefined}>
-              {itemLabel}
-            </Link>
-          </li>
-        ))}
-      </ul>
-    </nav>
-  );
+  return <ChipNav label={label} lead="In this section:" items={items} className={className} />;
 }
diff --git a/docs-site/src/components/Sources.module.css b/docs-site/src/components/Sources.module.css
new file mode 100644
index 0000000..f7762d7
--- /dev/null
+++ b/docs-site/src/components/Sources.module.css
@@ -0,0 +1,10 @@
+.sources {
+  margin-top: var(--space-2);
+  font-size: var(--text-sm);
+  color: var(--color-text-secondary);
+}
+
+.small {
+  font-size: 0.8125rem;
+  white-space: nowrap;
+}
diff --git a/docs-site/src/components/Sources.tsx b/docs-site/src/components/Sources.tsx
new file mode 100644
index 0000000..bb36937
--- /dev/null
+++ b/docs-site/src/components/Sources.tsx
@@ -0,0 +1,58 @@
+import { Fragment } from 'react';
+import { githubUrl, type Source } from '../content/facts';
+import { SourceLink } from './SourceLink';
+import styles from './Sources.module.css';
+
+export interface SourcesProps {
+  sources: Source[];
+  label?: string;
+  /** Render as a span inside running text instead of a paragraph. */
+  inline?: boolean;
+  className?: string;
+}
+
+/**
+ * "Source: file: heading, file" line under a table, list or paragraph. Several
+ * quotes from the same file and heading collapse into one link. The one
+ * treatment for source lines across the site.
+ */
+export function Sources({ sources, label = 'Source', inline = false, className }: SourcesProps) {
+  const unique = [...new Map(sources.map((source) => [githubUrl(source), source])).values()];
+  const fileNames = unique.map((source) => source.file?.split('/').pop());
+  const Tag = inline ? 'span' : 'p';
+  return (
+    <Tag className={[styles.sources, className].filter(Boolean).join(' ')} data-sources>
+      {label}:{' '}
+      {unique.map((source, index) => {
+        // Two files with the same name (module-3b/index.en.md, step-7/index.en.md) get their folder.
+        const repeated =
+          fileNames[index] !== undefined && fileNames.filter((name) => name === fileNames[index]).length > 1;
+        return (
+          <Fragment key={githubUrl(source)}>
+            {index > 0 && ', '}
+            <SourceLink source={source}>{repeated ? sourceLabel(source) : undefined}</SourceLink>
+          </Fragment>
+        );
+      })}
+    </Tag>
+  );
+}
+
+/** Small "source" link with hidden context, for a step or a single value. */
+export function SmallSource({ source, context, className }: { source: Source; context: string; className?: string }) {
+  return (
+    <SourceLink source={source} className={[styles.small, className].filter(Boolean).join(' ')}>
+      source<span className="visually-hidden"> for {context}</span>
+    </SourceLink>
+  );
+}
+
+/** "folder/file.md: Heading" for a source whose file name alone would be ambiguous. */
+function sourceLabel(source: Source): string | undefined {
+  if (!source.file) return undefined;
+  const parts = source.file.split('/');
+  const file = parts.pop() ?? source.file;
+  const folder = parts.pop();
+  const base = folder ? `${folder}/${file}` : file;
+  return source.heading ? `${base}: ${source.heading}` : base;
+}
diff --git a/docs-site/src/components/StageBadge.module.css b/docs-site/src/components/StageBadge.module.css
index 0dede68..f144c5d 100644
--- a/docs-site/src/components/StageBadge.module.css
+++ b/docs-site/src/components/StageBadge.module.css
@@ -3,7 +3,7 @@
   align-items: center;
   min-height: var(--target-min);
   padding: 0 var(--space-3);
-  border-radius: 999px;
+  border-radius: var(--radius-pill);
   font-size: 0.75rem;
   font-weight: 700;
   letter-spacing: 0.04em;
diff --git a/docs-site/src/components/StageJourney.module.css b/docs-site/src/components/StageJourney.module.css
new file mode 100644
index 0000000..70a54c4
--- /dev/null
+++ b/docs-site/src/components/StageJourney.module.css
@@ -0,0 +1,128 @@
+.journey {
+  list-style: none;
+  display: flex;
+  flex-wrap: wrap;
+  align-items: stretch;
+  justify-content: center;
+  gap: var(--space-2);
+  margin: 0;
+  padding: 0;
+}
+
+.item {
+  display: flex;
+  align-items: center;
+  gap: var(--space-2);
+  min-width: 0;
+}
+
+.item[data-stage='learn'] {
+  --stage-color: var(--stage-learn);
+  --stage-tint: var(--stage-learn-tint);
+}
+
+.item[data-stage='build'] {
+  --stage-color: var(--stage-build);
+  --stage-tint: var(--stage-build-tint);
+}
+
+.item[data-stage='govern'] {
+  --stage-color: var(--stage-govern);
+  --stage-tint: var(--stage-govern-tint);
+}
+
+.item[data-stage='scale'] {
+  --stage-color: var(--stage-scale);
+  --stage-tint: var(--stage-scale-tint);
+}
+
+/* Arrow between stages, drawn as a rotated border so the list keeps four items. */
+.item:not(:last-child)::after {
+  content: '';
+  flex-shrink: 0;
+  width: 0.5rem;
+  height: 0.5rem;
+  border-top: 2px solid var(--color-text-secondary);
+  border-right: 2px solid var(--color-text-secondary);
+  rotate: 45deg;
+  margin-right: var(--space-1);
+}
+
+.pill {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-2);
+  min-height: 2.75rem;
+  padding: var(--space-1) var(--space-3) var(--space-1) var(--space-2);
+  border: 1px solid var(--stage-tint);
+  border-radius: var(--radius-pill);
+  background: color-mix(in srgb, var(--stage-tint) 12%, transparent);
+  color: var(--color-text-primary);
+  text-decoration: none;
+  transition:
+    border-color var(--transition-fast),
+    background-color var(--transition-fast);
+}
+
+.pill:hover {
+  text-decoration: none;
+  color: var(--color-text-primary);
+  background: color-mix(in srgb, var(--stage-tint) 24%, transparent);
+  border-color: var(--stage-color);
+}
+
+.pill:focus-visible {
+  outline: var(--focus-ring);
+  outline-offset: 2px;
+}
+
+.icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 2rem;
+  height: 2rem;
+  border-radius: var(--radius-pill);
+  background: var(--stage-color);
+  color: var(--stage-fill-text);
+  flex-shrink: 0;
+}
+
+.icon > svg {
+  display: block;
+}
+
+.text {
+  display: flex;
+  flex-direction: column;
+  line-height: 1.2;
+  min-width: 0;
+}
+
+.stage {
+  font-size: var(--text-xs);
+  font-weight: 700;
+  letter-spacing: var(--label-tracking);
+  text-transform: uppercase;
+  color: var(--stage-color);
+}
+
+.project {
+  font-size: var(--text-sm);
+  font-weight: 600;
+  white-space: nowrap;
+}
+
+.journey[data-size='sm'] .pill {
+  min-height: 2.25rem;
+  padding: var(--space-1) var(--space-2);
+}
+
+.journey[data-size='sm'] .icon {
+  width: 1.5rem;
+  height: 1.5rem;
+}
+
+.journey[data-size='sm'] .project {
+  font-size: var(--text-xs);
+}
diff --git a/docs-site/src/components/StageJourney.test.tsx b/docs-site/src/components/StageJourney.test.tsx
new file mode 100644
index 0000000..1aed9ab
--- /dev/null
+++ b/docs-site/src/components/StageJourney.test.tsx
@@ -0,0 +1,36 @@
+import { render, screen } from '@testing-library/react';
+import { MemoryRouter } from 'react-router-dom';
+import { describe, expect, it } from 'vitest';
+import { projects } from '../content/data';
+import { StageJourney } from './StageJourney';
+
+describe('StageJourney', () => {
+  it('renders the four stages in order as links to their project pages', () => {
+    render(
+      <MemoryRouter>
+        <StageJourney />
+      </MemoryRouter>,
+    );
+    const list = screen.getByRole('list', { name: 'Journey stages' });
+    const items = screen.getAllByRole('listitem');
+    expect(items).toHaveLength(4);
+    expect(items.map((item) => item.getAttribute('data-stage'))).toEqual(['learn', 'build', 'govern', 'scale']);
+    const links = screen.getAllByRole('link');
+    const ordered = [...projects].sort((a, b) => a.stageNumber - b.stageNumber);
+    expect(links.map((link) => link.getAttribute('href'))).toEqual(ordered.map((project) => project.route));
+    expect(links[0]).toHaveTextContent('1. Learn');
+    expect(links[0]).toHaveTextContent(ordered[0].shortName);
+    expect(list.querySelectorAll('svg[aria-hidden], [aria-hidden="true"] svg').length).toBeGreaterThan(0);
+  });
+
+  it('can hide project names and shrink', () => {
+    render(
+      <MemoryRouter>
+        <StageJourney showProjects={false} size="sm" label="Stages" />
+      </MemoryRouter>,
+    );
+    const list = screen.getByRole('list', { name: 'Stages' });
+    expect(list).toHaveAttribute('data-size', 'sm');
+    expect(screen.queryByText(projects[0].shortName)).toBeNull();
+  });
+});
diff --git a/docs-site/src/components/StageJourney.tsx b/docs-site/src/components/StageJourney.tsx
new file mode 100644
index 0000000..b913de7
--- /dev/null
+++ b/docs-site/src/components/StageJourney.tsx
@@ -0,0 +1,45 @@
+import { Link } from 'react-router-dom';
+import { projects } from '../content/data';
+import { STAGE_ICONS } from '../stage';
+import styles from './StageJourney.module.css';
+
+export interface StageJourneyProps {
+  /** Accessible name of the list. */
+  label?: string;
+  /** Show the project short name under the stage. */
+  showProjects?: boolean;
+  /** compact: smaller pills for narrow places (Projects index header). */
+  size?: 'md' | 'sm';
+  className?: string;
+}
+
+/**
+ * The four-stage journey as a row of linked pills: icon, "1. Learn", project name,
+ * joined by arrows drawn in CSS so the list still has exactly four items. Reads the
+ * projects in stage order from the content model.
+ */
+export function StageJourney({ label = 'Journey stages', showProjects = true, size = 'md', className }: StageJourneyProps) {
+  const ordered = [...projects].sort((a, b) => a.stageNumber - b.stageNumber);
+  return (
+    <ol className={[styles.journey, className].filter(Boolean).join(' ')} aria-label={label} data-stage-journey data-size={size}>
+      {ordered.map((project) => {
+        const Icon = STAGE_ICONS[project.stage];
+        return (
+          <li key={project.id} className={styles.item} data-stage={project.stage}>
+            <Link to={project.route} className={styles.pill}>
+              <span className={styles.icon} aria-hidden="true">
+                <Icon size={size === 'sm' ? 14 : 18} />
+              </span>
+              <span className={styles.text}>
+                <span className={styles.stage}>
+                  {project.stageNumber}. {project.stageLabel}
+                </span>
+                {showProjects && <span className={styles.project}>{project.shortName}</span>}
+              </span>
+            </Link>
+          </li>
+        );
+      })}
+    </ol>
+  );
+}
diff --git a/docs-site/src/components/StatTile.module.css b/docs-site/src/components/StatTile.module.css
new file mode 100644
index 0000000..18d62a6
--- /dev/null
+++ b/docs-site/src/components/StatTile.module.css
@@ -0,0 +1,101 @@
+.tile {
+  margin: 0;
+  min-width: 0;
+}
+
+.label {
+  display: flex;
+  align-items: center;
+  gap: var(--space-1);
+  font-size: var(--text-xs);
+  font-weight: 700;
+  letter-spacing: var(--label-tracking);
+  text-transform: uppercase;
+  color: var(--color-text-secondary);
+}
+
+.icon {
+  display: inline-flex;
+  color: var(--stage-color, var(--color-text-secondary));
+}
+
+.icon > svg {
+  display: block;
+  width: 0.875rem;
+  height: 0.875rem;
+}
+
+.value {
+  margin: var(--space-1) 0 0;
+  font-size: var(--text-sm);
+  line-height: 1.5;
+}
+
+/* Inline layout: "Label: value" on one line, for compact fact rows. */
+.tile[data-layout='inline'] {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: baseline;
+  gap: 0 var(--space-2);
+}
+
+.tile[data-layout='inline'] .label {
+  text-transform: none;
+  letter-spacing: 0;
+  font-size: var(--text-sm);
+  font-weight: 600;
+}
+
+.tile[data-layout='inline'] .label::after {
+  content: ':';
+}
+
+.tile[data-layout='inline'] .value {
+  margin-top: 0;
+}
+
+.muted {
+  color: var(--color-text-secondary);
+}
+
+.source {
+  font-size: 0.8125rem;
+  white-space: nowrap;
+}
+
+.note {
+  display: block;
+  margin-top: 2px;
+  font-size: 0.8125rem;
+  line-height: 1.4;
+  color: var(--color-text-secondary);
+}
+
+.details {
+  margin-top: var(--space-1);
+}
+
+.summary {
+  display: inline-flex;
+  align-items: center;
+  min-height: var(--target-min);
+  font-size: 0.8125rem;
+  color: var(--color-link);
+  cursor: pointer;
+  text-decoration: underline;
+  text-underline-offset: 0.15em;
+}
+
+.summary:hover {
+  color: var(--color-link-hover);
+}
+
+.summary:focus-visible {
+  outline: var(--focus-ring);
+  outline-offset: 2px;
+  border-radius: var(--radius-sm);
+}
+
+.details[open] .summary {
+  margin-bottom: var(--space-1);
+}
diff --git a/docs-site/src/components/StatTile.test.tsx b/docs-site/src/components/StatTile.test.tsx
new file mode 100644
index 0000000..56855d2
--- /dev/null
+++ b/docs-site/src/components/StatTile.test.tsx
@@ -0,0 +1,48 @@
+import { render, screen } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+import type { Fact } from '../content/facts';
+import { FactStat, StatTile } from './StatTile';
+
+const fact: Fact = {
+  value: 'About 5 minutes',
+  note: 'The gateway stack itself takes about 2 minutes.',
+  source: { file: 'enterprise-mcp-governance-gateway/README.md', heading: 'Quick start', quote: 'about 5 minutes' },
+};
+
+describe('StatTile', () => {
+  it('renders a dt/dd pair with a source link that carries hidden context', () => {
+    render(
+      <dl>
+        <StatTile label="First deploy" value="About 5 minutes" source={fact.source} context="first deploy, MCP Gateway" />
+      </dl>,
+    );
+    expect(screen.getByRole('term')).toHaveTextContent('First deploy');
+    expect(screen.getByRole('definition')).toHaveTextContent('About 5 minutes');
+    const link = screen.getByRole('link', { name: 'source for first deploy, MCP Gateway (opens in new tab)' });
+    expect(link).toHaveAttribute('href', expect.stringContaining('enterprise-mcp-governance-gateway/README.md'));
+  });
+
+  it('collapses the note behind a disclosure when asked', () => {
+    render(
+      <dl>
+        <FactStat label="First deploy" fact={fact} project="MCP Gateway" noteMode="collapsed" />
+      </dl>,
+    );
+    expect(screen.getByText('Why this figure', { exact: false })).toBeInTheDocument();
+    const details = screen.getByText(fact.note!).closest('details');
+    expect(details).not.toBeNull();
+    expect(details).not.toHaveAttribute('open');
+    expect(screen.getByRole('link', { name: 'source for first deploy, MCP Gateway (opens in new tab)' })).toBeInTheDocument();
+  });
+
+  it('renders not-documented facts muted and without a source link', () => {
+    render(
+      <dl>
+        <FactStat label="Cost" fact={{ value: '', notDocumented: true, note: 'No figure is published.' }} />
+      </dl>,
+    );
+    expect(screen.getByRole('definition')).toHaveTextContent('not documented');
+    expect(screen.getByText('No figure is published.')).toBeInTheDocument();
+    expect(screen.queryByRole('link')).toBeNull();
+  });
+});
diff --git a/docs-site/src/components/StatTile.tsx b/docs-site/src/components/StatTile.tsx
new file mode 100644
index 0000000..49c6247
--- /dev/null
+++ b/docs-site/src/components/StatTile.tsx
@@ -0,0 +1,100 @@
+import type { ReactNode } from 'react';
+import { factText, type Fact, type Source } from '../content/facts';
+import { SourceLink } from './SourceLink';
+import styles from './StatTile.module.css';
+
+export interface StatTileProps {
+  label: ReactNode;
+  value: ReactNode;
+  /** Caveat under the value. `inline` shows it in muted text; `collapsed` puts it behind a native disclosure. */
+  note?: ReactNode;
+  noteMode?: 'inline' | 'collapsed';
+  /** Repository source for the value; rendered as a small "source" link. */
+  source?: Source;
+  /** Hidden context for the source link and the disclosure ("cost, Self-Service"), so repeated links stay distinguishable. */
+  context?: string;
+  /** Decorative icon before the label (rendered aria-hidden). */
+  icon?: ReactNode;
+  /** stacked: label above value; inline: "Label: value" on one line. */
+  layout?: 'stacked' | 'inline';
+  /** Render the value in secondary text (for "not documented"). */
+  muted?: boolean;
+  className?: string;
+}
+
+/**
+ * One fact as a `dt`/`dd` pair, to slot into a `<dl>`: label with optional icon,
+ * value, a small source link and an optional caveat. Long caveats can collapse
+ * behind a `<details>` so tiles stay scannable while the source stays visible.
+ */
+export function StatTile({
+  label,
+  value,
+  note,
+  noteMode = 'inline',
+  source,
+  context,
+  icon,
+  layout = 'stacked',
+  muted = false,
+  className,
+}: StatTileProps) {
+  return (
+    <div className={[styles.tile, className].filter(Boolean).join(' ')} data-stat-tile data-layout={layout}>
+      <dt className={styles.label}>
+        {icon && (
+          <span className={styles.icon} aria-hidden="true">
+            {icon}
+          </span>
+        )}
+        <span>{label}</span>
+      </dt>
+      <dd className={styles.value}>
+        <span className={muted ? styles.muted : undefined}>{value}</span>
+        {source && (
+          <>
+            {' '}
+            <SourceLink source={source} className={styles.source}>
+              source
+              {context && <span className="visually-hidden"> for {context}</span>}
+            </SourceLink>
+          </>
+        )}
+        {note && noteMode === 'inline' && <span className={styles.note}>{note}</span>}
+        {note && noteMode === 'collapsed' && (
+          <details className={styles.details}>
+            <summary className={styles.summary}>
+              Why this figure{context && <span className="visually-hidden"> ({context})</span>}
+            </summary>
+            <p className={styles.note}>{note}</p>
+          </details>
+        )}
+      </dd>
+    </div>
+  );
+}
+
+export interface FactStatProps extends Omit<StatTileProps, 'value' | 'note' | 'source' | 'muted'> {
+  fact: Fact;
+  /** Project name for the hidden source context. */
+  project?: string;
+  /** Plain label text used in the hidden context when `label` is a node. */
+  labelText?: string;
+}
+
+/** A `StatTile` fed from a typed fact: value, source, note and the not-documented state. */
+export function FactStat({ fact, project, label, labelText, context, ...rest }: FactStatProps) {
+  const text = labelText ?? (typeof label === 'string' ? label : undefined);
+  const ctx = context ?? (text ? `${text.toLowerCase()}${project ? `, ${project}` : ''}` : project);
+  return (
+    <StatTile
+      {...rest}
+      label={label}
+      value={fact.notDocumented ? <em>{factText(fact)}</em> : factText(fact)}
+      muted={Boolean(fact.notDocumented)}
+      source={fact.source}
+      note={fact.note}
+      context={ctx}
+    />
+  );
+}
diff --git a/docs-site/src/content/capabilityLayers.test.ts b/docs-site/src/content/capabilityLayers.test.ts
new file mode 100644
index 0000000..efce18d
--- /dev/null
+++ b/docs-site/src/content/capabilityLayers.test.ts
@@ -0,0 +1,58 @@
+import { describe, expect, it } from 'vitest';
+import { CAPABILITY_LAYERS, fillFor, postureDots, postureSentence } from './capabilityLayers';
+import { capabilities, projects } from './data';
+import { capabilityMatrix, POSTURE_LABELS } from './matrix';
+
+describe('capability layers', () => {
+  it('lists every capability id exactly once across the layers', () => {
+    const ids = CAPABILITY_LAYERS.flatMap((layer) => layer.capabilityIds);
+    expect(ids.length).toBe(new Set(ids).size);
+    expect([...ids].sort()).toEqual(capabilities.map((capability) => capability.id).sort());
+    expect(CAPABILITY_LAYERS).toHaveLength(5);
+    expect(new Set(CAPABILITY_LAYERS.map((layer) => layer.id)).size).toBe(CAPABILITY_LAYERS.length);
+  });
+
+  it('maps postures to dot fills', () => {
+    expect(fillFor('enforced')).toBe('solid');
+    expect(fillFor('advisory')).toBe('outline');
+    expect(fillFor('illustrative')).toBe('outline');
+    expect(fillFor('not-applicable')).toBe('none');
+    expect(fillFor('outside-envelope')).toBe('none');
+  });
+
+  it('returns four dots per capability, in project order, with fills matching the matrix', () => {
+    for (const capability of capabilities) {
+      const dots = postureDots(capability.id);
+      const row = capabilityMatrix.find((entry) => entry.capabilityId === capability.id);
+      expect(row).toBeDefined();
+      expect(dots).toHaveLength(4);
+      expect(dots.map((dot) => dot.projectId)).toEqual(projects.map((project) => project.id));
+      dots.forEach((dot, index) => {
+        const posture = row!.cells[projects[index].id].posture;
+        expect(dot.stage).toBe(projects[index].stage);
+        expect(dot.posture).toBe(posture);
+        expect(dot.fill).toBe(fillFor(posture));
+      });
+    }
+  });
+
+  it('builds the hidden sentence from project short names and posture labels', () => {
+    expect(postureSentence('llm-gateway')).toBe(
+      'Workshop: Illustrative; Self-Service: Not applicable; MCP Gateway: Not applicable; Blueprint: Enforced',
+    );
+    for (const capability of capabilities) {
+      const sentence = postureSentence(capability.id);
+      const parts = sentence.split('; ');
+      expect(parts).toHaveLength(4);
+      parts.forEach((part, index) => {
+        const [name, label] = part.split(': ');
+        expect(name).toBe(projects[index].shortName);
+        expect(Object.values(POSTURE_LABELS).map((entry) => entry.label)).toContain(label);
+      });
+    }
+  });
+
+  it('throws for an unknown capability id', () => {
+    expect(() => postureDots('nope')).toThrow(/nope/);
+  });
+});
diff --git a/docs-site/src/content/capabilityLayers.ts b/docs-site/src/content/capabilityLayers.ts
new file mode 100644
index 0000000..0c3b80f
--- /dev/null
+++ b/docs-site/src/content/capabilityLayers.ts
@@ -0,0 +1,67 @@
+/**
+ * The Home page capability stack: the ten shared capabilities grouped into five
+ * layers, and the posture of each project for each capability, reduced to a dot
+ * fill so the stack can be read at a glance. Pure data over `data.ts` and `matrix.ts`.
+ */
+import { projects, type JourneyStage, type ProjectId } from './data';
+import { capabilityMatrix, POSTURE_LABELS, type Posture } from './matrix';
+
+export interface CapabilityLayer {
+  id: string;
+  /** Layer name rendered as the panel heading. */
+  name: string;
+  /** `Capability.id` values from data.ts, in display order. */
+  capabilityIds: string[];
+}
+
+/** Every capability id appears exactly once (asserted by the unit test). */
+export const CAPABILITY_LAYERS: CapabilityLayer[] = [
+  { id: 'inference', name: 'Inference', capabilityIds: ['llm-gateway'] },
+  { id: 'tools', name: 'Tools and catalogue', capabilityIds: ['tool-gateway', 'registry'] },
+  { id: 'runtime', name: 'Runtime', capabilityIds: ['runtime', 'memory'] },
+  { id: 'trust', name: 'Trust', capabilityIds: ['identity', 'policy'] },
+  { id: 'operate', name: 'Operate', capabilityIds: ['delivery', 'observability', 'cost'] },
+];
+
+/** How a posture dot is drawn: filled, outlined in the stage colour, or a neutral border only. */
+export type DotFill = 'solid' | 'outline' | 'none';
+
+export interface PostureDot {
+  projectId: ProjectId;
+  stage: JourneyStage;
+  posture: Posture;
+  fill: DotFill;
+}
+
+export function fillFor(posture: Posture): DotFill {
+  switch (posture) {
+    case 'enforced':
+      return 'solid';
+    case 'advisory':
+    case 'illustrative':
+      return 'outline';
+    default:
+      return 'none';
+  }
+}
+
+function rowFor(capabilityId: string) {
+  const row = capabilityMatrix.find((entry) => entry.capabilityId === capabilityId);
+  if (!row) throw new Error(`No capability matrix row for "${capabilityId}"`);
+  return row;
+}
+
+/** One dot per project, in `projects` order, from the capability matrix. */
+export function postureDots(capabilityId: string): PostureDot[] {
+  const row = rowFor(capabilityId);
+  return projects.map((project) => {
+    const { posture } = row.cells[project.id];
+    return { projectId: project.id, stage: project.stage, posture, fill: fillFor(posture) };
+  });
+}
+
+/** Text alternative for the dots: "Workshop: Illustrative; Self-Service: Not applicable; ...". */
+export function postureSentence(capabilityId: string): string {
+  const row = rowFor(capabilityId);
+  return projects.map((project) => `${project.shortName}: ${POSTURE_LABELS[row.cells[project.id].posture].label}`).join('; ');
+}
diff --git a/docs-site/src/content/data.ts b/docs-site/src/content/data.ts
index 613d59a..ca15a56 100644
--- a/docs-site/src/content/data.ts
+++ b/docs-site/src/content/data.ts
@@ -407,3 +407,57 @@ export function getProjectByStage(stage: JourneyStage): Project | undefined {
 export function getProjectById(id: string): Project | undefined {
   return projects.find(p => p.id === id);
 }
+
+/** Icon key for a persona card; the Home page maps it to a lucide icon. */
+export type PersonaIcon = 'server' | 'bot' | 'shield' | 'compass' | 'briefcase';
+
+/** A reader role on the Home page and the one place that role should start. */
+export interface Persona {
+  /** Role name, rendered as the card heading. */
+  role: string;
+  /** One sentence on what that role gets from the projects. */
+  text: string;
+  /** Visible text of the start link. */
+  linkLabel: string;
+  /** Site route with a trailing slash. */
+  to: string;
+  icon: PersonaIcon;
+}
+
+export const personas: Persona[] = [
+  {
+    role: 'Platform engineer',
+    text: 'Build the LLM Gateway, registries and Tools Gateway module by module.',
+    linkLabel: 'Start with the Workshop',
+    to: '/projects/workshop/',
+    icon: 'server',
+  },
+  {
+    role: 'AI/ML engineer',
+    text: 'Ship an agent on Amazon Bedrock AgentCore from a template on a visual canvas.',
+    linkLabel: 'Start with Self-Service',
+    to: '/projects/self-service/',
+    icon: 'bot',
+  },
+  {
+    role: 'Security engineer',
+    text: 'See Cedar ENFORCE, JWT authentication, interceptors and a Guardrail on a live MCP endpoint.',
+    linkLabel: 'Start with the MCP Gateway',
+    to: '/projects/mcp-gateway/',
+    icon: 'shield',
+  },
+  {
+    role: 'Solutions architect',
+    text: 'Compare regions, deploy time, cost and topology before recommending a project.',
+    linkLabel: 'Start with the comparison',
+    to: '/start/which-project/',
+    icon: 'compass',
+  },
+  {
+    role: 'Engineering director',
+    text: 'Know what each sample is and is not before committing a team.',
+    linkLabel: 'Start with the support envelope',
+    to: '/reference/support-envelope/',
+    icon: 'briefcase',
+  },
+];
diff --git a/docs-site/src/pages/NotFoundPage.module.css b/docs-site/src/pages/NotFoundPage.module.css
index d7d0e38..10bd58a 100644
--- a/docs-site/src/pages/NotFoundPage.module.css
+++ b/docs-site/src/pages/NotFoundPage.module.css
@@ -1,72 +1,5 @@
+/* The band carries the whole page; the minimum height keeps the footer from sitting
+   directly under it on tall viewports. */
 .page {
-  display: flex;
-  align-items: center;
-  justify-content: center;
   min-height: 60vh;
-  padding: var(--space-8) var(--space-4);
-}
-
-.content {
-  text-align: center;
-  max-width: 400px;
-}
-
-.title {
-  font-size: 2rem;
-  margin-bottom: var(--space-4);
-  color: var(--color-text-primary);
-}
-
-.message {
-  font-size: 1rem;
-  color: var(--color-text-secondary);
-  margin-bottom: var(--space-6);
-}
-
-.actions {
-  display: flex;
-  flex-direction: column;
-  gap: var(--space-3);
-  align-items: center;
-}
-
-@media (min-width: 480px) {
-  .actions {
-    flex-direction: row;
-    justify-content: center;
-  }
-}
-
-.homeLink,
-.backButton {
-  display: inline-flex;
-  align-items: center;
-  gap: var(--space-2);
-  padding: var(--space-3) var(--space-5);
-  font-size: 0.9375rem;
-  font-weight: 500;
-  border-radius: var(--radius-md);
-  cursor: pointer;
-  transition: background var(--transition-fast), border-color var(--transition-fast);
-}
-
-.homeLink {
-  background: var(--color-blue);
-  color: white;
-}
-
-.homeLink:hover {
-  background: var(--color-blue-hover);
-  text-decoration: none;
-}
-
-.backButton {
-  background: transparent;
-  color: var(--color-text-primary);
-  border: 1px solid var(--color-border);
-}
-
-.backButton:hover {
-  border-color: var(--color-blue);
-  background: rgba(37, 99, 235, 0.05);
 }
diff --git a/docs-site/src/pages/NotFoundPage.tsx b/docs-site/src/pages/NotFoundPage.tsx
index aa4a74e..654cc3e 100644
--- a/docs-site/src/pages/NotFoundPage.tsx
+++ b/docs-site/src/pages/NotFoundPage.tsx
@@ -1,9 +1,24 @@
-import { Home, ArrowLeft } from 'lucide-react';
-import { HomeLink } from '../components/HomeLink';
+import type { MouseEvent } from 'react';
+import { useNavigate } from 'react-router-dom';
+import { ArrowLeft, Home } from 'lucide-react';
+import { Button } from '../components/Button';
+import { PageHeader } from '../components/PageHeader';
 import { PageMeta } from '../components/PageMeta';
 import styles from './NotFoundPage.module.css';
 
+/**
+ * 404 page: a slate header band with the two recovery actions. The home action writes
+ * `import.meta.env.BASE_URL` (always with the trailing slash) like `HomeLink` does, because
+ * react-router renders `to="/"` as the bare basename, which GitHub Pages answers with a
+ * redirect; a plain left click still navigates client-side.
+ */
 export function NotFoundPage() {
+  const navigate = useNavigate();
+  const goHome = (event: MouseEvent<HTMLAnchorElement>) => {
+    if (event.button !== 0 || event.metaKey || event.altKey || event.ctrlKey || event.shiftKey) return;
+    event.preventDefault();
+    navigate('/');
+  };
   return (
     <div className={styles.page}>
       <PageMeta
@@ -11,20 +26,22 @@ export function NotFoundPage() {
         description="The page you requested does not exist on the AI Agent Factory site."
         status={404}
       />
-      <div className={styles.content}>
-        <h1 className={styles.title}>Page not found</h1>
-        <p className={styles.message}>The page you are looking for does not exist or has moved.</p>
-        <div className={styles.actions}>
-          <HomeLink className={styles.homeLink}>
-            <Home size={18} aria-hidden="true" />
-            Go to Home
-          </HomeLink>
-          <button type="button" onClick={() => window.history.back()} className={styles.backButton}>
-            <ArrowLeft size={18} aria-hidden="true" />
-            Go back
-          </button>
-        </div>
-      </div>
+      <PageHeader
+        eyebrow="404"
+        hue="slate"
+        title="Page not found"
+        lead="The page you are looking for does not exist or has moved."
+        actions={
+          <>
+            <Button href={import.meta.env.BASE_URL} onClick={goHome} iconStart={<Home size={18} />}>
+              Go to the home page
+            </Button>
+            <Button variant="secondary" onClick={() => window.history.back()} iconStart={<ArrowLeft size={18} />}>
+              Go back
+            </Button>
+          </>
+        }
+      />
     </div>
   );
 }
diff --git a/docs-site/src/pages/concepts/AgentFactoryPage.module.css b/docs-site/src/pages/concepts/AgentFactoryPage.module.css
index b47271b..126fcf4 100644
--- a/docs-site/src/pages/concepts/AgentFactoryPage.module.css
+++ b/docs-site/src/pages/concepts/AgentFactoryPage.module.css
@@ -5,43 +5,25 @@
   padding-bottom: var(--section-padding-y);
 }
 
-.section {
-  padding: var(--space-10) 0 0;
-}
-
-.section h2 {
-  margin-bottom: var(--space-4);
-}
-
 .prose {
   max-width: 72ch;
   color: var(--color-text-primary);
 }
 
-.prose + .prose {
-  margin-top: var(--space-4);
-}
-
 /* How this site groups the four projects */
 .partsGrid {
+  list-style: none;
   display: grid;
   grid-template-columns: repeat(auto-fit, minmax(min(16rem, 100%), 1fr));
   gap: var(--space-4);
+  margin: 0;
+  padding: 0;
 }
 
 .partCard {
-  position: relative;
   display: flex;
   flex-direction: column;
   gap: var(--space-3);
-  padding: var(--space-6);
-  background: var(--color-bg-secondary);
-  border: 1px solid var(--color-border);
-  border-radius: var(--radius-lg);
-}
-
-.partCard h3 {
-  font-size: 1.25rem;
 }
 
 .partNumber {
@@ -50,10 +32,17 @@
   justify-content: center;
   width: 2.25rem;
   height: 2.25rem;
-  border-radius: 999px;
-  background: var(--color-midnight);
-  color: var(--color-cloud);
+  border-radius: var(--radius-pill);
+  background: var(--color-band);
+  color: var(--color-text-inverse);
   font-weight: 700;
+  /* Transparent border so forced-colors mode still draws the circle. */
+  border: 1px solid transparent;
+}
+
+.partsGrid .partTitle {
+  font-size: 1.25rem;
+  margin: 0;
 }
 
 .partProjects {
@@ -81,18 +70,8 @@
 }
 
 /* Eight steps */
-.stepsList {
+.steps {
   max-width: 72ch;
-  margin: var(--space-4) 0;
-  padding-left: var(--space-6);
-  display: flex;
-  flex-direction: column;
-  gap: var(--space-3);
-}
-
-.stepsList li::marker {
-  font-weight: 700;
-  color: var(--stage-scale-ink);
 }
 
 /* Per-project shipping */
@@ -101,46 +80,35 @@
   display: grid;
   grid-template-columns: repeat(auto-fit, minmax(min(18rem, 100%), 1fr));
   gap: var(--space-4);
-  margin-bottom: var(--space-6);
+  margin: 0 0 var(--space-6);
+  padding: 0;
 }
 
 .shipItem {
   display: flex;
   flex-direction: column;
   gap: var(--space-3);
-  padding: var(--space-5);
-  background: var(--color-bg-secondary);
-  border: 1px solid var(--color-border);
-  border-radius: var(--radius-lg);
 }
 
 .shipHeading {
   display: flex;
   flex-wrap: wrap;
   align-items: center;
-  gap: var(--space-3);
+  gap: var(--space-2) var(--space-3);
+}
+
+.shipIcon {
+  flex-shrink: 0;
+  color: var(--stage-color);
 }
 
-.shipHeading h3 {
+.shipList .shipTitle {
   font-size: 1.25rem;
+  margin: 0;
 }
 
-.shipFact {
+.shipFacts {
   margin-top: auto;
   padding-top: var(--space-3);
   border-top: 1px solid var(--color-border);
-  font-size: 0.9375rem;
-  color: var(--color-text-secondary);
-}
-
-.shipFactLabel {
-  font-weight: 600;
-  color: var(--color-text-primary);
-}
-
-/* Links inside secondary-coloured text need more than colour to stand out. */
-.shipFact a,
-.partProjectsLabel a {
-  text-decoration: underline;
-  text-underline-offset: 0.15em;
 }
diff --git a/docs-site/src/pages/concepts/AgentFactoryPage.tsx b/docs-site/src/pages/concepts/AgentFactoryPage.tsx
index 9d62da2..438e819 100644
--- a/docs-site/src/pages/concepts/AgentFactoryPage.tsx
+++ b/docs-site/src/pages/concepts/AgentFactoryPage.tsx
@@ -1,12 +1,17 @@
 import { Link } from 'react-router-dom';
+import { Card } from '../../components/Card';
+import { NumberedSteps } from '../../components/NumberedSteps';
 import { PageHeader } from '../../components/PageHeader';
 import { PageMeta } from '../../components/PageMeta';
-import { ConceptsNav } from './ConceptsNav';
+import { Section } from '../../components/Section';
 import { SourceLink } from '../../components/SourceLink';
 import { StageBadge } from '../../components/StageBadge';
+import { FactStat } from '../../components/StatTile';
 import { getProjectById, projects, type ProjectId } from '../../content/data';
-import { facts, factText, type Fact, type Source } from '../../content/facts';
+import { facts, type Fact, type Source } from '../../content/facts';
 import { PATHS, projectPath } from '../../paths';
+import { STAGE_ICONS } from '../../stage';
+import { ConceptsNav } from './ConceptsNav';
 import styles from './AgentFactoryPage.module.css';
 
 const ROOT_README = 'README.md';
@@ -147,8 +152,7 @@ export function AgentFactoryPage() {
       <div className="container">
         <ConceptsNav />
 
-        <section className={styles.section} aria-labelledby="concept">
-          <h2 id="concept">The Agent Factory concept</h2>
+        <Section id="concept" title="The Agent Factory concept" flush>
           <p className={styles.prose}>
             An <strong>AI Agent Factory</strong> is the people, patterns, and platform that let an organization turn
             ideas into production agents reliably and at scale. The hard part is everything around the model:
@@ -162,21 +166,20 @@ export function AgentFactoryPage() {
             how enterprises move from learning to agent operations at scale (
             <SourceLink source={INDEPENDENCE_SOURCE}>What This Is</SourceLink>).
           </p>
-        </section>
+        </Section>
 
-        <section className={styles.section} aria-labelledby="site-grouping">
-          <h2 id="site-grouping">How this site groups the four projects</h2>
-          <p className={styles.prose}>
-            This grouping is this site&apos;s reading of the repository, not a structure the project READMEs use. It
-            exists to show which project answers which need.
-          </p>
-          <div className={styles.partsGrid}>
+        <Section
+          id="site-grouping"
+          title="How this site groups the four projects"
+          lead="This grouping is this site's reading of the repository, not a structure the project READMEs use. It exists to show which project answers which need."
+        >
+          <ol className={styles.partsGrid}>
             {STORY_PARTS.map((part, index) => (
-              <article key={part.title} className={styles.partCard}>
+              <Card as="li" key={part.title} reveal padding="lg" className={styles.partCard}>
                 <span className={styles.partNumber} aria-hidden="true">
                   {index + 1}
                 </span>
-                <h3>{part.title}</h3>
+                <h3 className={styles.partTitle}>{part.title}</h3>
                 <p>{part.text}</p>
                 <p className={styles.partProjects}>
                   <span className={styles.partProjectsLabel}>Projects:</span>
@@ -191,13 +194,12 @@ export function AgentFactoryPage() {
                     );
                   })}
                 </p>
-              </article>
+              </Card>
             ))}
-          </div>
-        </section>
+          </ol>
+        </Section>
 
-        <section className={styles.section} aria-labelledby="ships">
-          <h2 id="ships">How an engineer ships an agent (Blueprint)</h2>
+        <Section id="ships" title="How an engineer ships an agent (Blueprint)">
           <p className={styles.prose}>
             The <Link to={projectPath('blueprint')}>{BLUEPRINT_NAME}</Link> (the Blueprint, in the rest of this page)
             describes this flow in its README. It is the Blueprint&apos;s pull-request-and-pipeline path; the other
@@ -205,44 +207,39 @@ export function AgentFactoryPage() {
             README&apos;s own and the first step is quoted; the other descriptions are condensed. Source:{' '}
             <SourceLink source={SHIPPING_SOURCE} />.
           </p>
-          <ol className={styles.stepsList}>
+          <NumberedSteps stage="scale" connector className={styles.steps}>
             {BLUEPRINT_STEPS.map((step) => (
-              <li key={step.title}>
-                <strong>{step.title}</strong> {step.text}
-              </li>
+              <NumberedSteps.Item key={step.title} title={step.title}>
+                <p>{step.text}</p>
+              </NumberedSteps.Item>
             ))}
-          </ol>
+          </NumberedSteps>
           <p className={styles.prose}>
             In the Blueprint, the Platform team is not in the application deployment loop. It owns the contracts that
             make independent deployment safe.
           </p>
-        </section>
+        </Section>
 
-        <section className={styles.section} aria-labelledby="each-project">
-          <h2 id="each-project">How each project actually ships an agent</h2>
+        <Section id="each-project" title="How each project actually ships an agent">
           <ul className={styles.shipList}>
             {PROJECT_SHIPPING.map((entry) => {
               const project = getProjectById(entry.projectId);
               if (!project) return null;
+              const Icon = STAGE_ICONS[project.stage];
               return (
-                <li key={entry.projectId} className={styles.shipItem}>
+                <Card as="li" key={entry.projectId} variant="accent" stage={project.stage} reveal className={styles.shipItem}>
                   <div className={styles.shipHeading}>
-                    <StageBadge stage={project.stage} label={project.stageLabel} />
-                    <h3>
+                    <Icon size={20} aria-hidden="true" className={styles.shipIcon} />
+                    <h3 className={styles.shipTitle}>
                       <Link to={projectPath(project.id)}>{project.shortName}</Link>
                     </h3>
+                    <StageBadge stage={project.stage} label={project.stageLabel} />
                   </div>
                   <p>{entry.text}</p>
-                  <p className={styles.shipFact}>
-                    <span className={styles.shipFactLabel}>{entry.factLabel}:</span> {factText(entry.fact)}
-                    {entry.fact.source && (
-                      <>
-                        {' '}
-                        (<SourceLink source={entry.fact.source}>source</SourceLink>)
-                      </>
-                    )}
-                  </p>
-                </li>
+                  <dl className={styles.shipFacts}>
+                    <FactStat fact={entry.fact} label={entry.factLabel} project={project.shortName} />
+                  </dl>
+                </Card>
               );
             })}
           </ul>
@@ -252,7 +249,7 @@ export function AgentFactoryPage() {
             <SourceLink source={INDEPENDENCE_SOURCE}>root README</SourceLink>). To pick one, use{' '}
             <Link to={PATHS.whichProject}>Which project is for me</Link>.
           </p>
-        </section>
+        </Section>
       </div>
     </div>
   );
diff --git a/docs-site/src/pages/concepts/ArchitecturePage.module.css b/docs-site/src/pages/concepts/ArchitecturePage.module.css
index e35534a..14099db 100644
--- a/docs-site/src/pages/concepts/ArchitecturePage.module.css
+++ b/docs-site/src/pages/concepts/ArchitecturePage.module.css
@@ -5,31 +5,25 @@
   padding-bottom: var(--section-padding-y);
 }
 
-.section {
-  padding: var(--space-10) 0 0;
-}
-
-.section h2 {
-  margin-bottom: var(--space-4);
-}
-
 .prose {
   max-width: 72ch;
   margin-bottom: var(--space-4);
 }
 
-/* Links inside secondary-coloured text (figure captions, source lines) need more than colour. */
-.section figcaption a,
-.conceptSource a,
+/* Links inside secondary-coloured text need more than colour. */
 .atlasHub a {
   text-decoration: underline;
   text-underline-offset: 0.15em;
 }
 
 /* Atlas: the SVG carries its own dark background, so it sits in a dark frame on the light page */
+/* Header figure: the Atlas on a raised panel inside the dark page header. The page header is
+   itself `--color-band`, so the raised band token and a translucent light hairline make the
+   panel read as a frame in both colour schemes. */
 .atlasFrame {
   padding: var(--space-4);
-  background: var(--color-midnight);
+  background: var(--color-band-raised);
+  border: 1px solid color-mix(in srgb, var(--color-text-inverse) 18%, transparent);
   border-radius: var(--radius-lg);
 }
 
@@ -39,10 +33,6 @@
   height: auto;
 }
 
-.atlasList {
-  margin-top: var(--space-6);
-}
-
 .atlasListIntro {
   color: var(--color-text-secondary);
   margin-bottom: var(--space-2);
@@ -59,10 +49,6 @@
   display: flex;
   align-items: flex-start;
   gap: var(--space-3);
-  padding: var(--space-3);
-  border: 1px solid var(--color-border);
-  border-radius: var(--radius-md);
-  background: var(--color-bg-secondary);
 }
 
 .atlasProjectLink {
@@ -86,59 +72,77 @@
   font-weight: 700;
 }
 
-/* Blueprint concepts */
-.conceptGrid {
+/* Blueprint concepts: three articles stacked with one rhythm. */
+.concepts {
   display: grid;
-  grid-template-columns: repeat(auto-fit, minmax(min(20rem, 100%), 1fr));
-  gap: var(--space-4);
+  gap: var(--space-6);
 }
 
-.conceptCard {
+.concept {
   display: flex;
   flex-direction: column;
   gap: var(--space-3);
-  padding: var(--space-5);
-  background: var(--color-bg-secondary);
-  border: 1px solid var(--color-border);
-  border-radius: var(--radius-lg);
+  min-width: 0;
 }
 
-.conceptCard h3 {
+.concepts .concept h3 {
   font-size: 1.25rem;
+  margin: 0;
 }
 
-.conceptCardWide {
-  grid-column: 1 / -1;
-}
-
-.conceptList {
-  padding-left: var(--space-6);
-  display: flex;
-  flex-direction: column;
+/* Four planes: full-width bands, each with a 4 px left rule in one stage tint
+   (--card-accent comes from the Card's stage). */
+.planes {
+  list-style: none;
+  display: grid;
   gap: var(--space-2);
+  margin: 0;
+  padding: 0;
 }
 
-.conceptSource {
-  margin-top: auto;
-  padding-top: var(--space-3);
-  border-top: 1px solid var(--color-border);
-  font-size: 0.9375rem;
-  color: var(--color-text-secondary);
-}
-
-.flowList {
+.planes .plane {
   display: grid;
-  grid-template-columns: repeat(auto-fit, minmax(min(18rem, 100%), 1fr));
-  gap: var(--space-4);
-  margin: 0;
+  grid-template-columns: auto 1fr;
+  grid-template-areas:
+    'number name'
+    'number text';
+  column-gap: var(--space-3);
+  row-gap: var(--space-1);
+  align-items: center;
+  border-left: 4px solid var(--card-accent, var(--color-border));
+}
+
+@media (min-width: 1024px) {
+  .planes .plane {
+    grid-template-columns: auto minmax(14rem, 18rem) 1fr;
+    grid-template-areas: 'number name text';
+    column-gap: var(--space-5);
+  }
+}
+
+.planeNumber {
+  grid-area: number;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 1.75rem;
+  height: 1.75rem;
+  border-radius: var(--radius-pill);
+  background: var(--stage-color, var(--color-text-primary));
+  color: var(--stage-fill-text);
+  font-size: var(--text-sm);
+  font-weight: 700;
+  /* Transparent border so forced-colors mode still draws the circle. */
+  border: 1px solid transparent;
 }
 
-.flowItem dt {
-  font-weight: 700;
-  margin-bottom: var(--space-1);
+.planeName {
+  grid-area: name;
+  font-weight: 600;
 }
 
-.flowItem dd {
-  margin: 0;
-  font-size: 0.9375rem;
+.planeText {
+  grid-area: text;
+  font-size: var(--text-sm);
+  color: var(--color-text-secondary);
 }
diff --git a/docs-site/src/pages/concepts/ArchitecturePage.tsx b/docs-site/src/pages/concepts/ArchitecturePage.tsx
index 6acbcc3..c3ab920 100644
--- a/docs-site/src/pages/concepts/ArchitecturePage.tsx
+++ b/docs-site/src/pages/concepts/ArchitecturePage.tsx
@@ -1,17 +1,22 @@
 import { Link } from 'react-router-dom';
+import { Card } from '../../components/Card';
 import { Figure } from '../../components/Figure';
+import { FlowStrip, type FlowStripItem } from '../../components/FlowStrip';
 import { PageHeader } from '../../components/PageHeader';
 import { PageMeta } from '../../components/PageMeta';
-import { ConceptsNav } from './ConceptsNav';
+import { Section } from '../../components/Section';
 import { SourceLink } from '../../components/SourceLink';
+import { Sources } from '../../components/Sources';
 import { StageBadge } from '../../components/StageBadge';
-import { capabilities, projects } from '../../content/data';
+import { capabilities, projects, type JourneyStage } from '../../content/data';
 import type { Source } from '../../content/facts';
 import { blob } from '../../content/links';
 import { projectPath } from '../../paths';
+import { ConceptsNav } from './ConceptsNav';
 import blueprintConcept from '../../../../enterprise-agentic-ai-platform-blueprint/assets/enterprise-agent-factory-concept.svg';
 import blueprintServices from '../../../../enterprise-agentic-ai-platform-blueprint/assets/enterprise-agent-factory-aws-services.svg';
 import workshopLandingZone from '../../../../workshop-building-agentic-ai-platform/static/img/module-1/agentic-ai-platform-architecture.png';
+import workshopLlmGateway from '../../../../workshop-building-agentic-ai-platform/static/img/module-2/llm-gateway-architecture.png';
 import selfServiceArchitecture from '../../../../Agentic-ai-self-service/docs/architecture.jpg';
 import styles from './ArchitecturePage.module.css';
 
@@ -20,10 +25,13 @@ const BASE_URL = import.meta.env.BASE_URL || '/';
 const BLUEPRINT_README = 'enterprise-agentic-ai-platform-blueprint/README.md';
 const BLUEPRINT_ASSETS = 'enterprise-agentic-ai-platform-blueprint/assets';
 const WORKSHOP_PLATFORM_PAGE = 'workshop-building-agentic-ai-platform/content/module-1/the-platform/index.en.md';
+const WORKSHOP_LLM_GATEWAY_PAGE = 'workshop-building-agentic-ai-platform/content/module-2/step-1/index.en.md';
 const SELF_SERVICE_README = 'Agentic-ai-self-service/README.md';
 
 const BLUEPRINT_VIEWS_SOURCE: Source = { file: BLUEPRINT_README, heading: 'Two complementary architecture views' };
 const WORKSHOP_FIGURE_SOURCE: Source = { file: WORKSHOP_PLATFORM_PAGE };
+/** The Module 2 page that embeds the LLM Gateway diagram, under its "Why an LLM Gateway?" heading. */
+const WORKSHOP_LLM_GATEWAY_SOURCE: Source = { file: WORKSHOP_LLM_GATEWAY_PAGE, heading: 'Why an LLM Gateway?' };
 const SELF_SERVICE_FIGURE_SOURCE: Source = { file: SELF_SERVICE_README, heading: 'Architecture' };
 const FOUR_PLANES_SOURCE: Source = { file: BLUEPRINT_README, heading: '1. Overview' };
 const CELL_SOURCE: Source = { file: BLUEPRINT_README, heading: '2.3 Repeatable Workstream cell' };
@@ -44,54 +52,66 @@ const SERVICES_ALT =
 const WORKSHOP_ALT =
   'Workshop platform architecture: a multi-account AWS landing zone. An AWS Organization holds governance accounts (Management with Organizations, Control Tower and IAM Identity Center; Log Archive with organization CloudTrail, WORM S3 and Bedrock invocation logs; Audit with Security Hub, GuardDuty, Config, Inspector and CloudWatch OAM). A central Platform account hosts the auth boundary (API Gateway, WAF, Cognito), Bedrock AgentCore (Gateway, Registry, Cedar), the inference gateway (LiteLLM on ECS Fargate), and security and cost controls (Guardrails, CUR, KMS). Per-application Workload accounts run AgentCore services, agent blueprints, RAG and knowledge stores, and PrivateLink egress. A CI/CD pipeline runs from source through build and test, non-production deploy, an evaluation gate, a canary stage, production, and a teardown test.';
 
+const WORKSHOP_LLM_GATEWAY_ALT =
+  'LLM Gateway architecture in one AWS region. Tenant clients reach the gateway through distribution options (Amazon CloudFront or Route 53), AWS WAF and an Application Load Balancer with an ACM certificate. Inside a cluster VPC, an ECS cluster or EKS cluster runs API middleware tasks and the LiteLLM proxy, pulling images from Amazon ECR and reading credentials from AWS Secrets Manager. LiteLLM routes requests to AWS model providers (Amazon Bedrock, Amazon Nova, Amazon SageMaker AI) and to external model providers (OpenAI, Anthropic, Vertex AI, Cohere), stores state in Amazon RDS and Amazon ElastiCache for Redis OSS, and writes logs to Amazon S3. Numbered steps mark the request path from client to model provider.';
+
 const SELF_SERVICE_ALT =
   'AgentCore Visual Workflow Platform architecture in one AWS region. A React single-page app served by CloudFront and S3 calls API Gateway. Lambda workflow and deployment APIs store workflows, flows and deployments in DynamoDB and start a Step Functions deployment pipeline. Cognito, IAM, CloudWatch and Systems Manager provide identity, permissions, logs and configuration; a single CDK stack deploys everything and a CloudFormation export is available. The pipeline runs steps such as validate, guardrails, MCP server, knowledge base, gateway, memory, policy, code generation, IAM role, runtime configure and launch, evaluation, JWT auth and status update. For each agent it creates an Agent Runtime, an MCP Gateway with JWT auth, an MCP Server Runtime, tool Lambdas, AgentCore Memory, Knowledge Base, Evaluation, Policy and Observability, and a per-agent Cognito user pool.';
 
 interface Plane {
   name: string;
   text: string;
+  /** Stage whose tint colours the band's left rule (decorative, one per plane). */
+  stage: JourneyStage;
 }
 
 const FOUR_PLANES: Plane[] = [
   {
     name: 'Developer experience plane',
     text: 'Versioned agent templates, CLI and repository workflows, approved extension points, and self-service onboarding.',
+    stage: 'learn',
   },
   {
     name: 'Platform control plane',
     text: 'Registry governance, model and Guardrail policy, shared inference, release orchestration, and reusable account baselines.',
+    stage: 'build',
   },
   {
     name: 'Workstream execution plane',
     text: 'Isolated cells containing team-owned Runtime, Memory, Tool Gateway, tools, and application data.',
+    stage: 'govern',
   },
   {
     name: 'Assurance and operations plane',
     text: 'Organization policy, evidence gates, fleet telemetry, audit, incident response, quota management, and chargeback.',
+    stage: 'scale',
   },
 ];
 
-interface Flow {
-  name: string;
-  text: string;
-}
-
-const FOUR_FLOWS: Flow[] = [
+const FOUR_FLOWS: FlowStripItem[] = [
   {
+    id: 'delivery',
     name: 'Software delivery flow',
-    text: 'From pull request through source, build and synth, policy and image gates, stable roles, the permission handoff, nonproduction, deployed-runtime evaluation and human approval to production. No direct developer deployment path writes into a Workstream account.',
+    detail:
+      'From pull request through source, build and synth, policy and image gates, stable roles, the permission handoff, nonproduction, deployed-runtime evaluation and human approval to production. No direct developer deployment path writes into a Workstream account.',
   },
   {
+    id: 'inference',
     name: 'Inference flow',
-    text: 'A governed LLM Gateway sits between agent workloads and model providers. The agent obtains a short-lived token through AgentCore Identity and Cognito M2M, calls the AgentCore Gateway inference endpoint, a request interceptor applies the stage Bedrock Guardrail, and the Gateway role invokes only an allow-listed Bedrock model.',
+    detail:
+      'A governed LLM Gateway sits between agent workloads and model providers. The agent obtains a short-lived token through AgentCore Identity and Cognito M2M, calls the AgentCore Gateway inference endpoint, a request interceptor applies the stage Bedrock Guardrail, and the Gateway role invokes only an allow-listed Bedrock model.',
   },
   {
+    id: 'tool',
     name: 'Tool flow',
-    text: 'A governed Tool Gateway sits between agents and enterprise actions. AgentCore Gateway authenticates the Runtime role with AWS_IAM, targets come from approved Registry records, and the Gateway role invokes only subscribed Platform Lambda aliases. AgentCore PolicyEngine can enforce per-tool policy, with the Lambda Cedar wrapper as rollback and defense in depth.',
+    detail:
+      'A governed Tool Gateway sits between agents and enterprise actions. AgentCore Gateway authenticates the Runtime role with AWS_IAM, targets come from approved Registry records, and the Gateway role invokes only subscribed Platform Lambda aliases. AgentCore PolicyEngine can enforce per-tool policy, with the Lambda Cedar wrapper as rollback and defense in depth.',
   },
   {
+    id: 'telemetry',
     name: 'Telemetry and assurance flow',
-    text: 'Every cell emits common logs, metrics, traces, deployment evidence and allocation dimensions. OAM links make Platform and Workstream telemetry queryable from Management, and CloudTrail plus retained audit data corroborate control-plane actions.',
+    detail:
+      'Every cell emits common logs, metrics, traces, deployment evidence and allocation dimensions. OAM links make Platform and Workstream telemetry queryable from Management, and CloudTrail plus retained audit data corroborate control-plane actions.',
   },
 ];
 
@@ -100,39 +120,41 @@ export function ArchitecturePage() {
     <div className={styles.page}>
       <PageMeta
         title="Architecture"
-        description="Architecture diagrams for the AI Agent Factory: the repository atlas, the Blueprint's operating-model and AWS service-level figures, the workshop landing zone, the Self-Service platform architecture, and the Blueprint concepts of planes, cells and governed flows."
+        description="Architecture diagrams for the AI Agent Factory: the repository atlas, the Blueprint's operating-model and AWS service-level figures, the workshop landing zone and LLM Gateway, the Self-Service platform architecture, and the Blueprint concepts of planes, cells and governed flows."
       />
       <PageHeader
         eyebrow="Concepts"
         title="Architecture"
         lead={`The repository map, the two reference diagrams of the ${BLUEPRINT_NAME} (the Blueprint), and the architecture figures the Workshop and Self-Service projects publish. Each project diagram shows where Amazon Bedrock AgentCore sits in that design, and every diagram is labelled with the project it belongs to.`}
-      />
-
-      <div className="container">
-        <ConceptsNav />
-
-        <section className={styles.section} aria-labelledby="atlas">
-          <h2 id="atlas">The repository at a glance</h2>
-          <p className={styles.prose}>
-            The atlas shows the four projects in their Learn, Build, Govern, Scale order around the capabilities they
-            share. The figure uses its own labels: it calls the Self-Service project the Visual Workflow Platform and
-            the Blueprint the Enterprise Blueprint. The list below carries the same information as text, with the
-            names this site uses.
-          </p>
-          <div className={`${styles.atlasFrame} on-dark`}>
+        figure={
+          <div className={styles.atlasFrame} data-atlas-figure>
             <img
               src={`${BASE_URL}repository-atlas-journey.svg`}
               alt={ATLAS_ALT}
               width={1200}
               height={700}
+              loading="eager"
+              decoding="async"
               className={styles.atlasImage}
             />
           </div>
-          <div className={styles.atlasList}>
+        }
+      />
+
+      <div className="container">
+        <ConceptsNav />
+
+        <Section
+          id="atlas"
+          title="The repository at a glance"
+          flush
+          lead="The atlas in the page header shows the four projects in their Learn, Build, Govern, Scale order around the capabilities they share. The figure uses its own labels: it calls the Self-Service project the Visual Workflow Platform and the Blueprint the Enterprise Blueprint. The list below carries the same information as text, with the names this site uses."
+        >
+          <div>
             <p className={styles.atlasListIntro}>The same map as a list:</p>
             <ol className={styles.atlasProjects}>
               {projects.map((project) => (
-                <li key={project.id} className={styles.atlasProject}>
+                <Card as="li" key={project.id} padding="sm" className={styles.atlasProject}>
                   <StageBadge stage={project.stage} label={`${project.stageNumber}. ${project.stageLabel}`} />
                   <span>
                     <Link to={projectPath(project.id)} className={styles.atlasProjectLink}>
@@ -140,7 +162,7 @@ export function ArchitecturePage() {
                     </Link>
                     <span className={styles.atlasTagline}> {project.tagline}</span>
                   </span>
-                </li>
+                </Card>
               ))}
             </ol>
             <p className={styles.atlasHub}>
@@ -148,10 +170,9 @@ export function ArchitecturePage() {
               {capabilities.map((cap) => cap.name).join(', ')}.
             </p>
           </div>
-        </section>
+        </Section>
 
-        <section className={styles.section} aria-labelledby="blueprint-figures">
-          <h2 id="blueprint-figures">Blueprint: two reference diagrams</h2>
+        <Section id="blueprint-figures" title="Blueprint: two reference diagrams">
           <p className={styles.prose}>
             Both figures belong to the <Link to={projectPath('blueprint')}>Blueprint</Link>. Its README explains that
             Figure 1 is the operating-model view: people, ownership, shared capability planes, repeatable cells, and
@@ -166,9 +187,8 @@ export function ArchitecturePage() {
             height={1330}
             caption={
               <>
-                <strong>Figure 1 (Blueprint).</strong> Enterprise operating model and governed flow. AWS
-                labels illustrate the repository&apos;s reference choices; the capability boundaries are the
-                architecture.
+                <strong>Figure 1 (Blueprint).</strong> Enterprise operating model and governed flow. AWS labels
+                illustrate the repository&apos;s reference choices; the capability boundaries are the architecture.
               </>
             }
             download={{
@@ -183,8 +203,8 @@ export function ArchitecturePage() {
             height={1470}
             caption={
               <>
-                <strong>Figure 2 (Blueprint).</strong> AWS service-level reference implementation. Account
-                IDs are documentation placeholders.
+                <strong>Figure 2 (Blueprint).</strong> AWS service-level reference implementation. Account IDs are
+                documentation placeholders.
               </>
             }
             download={{
@@ -192,14 +212,14 @@ export function ArchitecturePage() {
               label: 'Open the editable Draw.io source',
             }}
           />
-        </section>
+        </Section>
 
-        <section className={styles.section} aria-labelledby="workshop-figure">
-          <h2 id="workshop-figure">Workshop: the landing-zone pattern</h2>
+        <Section id="workshop-figure" title="Workshop: the landing-zone pattern and the LLM Gateway">
           <p className={styles.prose}>
-            The <Link to={projectPath('workshop')}>Workshop</Link> opens with this diagram in Module 1. It is the
+            The <Link to={projectPath('workshop')}>Workshop</Link> opens with the first diagram in Module 1. It is the
             multi-account pattern the modules teach; the self-paced deploy script stands up the Platform-account
-            pieces in a single account.
+            pieces in a single account. Module 2 adds the second diagram, the LLM Gateway that the workshop deploys as
+            a LiteLLM proxy.
           </p>
           <Figure
             src={workshopLandingZone}
@@ -214,10 +234,23 @@ export function ArchitecturePage() {
               </>
             }
           />
-        </section>
+          <Figure
+            src={workshopLlmGateway}
+            alt={WORKSHOP_LLM_GATEWAY_ALT}
+            width={1851}
+            height={1111}
+            caption={
+              <>
+                <strong>Workshop (Module 2).</strong> LLM Gateway architecture, shown under the heading &quot;Why an
+                LLM Gateway?&quot;: a LiteLLM proxy on ECS or EKS behind WAF and a load balancer, routing to AWS and
+                external model providers.{' '}
+                <SourceLink source={WORKSHOP_LLM_GATEWAY_SOURCE}>Source page</SourceLink>.
+              </>
+            }
+          />
+        </Section>
 
-        <section className={styles.section} aria-labelledby="self-service-figure">
-          <h2 id="self-service-figure">Self-Service: platform architecture</h2>
+        <Section id="self-service-figure" title="Self-Service: platform architecture">
           <p className={styles.prose}>
             The <Link to={projectPath('self-service')}>Self-Service</Link> project (AgentCore Visual Workflow Platform)
             publishes this diagram in its README: the serverless control plane, the Step Functions deployment pipeline,
@@ -239,33 +272,33 @@ export function ArchitecturePage() {
               label: 'Open the editable Draw.io source',
             }}
           />
-        </section>
+        </Section>
 
-        <section className={styles.section} aria-labelledby="blueprint-concepts">
-          <h2 id="blueprint-concepts">Concepts from the Blueprint</h2>
-          <p className={styles.prose}>
-            The three ideas below come from the Blueprint&apos;s README and describe the Blueprint only. The Workshop,
-            Self-Service and MCP Gateway projects do not use them.
-          </p>
-
-          <div className={styles.conceptGrid}>
-            <article className={styles.conceptCard}>
-              <h3>Four planes</h3>
+        <Section
+          id="blueprint-concepts"
+          title="Concepts from the Blueprint"
+          lead="The three ideas below come from the Blueprint's README and describe the Blueprint only. The Workshop, Self-Service and MCP Gateway projects do not use them."
+        >
+          <div className={styles.concepts}>
+            <article className={styles.concept} aria-labelledby="four-planes">
+              <h3 id="four-planes">Four planes</h3>
               <p>The Blueprint treats the Agent Factory as a product with four planes:</p>
-              <ol className={styles.conceptList}>
-                {FOUR_PLANES.map((plane) => (
-                  <li key={plane.name}>
-                    <strong>{plane.name}.</strong> {plane.text}
-                  </li>
+              <ol className={styles.planes}>
+                {FOUR_PLANES.map((plane, index) => (
+                  <Card as="li" key={plane.name} padding="sm" reveal stage={plane.stage} className={styles.plane}>
+                    <span className={styles.planeNumber} aria-hidden="true">
+                      {index + 1}
+                    </span>
+                    <span className={styles.planeName}>{plane.name}</span>
+                    <span className={styles.planeText}>{plane.text}</span>
+                  </Card>
                 ))}
               </ol>
-              <p className={styles.conceptSource}>
-                Source: <SourceLink source={FOUR_PLANES_SOURCE} />
-              </p>
+              <Sources sources={[FOUR_PLANES_SOURCE]} />
             </article>
 
-            <article className={styles.conceptCard}>
-              <h3>Workstream cells</h3>
+            <Card as="article" reveal className={styles.concept} aria-labelledby="workstream-cells">
+              <h3 id="workstream-cells">Workstream cells</h3>
               <p>
                 The unit of scale is a workstream cell, not a manually configured agent. A cell can represent a product,
                 business domain, regulated boundary, or portfolio team. Each cell is an isolated execution boundary with
@@ -275,27 +308,20 @@ export function ArchitecturePage() {
                 into the observability plane. A cell can deploy, roll back, or fail without another team coordinating
                 its release.
               </p>
-              <p className={styles.conceptSource}>
-                Source: <SourceLink source={CELL_SOURCE} />
-              </p>
-            </article>
+              <Sources sources={[CELL_SOURCE]} />
+            </Card>
 
-            <article className={`${styles.conceptCard} ${styles.conceptCardWide}`}>
-              <h3>Four governed flows</h3>
-              <dl className={styles.flowList}>
-                {FOUR_FLOWS.map((flow) => (
-                  <div key={flow.name} className={styles.flowItem}>
-                    <dt>{flow.name}</dt>
-                    <dd>{flow.text}</dd>
-                  </div>
-                ))}
-              </dl>
-              <p className={styles.conceptSource}>
-                Source: <SourceLink source={FLOWS_SOURCE} />
-              </p>
+            <article className={styles.concept} aria-labelledby="four-flows">
+              <h3 id="four-flows">Four governed flows</h3>
+              <FlowStrip
+                items={FOUR_FLOWS}
+                stage="scale"
+                label="Four governed flows"
+                caption={<Sources sources={[FLOWS_SOURCE]} inline />}
+              />
             </article>
           </div>
-        </section>
+        </Section>
       </div>
     </div>
   );
diff --git a/docs-site/src/pages/concepts/CapabilityContractsPage.module.css b/docs-site/src/pages/concepts/CapabilityContractsPage.module.css
index 8adf61f..ed888b7 100644
--- a/docs-site/src/pages/concepts/CapabilityContractsPage.module.css
+++ b/docs-site/src/pages/concepts/CapabilityContractsPage.module.css
@@ -5,40 +5,16 @@
   padding-bottom: var(--section-padding-y);
 }
 
-.section {
-  padding: var(--space-10) 0 0;
-}
-
-.section h2 {
-  margin-bottom: var(--space-4);
-}
-
-.prose {
-  max-width: 72ch;
-  margin-bottom: var(--space-4);
-}
-
-/* Canonical contract statement */
-.contractBox {
+/* Tinted statement and checklist boxes (the Card owns the surface). */
+.tintedBox {
   max-width: 80ch;
-  padding: var(--space-6);
-  background: var(--tint-blue);
-  border-left: 4px solid var(--stage-scale-tint);
-  border-radius: var(--radius-md);
 }
 
-.contractBox p + p {
-  margin-top: var(--space-4);
-}
-
-.contractSource {
-  font-size: 0.9375rem;
-  color: var(--color-text-secondary);
-}
-
-.contractSource a {
-  text-decoration: underline;
-  text-underline-offset: 0.15em;
+.checklist {
+  padding-left: var(--space-6);
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-2);
 }
 
 /* Capability cards */
@@ -52,18 +28,28 @@
   display: flex;
   flex-direction: column;
   gap: var(--space-3);
-  padding: var(--space-5);
-  background: var(--color-bg-secondary);
-  border: 1px solid var(--color-border);
-  border-radius: var(--radius-lg);
 }
 
-.capabilityName {
-  font-size: 1.25rem;
+.capabilityHead {
+  display: flex;
+  align-items: center;
+  gap: var(--space-3);
+}
+
+.capabilityIcon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  width: 2.25rem;
+  height: 2.25rem;
+  border-radius: var(--radius-md);
+  background: var(--tint-blue);
+  color: var(--tint-heading-blue);
 }
 
-.capabilityDescription {
-  color: var(--color-text-primary);
+.capabilityName {
+  font-size: 1.25rem;
 }
 
 .capabilityMeta {
@@ -74,9 +60,9 @@
 }
 
 .capabilityMeta dt {
-  font-size: 0.75rem;
+  font-size: var(--text-xs);
   font-weight: 700;
-  letter-spacing: 0.04em;
+  letter-spacing: var(--label-tracking);
   text-transform: uppercase;
   color: var(--color-text-secondary);
 }
@@ -99,7 +85,7 @@
   min-height: var(--target-min);
   padding: 0 var(--space-2);
   border-radius: var(--radius-sm);
-  background: var(--color-cloud);
+  background: var(--color-surface-sunken);
   border: 1px solid var(--color-border);
   font-family: var(--font-mono);
   font-size: 0.8125rem;
@@ -108,6 +94,7 @@
 .matrixLink {
   display: inline-flex;
   align-items: center;
+  gap: var(--space-1);
   min-height: var(--target-min);
   margin-top: auto;
   font-size: 0.9375rem;
@@ -116,19 +103,13 @@
   text-underline-offset: 0.15em;
 }
 
-/* Replacement checklist */
-.checklistBox {
-  max-width: 80ch;
-  padding: var(--space-6);
-  background: var(--tint-amber);
-  border-left: 4px solid var(--stage-learn-tint);
-  border-radius: var(--radius-md);
-}
+@media (hover: hover) and (prefers-reduced-motion: no-preference) {
+  .matrixLink svg {
+    transition: translate var(--transition-fast);
+  }
 
-.checklistBox ul {
-  margin: var(--space-3) 0;
-  padding-left: var(--space-6);
-  display: flex;
-  flex-direction: column;
-  gap: var(--space-2);
+  .capabilityCard:hover .matrixLink svg,
+  .matrixLink:focus-visible svg {
+    translate: 2px 0;
+  }
 }
diff --git a/docs-site/src/pages/concepts/CapabilityContractsPage.tsx b/docs-site/src/pages/concepts/CapabilityContractsPage.tsx
index 326cfb5..ac6aeb0 100644
--- a/docs-site/src/pages/concepts/CapabilityContractsPage.tsx
+++ b/docs-site/src/pages/concepts/CapabilityContractsPage.tsx
@@ -1,11 +1,15 @@
+import { ArrowRight } from 'lucide-react';
 import { Link } from 'react-router-dom';
+import { Card } from '../../components/Card';
 import { PageHeader } from '../../components/PageHeader';
 import { PageMeta } from '../../components/PageMeta';
-import { ConceptsNav } from './ConceptsNav';
-import { SourceLink } from '../../components/SourceLink';
+import { Section } from '../../components/Section';
+import { Sources } from '../../components/Sources';
 import { capabilities } from '../../content/data';
 import { CAPABILITY_CONTRACT_SOURCE, capabilityMatrix } from '../../content/matrix';
 import { PATHS } from '../../paths';
+import { capabilityIcon } from './capabilityIcons';
+import { ConceptsNav } from './ConceptsNav';
 import { PostureLegend, PostureMatrix } from './PostureMatrix';
 import styles from './CapabilityContractsPage.module.css';
 
@@ -34,9 +38,8 @@ export function CapabilityContractsPage() {
       <div className="container">
         <ConceptsNav />
 
-        <section className={styles.section} aria-labelledby="contracts">
-          <h2 id="contracts">Contracts versus implementations</h2>
-          <div className={styles.contractBox}>
+        <Section id="contracts" title="Contracts versus implementations" flush>
+          <Card variant="tinted" tint="blue" padding="lg" className={styles.tintedBox}>
             <p>
               Labels like LLM Gateway, Tool Gateway, agent runtime, memory, identity, registry, policy engine, delivery
               pipeline, and observability describe <strong>architectural capabilities</strong>. A capability contract
@@ -50,64 +53,68 @@ export function CapabilityContractsPage() {
               after the same positive and adversarial, mutation, load, rollback, observability, and teardown obligations
               pass for that implementation.
             </p>
-            <p className={styles.contractSource}>
-              Source: <SourceLink source={CAPABILITY_CONTRACT_SOURCE} />
-            </p>
-          </div>
-        </section>
+            <Sources sources={[CAPABILITY_CONTRACT_SOURCE]} />
+          </Card>
+        </Section>
 
-        <section className={styles.section} aria-labelledby="capabilities">
-          <h2 id="capabilities">The capabilities</h2>
-          <p className={styles.prose}>
-            The root README lists {capabilities.length} capabilities. Each card names the capability, what it does,
-            the reference implementations in this repository, and what a replacement must keep.
-          </p>
+        <Section
+          id="capabilities"
+          title="The capabilities"
+          lead={`The root README lists ${capabilities.length} capabilities. Each card names the capability, what it does, the reference implementations in this repository, and what a replacement must keep.`}
+        >
           <div className={styles.capabilitiesGrid}>
-            {capabilities.map((cap) => (
-              <article key={cap.id} className={styles.capabilityCard} id={`capability-${cap.id}`} data-reveal data-lift>
-                <h3 className={styles.capabilityName}>{cap.name}</h3>
-                <p className={styles.capabilityDescription}>{cap.description}</p>
-                <dl className={styles.capabilityMeta}>
-                  <dt>Reference implementations</dt>
-                  <dd>
-                    <ul className={styles.implTags}>
-                      {cap.implementations.map((impl) => (
-                        <li key={impl} className={styles.implTag}>
-                          {impl}
-                        </li>
-                      ))}
-                    </ul>
-                  </dd>
-                  {cap.contractNote && (
-                    <>
-                      <dt>Contract</dt>
-                      <dd>{cap.contractNote}</dd>
-                    </>
-                  )}
-                </dl>
-                <a href={`#matrix-${cap.id}`} className={styles.matrixLink}>
-                  See {cap.name} by project
-                </a>
-              </article>
-            ))}
+            {capabilities.map((cap) => {
+              const Icon = capabilityIcon(cap.id);
+              return (
+                <Card as="article" key={cap.id} id={`capability-${cap.id}`} interactive reveal className={styles.capabilityCard}>
+                  <div className={styles.capabilityHead}>
+                    <span className={styles.capabilityIcon} aria-hidden="true">
+                      <Icon size={20} />
+                    </span>
+                    <h3 className={styles.capabilityName}>{cap.name}</h3>
+                  </div>
+                  <p>{cap.description}</p>
+                  <dl className={styles.capabilityMeta}>
+                    <dt>Reference implementations</dt>
+                    <dd>
+                      <ul className={styles.implTags}>
+                        {cap.implementations.map((impl) => (
+                          <li key={impl} className={styles.implTag}>
+                            {impl}
+                          </li>
+                        ))}
+                      </ul>
+                    </dd>
+                    {cap.contractNote && (
+                      <>
+                        <dt>Contract</dt>
+                        <dd>{cap.contractNote}</dd>
+                      </>
+                    )}
+                  </dl>
+                  <a href={`#matrix-${cap.id}`} className={styles.matrixLink} data-stretch>
+                    See {cap.name} by project
+                    <ArrowRight size={16} aria-hidden="true" />
+                  </a>
+                </Card>
+              );
+            })}
           </div>
-        </section>
+        </Section>
 
-        <section className={styles.section} aria-labelledby="matrix">
-          <h2 id="matrix">Capability by project</h2>
-          <p className={styles.prose}>
-            The table states how strongly each project delivers each capability in its tested form. Postures are
-            coarse on purpose; the text in each cell carries the nuance and links to the file it comes from.
-          </p>
+        <Section
+          id="matrix"
+          title="Capability by project"
+          lead="The table states how strongly each project delivers each capability in its tested form. Postures are coarse on purpose; the text in each cell carries the nuance and links to the file it comes from."
+        >
           <PostureLegend />
           <PostureMatrix caption="Capability posture by project, with sources" rowHeader="Capability" rows={matrixRows} />
-        </section>
+        </Section>
 
-        <section className={styles.section} aria-labelledby="replacing">
-          <h2 id="replacing">Replacing an implementation</h2>
-          <div className={styles.checklistBox}>
+        <Section id="replacing" title="Replacing an implementation">
+          <Card variant="tinted" tint="amber" padding="lg" className={styles.tintedBox}>
             <p>When replacing a reference implementation with an alternative:</p>
-            <ul>
+            <ul className={styles.checklist}>
               {REPLACEMENT_CHECKLIST.map((item) => (
                 <li key={item}>{item}</li>
               ))}
@@ -116,8 +123,8 @@ export function CapabilityContractsPage() {
               The tested regions, versions and known limitations per project are collected on the{' '}
               <Link to={PATHS.referenceSupportEnvelope}>support envelope</Link> page.
             </p>
-          </div>
-        </section>
+          </Card>
+        </Section>
       </div>
     </div>
   );
diff --git a/docs-site/src/pages/concepts/GlossaryPage.module.css b/docs-site/src/pages/concepts/GlossaryPage.module.css
index 7e252bd..1642d6a 100644
--- a/docs-site/src/pages/concepts/GlossaryPage.module.css
+++ b/docs-site/src/pages/concepts/GlossaryPage.module.css
@@ -7,54 +7,23 @@
 
 .intro {
   max-width: 72ch;
-  margin: var(--space-6) 0 var(--space-6);
+  margin: var(--space-6) 0;
 }
 
-/* Letter navigation */
+/* A rule under the sticky letter rail separates it from the entries scrolling beneath. */
 .letterNav {
-  position: sticky;
-  top: var(--header-height);
-  z-index: 5;
-  margin: 0 calc(-1 * var(--page-padding-x));
-  padding: var(--space-2) var(--page-padding-x);
-  background: var(--color-bg-primary);
   border-bottom: 1px solid var(--color-border);
 }
 
-.letterList {
-  list-style: none;
-  display: flex;
-  flex-wrap: wrap;
-  gap: var(--space-2);
-}
-
-.letterLink {
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  min-width: 2rem;
-  min-height: 2rem;
-  padding: 0 var(--space-2);
-  border: 1px solid var(--color-border);
-  border-radius: var(--radius-sm);
-  background: var(--color-bg-secondary);
-  font-weight: 600;
-  text-decoration: none;
-}
-
-.letterLink:hover {
-  border-color: var(--color-blue);
-  text-decoration: underline;
-}
-
 /* Letter sections */
 .letterSection {
   padding-top: var(--space-8);
+  scroll-margin-top: calc(var(--header-height) + var(--space-4));
 }
 
 .letterHeading {
   padding-bottom: var(--space-2);
-  border-bottom: 2px solid var(--color-midnight);
+  border-bottom: 2px solid var(--color-text-primary);
   margin-bottom: var(--space-4);
 }
 
@@ -66,10 +35,6 @@
 }
 
 .termEntry {
-  padding: var(--space-5);
-  background: var(--color-bg-secondary);
-  border: 1px solid var(--color-border);
-  border-radius: var(--radius-lg);
   /* Keep the term visible below the sticky letter nav and site header when jumped to. */
   scroll-margin-top: calc(var(--header-height) + 4rem);
 }
diff --git a/docs-site/src/pages/concepts/GlossaryPage.tsx b/docs-site/src/pages/concepts/GlossaryPage.tsx
index f296bdc..eeeda35 100644
--- a/docs-site/src/pages/concepts/GlossaryPage.tsx
+++ b/docs-site/src/pages/concepts/GlossaryPage.tsx
@@ -1,12 +1,14 @@
 import { Link } from 'react-router-dom';
+import { Card } from '../../components/Card';
+import { ChipNav } from '../../components/ChipNav';
 import { PageHeader } from '../../components/PageHeader';
 import { PageMeta } from '../../components/PageMeta';
-import { ConceptsNav } from './ConceptsNav';
-import { SourceLink } from '../../components/SourceLink';
+import { SmallSource } from '../../components/Sources';
 import { StageBadge } from '../../components/StageBadge';
 import { getProjectById } from '../../content/data';
 import { glossary, type GlossaryTerm } from '../../content/glossary';
 import { projectPath } from '../../paths';
+import { ConceptsNav } from './ConceptsNav';
 import styles from './GlossaryPage.module.css';
 
 /** First letter (A to Z or 0 to 9) a term sorts under. */
@@ -38,6 +40,7 @@ function groupAlphabetically(terms: readonly GlossaryTerm[]): LetterGroup[] {
 
 const GROUPS = groupAlphabetically(glossary);
 const TERMS_BY_ID = new Map(glossary.map((term) => [term.id, term]));
+const LETTER_ITEMS = GROUPS.map((group) => ({ label: group.letter, href: `#letter-${group.letter}` }));
 
 export function GlossaryPage() {
   return (
@@ -63,17 +66,7 @@ export function GlossaryPage() {
           from.
         </p>
 
-        <nav aria-label="Glossary sections" className={styles.letterNav}>
-          <ul className={styles.letterList}>
-            {GROUPS.map((group) => (
-              <li key={group.letter}>
-                <a href={`#letter-${group.letter}`} className={styles.letterLink}>
-                  {group.letter}
-                </a>
-              </li>
-            ))}
-          </ul>
-        </nav>
+        <ChipNav label="Glossary letters" size="sm" sticky overflow="wrap" items={LETTER_ITEMS} className={styles.letterNav} />
 
         {GROUPS.map((group) => (
           <section key={group.letter} className={styles.letterSection} aria-labelledby={`letter-${group.letter}`}>
@@ -82,7 +75,7 @@ export function GlossaryPage() {
             </h2>
             <dl className={styles.termList}>
               {group.terms.map((term) => (
-                <div key={term.id} className={styles.termEntry}>
+                <Card key={term.id} className={styles.termEntry}>
                   <dt id={term.id} className={styles.term}>
                     {term.term}
                   </dt>
@@ -92,7 +85,7 @@ export function GlossaryPage() {
                       {term.source && (
                         <>
                           {' '}
-                          (<SourceLink source={term.source}>source</SourceLink>)
+                          <SmallSource source={term.source} context={term.term} />
                         </>
                       )}
                     </p>
@@ -110,7 +103,8 @@ export function GlossaryPage() {
                                 </Link>
                               </span>
                               <span className={styles.meaningText}>
-                                {meaning.meaning} (<SourceLink source={meaning.source}>source</SourceLink>)
+                                {meaning.meaning}{' '}
+                                <SmallSource source={meaning.source} context={`${term.term} in ${project.shortName}`} />
                               </span>
                             </li>
                           );
@@ -133,7 +127,7 @@ export function GlossaryPage() {
                       </p>
                     )}
                   </dd>
-                </div>
+                </Card>
               ))}
             </dl>
           </section>
diff --git a/docs-site/src/pages/concepts/PostureMatrix.module.css b/docs-site/src/pages/concepts/PostureMatrix.module.css
index 5c89795..3bc804a 100644
--- a/docs-site/src/pages/concepts/PostureMatrix.module.css
+++ b/docs-site/src/pages/concepts/PostureMatrix.module.css
@@ -1,12 +1,12 @@
-/* PostureMatrix.module.css: capability-by-project and control-by-project tables */
+/* PostureMatrix.module.css: capability-by-project and control-by-project heat-maps */
 
 .scrollHint {
   margin: var(--space-4) 0 calc(-1 * var(--space-2));
-  font-size: 0.875rem;
+  font-size: var(--text-sm);
   color: var(--color-text-secondary);
 }
 
-@media (min-width: 1100px) {
+@media (min-width: 1280px) {
   .scrollHint {
     display: none;
   }
@@ -24,55 +24,106 @@
   caption-side: top;
 }
 
-.rowHeader {
+/* `.table .x` outranks ResponsiveTable's own `.table th` rule for backgrounds. */
+.table .rowHeader {
   position: sticky;
   left: 0;
   z-index: 1;
   min-width: 9rem;
-  background: var(--color-cloud);
+  background: var(--color-surface-sunken);
   font-weight: 600;
   vertical-align: top;
   box-shadow: 1px 0 0 var(--color-border);
+  scroll-margin-top: calc(var(--header-height) + var(--space-4));
 }
 
-.colHeader {
+/* Project columns: a 3 px stage rule on top, the stage icon beside the name. */
+.table .colHeader {
   min-width: 13rem;
   vertical-align: top;
+  border-top: 3px solid var(--stage-tint, var(--color-border));
 }
 
-.colHeader a {
+.colHeader[data-stage='learn'] {
+  --stage-color: var(--stage-learn);
+  --stage-tint: var(--stage-learn-tint);
+}
+
+.colHeader[data-stage='build'] {
+  --stage-color: var(--stage-build);
+  --stage-tint: var(--stage-build-tint);
+}
+
+.colHeader[data-stage='govern'] {
+  --stage-color: var(--stage-govern);
+  --stage-tint: var(--stage-govern-tint);
+}
+
+.colHeader[data-stage='scale'] {
+  --stage-color: var(--stage-scale);
+  --stage-tint: var(--stage-scale-tint);
+}
+
+.colHeaderName {
+  display: flex;
+  align-items: center;
+  gap: var(--space-2);
+}
+
+.colHeaderName a {
   font-weight: 700;
   text-decoration: underline;
   text-underline-offset: 0.15em;
 }
 
+.stageIcon {
+  flex-shrink: 0;
+  color: var(--stage-color);
+}
+
 .stageLabel {
   display: block;
   margin-top: var(--space-1);
-  font-size: 0.75rem;
+  font-size: var(--text-xs);
   font-weight: 700;
-  letter-spacing: 0.04em;
+  letter-spacing: var(--label-tracking);
   text-transform: uppercase;
+  color: var(--stage-color);
 }
 
-.stageLabel[data-stage='learn'] {
-  color: var(--stage-learn);
+/* Heat-map cells: background tint by posture. Body text stays midnight on every tint (AA),
+   and the badge below keeps the icon and label, so colour is never the only cue. */
+.cell {
+  vertical-align: top;
+  background-color: var(--cell-tint, var(--color-surface));
 }
 
-.stageLabel[data-stage='build'] {
-  color: var(--stage-build);
+.cell[data-posture='enforced'] {
+  --cell-tint: var(--tint-green);
 }
 
-.stageLabel[data-stage='govern'] {
-  color: var(--stage-govern);
+.cell[data-posture='advisory'] {
+  --cell-tint: var(--tint-amber);
 }
 
-.stageLabel[data-stage='scale'] {
-  color: var(--stage-scale);
+.cell[data-posture='illustrative'] {
+  --cell-tint: var(--tint-blue);
 }
 
-.cell {
-  vertical-align: top;
+.cell[data-posture='outside-envelope'] {
+  --cell-tint: var(--tint-violet);
+}
+
+.cell[data-posture='not-applicable'] {
+  --cell-tint: var(--color-surface-sunken);
+}
+
+/* Row hover: a translucent overlay layered over the tint (and over the sticky row header). */
+@media (hover: hover) {
+  .row:hover > th,
+  .row:hover > td {
+    background-image: linear-gradient(var(--color-overlay-hover), var(--color-overlay-hover));
+  }
 }
 
 .cellText {
@@ -91,16 +142,19 @@
   text-underline-offset: 0.15em;
 }
 
-/* Posture badges: icon plus text; tinted surfaces with dark heading colours (4.5:1 or better). */
+/* Posture badges: icon plus text on the card surface with a distinct border style per
+   posture, in the tint heading colours (4.5:1 or better on the surface). */
 .badge {
   display: inline-flex;
   align-items: center;
   gap: var(--space-1);
   min-height: var(--target-min);
   padding: 0 var(--space-2);
-  border: 1px solid transparent;
+  border: 1px solid var(--badge-border, var(--color-border));
   border-radius: var(--radius-sm);
-  font-size: 0.75rem;
+  background: var(--color-surface);
+  color: var(--badge-color, var(--color-text-secondary));
+  font-size: var(--text-xs);
   font-weight: 700;
   letter-spacing: 0.02em;
   text-transform: uppercase;
@@ -112,50 +166,39 @@
   flex-shrink: 0;
 }
 
-.enforced {
-  background: var(--tint-green);
-  color: var(--tint-heading-green);
-  border-color: var(--stage-build-tint);
+.badge[data-posture='enforced'] {
+  --badge-color: var(--tint-heading-green);
+  --badge-border: var(--stage-build-tint);
 }
 
-.advisory {
-  background: var(--tint-amber);
-  color: var(--tint-heading-amber);
-  border-color: var(--stage-learn-tint);
+.badge[data-posture='advisory'] {
+  --badge-color: var(--tint-heading-amber);
+  --badge-border: var(--stage-learn-tint);
   border-style: dashed;
 }
 
-.illustrative {
-  background: var(--tint-blue);
-  color: var(--tint-heading-blue);
-  border-color: var(--stage-scale-tint);
+.badge[data-posture='illustrative'] {
+  --badge-color: var(--tint-heading-blue);
+  --badge-border: var(--stage-scale-tint);
   border-style: dotted;
 }
 
-.outsideEnvelope {
-  background: var(--tint-violet);
-  color: var(--tint-heading-violet);
-  border-color: var(--stage-govern-tint);
+.badge[data-posture='outside-envelope'] {
+  --badge-color: var(--tint-heading-violet);
+  --badge-border: var(--stage-govern-tint);
   border-style: double;
 }
 
-.notApplicable {
-  background: var(--color-bg-secondary);
-  color: var(--color-text-secondary);
-  border-color: var(--color-border);
-}
-
 /* Legend */
 .legend {
+  margin: var(--space-4) 0;
+}
+
+.legendList {
   list-style: none;
   display: grid;
   grid-template-columns: repeat(auto-fit, minmax(min(16rem, 100%), 1fr));
   gap: var(--space-3) var(--space-6);
-  margin: var(--space-4) 0;
-  padding: var(--space-4);
-  border: 1px solid var(--color-border);
-  border-radius: var(--radius-md);
-  background: var(--color-bg-secondary);
 }
 
 .legendItem {
@@ -166,6 +209,6 @@
 }
 
 .legendMeaning {
-  font-size: 0.875rem;
+  font-size: var(--text-sm);
   color: var(--color-text-secondary);
 }
diff --git a/docs-site/src/pages/concepts/PostureMatrix.tsx b/docs-site/src/pages/concepts/PostureMatrix.tsx
index 98ce366..f4887ca 100644
--- a/docs-site/src/pages/concepts/PostureMatrix.tsx
+++ b/docs-site/src/pages/concepts/PostureMatrix.tsx
@@ -1,11 +1,13 @@
 import { BookOpen, CircleSlash, Eye, Minus, ShieldCheck } from 'lucide-react';
 import { Link } from 'react-router-dom';
+import { Card } from '../../components/Card';
 import { ResponsiveTable } from '../../components/ResponsiveTable';
 import { SourceLink } from '../../components/SourceLink';
 import { projects, type ProjectId } from '../../content/data';
 import type { Source } from '../../content/facts';
 import { POSTURE_LABELS, type MatrixCell, type Posture } from '../../content/matrix';
 import { projectPath } from '../../paths';
+import { STAGE_ICONS } from '../../stage';
 import styles from './PostureMatrix.module.css';
 
 /**
@@ -47,19 +49,11 @@ const POSTURE_ICONS = {
   'not-applicable': Minus,
 } as const;
 
-const POSTURE_CLASS: Record<Posture, string> = {
-  enforced: styles.enforced,
-  advisory: styles.advisory,
-  illustrative: styles.illustrative,
-  'outside-envelope': styles.outsideEnvelope,
-  'not-applicable': styles.notApplicable,
-};
-
 /** Posture label with an aria-hidden icon. The text is always visible. */
 export function PostureBadge({ posture }: { posture: Posture }) {
   const Icon = POSTURE_ICONS[posture];
   return (
-    <span className={`${styles.badge} ${POSTURE_CLASS[posture]}`}>
+    <span className={styles.badge} data-posture={posture}>
       <Icon size={14} aria-hidden="true" className={styles.badgeIcon} />
       {POSTURE_LABELS[posture].label}
     </span>
@@ -69,66 +63,74 @@ export function PostureBadge({ posture }: { posture: Posture }) {
 /** Legend explaining the five postures. Render once above a matrix. */
 export function PostureLegend() {
   return (
-    <ul className={styles.legend} aria-label="Posture legend">
-      {POSTURE_ORDER.map((posture) => (
-        <li key={posture} className={styles.legendItem}>
-          <PostureBadge posture={posture} />
-          <span className={styles.legendMeaning}>{POSTURE_LABELS[posture].meaning}</span>
-        </li>
-      ))}
-    </ul>
+    <Card padding="sm" className={styles.legend}>
+      <ul className={styles.legendList} aria-label="Posture legend">
+        {POSTURE_ORDER.map((posture) => (
+          <li key={posture} className={styles.legendItem}>
+            <PostureBadge posture={posture} />
+            <span className={styles.legendMeaning}>{POSTURE_LABELS[posture].meaning}</span>
+          </li>
+        ))}
+      </ul>
+    </Card>
   );
 }
 
 /**
- * Capability-by-project or control-by-project table. Every cell shows the
- * posture as text with a distinct icon, a short statement, and a link to the
- * repository file the statement comes from.
+ * Capability-by-project or control-by-project heat-map. Every cell is tinted by
+ * posture and also shows the posture as text with a distinct icon, a short
+ * statement, and a link to the repository file the statement comes from, so
+ * colour is never the only cue. Row-header cells carry `id="matrix-<rowId>"`
+ * so other pages can link to a row.
  */
 export function PostureMatrix({ caption, rowHeader, rows }: PostureMatrixProps) {
   return (
     <>
       <p className={styles.scrollHint}>The table is wider than the screen. Scroll it sideways to see every project.</p>
-      <ResponsiveTable className={styles.table}>
+      <ResponsiveTable className={styles.table} data-posture-matrix>
         <caption className={styles.caption}>{caption}</caption>
-      <thead>
-        <tr>
-          <th scope="col" className={styles.rowHeader}>
-            {rowHeader}
-          </th>
-          {projects.map((project) => (
-            <th scope="col" key={project.id} className={styles.colHeader}>
-              <Link to={projectPath(project.id)}>{project.shortName}</Link>
-              <span className={styles.stageLabel} data-stage={project.stage}>
-                {project.stageLabel}
-              </span>
-            </th>
-          ))}
-        </tr>
-      </thead>
-      <tbody>
-        {rows.map((row) => (
-          <tr key={row.id} id={`matrix-${row.id}`}>
-            <th scope="row" className={styles.rowHeader}>
-              {row.name}
+        <thead>
+          <tr>
+            <th scope="col" className={styles.rowHeader}>
+              {rowHeader}
             </th>
             {projects.map((project) => {
-              const cell = row.cells[project.id];
+              const Icon = STAGE_ICONS[project.stage];
               return (
-                <td key={project.id} className={styles.cell}>
-                  <PostureBadge posture={cell.posture} />
-                  <p className={styles.cellText}>{cell.text}</p>
-                  {cell.source && (
-                    <p className={styles.cellSource}>
-                      <SourceLink source={cell.source}>{sourceLabel(cell.source)}</SourceLink>
-                    </p>
-                  )}
-                </td>
+                <th scope="col" key={project.id} className={styles.colHeader} data-stage={project.stage}>
+                  <span className={styles.colHeaderName}>
+                    <Icon size={18} aria-hidden="true" className={styles.stageIcon} />
+                    <Link to={projectPath(project.id)}>{project.shortName}</Link>
+                  </span>
+                  <span className={styles.stageLabel}>{project.stageLabel}</span>
+                </th>
               );
             })}
           </tr>
-        ))}
-      </tbody>
+        </thead>
+        <tbody>
+          {rows.map((row) => (
+            <tr key={row.id} className={styles.row}>
+              <th scope="row" id={`matrix-${row.id}`} className={styles.rowHeader}>
+                {row.name}
+              </th>
+              {projects.map((project) => {
+                const cell = row.cells[project.id];
+                return (
+                  <td key={project.id} className={styles.cell} data-posture={cell.posture}>
+                    <PostureBadge posture={cell.posture} />
+                    <p className={styles.cellText}>{cell.text}</p>
+                    {cell.source && (
+                      <p className={styles.cellSource}>
+                        <SourceLink source={cell.source}>{sourceLabel(cell.source)}</SourceLink>
+                      </p>
+                    )}
+                  </td>
+                );
+              })}
+            </tr>
+          ))}
+        </tbody>
       </ResponsiveTable>
     </>
   );
diff --git a/docs-site/src/pages/concepts/capabilityIcons.ts b/docs-site/src/pages/concepts/capabilityIcons.ts
new file mode 100644
index 0000000..8b6e1a7
--- /dev/null
+++ b/docs-site/src/pages/concepts/capabilityIcons.ts
@@ -0,0 +1,35 @@
+import {
+  Activity,
+  BookMarked,
+  Brain,
+  Coins,
+  Cpu,
+  KeyRound,
+  Plug,
+  Rocket,
+  Route,
+  Scale,
+  type LucideIcon,
+} from 'lucide-react';
+
+/**
+ * One icon per shared capability (ids from `capabilities` in content/data.ts).
+ * Icons are decorative: render them `aria-hidden` beside the capability name.
+ */
+export const CAPABILITY_ICONS: Record<string, LucideIcon> = {
+  'llm-gateway': Route,
+  'tool-gateway': Plug,
+  runtime: Cpu,
+  memory: Brain,
+  identity: KeyRound,
+  registry: BookMarked,
+  policy: Scale,
+  delivery: Rocket,
+  observability: Activity,
+  cost: Coins,
+};
+
+/** Icon for a capability id; falls back to the registry icon for an unknown id. */
+export function capabilityIcon(id: string): LucideIcon {
+  return CAPABILITY_ICONS[id] ?? BookMarked;
+}
diff --git a/docs-site/src/pages/home/CapabilityStack.module.css b/docs-site/src/pages/home/CapabilityStack.module.css
new file mode 100644
index 0000000..65c52bd
--- /dev/null
+++ b/docs-site/src/pages/home/CapabilityStack.module.css
@@ -0,0 +1,183 @@
+.stack {
+  display: grid;
+  gap: var(--space-5);
+}
+
+/* Legend: dot fills on the left, project order (as stage badges) on the right. */
+.legend {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: center;
+  gap: var(--space-2) var(--space-8);
+  font-size: var(--text-sm);
+  color: var(--color-text-secondary);
+}
+
+.legendList {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: center;
+  gap: var(--space-2) var(--space-4);
+  list-style: none;
+}
+
+.legendItem {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-2);
+  min-height: var(--target-min);
+}
+
+.legendProject {
+  font-weight: 600;
+  color: var(--color-text-primary);
+}
+
+/* Layer panels */
+.layers {
+  list-style: none;
+  display: grid;
+  gap: var(--space-3);
+}
+
+.layer {
+  display: grid;
+  gap: var(--space-2);
+  overflow: hidden;
+}
+
+/* 3 px rule in the four stage tints along the top of each panel. */
+.layer::before {
+  content: '';
+  position: absolute;
+  inset: 0 0 auto 0;
+  height: 3px;
+  background: linear-gradient(
+    90deg,
+    var(--stage-learn-tint),
+    var(--stage-build-tint),
+    var(--stage-govern-tint),
+    var(--stage-scale-tint)
+  );
+}
+
+.layerName {
+  font-size: var(--text-base);
+  font-weight: 700;
+}
+
+.capabilities {
+  list-style: none;
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--space-2);
+}
+
+@media (min-width: 640px) {
+  .layer {
+    grid-template-columns: 11rem minmax(0, 1fr);
+    align-items: center;
+    column-gap: var(--space-4);
+  }
+}
+
+/* Capability chip: icon, name, four dots; the whole chip links to the matrix row. */
+.chip {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-2);
+  min-height: 2.5rem;
+  padding: 0 var(--space-3) 0 var(--space-2);
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-pill);
+  background: var(--color-surface-sunken);
+  color: var(--color-text-primary);
+  font-size: var(--text-sm);
+  font-weight: 600;
+  text-decoration: none;
+  transition:
+    border-color var(--transition-fast),
+    background-color var(--transition-fast),
+    color var(--transition-fast);
+}
+
+.chip:hover {
+  border-color: var(--color-link);
+  color: var(--color-link-hover);
+  text-decoration: none;
+}
+
+.chip:hover .chipName {
+  text-decoration: underline;
+  text-underline-offset: 0.15em;
+}
+
+.chip:focus-visible {
+  outline: var(--focus-ring);
+  outline-offset: 2px;
+}
+
+.chipIcon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 1.75rem;
+  height: 1.75rem;
+  border-radius: var(--radius-pill);
+  background: var(--color-surface);
+  color: var(--color-text-secondary);
+  flex-shrink: 0;
+}
+
+.chipIcon > svg {
+  display: block;
+}
+
+.chipName {
+  white-space: nowrap;
+}
+
+.dots {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  margin-left: var(--space-1);
+}
+
+/* Posture dots: solid = enforced, outline = advisory or illustrative, none = not part of the project. */
+.dot {
+  display: inline-block;
+  width: 10px;
+  height: 10px;
+  border-radius: var(--radius-pill);
+  flex-shrink: 0;
+}
+
+.dot[data-stage='learn'] {
+  --stage-color: var(--stage-learn);
+}
+
+.dot[data-stage='build'] {
+  --stage-color: var(--stage-build);
+}
+
+.dot[data-stage='govern'] {
+  --stage-color: var(--stage-govern);
+}
+
+.dot[data-stage='scale'] {
+  --stage-color: var(--stage-scale);
+}
+
+.dot[data-fill='solid'] {
+  background: var(--stage-color, var(--color-text-secondary));
+  border: 1px solid var(--stage-color, var(--color-text-secondary));
+}
+
+.dot[data-fill='outline'] {
+  border: 2px solid var(--stage-color, var(--color-text-secondary));
+}
+
+.dot[data-fill='none'] {
+  border: 1px solid var(--color-border);
+}
diff --git a/docs-site/src/pages/home/CapabilityStack.test.tsx b/docs-site/src/pages/home/CapabilityStack.test.tsx
new file mode 100644
index 0000000..72511e1
--- /dev/null
+++ b/docs-site/src/pages/home/CapabilityStack.test.tsx
@@ -0,0 +1,71 @@
+import { render, screen } from '@testing-library/react';
+import { MemoryRouter } from 'react-router-dom';
+import { describe, expect, it } from 'vitest';
+import { CAPABILITY_LAYERS, postureSentence } from '../../content/capabilityLayers';
+import { capabilities } from '../../content/data';
+import { CapabilityStack } from './CapabilityStack';
+
+function renderStack() {
+  return render(
+    <MemoryRouter>
+      <CapabilityStack />
+    </MemoryRouter>,
+  );
+}
+
+describe('<CapabilityStack>', () => {
+  it('renders five layer panels with an h3 each and every capability once', () => {
+    renderStack();
+    const stack = document.querySelector('[data-capability-stack]');
+    expect(stack).not.toBeNull();
+    expect(stack?.tagName).toBe('OL');
+    expect(screen.getAllByRole('heading', { level: 3 }).map((heading) => heading.textContent)).toEqual(
+      CAPABILITY_LAYERS.map((layer) => layer.name),
+    );
+    for (const capability of capabilities) {
+      expect(screen.getByRole('link', { name: new RegExp(`^${capability.name}\\b`) })).toBeInTheDocument();
+    }
+  });
+
+  it('draws 40 decorative posture dots and one hidden sentence per capability', () => {
+    renderStack();
+    const stack = document.querySelector('[data-capability-stack]') as HTMLElement;
+    const dots = stack.querySelectorAll('[data-fill]');
+    expect(dots).toHaveLength(40);
+    dots.forEach((dot) => {
+      expect(dot).toHaveAttribute('aria-hidden', 'true');
+      expect(dot.getAttribute('data-stage')).toMatch(/^(learn|build|govern|scale)$/);
+      expect(dot.getAttribute('data-fill')).toMatch(/^(solid|outline|none)$/);
+    });
+    const sentences = stack.querySelectorAll('[data-posture-text]');
+    expect(sentences).toHaveLength(10);
+    sentences.forEach((sentence) => {
+      expect(sentence).toHaveClass('visually-hidden');
+    });
+    // Capabilities with the same postures share a sentence, so compare the full list in order.
+    expect(Array.from(sentences).map((sentence) => sentence.textContent)).toEqual(
+      CAPABILITY_LAYERS.flatMap((layer) => layer.capabilityIds).map((id) => postureSentence(id)),
+    );
+  });
+
+  it('links every capability to its matrix row on the contracts page', () => {
+    renderStack();
+    const stack = document.querySelector('[data-capability-stack]') as HTMLElement;
+    const links = stack.querySelectorAll('a[href*="/concepts/capability-contracts/#matrix-"]');
+    expect(links).toHaveLength(10);
+    const targets = Array.from(links).map((link) => link.getAttribute('href')?.split('#matrix-')[1]);
+    expect([...targets].sort()).toEqual(capabilities.map((capability) => capability.id).sort());
+  });
+
+  it('shows a legend with the three fills and the four stage keys, outside the counted stack', () => {
+    renderStack();
+    const legend = screen.getByRole('list', { name: 'Dot legend' });
+    expect(legend).toHaveTextContent('Enforced');
+    expect(legend).toHaveTextContent('Advisory or illustrative');
+    expect(legend).toHaveTextContent('Not part of the project');
+    const order = screen.getByRole('list', { name: 'Dot order' });
+    expect(order.querySelectorAll('[data-stage]')).toHaveLength(4);
+    expect(order).toHaveTextContent('1. Learn');
+    expect(order).toHaveTextContent('Blueprint');
+  });
+});
diff --git a/docs-site/src/pages/home/CapabilityStack.tsx b/docs-site/src/pages/home/CapabilityStack.tsx
new file mode 100644
index 0000000..8419116
--- /dev/null
+++ b/docs-site/src/pages/home/CapabilityStack.tsx
@@ -0,0 +1,93 @@
+import { Activity, BookMarked, Brain, Coins, Cpu, KeyRound, Plug, Rocket, Route, Scale, type LucideIcon } from 'lucide-react';
+import { Link } from 'react-router-dom';
+import { Card } from '../../components/Card';
+import { StageBadge } from '../../components/StageBadge';
+import { CAPABILITY_LAYERS, postureDots, postureSentence, type DotFill } from '../../content/capabilityLayers';
+import { capabilities, projects } from '../../content/data';
+import { PATHS } from '../../paths';
+import styles from './CapabilityStack.module.css';
+
+/** One lucide icon per capability, always rendered aria-hidden beside the name. */
+const CAPABILITY_ICONS: Record<string, LucideIcon> = {
+  'llm-gateway': Route,
+  'tool-gateway': Plug,
+  runtime: Cpu,
+  memory: Brain,
+  identity: KeyRound,
+  registry: BookMarked,
+  policy: Scale,
+  delivery: Rocket,
+  observability: Activity,
+  cost: Coins,
+};
+
+const FILL_LEGEND: ReadonlyArray<{ fill: DotFill; label: string }> = [
+  { fill: 'solid', label: 'Enforced' },
+  { fill: 'outline', label: 'Advisory or illustrative' },
+  { fill: 'none', label: 'Not part of the project' },
+];
+
+/**
+ * The shared capabilities as a stack of five layers. Each capability is a link to its
+ * row in the capability matrix, with four posture dots (one per project, in stage order)
+ * that are decorative; the visually hidden sentence beside them carries the postures.
+ */
+export function CapabilityStack() {
+  return (
+    <div className={styles.stack}>
+      <div className={styles.legend}>
+        <ul className={styles.legendList} aria-label="Dot legend">
+          {FILL_LEGEND.map(({ fill, label }) => (
+            <li key={fill} className={styles.legendItem}>
+              <span className={styles.dot} data-fill={fill} aria-hidden="true" />
+              {label}
+            </li>
+          ))}
+        </ul>
+        <ul className={styles.legendList} aria-label="Dot order">
+          {projects.map((project) => (
+            <li key={project.id} className={styles.legendItem}>
+              <StageBadge stage={project.stage} variant="outline" label={`${project.stageNumber}. ${project.stageLabel}`} />
+              <span className={styles.legendProject}>{project.shortName}</span>
+            </li>
+          ))}
+        </ul>
+      </div>
+
+      <ol className={styles.layers} data-capability-stack>
+        {CAPABILITY_LAYERS.map((layer) => (
+          <Card as="li" key={layer.id} padding="sm" className={styles.layer}>
+            <h3 className={styles.layerName}>{layer.name}</h3>
+            <ul className={styles.capabilities}>
+              {layer.capabilityIds.map((id) => {
+                const capability = capabilities.find((entry) => entry.id === id);
+                if (!capability) return null;
+                const Icon = CAPABILITY_ICONS[id];
+                return (
+                  <li key={id}>
+                    <Link to={`${PATHS.conceptsCapabilityContracts}#matrix-${id}`} className={styles.chip}>
+                      {Icon && (
+                        <span className={styles.chipIcon} aria-hidden="true">
+                          <Icon size={16} />
+                        </span>
+                      )}
+                      <span className={styles.chipName}>{capability.name}</span>
+                      <span className={styles.dots}>
+                        {postureDots(id).map((dot) => (
+                          <span key={dot.projectId} className={styles.dot} data-fill={dot.fill} data-stage={dot.stage} aria-hidden="true" />
+                        ))}
+                      </span>{' '}
+                      <span className="visually-hidden" data-posture-text>
+                        {postureSentence(id)}
+                      </span>
+                    </Link>
+                  </li>
+                );
+              })}
+            </ul>
+          </Card>
+        ))}
+      </ol>
+    </div>
+  );
+}
diff --git a/docs-site/src/pages/home/HomePage.module.css b/docs-site/src/pages/home/HomePage.module.css
index 77a145b..727b4a2 100644
--- a/docs-site/src/pages/home/HomePage.module.css
+++ b/docs-site/src/pages/home/HomePage.module.css
@@ -2,138 +2,241 @@
   width: 100%;
 }
 
-/* Atlas band: image from 1024 px, typed stage list below */
-.atlas {
-  padding-top: var(--space-4);
+/* Section bands. Dark bands also carry the global `on-dark` class. */
+.band {
+  padding: var(--section-padding-y) 0;
 }
 
-.atlasHeading {
-  margin-bottom: var(--space-3);
+.bandAlt {
+  background: var(--color-surface);
+  border-block: 1px solid var(--color-border);
 }
 
-.atlasImage {
+.bandDark {
+  background: var(--color-band);
+}
+
+/* Hero title accent on "Factory": a gradient in the two outer stage colours where the browser
+   can clip a background to text, otherwise (and for contrast tools, which read `color`) the
+   solid Scale on-dark blue, which passes 4.5:1 on the band. */
+.titleAccent {
+  color: var(--stage-scale-on-dark);
+}
+
+@supports (background-clip: text) or (-webkit-background-clip: text) {
+  .titleAccent {
+    background: linear-gradient(90deg, var(--stage-scale-on-dark), var(--stage-govern-on-dark));
+    -webkit-background-clip: text;
+    background-clip: text;
+    -webkit-text-fill-color: transparent;
+  }
+}
+
+@media (forced-colors: active) {
+  .titleAccent {
+    background: none;
+    -webkit-text-fill-color: currentColor;
+  }
+}
+
+/* Atlas band: desktop only. Below 1024 px the hero journey strip already carries the
+   same four links, so the band would read as a duplicate. */
+.atlas {
   display: none;
+  padding-top: var(--space-8);
+}
+
+.atlasImage {
   width: 100%;
   height: auto;
 }
 
-.stageList {
+@media (min-width: 1024px) {
+  .atlas {
+    display: block;
+  }
+}
+
+/* Project tiles */
+.tileGrid {
   list-style: none;
   display: grid;
+  gap: var(--space-4);
+}
+
+@media (min-width: 640px) {
+  .tileGrid {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+}
+
+@media (min-width: 1024px) {
+  .tileGrid {
+    grid-template-columns: repeat(4, minmax(0, 1fr));
+  }
+}
+
+.tile {
+  display: flex;
+  flex-direction: column;
   gap: var(--space-2);
 }
 
-.atlas .stageLink {
+.tileHead {
   display: flex;
   align-items: center;
-  gap: var(--space-3);
-  min-height: 44px;
-  padding: var(--space-1) var(--space-3);
-  border: 1px solid var(--color-midnight-light);
-  border-radius: var(--radius-md);
-  background: var(--color-midnight-light);
-  color: var(--color-cloud);
-  text-decoration: none;
+  gap: var(--space-2);
 }
 
-.atlas .stageLink:hover {
-  border-color: var(--color-mist);
-  color: var(--color-cloud);
-  text-decoration: none;
+/* Stage icon in a soft disc of the card's accent hue; `--card-accent` and `--stage-color` come from Card. */
+.tileIcon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 2rem;
+  height: 2rem;
+  flex-shrink: 0;
+  border-radius: var(--radius-pill);
+  background: color-mix(in srgb, var(--card-accent, var(--color-border)) 14%, transparent);
+  color: var(--stage-color, var(--color-text-secondary));
 }
 
-.atlas .stageLink:hover strong {
-  text-decoration: underline;
+.tileIcon > svg {
+  display: block;
 }
 
-.stageLink svg {
-  flex-shrink: 0;
+.tileTitle {
+  font-size: var(--text-lg);
+  line-height: 1.3;
 }
 
-.stageText {
-  flex: 1;
-  display: flex;
-  flex-wrap: wrap;
-  align-items: baseline;
-  gap: 0 var(--space-2);
+.tileTitle a {
+  color: var(--color-text-primary);
+  text-decoration: none;
 }
 
-.stageTagline {
-  display: none;
-  color: var(--color-text-inverse-muted);
-  font-size: 0.875rem;
+.tileTitle a:hover {
+  color: var(--color-link-hover);
+  text-decoration: underline;
+  text-underline-offset: 0.15em;
 }
 
-@media (min-width: 640px) {
-  .stageTagline {
-    display: inline;
-  }
+.tileTitle a:focus-visible {
+  outline: var(--focus-ring);
+  outline-offset: 2px;
 }
 
-@media (min-width: 1024px) {
-  .atlas {
-    padding-top: var(--space-8);
-  }
+.tileTagline {
+  font-size: var(--text-sm);
+  color: var(--color-text-secondary);
+}
 
-  .atlasImage {
-    display: block;
-  }
+.tileText {
+  font-size: var(--text-sm);
+  line-height: 1.5;
+}
 
-  .stageList {
-    display: none;
-  }
+.facts {
+  display: grid;
+  gap: var(--space-3);
+  margin-top: var(--space-1);
+  padding-top: var(--space-3);
+  border-top: 1px solid var(--color-border);
 }
 
-/* Personas: plain text blocks, no card chrome */
+/* Personas: five cards, one column, two from 640 px, three plus two from 1024 px */
 .personas {
   list-style: none;
   display: grid;
-  gap: var(--space-2);
+  gap: var(--space-4);
 }
 
 .persona {
-  font-size: 0.875rem;
-  line-height: 1.45;
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-2);
 }
 
-@media (min-width: 640px) {
-  .persona {
-    font-size: 0.9375rem;
-  }
+.personaIcon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 2.5rem;
+  height: 2.5rem;
+  border-radius: var(--radius-md);
+  background: var(--color-surface-sunken);
+  color: var(--color-link);
 }
 
-.persona p {
-  color: var(--color-text-secondary);
+.personaIcon > svg {
+  display: block;
 }
 
 .personaRole {
-  font-size: 1rem;
-  margin-bottom: var(--space-1);
+  font-size: var(--text-lg);
+  line-height: 1.3;
+}
+
+.personaText {
+  flex: 1;
+  font-size: var(--text-sm);
+  line-height: 1.5;
+  color: var(--color-text-secondary);
 }
 
-/* Flows with the sentence so long labels wrap inside narrow columns */
 .personaLink {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-1);
+  min-height: var(--target-min);
+  font-size: var(--text-sm);
   font-weight: 600;
+  color: var(--color-link);
+  text-decoration: none;
+}
+
+.personaLink:hover {
+  color: var(--color-link-hover);
   text-decoration: underline;
   text-underline-offset: 0.15em;
 }
 
-.personaLink svg {
-  vertical-align: middle;
-  margin-left: 2px;
+.personaLink > svg {
+  flex-shrink: 0;
+}
+
+@media (hover: hover) and (prefers-reduced-motion: no-preference) {
+  .personaLink > svg {
+    transition: translate var(--transition-fast);
+  }
+
+  .persona:hover .personaLink > svg,
+  .personaLink:focus-visible > svg {
+    translate: 2px 0;
+  }
 }
 
 @media (min-width: 640px) {
   .personas {
     grid-template-columns: repeat(2, minmax(0, 1fr));
-    gap: var(--space-6) var(--space-8);
   }
 }
 
-@media (min-width: 1100px) {
+@media (min-width: 1024px) {
   .personas {
-    grid-template-columns: repeat(5, minmax(0, 1fr));
-    gap: var(--space-6);
+    grid-template-columns: repeat(6, minmax(0, 1fr));
+  }
+
+  .persona {
+    grid-column: span 2;
+  }
+
+  .persona:nth-child(4) {
+    grid-column: 2 / span 2;
+  }
+
+  .persona:nth-child(5) {
+    grid-column: 4 / span 2;
   }
 }
 
@@ -144,12 +247,12 @@
 
 .notices :global([role='note']) {
   margin: var(--space-3) 0 0;
-  font-size: 0.875rem;
+  font-size: var(--text-sm);
 }
 
 @media (min-width: 640px) {
   .notices :global([role='note']) {
-    font-size: 1rem;
+    font-size: var(--text-base);
   }
 }
 
@@ -178,10 +281,13 @@
   text-align: center;
 }
 
-.closing h2 {
+.closingHeading {
   margin-bottom: var(--space-4);
 }
 
 .closingActions {
+  display: flex;
+  flex-wrap: wrap;
   justify-content: center;
+  gap: var(--space-3);
 }
diff --git a/docs-site/src/pages/home/HomePage.tsx b/docs-site/src/pages/home/HomePage.tsx
index ccf4e9f..d6a346c 100644
--- a/docs-site/src/pages/home/HomePage.tsx
+++ b/docs-site/src/pages/home/HomePage.tsx
@@ -1,17 +1,22 @@
 import { lazy, Suspense, useEffect, useState } from 'react';
 import { Link } from 'react-router-dom';
-import { ArrowRight } from 'lucide-react';
+import { ArrowRight, Bot, Briefcase, Coins, Compass, MapPin, Server, Shield, Timer, type LucideIcon } from 'lucide-react';
+import { Button } from '../../components/Button';
 import { Callout } from '../../components/Callout';
+import { Card } from '../../components/Card';
 import { ExternalLink } from '../../components/ExternalLink';
 import { PageHeader } from '../../components/PageHeader';
 import { PageMeta } from '../../components/PageMeta';
+import { SectionHeading } from '../../components/SectionHeading';
 import { StageBadge } from '../../components/StageBadge';
-import { capabilities, projects } from '../../content/data';
+import { StageJourney } from '../../components/StageJourney';
+import { FactStat } from '../../components/StatTile';
+import { personas, projects, type PersonaIcon } from '../../content/data';
 import { FACT_LABELS, getFacts } from '../../content/facts';
 import { blob, REPO_URL } from '../../content/links';
 import { PATHS, projectPath } from '../../paths';
-import { FactItem } from '../start/shared';
-import shared from '../start/start.module.css';
+import { STAGE_ICONS } from '../../stage';
+import { CapabilityStack } from './CapabilityStack';
 import styles from './HomePage.module.css';
 
 const BASE_URL = import.meta.env.BASE_URL || '/';
@@ -47,45 +52,14 @@ function HeroBackdrop() {
 const ATLAS_ALT =
   'AI Agent Factory Atlas: four complementary projects for enterprise agentic AI on AWS. In the centre sits a hub labelled Agent Factory Capabilities: LLM Gateway, Tool Gateway, Identity and Registry, Policy and Observability. Around it, four stages in order. Learn: Workshop, hands-on platform patterns. Build: Visual Workflow Platform, drag-and-drop agent builder. Govern: MCP Governance Gateway, per-tool-call authorization. Scale: Enterprise Blueprint, multi-account reference blueprint. A legend distinguishes the sequential journey path, a skip-ahead path, and the shared-capability links from each project to the hub. A footer reads: Each project is self-contained. Start anywhere based on your role and goals.';
 
-interface Persona {
-  role: string;
-  text: string;
-  startLabel: string;
-  to: string;
-}
-
-const personas: Persona[] = [
-  {
-    role: 'Platform engineer',
-    text: 'Build the LLM Gateway, registries and Tools Gateway module by module.',
-    startLabel: 'Start with the Workshop',
-    to: projectPath('workshop'),
-  },
-  {
-    role: 'AI/ML engineer',
-    text: 'Ship an agent on Amazon Bedrock AgentCore from a template on a visual canvas.',
-    startLabel: 'Start with Self-Service',
-    to: projectPath('self-service'),
-  },
-  {
-    role: 'Security engineer',
-    text: 'See Cedar ENFORCE, JWT authentication, interceptors and a Guardrail on a live MCP endpoint.',
-    startLabel: 'Start with the MCP Gateway',
-    to: projectPath('mcp-gateway'),
-  },
-  {
-    role: 'Solutions architect',
-    text: 'Compare regions, deploy time, cost and topology before recommending a project.',
-    startLabel: 'Start with the comparison',
-    to: PATHS.whichProject,
-  },
-  {
-    role: 'Engineering director',
-    text: 'Know what each sample is and is not before committing a team.',
-    startLabel: 'Start with the support envelope',
-    to: PATHS.referenceSupportEnvelope,
-  },
-];
+/** Role icons for the persona cards (always rendered aria-hidden beside the role name). */
+const PERSONA_ICONS: Record<PersonaIcon, LucideIcon> = {
+  server: Server,
+  bot: Bot,
+  shield: Shield,
+  compass: Compass,
+  briefcase: Briefcase,
+};
 
 export function HomePage() {
   return (
@@ -97,28 +71,31 @@ export function HomePage() {
       />
 
       <PageHeader
-        title="AI Agent Factory"
+        align="center"
+        title={
+          <>
+            AI Agent <span className={styles.titleAccent}>Factory</span>
+          </>
+        }
         lead="Enterprise samples for building, governing, and operating agentic AI on AWS with Amazon Bedrock and Amazon Bedrock AgentCore."
         backdrop={<HeroBackdrop />}
+        meta={<StageJourney label="Journey stages" />}
         actions={
           <>
-            <Link to={PATHS.whichProject} className={shared.btnPrimary}>
+            <Button to={PATHS.whichProject} iconEnd={<ArrowRight size={18} />}>
               Find your project
-              <ArrowRight size={18} aria-hidden="true" />
-            </Link>
-            <Link to={PATHS.start} className={shared.btnSecondary}>
+            </Button>
+            <Button to={PATHS.start} variant="secondary">
               Get started
-            </Link>
+            </Button>
           </>
         }
       />
 
-      {/* Atlas: image from 1024 px, typed list below */}
-      <section className={`${shared.band} ${shared.bandDark} on-dark ${styles.atlas}`} aria-labelledby="atlas-heading">
+      {/* Atlas: desktop only; the hero journey strip covers narrower screens */}
+      <section className={`${styles.band} ${styles.bandDark} on-dark ${styles.atlas}`} aria-labelledby="atlas-heading">
         <div className="container">
-          <h2 id="atlas-heading" className={styles.atlasHeading}>
-            One journey, four starting points
-          </h2>
+          <SectionHeading id="atlas-heading" eyebrow="Atlas" title="One journey, four starting points" align="center" />
           <img
             className={styles.atlasImage}
             src={`${BASE_URL}repository-atlas-journey.svg`}
@@ -126,57 +103,76 @@ export function HomePage() {
             width="1200"
             height="700"
           />
-          <ol className={styles.stageList}>
-            {projects.map((project) => (
-              <li key={project.id}>
-                <Link to={projectPath(project.id)} className={styles.stageLink}>
-                  <StageBadge stage={project.stage} label={`${project.stageNumber}. ${project.stageLabel}`} />
-                  <span className={styles.stageText}>
-                    <strong>{project.shortName}</strong>
-                    <span className={styles.stageTagline}>{project.tagline}</span>
-                  </span>
-                  <ArrowRight size={18} aria-hidden="true" />
-                </Link>
-              </li>
-            ))}
-          </ol>
         </div>
       </section>
 
       {/* Project tiles: the decision matrix */}
-      <section className={shared.band} aria-labelledby="tiles-heading">
+      <section className={styles.band} aria-labelledby="tiles-heading">
         <div className="container">
-          <div className={shared.sectionHead}>
-            <h2 id="tiles-heading">Pick a project</h2>
-            <p className={shared.lead}>
-              Stage, audience, validated regions, first deploy and cost, every fact linked to its source.{' '}
-              <Link to={PATHS.whichProject}>See the full comparison</Link>.
-            </p>
-          </div>
-          <ul className={`${shared.tileGrid} ${shared.tileGrid4}`}>
+          <SectionHeading
+            id="tiles-heading"
+            eyebrow="Projects"
+            title="Pick a project"
+            align="center"
+            lead={
+              <>
+                Stage, audience, validated regions, first deploy and cost, every fact linked to its source.{' '}
+                <Link to={PATHS.whichProject}>See the full comparison</Link>.
+              </>
+            }
+          />
+          <ul className={styles.tileGrid}>
             {projects.map((project) => {
               const facts = getFacts(project.id);
+              const Icon = STAGE_ICONS[project.stage];
               return (
-                <li key={project.id} className={shared.tile} data-stage={project.stage} data-reveal data-lift>
-                  <div className={shared.tileHead}>
+                <Card
+                  as="li"
+                  key={project.id}
+                  variant="accent"
+                  stage={project.stage}
+                  interactive
+                  reveal
+                  padding="sm"
+                  className={styles.tile}
+                >
+                  <div className={styles.tileHead}>
+                    <span className={styles.tileIcon} aria-hidden="true">
+                      <Icon size={18} />
+                    </span>
                     <StageBadge stage={project.stage} label={`${project.stageNumber}. ${project.stageLabel}`} />
-                    <Link to={projectPath(project.id)} className={shared.tileLink}>
-                      Details
-                      <span className="visually-hidden"> about {project.shortName}</span>
-                      <ArrowRight size={16} aria-hidden="true" />
-                    </Link>
                   </div>
-                  <h3 className={shared.tileTitle}>{project.name}</h3>
-                  <p className={shared.tileTagline}>{project.tagline}</p>
-                  <p className={shared.tileText}>
+                  <h3 className={styles.tileTitle}>
+                    <Link to={projectPath(project.id)}>{project.name}</Link>
+                  </h3>
+                  <p className={styles.tileTagline}>{project.tagline}</p>
+                  <p className={styles.tileText}>
                     <strong>Best for:</strong> {project.bestFor}
                   </p>
-                  <dl className={shared.facts}>
-                    <FactItem label={FACT_LABELS.regions} fact={facts.regions} project={project.shortName} compactNote />
-                    <FactItem label={FACT_LABELS.firstDeploy} fact={facts.firstDeploy} project={project.shortName} compactNote />
-                    <FactItem label={FACT_LABELS.cost} fact={facts.cost} project={project.shortName} compactNote />
+                  <dl className={styles.facts}>
+                    <FactStat
+                      label={FACT_LABELS.regions}
+                      fact={facts.regions}
+                      project={project.shortName}
+                      icon={<MapPin />}
+                      noteMode="collapsed"
+                    />
+                    <FactStat
+                      label={FACT_LABELS.firstDeploy}
+                      fact={facts.firstDeploy}
+                      project={project.shortName}
+                      icon={<Timer />}
+                      noteMode="collapsed"
+                    />
+                    <FactStat
+                      label={FACT_LABELS.cost}
+                      fact={facts.cost}
+                      project={project.shortName}
+                      icon={<Coins />}
+                      noteMode="collapsed"
+                    />
                   </dl>
-                </li>
+                </Card>
               );
             })}
           </ul>
@@ -184,54 +180,49 @@ export function HomePage() {
       </section>
 
       {/* Personas */}
-      <section className={`${shared.band} ${shared.bandAlt}`} aria-labelledby="personas-heading">
+      <section className={`${styles.band} ${styles.bandAlt}`} aria-labelledby="personas-heading">
         <div className="container">
-          <div className={shared.sectionHead}>
-            <h2 id="personas-heading">Who is this for?</h2>
-          </div>
+          <SectionHeading id="personas-heading" eyebrow="Roles" title="Who is this for?" align="center" />
           <ul className={styles.personas}>
-            {personas.map((persona) => (
-              <li key={persona.role} className={styles.persona} data-reveal>
-                <h3 className={styles.personaRole}>{persona.role}</h3>
-                <p>
-                  {persona.text}{' '}
-                  <Link to={persona.to} className={styles.personaLink}>
-                    {persona.startLabel}
-                    <ArrowRight size={14} aria-hidden="true" />
+            {personas.map((persona) => {
+              const Icon = PERSONA_ICONS[persona.icon];
+              return (
+                <Card as="li" key={persona.role} interactive reveal className={styles.persona}>
+                  <span className={styles.personaIcon} aria-hidden="true">
+                    <Icon size={20} />
+                  </span>
+                  <h3 className={styles.personaRole}>{persona.role}</h3>
+                  <p className={styles.personaText}>{persona.text}</p>
+                  <Link to={persona.to} className={styles.personaLink} data-stretch>
+                    {persona.linkLabel}
+                    <ArrowRight size={16} aria-hidden="true" />
                   </Link>
-                </p>
-              </li>
-            ))}
+                </Card>
+              );
+            })}
           </ul>
         </div>
       </section>
 
-      {/* Capability strip */}
-      <section className={shared.band} aria-labelledby="capabilities-heading">
+      {/* Capability stack */}
+      <section className={styles.band} aria-labelledby="capabilities-heading">
         <div className="container">
-          <div className={shared.sectionHead}>
-            <h2 id="capabilities-heading">Shared capabilities</h2>
-            <p className={shared.lead}>
-              Every project draws on the same capability contracts; the implementations are replaceable.
-            </p>
-          </div>
-          <ul className={shared.chips}>
-            {capabilities.slice(0, 6).map((capability) => (
-              <li key={capability.id}>
-                <Link to={PATHS.conceptsCapabilityContracts} className={shared.chip}>
-                  {capability.name}
-                </Link>
-              </li>
-            ))}
-          </ul>
+          <SectionHeading
+            id="capabilities-heading"
+            eyebrow="Capabilities"
+            title="Shared capabilities"
+            align="center"
+            lead="Every project draws on the same capability contracts; the implementations are replaceable."
+          />
+          <CapabilityStack />
         </div>
       </section>
 
       {/* A short pre-deploy notice (the footer carries the disclaimer). A plain div,
           not a labelled section, so the callout is not nested inside a region landmark. */}
-      <div className={`${shared.band} ${shared.bandAlt} ${styles.notices}`}>
+      <div className={`${styles.band} ${styles.bandAlt} ${styles.notices}`}>
         <div className="container">
-          <h2 className={styles.noticesHeading}>Before you deploy</h2>
+          <SectionHeading title="Before you deploy" className={styles.noticesHeading} />
           <div data-reveal>
             <Callout kind="important" title="Real resources, real costs">
               <p>
@@ -256,19 +247,18 @@ export function HomePage() {
 
       {/* Closing call to action */}
       <section
-        className={`${shared.band} ${shared.bandDark} on-dark ${styles.closing}`}
+        className={`${styles.band} ${styles.bandDark} on-dark ${styles.closing}`}
         aria-labelledby="closing-heading"
       >
         <div className="container">
-          <h2 id="closing-heading">Ready to start?</h2>
-          <div className={`${shared.actions} ${styles.closingActions}`}>
-            <Link to={PATHS.start} className={shared.btnPrimary}>
+          <SectionHeading id="closing-heading" title="Ready to start?" align="center" className={styles.closingHeading} />
+          <div className={styles.closingActions}>
+            <Button to={PATHS.start} iconEnd={<ArrowRight size={18} />}>
               Get started
-              <ArrowRight size={18} aria-hidden="true" />
-            </Link>
-            <ExternalLink href={REPO_URL} className={shared.btnSecondary}>
+            </Button>
+            <Button href={REPO_URL} external variant="secondary">
               Source on GitHub
-            </ExternalLink>
+            </Button>
           </div>
         </div>
       </section>
diff --git a/docs-site/src/pages/projects/PoliciesPage.module.css b/docs-site/src/pages/projects/PoliciesPage.module.css
index c99ce1b..86d1888 100644
--- a/docs-site/src/pages/projects/PoliciesPage.module.css
+++ b/docs-site/src/pages/projects/PoliciesPage.module.css
@@ -10,7 +10,78 @@
   padding: var(--space-6) 0 var(--section-padding-y);
 }
 
-.fileHeading code {
+.fileCode {
   font-size: 0.85em;
   padding: 0.125em 0.5em;
 }
+
+/* Summary grid: one card per policy file */
+
+.summaryGrid {
+  list-style: none;
+  display: grid;
+  grid-template-columns: minmax(0, 1fr);
+  gap: var(--space-3);
+}
+
+@media (min-width: 640px) {
+  .summaryGrid {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+}
+
+.summaryCard {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-2);
+}
+
+.summaryHead {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--space-2);
+}
+
+.summaryName {
+  display: inline-flex;
+  align-items: center;
+  min-height: var(--target-min);
+  text-decoration: none;
+}
+
+.summaryName code {
+  font-size: var(--text-sm);
+}
+
+.summaryPurpose {
+  font-size: var(--text-sm);
+  color: var(--color-text-secondary);
+}
+
+/* Deployed / Not deployed pill: icon plus text */
+
+.deployBadge {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-1);
+  min-height: var(--target-min);
+  padding: 0 var(--space-2);
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-pill);
+  background: var(--color-surface-sunken);
+  color: var(--color-text-secondary);
+  font-size: var(--text-xs);
+  font-weight: 700;
+  letter-spacing: var(--label-tracking);
+  text-transform: uppercase;
+  line-height: 1;
+  white-space: nowrap;
+}
+
+.deployBadge[data-deployed] {
+  background: var(--tint-green);
+  border-color: var(--stage-build-tint);
+  color: var(--tint-heading-green);
+}
diff --git a/docs-site/src/pages/projects/PoliciesPage.tsx b/docs-site/src/pages/projects/PoliciesPage.tsx
index 40f8abb..2d26532 100644
--- a/docs-site/src/pages/projects/PoliciesPage.tsx
+++ b/docs-site/src/pages/projects/PoliciesPage.tsx
@@ -1,6 +1,8 @@
-import { Link } from 'react-router-dom';
 import { cedarPolicies } from 'virtual:repo-index';
+import { CircleCheck, CircleMinus } from 'lucide-react';
+import { Button } from '../../components/Button';
 import { Callout } from '../../components/Callout';
+import { Card } from '../../components/Card';
 import { CodeBlock } from '../../components/CodeBlock';
 import { ExternalLink } from '../../components/ExternalLink';
 import { PageHeader } from '../../components/PageHeader';
@@ -12,13 +14,24 @@ import {
   GATEWAY_POLICIES_DIR,
   manifestValidationNote,
   policyPurposeFor,
+  policyPurposes,
 } from '../../content/projects/mcp-gateway-demo';
 import { projectPath } from '../../paths';
-import { Sources } from './sections/shared';
+import { Section, Sources } from './sections/shared';
 import sectionStyles from './sections/ProjectSections.module.css';
-import detailStyles from './ProjectDetailPage.module.css';
 import styles from './PoliciesPage.module.css';
 
+/** Deployed or not deployed, as the manifest lists the file. Icon and text together, never colour alone. */
+function DeployedBadge({ active }: { active: boolean }) {
+  const Icon = active ? CircleCheck : CircleMinus;
+  return (
+    <span className={styles.deployBadge} data-deployed={active ? '' : undefined}>
+      <Icon size={14} aria-hidden="true" />
+      {active ? 'Deployed' : 'Not deployed'}
+    </span>
+  );
+}
+
 export function PoliciesPage() {
   const project = getProjectById('mcp-gateway');
   const active = cedarPolicies.filter((policy) => policyPurposeFor(policy.name)?.active !== false);
@@ -38,12 +51,10 @@ export function PoliciesPage() {
         lead={`The ${cedarPolicies.length} policy files under policies/, rendered from the repository. ${active.length} are deployed by the manifest and ${disabled.length} are kept disabled.`}
         actions={
           <>
-            <Link to={projectPath('mcp-gateway')} className={detailStyles.actionPrimary}>
-              Back to the project page
-            </Link>
-            <ExternalLink href={tree(GATEWAY_POLICIES_DIR)} className={detailStyles.actionSecondary}>
+            <Button to={projectPath('mcp-gateway')}>Back to the project page</Button>
+            <Button href={tree(GATEWAY_POLICIES_DIR)} external variant="secondary">
               policies/ on GitHub
-            </ExternalLink>
+            </Button>
           </>
         }
       />
@@ -61,14 +72,35 @@ export function PoliciesPage() {
             </Callout>
           </div>
 
+          <Section
+            id="summary"
+            title="The policies at a glance"
+            lead="One card per file: its purpose and whether the manifest deploys it. Each card jumps to the full policy below."
+          >
+            <ul className={styles.summaryGrid}>
+              {policyPurposes.map((purpose) => (
+                <Card as="li" key={purpose.name} interactive reveal padding="sm" className={styles.summaryCard}>
+                  <div className={styles.summaryHead}>
+                    <a href={`#${purpose.name}`} className={styles.summaryName} data-stretch>
+                      <code>{purpose.name}.cedar</code>
+                    </a>
+                    <DeployedBadge active={purpose.active} />
+                  </div>
+                  <p className={styles.summaryPurpose}>{purpose.purpose}</p>
+                </Card>
+              ))}
+            </ul>
+          </Section>
+
           {cedarPolicies.map((policy) => {
             const purpose = policyPurposeFor(policy.name);
-            const headingId = `${policy.name}-heading`;
             return (
-              <section key={policy.file} id={policy.name} className={sectionStyles.section} aria-labelledby={headingId}>
-                <h2 id={headingId} className={styles.fileHeading}>
-                  <code>{policy.file}</code>
-                </h2>
+              <Section
+                key={policy.file}
+                id={policy.name}
+                title={<code className={styles.fileCode}>{policy.file}</code>}
+                badge={purpose ? <DeployedBadge active={purpose.active} /> : undefined}
+              >
                 {purpose && (
                   <>
                     <p className={sectionStyles.prose}>{purpose.purpose}</p>
@@ -84,7 +116,7 @@ export function PoliciesPage() {
                 <p>
                   <ExternalLink href={policy.githubUrl}>View {policy.file} on GitHub</ExternalLink>
                 </p>
-              </section>
+              </Section>
             );
           })}
         </div>
diff --git a/docs-site/src/pages/projects/ProjectDetailPage.module.css b/docs-site/src/pages/projects/ProjectDetailPage.module.css
index 88c6526..1c1046a 100644
--- a/docs-site/src/pages/projects/ProjectDetailPage.module.css
+++ b/docs-site/src/pages/projects/ProjectDetailPage.module.css
@@ -10,87 +10,32 @@
   padding-bottom: var(--section-padding-y);
 }
 
-/* Header actions */
-
-.actionPrimary,
-.actionSecondary {
-  display: inline-flex;
-  align-items: center;
-  gap: var(--space-2);
-  min-height: 44px;
-  padding: var(--space-2) var(--space-5);
-  border-radius: var(--radius-md);
-  font-weight: 600;
-  text-decoration: none;
-}
-
-a.actionPrimary,
-:global(.on-dark) a.actionPrimary {
-  background: var(--color-blue);
-  color: #ffffff;
-}
-
-a.actionPrimary:hover,
-:global(.on-dark) a.actionPrimary:hover {
-  background: var(--color-blue-hover);
-  color: #ffffff;
-  text-decoration: underline;
-}
-
-a.actionSecondary {
-  border: 1px solid var(--color-blue);
-  color: var(--color-blue);
-  background: transparent;
-}
-
-:global(.on-dark) a.actionSecondary {
-  border-color: var(--color-cloud);
-  color: var(--color-cloud);
-}
-
-a.actionSecondary:hover,
-:global(.on-dark) a.actionSecondary:hover {
-  text-decoration: underline;
-}
-
-/* Status */
+/* Status: two StatTiles on card surfaces */
 
 .statusList {
   display: grid;
-  grid-template-columns: 1fr;
+  grid-template-columns: minmax(0, 1fr);
   gap: var(--space-3);
   margin-bottom: var(--space-4);
 }
 
 @media (min-width: 640px) {
   .statusList {
-    grid-template-columns: repeat(2, 1fr);
+    grid-template-columns: repeat(2, minmax(0, 1fr));
   }
 }
 
 .statusItem {
   padding: var(--space-4);
-  background: var(--color-bg-secondary);
+  background: var(--color-surface);
   border: 1px solid var(--color-border);
-  border-radius: var(--radius-md);
-}
-
-.statusItem dt {
-  margin-bottom: var(--space-1);
-  font-size: 0.75rem;
-  font-weight: 600;
-  letter-spacing: 0.05em;
-  text-transform: uppercase;
-  color: var(--color-text-secondary);
-}
-
-.statusItem dd {
-  margin: 0;
+  border-radius: var(--radius-lg);
+  box-shadow: var(--shadow-card);
 }
 
 .note {
   color: var(--color-text-secondary);
-  font-size: 0.875rem;
+  font-size: var(--text-sm);
 }
 
 /* Quickstart */
@@ -101,36 +46,13 @@ a.actionSecondary:hover,
   border-top: 1px dashed var(--color-border);
 }
 
-.steps {
-  padding-left: var(--space-6);
-  margin-top: var(--space-4);
-}
-
-.steps > li {
-  margin-bottom: var(--space-5);
-}
-
-.steps > li > p + p {
-  margin-top: var(--space-2);
-}
-
-.stepTitle {
-  font-weight: 600;
-}
-
-/* Limitations and docs */
+/* Limitations, validated items and docs */
 
-.limitations {
+.cardList {
   list-style: none;
-}
-
-.limitations > li {
-  padding: var(--space-3) 0;
-  border-bottom: 1px solid var(--color-border);
-}
-
-.limitations > li:last-child {
-  border-bottom: 0;
+  display: grid;
+  gap: var(--space-3);
+  margin: var(--space-4) 0;
 }
 
 .docList {
@@ -156,43 +78,34 @@ a.actionSecondary:hover,
 .othersList {
   list-style: none;
   display: grid;
-  grid-template-columns: 1fr;
+  grid-template-columns: minmax(0, 1fr);
   gap: var(--space-3);
 }
 
 @media (min-width: 640px) {
   .othersList {
-    grid-template-columns: repeat(3, 1fr);
+    grid-template-columns: repeat(3, minmax(0, 1fr));
   }
 }
 
-.otherLink {
+.otherCard {
   display: flex;
   flex-direction: column;
   align-items: flex-start;
   gap: var(--space-2);
-  height: 100%;
-  padding: var(--space-4);
-  background: var(--color-bg-secondary);
-  border: 1px solid var(--color-border);
-  border-radius: var(--radius-md);
-  color: var(--color-text-primary);
-  text-decoration: none;
-}
-
-.otherLink:hover {
-  border-color: var(--color-blue);
-  color: var(--color-text-primary);
-  text-decoration: none;
 }
 
 .otherName {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-1);
+  min-height: var(--target-min);
   font-weight: 600;
-  color: var(--color-blue);
+  color: var(--color-link);
 }
 
-.otherLink:hover .otherName {
-  color: var(--color-blue-hover);
+.otherCard:hover .otherName {
+  color: var(--color-link-hover);
   text-decoration: underline;
 }
 
@@ -201,57 +114,20 @@ a.actionSecondary:hover,
   color: var(--color-text-secondary);
 }
 
-/* Forced-colors mode draws borders but not backgrounds; give the filled button an outline to keep. */
-a.actionPrimary {
-  border: 1px solid transparent;
-}
-
-/* Hero fact rows on the dark band. Hidden below 640px so a phone hero fits in about one viewport;
+/* Hero fact tiles on the dark band. Hidden below 640px so a phone hero fits in about one viewport;
    the same facts are repeated with sources in the "At a glance" table further down the page. */
 
 .heroFacts {
   display: none;
-  gap: var(--space-2);
-  margin: 0;
-}
-
-.heroFact {
-  display: grid;
-  gap: var(--space-1) var(--space-3);
+  gap: var(--space-3) var(--space-6);
   margin: 0;
 }
 
 @media (min-width: 640px) {
   .heroFacts {
     display: grid;
+    grid-template-columns: repeat(3, minmax(0, 1fr));
   }
-
-  .heroFact {
-    grid-template-columns: minmax(11rem, max-content) 1fr;
-  }
-}
-
-.heroFactLabel {
-  font-size: 0.75rem;
-  font-weight: 600;
-  letter-spacing: 0.05em;
-  text-transform: uppercase;
-  color: var(--color-cloud);
-  align-self: baseline;
-}
-
-.heroFactValue {
-  margin: 0;
-  color: var(--color-text-inverse);
-}
-
-.heroFactValue em {
-  color: var(--color-cloud);
-}
-
-.heroSource {
-  font-size: 0.8125rem;
-  white-space: nowrap;
 }
 
 .validated {
diff --git a/docs-site/src/pages/projects/ProjectDetailPage.tsx b/docs-site/src/pages/projects/ProjectDetailPage.tsx
index 50ca6ce..c6f703b 100644
--- a/docs-site/src/pages/projects/ProjectDetailPage.tsx
+++ b/docs-site/src/pages/projects/ProjectDetailPage.tsx
@@ -1,11 +1,16 @@
 import { Link, useParams } from 'react-router-dom';
+import { ArrowRight } from 'lucide-react';
+import { Button } from '../../components/Button';
+import { Card } from '../../components/Card';
 import { CodeBlock } from '../../components/CodeBlock';
 import { ExternalLink } from '../../components/ExternalLink';
 import { FactsTable } from '../../components/FactsTable';
+import { NumberedSteps } from '../../components/NumberedSteps';
 import { PageHeader } from '../../components/PageHeader';
 import { PageMeta } from '../../components/PageMeta';
 import { SourceLink } from '../../components/SourceLink';
 import { StageBadge } from '../../components/StageBadge';
+import { FactStat } from '../../components/StatTile';
 import { getProjectById, projects, type ProjectId } from '../../content/data';
 import { docsForProject } from '../../content/docs';
 import {
@@ -30,14 +35,16 @@ import { getQuickstarts, type QuickstartStep } from '../../content/quickstarts';
 import { docLabel, docTitle } from '../../docs/docModules';
 import { PATHS, projectPath } from '../../paths';
 import { NotFoundPage } from '../NotFoundPage';
+import { factIcon } from '../start/factIcons';
 import { EvidenceSection, WhatItIsSection } from './sections/CommonSections';
 import { getProjectExtras } from './sections/projectExtras';
 import { InlineMarkdown, Section, Sources } from './sections/shared';
 import styles from './ProjectDetailPage.module.css';
 
-/** Facts shown as rows in the page header, built from the same objects as the At a glance table. */
+/** Facts shown as tiles in the page header, built from the same objects as the At a glance table. */
 const HERO_FACT_KEYS: ReadonlyArray<keyof ProjectFacts> = ['firstDeploy', 'regions', 'iac'];
 
+/** A fact in running text: value, default-labelled source link and note. */
 function FactValue({ fact }: { fact: Fact }) {
   return (
     <>
@@ -53,40 +60,32 @@ function FactValue({ fact }: { fact: Fact }) {
   );
 }
 
-function HeroFacts({ projectFacts }: { projectFacts: ProjectFacts }) {
+/* Hidden below 640px so a phone hero fits in about one viewport; the same facts are repeated
+   with sources in the "At a glance" table further down the page. */
+function HeroFacts({ projectFacts, project }: { projectFacts: ProjectFacts; project: string }) {
   return (
     <dl className={styles.heroFacts}>
-      {HERO_FACT_KEYS.map((key) => {
-        const fact = projectFacts[key];
-        const label = FACT_LABELS[key];
-        return (
-          <div key={key} className={styles.heroFact}>
-            <dt className={styles.heroFactLabel}>{label}</dt>
-            <dd className={styles.heroFactValue}>
-              {fact.notDocumented ? <em>{factText(fact)}</em> : fact.value}
-              {fact.source && (
-                <>
-                  {' '}
-                  <SourceLink source={fact.source} className={styles.heroSource}>
-                    source<span className="visually-hidden"> for {label.toLowerCase()}</span>
-                  </SourceLink>
-                </>
-              )}
-            </dd>
-          </div>
-        );
-      })}
+      {HERO_FACT_KEYS.map((key) => (
+        <FactStat
+          key={key}
+          label={FACT_LABELS[key]}
+          fact={projectFacts[key]}
+          project={project}
+          icon={factIcon(key)}
+          layout="stacked"
+          noteMode="collapsed"
+        />
+      ))}
     </dl>
   );
 }
 
-function StepBody({ step }: { step: QuickstartStep }) {
+function StepItem({ step }: { step: QuickstartStep }) {
   const linkIsTitle = step.href !== undefined && (step.hrefLabel ?? step.href) === step.title;
   return (
-    <>
-      <p className={styles.stepTitle}>
-        {linkIsTitle && step.href ? <ExternalLink href={step.href}>{step.title}</ExternalLink> : step.title}
-      </p>
+    <NumberedSteps.Item
+      title={linkIsTitle && step.href ? <ExternalLink href={step.href}>{step.title}</ExternalLink> : step.title}
+    >
       {step.command && <CodeBlock code={step.command} language="bash" />}
       {step.note && <p>{step.note}</p>}
       {step.href && !linkIsTitle && (
@@ -95,7 +94,7 @@ function StepBody({ step }: { step: QuickstartStep }) {
         </p>
       )}
       <Sources sources={[step.source]} />
-    </>
+    </NumberedSteps.Item>
   );
 }
 
@@ -122,21 +121,21 @@ export function ProjectDetailPage() {
   const actions = (
     <>
       {isWorkshop && (
-        <ExternalLink href={WORKSHOP_URL} className={styles.actionPrimary}>
+        <Button href={WORKSHOP_URL} external variant="primary">
           {WORKSHOP_LINK_LABEL}
-        </ExternalLink>
+        </Button>
       )}
-      <a href="#quickstart" className={isWorkshop ? styles.actionSecondary : styles.actionPrimary}>
+      <Button href="#quickstart" variant={isWorkshop ? 'secondary' : 'primary'}>
         Quickstart
-      </a>
+      </Button>
       {isWorkshop && (
-        <ExternalLink href={WORKSHOPS_DISCOVER_URL} className={styles.actionSecondary}>
+        <Button href={WORKSHOPS_DISCOVER_URL} external variant="secondary">
           {WORKSHOPS_DISCOVER_LABEL}
-        </ExternalLink>
+        </Button>
       )}
-      <ExternalLink href={tree(project.folder)} className={styles.actionSecondary}>
+      <Button href={tree(project.folder)} external variant="secondary">
         Source on GitHub
-      </ExternalLink>
+      </Button>
     </>
   );
 
@@ -149,7 +148,7 @@ export function ProjectDetailPage() {
         stageLabel={project.stageLabel}
         title={project.name}
         lead={project.description}
-        meta={<HeroFacts projectFacts={projectFacts} />}
+        meta={<HeroFacts projectFacts={projectFacts} project={project.shortName} />}
         actions={actions}
         figure={extras.hero}
       />
@@ -160,18 +159,19 @@ export function ProjectDetailPage() {
 
           <Section id="status" title="Status">
             <dl className={styles.statusList}>
-              <div className={styles.statusItem}>
-                <dt>{FACT_LABELS.version}</dt>
-                <dd>
-                  <FactValue fact={projectFacts.version} />
-                </dd>
-              </div>
-              <div className={styles.statusItem}>
-                <dt>{FACT_LABELS.status}</dt>
-                <dd>
-                  <FactValue fact={projectFacts.status} />
-                </dd>
-              </div>
+              <FactStat
+                className={styles.statusItem}
+                label={FACT_LABELS.version}
+                fact={projectFacts.version}
+                project={project.shortName}
+              />
+              <FactStat
+                className={styles.statusItem}
+                label={FACT_LABELS.status}
+                fact={projectFacts.status}
+                project={project.shortName}
+                icon={factIcon('status')}
+              />
             </dl>
             <p>
               <ExternalLink href={commitsUrl}>Recent changes: commit history for {project.folder} on GitHub</ExternalLink>
@@ -200,13 +200,11 @@ export function ProjectDetailPage() {
                 <p>
                   <strong>Expected time:</strong> <FactValue fact={quickstart.expectedTime} />
                 </p>
-                <ol className={styles.steps}>
+                <NumberedSteps stage={project.stage} connector>
                   {quickstart.steps.map((step) => (
-                    <li key={step.title}>
-                      <StepBody step={step} />
-                    </li>
+                    <StepItem key={step.title} step={step} />
                   ))}
-                </ol>
+                </NumberedSteps>
               </div>
             ))}
           </Section>
@@ -222,9 +220,9 @@ export function ProjectDetailPage() {
 
           <Section id="limitations" title="Known limitations and support envelope">
             <p className={styles.note}>Each item is copied from the project README or docs without paraphrase.</p>
-            <ul className={styles.limitations}>
+            <ul className={styles.cardList}>
               {projectLimitations.map((limitation) => (
-                <li key={limitation.id}>
+                <Card as="li" key={limitation.id} reveal padding="sm">
                   {limitation.title && (
                     <strong>
                       <InlineMarkdown text={limitation.title} />
@@ -232,7 +230,7 @@ export function ProjectDetailPage() {
                     </strong>
                   )}
                   <InlineMarkdown text={limitation.text} /> <SourceLink source={limitation.source} />
-                </li>
+                </Card>
               ))}
             </ul>
             <p>
@@ -245,11 +243,11 @@ export function ProjectDetailPage() {
               <div className={styles.validated}>
                 <h3>Live-validated reference envelope</h3>
                 <p className={styles.note}>Each item is copied from the README without paraphrase and links its source.</p>
-                <ul className={styles.limitations}>
+                <ul className={styles.cardList}>
                   {projectValidated.map((item) => (
-                    <li key={item.id}>
+                    <Card as="li" key={item.id} reveal padding="sm">
                       <InlineMarkdown text={item.text} /> <SourceLink source={item.source} />
-                    </li>
+                    </Card>
                   ))}
                 </ul>
               </div>
@@ -296,13 +294,14 @@ export function ProjectDetailPage() {
             <h2 id="other-projects-heading">Other projects</h2>
             <ul className={styles.othersList}>
               {otherProjects.map((other) => (
-                <li key={other.id}>
-                  <Link to={projectPath(other.id)} className={styles.otherLink}>
-                    <StageBadge stage={other.stage} label={other.stageLabel} variant="outline" />
-                    <span className={styles.otherName}>{other.shortName}</span>
-                    <span className={styles.otherTagline}>{other.tagline}</span>
+                <Card as="li" key={other.id} interactive className={styles.otherCard}>
+                  <StageBadge stage={other.stage} label={other.stageLabel} variant="outline" />
+                  <Link to={projectPath(other.id)} className={styles.otherName} data-stretch>
+                    {other.shortName}
+                    <ArrowRight size={16} aria-hidden="true" />
                   </Link>
-                </li>
+                  <span className={styles.otherTagline}>{other.tagline}</span>
+                </Card>
               ))}
             </ul>
           </nav>
diff --git a/docs-site/src/pages/projects/ProjectsPage.module.css b/docs-site/src/pages/projects/ProjectsPage.module.css
index caf0731..5fa2b1e 100644
--- a/docs-site/src/pages/projects/ProjectsPage.module.css
+++ b/docs-site/src/pages/projects/ProjectsPage.module.css
@@ -4,45 +4,43 @@
   width: 100%;
 }
 
+.body {
+  padding: var(--space-8) var(--page-padding-x) var(--section-padding-y);
+}
+
 .grid {
   list-style: none;
   display: grid;
-  grid-template-columns: 1fr;
+  grid-template-columns: minmax(0, 1fr);
   gap: var(--space-6);
 }
 
-@media (min-width: 900px) {
+@media (min-width: 1024px) {
   .grid {
-    grid-template-columns: repeat(2, 1fr);
+    grid-template-columns: repeat(2, minmax(0, 1fr));
   }
 }
 
-.card {
-  --card-stage: var(--color-border);
+/* Inner layout of one directory card; the box itself comes from Card. */
+.projectCard {
   display: flex;
   flex-direction: column;
   gap: var(--space-3);
-  padding: var(--space-6);
-  background: var(--color-bg-secondary);
-  border: 1px solid var(--color-border);
-  border-top: 4px solid var(--card-stage);
-  border-radius: var(--radius-lg);
-}
-
-.card[data-stage='learn'] {
-  --card-stage: var(--stage-learn-tint);
 }
 
-.card[data-stage='build'] {
-  --card-stage: var(--stage-build-tint);
+.head {
+  display: flex;
+  align-items: center;
+  gap: var(--space-3);
 }
 
-.card[data-stage='govern'] {
-  --card-stage: var(--stage-govern-tint);
+.stageIcon {
+  display: inline-flex;
+  color: var(--stage-color, var(--color-text-secondary));
 }
 
-.card[data-stage='scale'] {
-  --card-stage: var(--stage-scale-tint);
+.stageIcon > svg {
+  display: block;
 }
 
 .cardTitle {
@@ -54,33 +52,18 @@
   color: var(--color-text-secondary);
 }
 
-.facts {
+/* Three facts as StatTiles on a sunken strip */
+.factList {
   display: grid;
-  grid-template-columns: 1fr;
-  gap: var(--space-2);
+  grid-template-columns: minmax(0, 1fr);
+  gap: var(--space-3);
   margin: 0;
-}
-
-.facts > div {
-  padding: var(--space-2) var(--space-3);
-  background: var(--color-cloud);
+  padding: var(--space-3) var(--space-4);
+  background: var(--color-surface-sunken);
   border: 1px solid var(--color-border);
   border-radius: var(--radius-md);
 }
 
-.facts dt {
-  font-size: 0.75rem;
-  font-weight: 600;
-  letter-spacing: 0.05em;
-  text-transform: uppercase;
-  color: var(--color-text-secondary);
-}
-
-.facts dd {
-  margin: 0;
-  font-size: 0.9375rem;
-}
-
 .actions {
   display: flex;
   flex-wrap: wrap;
@@ -89,38 +72,6 @@
   padding-top: var(--space-3);
 }
 
-.primary,
-.secondary {
-  display: inline-flex;
-  align-items: center;
-  gap: var(--space-2);
-  min-height: 44px;
-  padding: var(--space-2) var(--space-4);
-  border-radius: var(--radius-md);
-  font-weight: 600;
-  text-decoration: none;
-}
-
-a.primary {
-  background: var(--color-blue);
-  color: #ffffff;
-}
-
-a.primary:hover {
-  background: var(--color-blue-hover);
-  color: #ffffff;
-  text-decoration: underline;
-}
-
-a.secondary {
-  border: 1px solid var(--color-blue);
-  color: var(--color-blue);
-}
-
-a.secondary:hover {
-  text-decoration: underline;
-}
-
 .compare {
   margin-top: var(--space-8);
 }
diff --git a/docs-site/src/pages/projects/ProjectsPage.tsx b/docs-site/src/pages/projects/ProjectsPage.tsx
index c245e17..37b82b1 100644
--- a/docs-site/src/pages/projects/ProjectsPage.tsx
+++ b/docs-site/src/pages/projects/ProjectsPage.tsx
@@ -1,13 +1,18 @@
 import { Link } from 'react-router-dom';
-import { ExternalLink } from '../../components/ExternalLink';
+import { ArrowRight } from 'lucide-react';
+import { Button } from '../../components/Button';
+import { Card } from '../../components/Card';
 import { PageHeader } from '../../components/PageHeader';
 import { PageMeta } from '../../components/PageMeta';
 import { StageBadge } from '../../components/StageBadge';
+import { StageJourney } from '../../components/StageJourney';
+import { FactStat } from '../../components/StatTile';
 import { projects } from '../../content/data';
 import { FACT_LABELS, getFacts, type ProjectFacts } from '../../content/facts';
 import { tree } from '../../content/links';
 import { PATHS, projectPath } from '../../paths';
-import { FactItem } from '../start/shared';
+import { STAGE_ICONS } from '../../stage';
+import { factIcon } from '../start/factIcons';
 import styles from './ProjectsPage.module.css';
 
 /** Facts shown on each directory card, each with its source link. */
@@ -24,34 +29,57 @@ export function ProjectsPage() {
         eyebrow="Directory"
         title="Projects"
         lead="Four projects, one per stage. Each card links to the project page on this site and to its source folder on GitHub."
+        meta={<StageJourney label="Journey stages" size="sm" />}
       />
 
-      <div className="container page-section">
+      <div className={`container ${styles.body}`}>
         <ul className={styles.grid}>
           {projects.map((project) => {
             const projectFacts = getFacts(project.id);
+            const Icon = STAGE_ICONS[project.stage];
             return (
-              <li key={project.id} className={styles.card} data-stage={project.stage} data-reveal data-lift>
-                <StageBadge stage={project.stage} label={`${project.stageNumber}. ${project.stageLabel}`} />
+              <Card
+                as="li"
+                key={project.id}
+                variant="accent"
+                stage={project.stage}
+                interactive
+                reveal
+                padding="lg"
+                className={styles.projectCard}
+              >
+                <div className={styles.head}>
+                  <span className={styles.stageIcon} aria-hidden="true">
+                    <Icon size={20} />
+                  </span>
+                  <StageBadge stage={project.stage} label={`${project.stageNumber}. ${project.stageLabel}`} />
+                </div>
                 <h2 className={styles.cardTitle}>{project.name}</h2>
                 <p className={styles.tagline}>{project.tagline}</p>
                 <p>
                   <strong>Best for:</strong> {project.bestFor}
                 </p>
-                <dl className={styles.facts}>
+                <dl className={styles.factList}>
                   {CHIP_KEYS.map((key) => (
-                    <FactItem key={key} label={FACT_LABELS[key]} fact={projectFacts[key]} />
+                    <FactStat
+                      key={key}
+                      label={FACT_LABELS[key]}
+                      fact={projectFacts[key]}
+                      project={project.shortName}
+                      icon={factIcon(key)}
+                      noteMode="collapsed"
+                    />
                   ))}
                 </dl>
                 <div className={styles.actions}>
-                  <Link to={projectPath(project.id)} className={styles.primary}>
+                  <Button to={projectPath(project.id)} iconEnd={<ArrowRight size={16} />}>
                     {project.shortName} project page
-                  </Link>
-                  <ExternalLink href={tree(project.folder)} className={styles.secondary}>
+                  </Button>
+                  <Button href={tree(project.folder)} external variant="secondary">
                     Source on GitHub
-                  </ExternalLink>
+                  </Button>
                 </div>
-              </li>
+              </Card>
             );
           })}
         </ul>
diff --git a/docs-site/src/pages/projects/sections/BlueprintSections.tsx b/docs-site/src/pages/projects/sections/BlueprintSections.tsx
index 2f6bc73..67c4da0 100644
--- a/docs-site/src/pages/projects/sections/BlueprintSections.tsx
+++ b/docs-site/src/pages/projects/sections/BlueprintSections.tsx
@@ -1,8 +1,10 @@
 import servicesSvg from '../../../../../enterprise-agentic-ai-platform-blueprint/assets/enterprise-agent-factory-aws-services.svg';
 import conceptSvg from '../../../../../enterprise-agentic-ai-platform-blueprint/assets/enterprise-agent-factory-concept.svg';
+import { Card } from '../../../components/Card';
 import { DocImage } from '../../../components/DocImage';
 import { ExternalLink } from '../../../components/ExternalLink';
 import { Figure } from '../../../components/Figure';
+import { NumberedSteps } from '../../../components/NumberedSteps';
 import { ResponsiveTable } from '../../../components/ResponsiveTable';
 import { SourceLink } from '../../../components/SourceLink';
 import { blueprintScps } from '../../../content/facts';
@@ -44,14 +46,19 @@ export function BlueprintSections() {
           The Blueprint ships {blueprintScps.length} service control policies as TypeScript definitions. Each entry
           links to its source file.
         </p>
-        <ol className={styles.list}>
+        <NumberedSteps stage="scale" dense>
           {blueprintScps.map((scp) => (
-            <li key={scp.id}>
-              <code>{scp.id}</code> {scp.title}:{' '}
-              <SourceLink source={{ file: scp.file }}>{scp.file.split('/').pop()}</SourceLink>
-            </li>
+            <NumberedSteps.Item
+              key={scp.id}
+              title={
+                <span className={styles.stepText}>
+                  <code>{scp.id}</code> {scp.title}:{' '}
+                  <SourceLink source={{ file: scp.file }}>{scp.file.split('/').pop()}</SourceLink>
+                </span>
+              }
+            />
           ))}
-        </ol>
+        </NumberedSteps>
       </Section>
 
       <Section id="golden-paths" title="Golden paths">
@@ -93,7 +100,7 @@ export function BlueprintSections() {
         </p>
         <div className={styles.groups}>
           {packageGroups.map((group) => (
-            <div key={group.id} className={styles.group}>
+            <Card key={group.id} padding="sm" className={styles.group}>
               <h3>{group.name}</h3>
               <ul>
                 {group.packages.map((name) => (
@@ -102,7 +109,7 @@ export function BlueprintSections() {
                   </li>
                 ))}
               </ul>
-            </div>
+            </Card>
           ))}
         </div>
       </Section>
diff --git a/docs-site/src/pages/projects/sections/CommonSections.tsx b/docs-site/src/pages/projects/sections/CommonSections.tsx
index 231f4b3..74b9dc3 100644
--- a/docs-site/src/pages/projects/sections/CommonSections.tsx
+++ b/docs-site/src/pages/projects/sections/CommonSections.tsx
@@ -1,5 +1,6 @@
 import type { ReactNode } from 'react';
 import { Callout } from '../../../components/Callout';
+import { Card } from '../../../components/Card';
 import { CodeBlock } from '../../../components/CodeBlock';
 import type { ProjectId } from '../../../content/data';
 import { githubUrl } from '../../../content/facts';
@@ -52,7 +53,7 @@ export function EvidenceSection({ projectId, children }: { projectId: ProjectId;
       </Callout>
       {children}
       {data.items.map((item) => (
-        <div key={item.id} className={styles.evidenceItem} data-reveal>
+        <Card key={item.id} reveal className={styles.evidenceItem}>
           <h3>{item.what}</h3>
           {item.command && <CodeBlock code={item.command} language="bash" />}
           <p className={styles.prose}>
@@ -66,7 +67,7 @@ export function EvidenceSection({ projectId, children }: { projectId: ProjectId;
             </ol>
           )}
           <Sources sources={item.sources} />
-        </div>
+        </Card>
       ))}
     </Section>
   );
diff --git a/docs-site/src/pages/projects/sections/ProjectSections.module.css b/docs-site/src/pages/projects/sections/ProjectSections.module.css
index ab89026..4e6fe72 100644
--- a/docs-site/src/pages/projects/sections/ProjectSections.module.css
+++ b/docs-site/src/pages/projects/sections/ProjectSections.module.css
@@ -1,43 +1,10 @@
-/* Shared styles for the per-project sections and the policies page. */
-
-.section {
-  padding: var(--space-8) 0;
-  border-top: 1px solid var(--color-border);
-  /* In-page links (for example the hero's Quickstart action) land below the sticky header. */
-  scroll-margin-top: calc(var(--header-height) + var(--space-4));
-}
-
-.section:first-child {
-  border-top: 0;
-  padding-top: var(--space-4);
-}
-
-.section h2 {
-  margin-bottom: var(--space-4);
-}
-
-.section h3 {
-  margin: var(--space-6) 0 var(--space-3);
-}
-
-.section p + p,
-.section p + ul,
-.section p + ol,
-.section ul + p,
-.section ol + p {
-  margin-top: var(--space-3);
-}
+/* Shared styles for the per-project sections and the policies page. Section boxes, cards
+   and steppers come from the shared primitives; this file holds page-specific layout. */
 
 .prose {
   max-width: 72ch;
 }
 
-.sources {
-  margin-top: var(--space-2);
-  font-size: 0.875rem;
-  color: var(--color-text-secondary);
-}
-
 .caption {
   caption-side: top;
   padding: var(--space-3);
@@ -57,22 +24,9 @@
   margin-top: var(--space-2);
 }
 
-.plainList {
-  list-style: none;
-}
-
-.plainList > li {
-  padding: var(--space-3) 0;
-  border-bottom: 1px solid var(--color-border);
-}
-
-.plainList > li:last-child {
-  border-bottom: 0;
-}
-
 .muted {
   color: var(--color-text-secondary);
-  font-size: 0.875rem;
+  font-size: var(--text-sm);
 }
 
 .ok,
@@ -81,59 +35,59 @@
 }
 
 .ok {
-  color: var(--stage-build-ink);
+  color: var(--stage-build);
 }
 
 .no {
-  color: var(--stage-learn-ink);
+  color: var(--stage-learn);
 }
 
 .callouts > * + * {
   margin-top: var(--space-4);
 }
 
+/* Step title with mixed inline content (code, text, link) inside a NumberedSteps item */
+.stepText {
+  display: inline;
+  font-weight: 500;
+}
+
 /* Request-flow strip (MCP Gateway hero) */
 
 .flow {
-  --flow-bg: var(--color-bg-secondary);
-  --flow-border: var(--color-border);
   margin: 0;
   /* Sized by the header figure slot, so the grid follows the slot width, not the viewport. */
   container-type: inline-size;
 }
 
-:global(.on-dark) .flow {
-  --flow-bg: rgba(255, 255, 255, 0.06);
-  --flow-border: rgba(255, 255, 255, 0.28);
-}
-
 .flowList {
   list-style: none;
   display: grid;
-  grid-template-columns: 1fr;
+  grid-template-columns: minmax(0, 1fr);
   gap: var(--space-2);
 }
 
 @container (min-width: 340px) {
   .flowList {
-    grid-template-columns: repeat(2, 1fr);
+    grid-template-columns: repeat(2, minmax(0, 1fr));
   }
 }
 
 @container (min-width: 720px) {
   .flowList {
-    grid-template-columns: repeat(3, 1fr);
+    grid-template-columns: repeat(3, minmax(0, 1fr));
   }
 }
 
-.flowStep {
+/* The strip sits on the dark header band: raise the cards on the band colour so the
+   inherited light text stays readable. */
+.flow .flowStep {
   display: flex;
   flex-direction: column;
   gap: var(--space-1);
-  padding: var(--space-3);
-  border: 1px solid var(--flow-border);
-  border-radius: var(--radius-md);
-  background: var(--flow-bg);
+  background: var(--color-band-raised);
+  border-color: var(--color-overlay-strong);
+  box-shadow: none;
 }
 
 .flowIndex {
@@ -142,8 +96,8 @@
   justify-content: center;
   width: 1.5rem;
   height: 1.5rem;
-  border-radius: 50%;
-  font-size: 0.75rem;
+  border-radius: var(--radius-pill);
+  font-size: var(--text-xs);
   font-weight: 700;
   background: var(--stage-govern);
   color: var(--stage-fill-text);
@@ -168,10 +122,46 @@
 
 .flowCaption {
   margin-top: var(--space-3);
-  font-size: 0.875rem;
+  font-size: var(--text-sm);
+  color: var(--color-text-secondary);
+}
+
+/* Workshop track matrix: modules down, tracks across */
+
+.trackMatrix {
+  /* Wide enough for the three track columns; below that the ResponsiveTable wrapper scrolls. */
+  min-width: 600px;
+  table-layout: fixed;
+}
+
+.trackMatrix thead th:first-child {
+  width: 40%;
+}
+
+.trackHead {
+  display: grid;
+  gap: var(--space-1);
+}
+
+.trackDuration {
+  font-size: var(--text-xs);
+  font-weight: 600;
+  letter-spacing: var(--label-tracking);
+  text-transform: uppercase;
   color: var(--color-text-secondary);
 }
 
+.trackCell {
+  text-align: center;
+  vertical-align: middle;
+}
+
+.trackCell > svg {
+  display: inline-block;
+  vertical-align: middle;
+  color: var(--stage-build);
+}
+
 /* Notebook groups */
 
 .notebookGroup + .notebookGroup {
@@ -189,32 +179,25 @@
 
 .groups {
   display: grid;
-  grid-template-columns: 1fr;
+  grid-template-columns: minmax(0, 1fr);
   gap: var(--space-4);
 }
 
 @media (min-width: 640px) {
   .groups {
-    grid-template-columns: repeat(2, 1fr);
+    grid-template-columns: repeat(2, minmax(0, 1fr));
   }
 }
 
 @media (min-width: 1024px) {
   .groups {
-    grid-template-columns: repeat(3, 1fr);
+    grid-template-columns: repeat(3, minmax(0, 1fr));
   }
 }
 
-.group {
-  padding: var(--space-4);
-  background: var(--color-bg-secondary);
-  border: 1px solid var(--color-border);
-  border-radius: var(--radius-md);
-}
-
 .group h3 {
   margin: 0 0 var(--space-2);
-  font-size: 1rem;
+  font-size: var(--text-base);
 }
 
 .group ul {
@@ -229,7 +212,7 @@
 
 .heroFigure {
   padding: var(--space-2);
-  background: #ffffff;
+  background: var(--color-figure-panel);
   border-radius: var(--radius-md);
 }
 
@@ -241,7 +224,7 @@
 
 .heroDownload {
   margin-top: var(--space-2);
-  font-size: 0.875rem;
+  font-size: var(--text-sm);
 }
 
 /* Evidence section */
diff --git a/docs-site/src/pages/projects/sections/RequestFlowStrip.tsx b/docs-site/src/pages/projects/sections/RequestFlowStrip.tsx
index d90406f..03c8e08 100644
--- a/docs-site/src/pages/projects/sections/RequestFlowStrip.tsx
+++ b/docs-site/src/pages/projects/sections/RequestFlowStrip.tsx
@@ -1,3 +1,4 @@
+import { Card } from '../../../components/Card';
 import { SourceLink } from '../../../components/SourceLink';
 import { requestFlow, VERIFIED_ARCHITECTURE } from '../../../content/projects/mcp-gateway-demo';
 import styles from './ProjectSections.module.css';
@@ -11,13 +12,13 @@ export function RequestFlowStrip() {
     <figure className={styles.flow} aria-labelledby="request-flow-caption">
       <ol className={styles.flowList}>
         {requestFlow.map((step, index) => (
-          <li key={step.id} className={styles.flowStep}>
+          <Card as="li" key={step.id} padding="sm" className={styles.flowStep}>
             <span className={styles.flowIndex} aria-hidden="true">
               {index + 1}
             </span>
             <span className={styles.flowName}>{step.name}</span>
             <span className={styles.flowDetail}>{step.detail}</span>
-          </li>
+          </Card>
         ))}
       </ol>
       <figcaption id="request-flow-caption" className={styles.flowCaption}>
diff --git a/docs-site/src/pages/projects/sections/WorkshopSections.tsx b/docs-site/src/pages/projects/sections/WorkshopSections.tsx
index dc9e3d6..c837689 100644
--- a/docs-site/src/pages/projects/sections/WorkshopSections.tsx
+++ b/docs-site/src/pages/projects/sections/WorkshopSections.tsx
@@ -1,10 +1,12 @@
 import { Link } from 'react-router-dom';
+import { Check } from 'lucide-react';
 import { notebooks, type NotebookEntry } from 'virtual:repo-index';
 import architectureImg from '../../../../../workshop-building-agentic-ai-platform/static/img/module-1/agentic-ai-platform-architecture.png';
 import fastImg from '../../../../../workshop-building-agentic-ai-platform/static/img/module-4/fast-architecture.png';
 import { DocImage } from '../../../components/DocImage';
 import { ExternalLink } from '../../../components/ExternalLink';
 import { Figure } from '../../../components/Figure';
+import { NumberedSteps } from '../../../components/NumberedSteps';
 import { ResponsiveTable } from '../../../components/ResponsiveTable';
 import { SourceLink } from '../../../components/SourceLink';
 import {
@@ -48,49 +50,77 @@ export function WorkshopSections() {
         <p className={styles.prose}>
           The workshop has three tracks of its own. All tracks share Module 1, which ends with a track selector.
         </p>
-        <ResponsiveTable className={styles.table}>
-          <TableCaption>The three workshop tracks, from the README track table</TableCaption>
+        <ResponsiveTable className={`${styles.table} ${styles.trackMatrix}`}>
+          <TableCaption>The three workshop tracks and the modules each one includes, from the README track table</TableCaption>
           <thead>
             <tr>
-              <th scope="col">Track</th>
-              <th scope="col">Best for</th>
-              <th scope="col">You do</th>
-              <th scope="col">Duration</th>
+              <th scope="col">Module</th>
+              {workshopTracks.map((track) => (
+                <th scope="col" key={track.number}>
+                  <span className={styles.trackHead}>
+                    <span>
+                      {track.number}. {track.name}
+                    </span>
+                    <span className={styles.trackDuration}>{track.duration}</span>
+                  </span>
+                </th>
+              ))}
             </tr>
           </thead>
           <tbody>
-            {workshopTracks.map((track) => (
-              <tr key={track.number}>
+            {workshopModules.map((module) => (
+              <tr key={module.id}>
                 <th scope="row">
-                  {track.number}. {track.name}
+                  {module.name}: {module.title}
                 </th>
-                <td>{track.bestFor}</td>
-                <td>{track.youDo}</td>
-                <td>{track.duration}</td>
+                {workshopTracks.map((track) => {
+                  const included = track.modules.includes(module.name);
+                  return (
+                    <td key={track.number} className={styles.trackCell} data-included={included ? '' : undefined}>
+                      {included ? (
+                        <>
+                          <Check size={18} aria-hidden="true" />
+                          <span className="visually-hidden">included</span>
+                        </>
+                      ) : (
+                        <span className="visually-hidden">not included</span>
+                      )}
+                    </td>
+                  );
+                })}
               </tr>
             ))}
+            <tr>
+              <th scope="row">Best for</th>
+              {workshopTracks.map((track) => (
+                <td key={track.number}>{track.bestFor}</td>
+              ))}
+            </tr>
+            <tr>
+              <th scope="row">You do</th>
+              {workshopTracks.map((track) => (
+                <td key={track.number}>{track.youDo}</td>
+              ))}
+            </tr>
           </tbody>
         </ResponsiveTable>
         <Sources sources={[CHOOSE_YOUR_TRACK]} />
       </Section>
 
       <Section id="modules" title="Modules">
-        <ol className={styles.list}>
+        <NumberedSteps stage="learn" dense>
           {workshopModules.map((module) => (
-            <li key={module.id}>
-              <strong>
-                {module.name}: {module.title}.
-              </strong>{' '}
-              {module.summary}
+            <NumberedSteps.Item key={module.id} title={`${module.name}: ${module.title}`}>
+              <p>{module.summary}</p>
               {module.id === 'module-3b' && (
-                <span className={styles.moduleNote}>
+                <p className={styles.moduleNote}>
                   {module3bNote.text} See <Link to={`${PATHS.conceptsGlossary}#mcp-gateway`}>MCP Gateway in the glossary</Link>.{' '}
                   <Sources inline sources={module3bNote.sources} />
-                </span>
+                </p>
               )}
-            </li>
+            </NumberedSteps.Item>
           ))}
-        </ol>
+        </NumberedSteps>
         <Sources sources={[WHAT_YOULL_BUILD]} />
       </Section>
 
diff --git a/docs-site/src/pages/projects/sections/shared.tsx b/docs-site/src/pages/projects/sections/shared.tsx
index 94c5e65..753fa81 100644
--- a/docs-site/src/pages/projects/sections/shared.tsx
+++ b/docs-site/src/pages/projects/sections/shared.tsx
@@ -1,70 +1,8 @@
-import { Fragment, type ReactNode } from 'react';
-import { SourceLink } from '../../../components/SourceLink';
-import { githubUrl, type Source } from '../../../content/facts';
+import type { ReactNode } from 'react';
 import styles from './ProjectSections.module.css';
 
-/**
- * "Source: file: heading, file" line under a table, list or paragraph. Several
- * quotes from the same file and heading collapse into one link.
- */
-export function Sources({
-  sources,
-  label = 'Source',
-  inline = false,
-}: {
-  sources: Source[];
-  label?: string;
-  /** Render as a span inside running text instead of a paragraph. */
-  inline?: boolean;
-}) {
-  const unique = [...new Map(sources.map((source) => [githubUrl(source), source])).values()];
-  const fileNames = unique.map((source) => source.file?.split('/').pop());
-  const Tag = inline ? 'span' : 'p';
-  return (
-    <Tag className={styles.sources}>
-      {label}:{' '}
-      {unique.map((source, index) => {
-        // Two files with the same name (module-3b/index.en.md, step-7/index.en.md) get their folder.
-        const repeated =
-          fileNames[index] !== undefined && fileNames.filter((name) => name === fileNames[index]).length > 1;
-        return (
-          <Fragment key={githubUrl(source)}>
-            {index > 0 && ', '}
-            <SourceLink source={source}>{repeated ? sourceLabel(source) : undefined}</SourceLink>
-          </Fragment>
-        );
-      })}
-    </Tag>
-  );
-}
-
-/** "folder/file.md: Heading" for a source whose file name alone would be ambiguous. */
-function sourceLabel(source: Source): string | undefined {
-  if (!source.file) return undefined;
-  const parts = source.file.split('/');
-  const file = parts.pop() ?? source.file;
-  const folder = parts.pop();
-  const base = folder ? `${folder}/${file}` : file;
-  return source.heading ? `${base}: ${source.heading}` : base;
-}
-
-export interface SectionProps {
-  /** Fragment id, also used to label the region. */
-  id: string;
-  title: string;
-  children: ReactNode;
-}
-
-/** A page section with an h2 heading. */
-export function Section({ id, title, children }: SectionProps) {
-  const headingId = `${id}-heading`;
-  return (
-    <section id={id} className={styles.section} aria-labelledby={headingId}>
-      <h2 id={headingId}>{title}</h2>
-      {children}
-    </section>
-  );
-}
+export { Sources } from '../../../components/Sources';
+export { Section, type SectionProps } from '../../../components/Section';
 
 const INLINE_TOKEN = /(`[^`]+`|\*\*[^*]+\*\*|\*[^*]+\*)/g;
 
diff --git a/docs-site/src/pages/reference/SecurityPage.module.css b/docs-site/src/pages/reference/SecurityPage.module.css
index 687c794..4442d03 100644
--- a/docs-site/src/pages/reference/SecurityPage.module.css
+++ b/docs-site/src/pages/reference/SecurityPage.module.css
@@ -5,30 +5,12 @@
   padding-bottom: var(--section-padding-y);
 }
 
-.section {
-  padding: var(--space-10) 0 0;
-}
-
-.section h2 {
-  margin-bottom: var(--space-4);
-}
-
-.prose {
-  max-width: 72ch;
-  margin-bottom: var(--space-4);
-}
-
-/* Before production */
-.checklistBox {
+/* Tinted checklist and reporting boxes (the Card owns the surface). */
+.tintedBox {
   max-width: 80ch;
-  padding: var(--space-6);
-  background: var(--tint-amber);
-  border-left: 4px solid var(--stage-learn-tint);
-  border-radius: var(--radius-md);
 }
 
-.checklistBox ul {
-  margin-top: var(--space-3);
+.checklist {
   padding-left: var(--space-6);
   display: flex;
   flex-direction: column;
@@ -46,21 +28,23 @@
   display: flex;
   flex-direction: column;
   gap: var(--space-3);
-  padding: var(--space-5);
-  background: var(--color-bg-secondary);
-  border: 1px solid var(--color-border);
-  border-radius: var(--radius-lg);
 }
 
 .docHeading {
   display: flex;
   flex-wrap: wrap;
   align-items: center;
-  gap: var(--space-3);
+  gap: var(--space-2) var(--space-3);
 }
 
-.docHeading h3 {
+.docIcon {
+  flex-shrink: 0;
+  color: var(--stage-color);
+}
+
+.docGrid .docTitle {
   font-size: 1.25rem;
+  margin: 0;
 }
 
 .docList {
@@ -84,7 +68,7 @@
 }
 
 .docAside {
-  font-size: 0.875rem;
+  font-size: var(--text-sm);
   color: var(--color-text-secondary);
 }
 
@@ -92,16 +76,3 @@
   text-decoration: underline;
   text-underline-offset: 0.15em;
 }
-
-/* Reporting */
-.reportingBox {
-  max-width: 80ch;
-  padding: var(--space-6);
-  background: var(--tint-violet);
-  border-left: 4px solid var(--stage-govern-tint);
-  border-radius: var(--radius-md);
-}
-
-.reportingBox p + p {
-  margin-top: var(--space-3);
-}
diff --git a/docs-site/src/pages/reference/SecurityPage.tsx b/docs-site/src/pages/reference/SecurityPage.tsx
index 6dc9784..afd186c 100644
--- a/docs-site/src/pages/reference/SecurityPage.tsx
+++ b/docs-site/src/pages/reference/SecurityPage.tsx
@@ -1,8 +1,9 @@
 import { Link } from 'react-router-dom';
+import { Card } from '../../components/Card';
 import { ExternalLink } from '../../components/ExternalLink';
 import { PageHeader } from '../../components/PageHeader';
 import { PageMeta } from '../../components/PageMeta';
-import { ReferenceNav } from './ReferenceNav';
+import { Section } from '../../components/Section';
 import { StageBadge } from '../../components/StageBadge';
 import { getProjectById, type ProjectId } from '../../content/data';
 import { docById, PROJECT_FOLDERS, type DocEntry } from '../../content/docs';
@@ -10,7 +11,9 @@ import { blob, githubHeadingSlug, ISSUES_URL, VULN_REPORT_URL } from '../../cont
 import { securityMatrix } from '../../content/matrix';
 import { docLabel } from '../../docs/docModules';
 import { PATHS, projectPath, projectReadmePath } from '../../paths';
+import { STAGE_ICONS } from '../../stage';
 import { PostureLegend, PostureMatrix } from '../concepts/PostureMatrix';
+import { ReferenceNav } from './ReferenceNav';
 import styles from './SecurityPage.module.css';
 
 const PRODUCTION_CHECKLIST = [
@@ -113,21 +116,20 @@ export function SecurityPage() {
       <div className="container">
         <ReferenceNav />
 
-        <section className={styles.section} aria-labelledby="controls">
-          <h2 id="controls">Security controls by project</h2>
-          <p className={styles.prose}>
-            Each cell states the control as the project ships it, with a link to the file that says so. Postures are
-            coarse on purpose; read the cell text before relying on a control.
-          </p>
+        <Section
+          id="controls"
+          title="Security controls by project"
+          flush
+          lead="Each cell states the control as the project ships it, with a link to the file that says so. Postures are coarse on purpose; read the cell text before relying on a control."
+        >
           <PostureLegend />
           <PostureMatrix caption="Security control posture by project, with sources" rowHeader="Control" rows={matrixRows} />
-        </section>
+        </Section>
 
-        <section className={styles.section} aria-labelledby="before-production">
-          <h2 id="before-production">Before production use</h2>
-          <div className={styles.checklistBox}>
+        <Section id="before-production" title="Before production use">
+          <Card variant="tinted" tint="amber" padding="lg" className={styles.tintedBox}>
             <p>Before deploying any of these projects to a production environment, review:</p>
-            <ul>
+            <ul className={styles.checklist}>
               {PRODUCTION_CHECKLIST.map((item) => (
                 <li key={item}>{item}</li>
               ))}
@@ -136,27 +138,28 @@ export function SecurityPage() {
                 <Link to={PATHS.referenceSupportEnvelope}>support envelope</Link> page
               </li>
             </ul>
-          </div>
-        </section>
+          </Card>
+        </Section>
 
-        <section className={styles.section} aria-labelledby="docs">
-          <h2 id="docs">Security documentation on this site</h2>
-          <p className={styles.prose}>
-            Rendered documents open on this site. README sections open on the rendered README page, with a GitHub link
-            beside each. Files the site does not render link straight to GitHub.
-          </p>
+        <Section
+          id="docs"
+          title="Security documentation on this site"
+          lead="Rendered documents open on this site. README sections open on the rendered README page, with a GitHub link beside each. Files the site does not render link straight to GitHub."
+        >
           <div className={styles.docGrid}>
             {SECURITY_DOCS.map((entry) => {
               const project = getProjectById(entry.projectId);
               if (!project) return null;
+              const Icon = STAGE_ICONS[project.stage];
               const siteDocs = entry.siteDocIds.map((id) => docById(id)).filter((d): d is DocEntry => d !== undefined);
               return (
-                <article key={entry.projectId} className={styles.docCard}>
+                <Card as="article" key={entry.projectId} stage={project.stage} interactive reveal className={styles.docCard}>
                   <div className={styles.docHeading}>
-                    <StageBadge stage={project.stage} label={project.stageLabel} />
-                    <h3>
+                    <Icon size={20} aria-hidden="true" className={styles.docIcon} />
+                    <h3 className={styles.docTitle}>
                       <Link to={projectPath(project.id)}>{project.shortName}</Link>
                     </h3>
+                    <StageBadge stage={project.stage} label={project.stageLabel} />
                   </div>
                   <ul className={styles.docList}>
                     <li>
@@ -185,15 +188,14 @@ export function SecurityPage() {
                       </li>
                     ))}
                   </ul>
-                </article>
+                </Card>
               );
             })}
           </div>
-        </section>
+        </Section>
 
-        <section className={styles.section} aria-labelledby="reporting">
-          <h2 id="reporting">Reporting</h2>
-          <div className={styles.reportingBox}>
+        <Section id="reporting" title="Reporting">
+          <Card variant="tinted" tint="violet" padding="lg" className={styles.tintedBox}>
             <p>
               <strong>Security vulnerabilities:</strong> do not open a public GitHub issue. Report them through the{' '}
               <ExternalLink href={VULN_REPORT_URL}>AWS vulnerability reporting page</ExternalLink>, as the repository&apos;s{' '}
@@ -203,8 +205,8 @@ export function SecurityPage() {
               <strong>Bugs and documentation problems:</strong> open an issue in the{' '}
               <ExternalLink href={ISSUES_URL}>GitHub issue tracker</ExternalLink>.
             </p>
-          </div>
-        </section>
+          </Card>
+        </Section>
       </div>
     </div>
   );
diff --git a/docs-site/src/pages/reference/SupportEnvelopePage.module.css b/docs-site/src/pages/reference/SupportEnvelopePage.module.css
index 8b10e90..30858b4 100644
--- a/docs-site/src/pages/reference/SupportEnvelopePage.module.css
+++ b/docs-site/src/pages/reference/SupportEnvelopePage.module.css
@@ -7,90 +7,58 @@
 
 .intro {
   max-width: 72ch;
-  margin: var(--space-6) 0;
+  margin: var(--space-6) 0 var(--space-2);
 }
 
-/* Jump navigation */
-.jumpNav {
-  margin-bottom: var(--space-4);
-}
-
-.jumpList {
-  list-style: none;
-  display: flex;
-  flex-wrap: wrap;
-  gap: var(--space-2);
-}
-
-.jumpLink {
-  display: inline-flex;
-  align-items: center;
-  gap: var(--space-2);
-  min-height: 2.25rem;
-  padding: 0 var(--space-3);
-  border: 1px solid var(--color-border);
-  border-radius: 999px;
-  background: var(--color-bg-secondary);
-  font-weight: 600;
-  text-decoration: none;
+/* Validated-envelope check list (only projects that publish such a list render it). */
+.validatedIntro {
+  margin: var(--space-2) 0 var(--space-3);
+  font-size: 0.9375rem;
+  color: var(--color-text-secondary);
 }
 
-.jumpLink:hover {
-  border-color: var(--color-blue);
+.validatedIntro a {
   text-decoration: underline;
+  text-underline-offset: 0.15em;
 }
 
-/* Per-project sections */
-.projectSection {
-  padding: var(--space-10) 0 0;
-  scroll-margin-top: calc(var(--header-height) + var(--space-4));
-}
-
-.projectSection + .projectSection {
-  margin-top: var(--space-6);
-  border-top: 1px solid var(--color-border);
+.validatedList {
+  list-style: none;
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(min(20rem, 100%), 1fr));
+  gap: var(--space-2) var(--space-6);
+  margin: 0 0 var(--space-6);
+  padding: 0;
 }
 
-.projectHeading {
+.validatedItem {
   display: flex;
-  flex-wrap: wrap;
-  align-items: center;
-  gap: var(--space-3);
-  margin-bottom: var(--space-2);
-}
-
-.projectLinks {
-  margin-bottom: var(--space-4);
+  align-items: flex-start;
+  gap: var(--space-2);
+  padding: var(--space-2) 0;
+  scroll-margin-top: calc(var(--header-height) + var(--space-4));
 }
 
-.projectLinks a {
-  display: inline-block;
-  min-height: var(--target-min);
-  font-weight: 600;
-  text-decoration: underline;
-  text-underline-offset: 0.15em;
+.validatedIcon {
+  flex-shrink: 0;
+  margin-top: 0.2em;
+  color: var(--stage-build);
 }
 
 /* Limitations */
-.limitationsHeading {
-  margin: var(--space-6) 0 var(--space-3);
-}
-
 .limitationList {
   list-style: none;
   display: grid;
   grid-template-columns: repeat(auto-fill, minmax(min(20rem, 100%), 1fr));
   gap: var(--space-4);
+  margin: 0;
+  padding: 0;
 }
 
 .limitation {
   display: flex;
   flex-direction: column;
   gap: var(--space-2);
-  padding: var(--space-4);
-  background: var(--color-bg-secondary);
-  border: 1px solid var(--color-border);
-  border-radius: var(--radius-md);
   scroll-margin-top: calc(var(--header-height) + var(--space-4));
 }
 
@@ -98,47 +66,18 @@
   font-size: 0.9375rem;
 }
 
-.limitationText {
+/* Verbatim README text, in both the check list and the limitation cards. */
+.quote {
   margin: 0;
   padding-left: var(--space-3);
-  border-left: 3px solid var(--color-mist);
+  border-left: 3px solid var(--color-border);
   font-size: 0.9375rem;
   line-height: 1.55;
   overflow-wrap: anywhere;
 }
 
-/* Validated-envelope bullets (only projects that publish such a list render them). */
-.validatedIntro {
-  margin: var(--space-2) 0 var(--space-3);
-  font-size: 0.9375rem;
-  color: var(--color-text-secondary);
-}
-
-.validatedIntro a {
-  text-decoration: underline;
-  text-underline-offset: 0.15em;
-}
-
-.validatedList {
-  list-style: none;
-  display: grid;
-  grid-template-columns: repeat(auto-fill, minmax(min(20rem, 100%), 1fr));
-  gap: var(--space-3);
-  margin-bottom: var(--space-6);
-}
-
-.validatedItem {
-  padding: var(--space-3);
-  background: var(--color-bg-secondary);
-  border: 1px solid var(--color-border);
-  border-radius: var(--radius-md);
-  scroll-margin-top: calc(var(--header-height) + var(--space-4));
-}
-
 .limitationSource {
   margin-top: auto;
-  font-size: 0.875rem;
-  color: var(--color-text-secondary);
   overflow-wrap: anywhere;
 }
 
@@ -150,8 +89,7 @@
 }
 
 /* Links inside secondary-coloured text need more than colour to stand out. */
-.footerNote a,
-.limitationSource a {
+.footerNote a {
   text-decoration: underline;
   text-underline-offset: 0.15em;
 }
diff --git a/docs-site/src/pages/reference/SupportEnvelopePage.tsx b/docs-site/src/pages/reference/SupportEnvelopePage.tsx
index eed7310..70d2a89 100644
--- a/docs-site/src/pages/reference/SupportEnvelopePage.tsx
+++ b/docs-site/src/pages/reference/SupportEnvelopePage.tsx
@@ -1,15 +1,21 @@
 import type { ReactNode } from 'react';
+import { ArrowRight, ShieldCheck } from 'lucide-react';
 import { Link } from 'react-router-dom';
+import { Button } from '../../components/Button';
+import { Card } from '../../components/Card';
+import { ChipNav } from '../../components/ChipNav';
 import { FactsTable } from '../../components/FactsTable';
 import { PageHeader } from '../../components/PageHeader';
 import { PageMeta } from '../../components/PageMeta';
-import { ReferenceNav } from './ReferenceNav';
+import { Section } from '../../components/Section';
 import { SourceLink } from '../../components/SourceLink';
+import { Sources } from '../../components/Sources';
 import { StageBadge } from '../../components/StageBadge';
 import { projects } from '../../content/data';
 import { FACT_LABELS, getFacts, type ProjectFacts, type Source } from '../../content/facts';
 import { getLimitations, validated } from '../../content/limitations';
 import { PATHS, projectPath } from '../../paths';
+import { ReferenceNav } from './ReferenceNav';
 import styles from './SupportEnvelopePage.module.css';
 
 const ENVELOPE_SOURCE: Source = { file: 'README.md', heading: 'Support Envelope' };
@@ -17,6 +23,12 @@ const ENVELOPE_SOURCE: Source = { file: 'README.md', heading: 'Support Envelope'
 /** Fact rows shown per project, in order. */
 const ENVELOPE_FACT_KEYS: ReadonlyArray<keyof ProjectFacts> = ['regions', 'defaultRegion', 'status', 'version'];
 
+const JUMP_ITEMS = projects.map((project) => ({
+  label: project.shortName,
+  href: `#envelope-${project.id}`,
+  badge: <StageBadge stage={project.stage} label={project.stageLabel} variant="outline" />,
+}));
+
 /**
  * Render verbatim README text with its Markdown inline code and emphasis
  * markers turned into elements. No raw HTML is involved.
@@ -57,34 +69,26 @@ export function SupportEnvelopePage() {
           the project files without paraphrase.
         </p>
 
-        <nav aria-label="Projects on this page" className={styles.jumpNav}>
-          <ul className={styles.jumpList}>
-            {projects.map((project) => (
-              <li key={project.id}>
-                <a href={`#envelope-${project.id}`} className={styles.jumpLink}>
-                  <StageBadge stage={project.stage} label={project.stageLabel} variant="outline" />
-                  {project.shortName}
-                </a>
-              </li>
-            ))}
-          </ul>
-        </nav>
+        <ChipNav label="Projects on this page" lead="Jump to:" items={JUMP_ITEMS} overflow="wrap" />
 
-        {projects.map((project) => {
+        {projects.map((project, index) => {
           const facts = getFacts(project.id);
           const limitations = getLimitations(project.id);
           const validatedItems = validated[project.id];
           const validatedHeading = validatedItems[0]?.source.heading ?? 'Validated reference envelope';
           return (
-            <section key={project.id} className={styles.projectSection} aria-labelledby={`envelope-${project.id}`}>
-              <div className={styles.projectHeading}>
-                <StageBadge stage={project.stage} label={`${project.stageNumber}. ${project.stageLabel}`} />
-                <h2 id={`envelope-${project.id}`}>{project.name}</h2>
-              </div>
-              <p className={styles.projectLinks}>
-                <Link to={projectPath(project.id)}>Project page</Link>
-              </p>
-
+            <Section
+              key={project.id}
+              id={`envelope-${project.id}`}
+              title={project.name}
+              flush={index === 0}
+              badge={<StageBadge stage={project.stage} label={`${project.stageNumber}. ${project.stageLabel}`} />}
+              actions={
+                <Button variant="ghost" size="sm" to={projectPath(project.id)} iconEnd={<ArrowRight size={16} />}>
+                  Project page<span className="visually-hidden">: {project.shortName}</span>
+                </Button>
+              }
+            >
               <FactsTable
                 caption={`${project.shortName}: validated regions and status`}
                 rows={ENVELOPE_FACT_KEYS.map((key) => ({ label: FACT_LABELS[key], fact: facts[key] }))}
@@ -92,7 +96,7 @@ export function SupportEnvelopePage() {
 
               {validatedItems.length > 0 && (
                 <>
-                  <h3 className={styles.limitationsHeading}>{validatedHeading}</h3>
+                  <h3>{validatedHeading}</h3>
                   <p className={styles.validatedIntro}>
                     What {project.shortName} states it has validated, quoted from its README (
                     <SourceLink source={validatedItems[0].source}>source</SourceLink>). Anything outside this list is
@@ -101,26 +105,35 @@ export function SupportEnvelopePage() {
                   <ul className={styles.validatedList}>
                     {validatedItems.map((item) => (
                       <li key={item.id} id={item.id} className={styles.validatedItem}>
-                        <blockquote className={styles.limitationText}>{renderInline(item.text)}</blockquote>
+                        <ShieldCheck size={18} aria-hidden="true" className={styles.validatedIcon} />
+                        <span className="visually-hidden">Validated: </span>
+                        <blockquote className={styles.quote}>{renderInline(item.text)}</blockquote>
                       </li>
                     ))}
                   </ul>
                 </>
               )}
 
-              <h3 className={styles.limitationsHeading}>Known limitations, as documented</h3>
+              <h3>Known limitations, as documented</h3>
               <ul className={styles.limitationList}>
                 {limitations.map((limitation) => (
-                  <li key={limitation.id} id={limitation.id} className={styles.limitation} data-reveal>
+                  <Card
+                    as="li"
+                    key={limitation.id}
+                    id={limitation.id}
+                    variant="accent"
+                    stage={project.stage}
+                    reveal
+                    padding="sm"
+                    className={styles.limitation}
+                  >
                     {limitation.title && <strong className={styles.limitationTitle}>{limitation.title}</strong>}
-                    <blockquote className={styles.limitationText}>{renderInline(limitation.text)}</blockquote>
-                    <p className={styles.limitationSource}>
-                      Source: <SourceLink source={limitation.source} />
-                    </p>
-                  </li>
+                    <blockquote className={styles.quote}>{renderInline(limitation.text)}</blockquote>
+                    <Sources sources={[limitation.source]} className={styles.limitationSource} />
+                  </Card>
                 ))}
               </ul>
-            </section>
+            </Section>
           );
         })}
 
diff --git a/docs-site/src/pages/start/CostsAndCleanupPage.tsx b/docs-site/src/pages/start/CostsAndCleanupPage.tsx
index cf85ec6..455ca49 100644
--- a/docs-site/src/pages/start/CostsAndCleanupPage.tsx
+++ b/docs-site/src/pages/start/CostsAndCleanupPage.tsx
@@ -4,12 +4,13 @@ import { CodeBlock } from '../../components/CodeBlock';
 import { FactsTable } from '../../components/FactsTable';
 import { PageHeader } from '../../components/PageHeader';
 import { PageMeta } from '../../components/PageMeta';
+import { Section } from '../../components/Section';
 import { SourceLink } from '../../components/SourceLink';
 import { projects } from '../../content/data';
 import { FACT_LABELS, getFacts } from '../../content/facts';
 import { getQuickstarts } from '../../content/quickstarts';
 import { PATHS, projectPath } from '../../paths';
-import { JumpLinks, ProjectHeading, SmallSource, StartNav } from './shared';
+import { JumpLinks, ProjectBadge, SmallSource, StartNav } from './shared';
 import styles from './start.module.css';
 
 const ROOT_COSTS = { file: 'README.md', heading: 'Costs' };
@@ -50,13 +51,7 @@ export function CostsAndCleanupPage() {
           const facts = getFacts(project.id);
           const quickstarts = getQuickstarts(project.id);
           return (
-            <section
-              key={project.id}
-              id={project.id}
-              className={styles.projectSection}
-              aria-labelledby={`${project.id}-heading`}
-            >
-              <ProjectHeading project={project} id={`${project.id}-heading`} />
+            <Section key={project.id} id={project.id} title={project.name} badge={<ProjectBadge project={project} />}>
               <FactsTable
                 caption={`${project.shortName}: cost and teardown`}
                 rows={[
@@ -79,7 +74,7 @@ export function CostsAndCleanupPage() {
                 <Link to={`${PATHS.start}#${project.id}`}>first ten minutes with {project.shortName}</Link>, and the{' '}
                 <SourceLink source={facts.teardown.source ?? project.sources.features}>README</SourceLink>.
               </p>
-            </section>
+            </Section>
           );
         })}
       </div>
diff --git a/docs-site/src/pages/start/FaqPage.tsx b/docs-site/src/pages/start/FaqPage.tsx
index a751c11..0bb85da 100644
--- a/docs-site/src/pages/start/FaqPage.tsx
+++ b/docs-site/src/pages/start/FaqPage.tsx
@@ -1,7 +1,9 @@
+import { Card } from '../../components/Card';
+import { ChipNav } from '../../components/ChipNav';
 import { PageHeader } from '../../components/PageHeader';
 import { PageMeta } from '../../components/PageMeta';
 import { SmartLink } from '../../components/SmartLink';
-import { SourceLink } from '../../components/SourceLink';
+import { Sources } from '../../components/Sources';
 import { StageBadge } from '../../components/StageBadge';
 import { getProjectById } from '../../content/data';
 import { faq } from '../../content/faq';
@@ -23,59 +25,56 @@ export function FaqPage() {
       <div className="container">
         <StartNav />
 
-        <nav aria-label="Questions" className={styles.projectSection}>
-          <ol className={styles.bulletList}>
-            {faq.map((entry) => (
-              <li key={entry.id}>
-                <a href={`#${entry.id}`}>{entry.question}</a>
-              </li>
-            ))}
-          </ol>
-        </nav>
+        <ChipNav
+          label="Questions"
+          lead="Questions:"
+          overflow="wrap"
+          className={styles.faqNav}
+          items={faq.map((entry) => ({ href: `#${entry.id}`, label: entry.question }))}
+        />
 
-        {faq.map((entry) => (
-          <section
-            key={entry.id}
-            id={entry.id}
-            className={styles.projectSection}
-            aria-labelledby={`${entry.id}-heading`}
-          >
-            <h2 id={`${entry.id}-heading`}>{entry.question}</h2>
-            {entry.projectIds.length > 0 && (
-              <ul className={styles.chips} aria-label="Projects concerned">
-                {entry.projectIds.map((projectId) => {
-                  const project = getProjectById(projectId);
-                  return project ? (
-                    <li key={projectId}>
-                      <StageBadge stage={project.stage} label={project.shortName} variant="outline" />
-                    </li>
-                  ) : null;
-                })}
-              </ul>
-            )}
-            <div className={`${styles.prose} ${styles.subSection}`}>
-              <p>{entry.answer}</p>
-              {entry.links && entry.links.length > 0 && (
-                <ul className={styles.bulletList}>
-                  {entry.links.map((link) => (
-                    <li key={link.href}>
-                      <SmartLink href={link.href}>{link.label}</SmartLink>
-                    </li>
-                  ))}
+        <div className={styles.faqList}>
+          {faq.map((entry) => (
+            <Card
+              as="section"
+              key={entry.id}
+              id={entry.id}
+              aria-labelledby={`${entry.id}-heading`}
+              reveal
+              padding="lg"
+              className={styles.faqCard}
+            >
+              <h2 id={`${entry.id}-heading`} className={styles.faqQuestion}>
+                {entry.question}
+              </h2>
+              {entry.projectIds.length > 0 && (
+                <ul className={styles.badgeRow} aria-label="Projects concerned">
+                  {entry.projectIds.map((projectId) => {
+                    const project = getProjectById(projectId);
+                    return project ? (
+                      <li key={projectId}>
+                        <StageBadge stage={project.stage} label={project.shortName} variant="outline" />
+                      </li>
+                    ) : null;
+                  })}
                 </ul>
               )}
-              <p className={styles.meta}>
-                {entry.sources.length === 1 ? 'Source: ' : 'Sources: '}
-                {entry.sources.map((source, index) => (
-                  <span key={`${source.file}-${source.heading ?? ''}-${source.quote ?? index}`}>
-                    {index > 0 && '; '}
-                    <SourceLink source={source} />
-                  </span>
-                ))}
-              </p>
-            </div>
-          </section>
-        ))}
+              <div className={styles.prose}>
+                <p>{entry.answer}</p>
+                {entry.links && entry.links.length > 0 && (
+                  <ul className={styles.bulletList}>
+                    {entry.links.map((link) => (
+                      <li key={link.href}>
+                        <SmartLink href={link.href}>{link.label}</SmartLink>
+                      </li>
+                    ))}
+                  </ul>
+                )}
+                <Sources sources={entry.sources} label={entry.sources.length === 1 ? 'Source' : 'Sources'} />
+              </div>
+            </Card>
+          ))}
+        </div>
       </div>
     </>
   );
diff --git a/docs-site/src/pages/start/PrerequisitesPage.tsx b/docs-site/src/pages/start/PrerequisitesPage.tsx
index 0602d2f..d2b87e4 100644
--- a/docs-site/src/pages/start/PrerequisitesPage.tsx
+++ b/docs-site/src/pages/start/PrerequisitesPage.tsx
@@ -2,11 +2,12 @@ import { Link } from 'react-router-dom';
 import { FactsTable } from '../../components/FactsTable';
 import { PageHeader } from '../../components/PageHeader';
 import { PageMeta } from '../../components/PageMeta';
+import { Section } from '../../components/Section';
 import { SourceLink } from '../../components/SourceLink';
 import { projects } from '../../content/data';
 import { FACT_LABELS, getFacts } from '../../content/facts';
 import { PATHS, projectPath } from '../../paths';
-import { JumpLinks, ProjectHeading, StartNav } from './shared';
+import { JumpLinks, ProjectBadge, StartNav } from './shared';
 import styles from './start.module.css';
 
 export function PrerequisitesPage() {
@@ -35,13 +36,7 @@ export function PrerequisitesPage() {
         {projects.map((project) => {
           const facts = getFacts(project.id);
           return (
-            <section
-              key={project.id}
-              id={project.id}
-              className={styles.projectSection}
-              aria-labelledby={`${project.id}-heading`}
-            >
-              <ProjectHeading project={project} id={`${project.id}-heading`} />
+            <Section key={project.id} id={project.id} title={project.name} badge={<ProjectBadge project={project} />}>
               <p className={styles.meta}>
                 From the README: <SourceLink source={project.sources.prerequisites} />
               </p>
@@ -65,7 +60,7 @@ export function PrerequisitesPage() {
                 Next: <Link to={`${PATHS.start}#${project.id}`}>first ten minutes with {project.shortName}</Link> or the{' '}
                 <Link to={projectPath(project.id)}>{project.shortName} project page</Link>.
               </p>
-            </section>
+            </Section>
           );
         })}
       </div>
diff --git a/docs-site/src/pages/start/StartPage.tsx b/docs-site/src/pages/start/StartPage.tsx
index 397e2b2..bfffd10 100644
--- a/docs-site/src/pages/start/StartPage.tsx
+++ b/docs-site/src/pages/start/StartPage.tsx
@@ -1,14 +1,19 @@
 import { Link } from 'react-router-dom';
+import { Timer } from 'lucide-react';
 import { CodeBlock } from '../../components/CodeBlock';
 import { ExternalLink } from '../../components/ExternalLink';
+import { NumberedSteps } from '../../components/NumberedSteps';
 import { PageHeader } from '../../components/PageHeader';
 import { PageMeta } from '../../components/PageMeta';
+import { Section } from '../../components/Section';
 import { SourceLink } from '../../components/SourceLink';
+import { StatTile } from '../../components/StatTile';
 import { projects, type Project } from '../../content/data';
+import { factText, getFacts } from '../../content/facts';
 import { ISSUES_URL, REPO_URL, VULN_REPORT_URL } from '../../content/links';
 import { getQuickstarts, type Quickstart, type QuickstartStep } from '../../content/quickstarts';
 import { PATHS, projectPath } from '../../paths';
-import { FactValue, JumpLinks, ProjectHeading, SmallSource, StartNav } from './shared';
+import { FactValue, JumpLinks, ProjectBadge, SmallSource, StartNav } from './shared';
 import styles from './start.module.css';
 
 /** Root README wording for the clone step; the folder line is per project. */
@@ -46,20 +51,28 @@ function cloneStepFor(project: Project, quickstart: Quickstart): QuickstartStep
 
 function StepItem({ step }: { step: QuickstartStep }) {
   const linkIsTitle = Boolean(step.href) && step.hrefLabel === step.title;
+  const hasBody = Boolean(step.command || step.note || (step.href && !linkIsTitle));
   return (
-    <li className={styles.step}>
-      <p className={styles.stepTitle}>
-        {linkIsTitle && step.href ? <ExternalLink href={step.href}>{step.title}</ExternalLink> : step.title}
-        <SmallSource source={step.source} context={`step: ${step.title}`} />
-      </p>
-      {step.command && <CodeBlock code={step.command} language="bash" />}
-      {step.note && <p className={styles.stepNote}>{step.note}</p>}
-      {step.href && !linkIsTitle && (
-        <p className={styles.stepNote}>
-          <ExternalLink href={step.href}>{step.hrefLabel ?? 'Open the README section'}</ExternalLink>
-        </p>
+    <NumberedSteps.Item
+      title={
+        <span className={styles.stepTitle}>
+          {linkIsTitle && step.href ? <ExternalLink href={step.href}>{step.title}</ExternalLink> : step.title}{' '}
+          <SmallSource source={step.source} context={`step: ${step.title}`} />
+        </span>
+      }
+    >
+      {hasBody && (
+        <>
+          {step.command && <CodeBlock code={step.command} language="bash" />}
+          {step.note && <p className={styles.stepNote}>{step.note}</p>}
+          {step.href && !linkIsTitle && (
+            <p className={styles.stepNote}>
+              <ExternalLink href={step.href}>{step.hrefLabel ?? 'Open the README section'}</ExternalLink>
+            </p>
+          )}
+        </>
       )}
-    </li>
+    </NumberedSteps.Item>
   );
 }
 
@@ -81,12 +94,12 @@ function QuickstartBlock({ project, quickstart }: { project: Project; quickstart
         <strong>Expected time:</strong>{' '}
         <FactValue fact={quickstart.expectedTime} label="expected time" project={quickstart.name} />
       </p>
-      <ol className={styles.steps}>
+      <NumberedSteps stage={project.stage} connector>
         {clone && <StepItem step={clone} />}
         {firstSteps.map((step) => (
           <StepItem key={step.title} step={step} />
         ))}
-      </ol>
+      </NumberedSteps>
       <ul className={styles.linkRow}>
         <li>
           <Link to={`${projectPath(project.id)}#quickstart`}>
@@ -108,15 +121,42 @@ function QuickstartBlock({ project, quickstart }: { project: Project; quickstart
 function ProjectSection({ project }: { project: Project }) {
   const quickstarts = getQuickstarts(project.id);
   return (
-    <section id={project.id} className={styles.projectSection} aria-labelledby={`${project.id}-heading`}>
-      <ProjectHeading project={project} id={`${project.id}-heading`} />
-      <p className={styles.lead}>
-        {project.tagline}. <Link to={projectPath(project.id)}>{project.shortName} project page</Link>.
-      </p>
+    <Section
+      id={project.id}
+      title={project.name}
+      badge={<ProjectBadge project={project} />}
+      lead={
+        <>
+          {project.tagline}. <Link to={projectPath(project.id)}>{project.shortName} project page</Link>.
+        </>
+      }
+    >
       {quickstarts.map((quickstart) => (
         <QuickstartBlock key={quickstart.id} project={project} quickstart={quickstart} />
       ))}
-    </section>
+    </Section>
+  );
+}
+
+/** First-deploy time per project, shown on the header band. The notes and caveats follow in each section. */
+function FirstDeployRow() {
+  return (
+    <dl className={styles.heroFacts}>
+      {projects.map((project) => {
+        const fact = getFacts(project.id).firstDeploy;
+        return (
+          <StatTile
+            key={project.id}
+            label={project.shortName}
+            value={fact.notDocumented ? <em>{factText(fact)}</em> : factText(fact)}
+            muted={Boolean(fact.notDocumented)}
+            source={fact.source}
+            context={`first deploy, ${project.shortName}`}
+            icon={<Timer size={14} aria-hidden="true" />}
+          />
+        );
+      })}
+    </dl>
   );
 }
 
@@ -131,17 +171,23 @@ export function StartPage() {
         eyebrow="Start"
         title="Get started"
         lead="Pick one of the four samples for agentic AI on Amazon Bedrock and Amazon Bedrock AgentCore, clone the repository, and take its first steps here. The full quickstart and the teardown live on each project page; every path deploys real AWS resources."
+        meta={<FirstDeployRow />}
       />
       <div className="container">
         <StartNav />
 
-        <section className={styles.projectSection} aria-labelledby="first-heading">
-          <h2 id="first-heading">First ten minutes by project</h2>
-          <p className={styles.prose}>
-            Each section gives the clone and folder lines, the expected time and the first two steps of one project,
-            then hands over to the project page for the rest.{' '}
-            <SmallSource source={ROOT_QUICK_START} context="the clone command" />
-          </p>
+        <Section
+          id="first"
+          title="First ten minutes by project"
+          flush
+          lead={
+            <>
+              Each section gives the clone and folder lines, the expected time and the first two steps of one project,
+              then hands over to the project page for the rest.{' '}
+              <SmallSource source={ROOT_QUICK_START} context="the clone command" />
+            </>
+          }
+        >
           <JumpLinks
             label="First ten minutes by project"
             lead="Jump to:"
@@ -150,14 +196,13 @@ export function StartPage() {
               label: project.shortName,
             }))}
           />
-        </section>
+        </Section>
 
         {projects.map((project) => (
           <ProjectSection key={project.id} project={project} />
         ))}
 
-        <section className={styles.projectSection} aria-labelledby="support-heading">
-          <h2 id="support-heading">Support and feedback</h2>
+        <Section id="support" title="Support and feedback">
           <ul className={styles.bulletList}>
             <li>
               <strong>Questions, bugs, and feature requests:</strong>{' '}
@@ -187,7 +232,7 @@ export function StartPage() {
               <Link to={PATHS.faq}>FAQ</Link>.
             </li>
           </ul>
-        </section>
+        </Section>
       </div>
     </>
   );
diff --git a/docs-site/src/pages/start/WhichProjectPage.tsx b/docs-site/src/pages/start/WhichProjectPage.tsx
index 8972aba..a2b1159 100644
--- a/docs-site/src/pages/start/WhichProjectPage.tsx
+++ b/docs-site/src/pages/start/WhichProjectPage.tsx
@@ -1,14 +1,20 @@
 import { Link } from 'react-router-dom';
-import { ArrowRight } from 'lucide-react';
+import { ArrowRight, Timer } from 'lucide-react';
+import { Card } from '../../components/Card';
 import { PageHeader } from '../../components/PageHeader';
 import { PageMeta } from '../../components/PageMeta';
 import { ResponsiveTable } from '../../components/ResponsiveTable';
+import { Section } from '../../components/Section';
+import { SectionHeading } from '../../components/SectionHeading';
 import { StageBadge } from '../../components/StageBadge';
-import { getProjectById, projects } from '../../content/data';
+import { FactStat } from '../../components/StatTile';
+import { getProjectById, projects, type Project } from '../../content/data';
 import { FACT_KEYS, FACT_LABELS, getFacts, type ProjectFacts } from '../../content/facts';
 import { getSitePath, roleGuidance, sitePaths, timeGuidance } from '../../content/tracks';
 import { PATHS, projectPath } from '../../paths';
-import { FactItem, FactValue, SmallSource, StartNav } from './shared';
+import { STAGE_ICONS } from '../../stage';
+import { factIcon } from './factIcons';
+import { FactValue, SmallSource, StartNav } from './shared';
 import styles from './start.module.css';
 
 /**
@@ -39,6 +45,105 @@ const FACT_ROWS: ReadonlyArray<keyof ProjectFacts> = [
 /** One column per project, with its facts resolved once. */
 const columns = projects.map((project) => ({ project, facts: getFacts(project.id) }));
 
+function StageIcon({ project, size = 16 }: { project: Project; size?: number }) {
+  const Icon = STAGE_ICONS[project.stage];
+  return <Icon size={size} aria-hidden="true" className={styles.stageIcon} />;
+}
+
+/** The comparison as a table: columns are the projects, rows the facts. Shown from 640 px up. */
+function ComparisonTable() {
+  return (
+    <div className={styles.matrixDesktop}>
+      <ResponsiveTable className={styles.matrix}>
+        <caption>Comparison of the four projects. Each fact links to its source in the repository.</caption>
+        <thead>
+          <tr>
+            <th scope="col">Fact</th>
+            {columns.map(({ project }) => (
+              <th scope="col" key={project.id} data-stage={project.stage}>
+                <span className={styles.matrixProject}>
+                  <Link to={projectPath(project.id)} className={styles.matrixName}>
+                    <StageIcon project={project} />
+                    <span>{project.name}</span>
+                  </Link>
+                  <StageBadge stage={project.stage} label={`${project.stageNumber}. ${project.stageLabel}`} />
+                </span>
+              </th>
+            ))}
+          </tr>
+        </thead>
+        <tbody>
+          <tr>
+            <th scope="row">Stage</th>
+            {columns.map(({ project }) => (
+              <td key={project.id}>
+                {project.stageNumber}. {project.stageLabel}
+              </td>
+            ))}
+          </tr>
+          <tr className={styles.bestForRow}>
+            <th scope="row">Best for</th>
+            {columns.map(({ project }) => (
+              <td key={project.id}>{project.bestFor}</td>
+            ))}
+          </tr>
+          {FACT_ROWS.map((key) => (
+            <tr key={key}>
+              <th scope="row">
+                <span className={styles.rowLabel}>
+                  {factIcon(key)}
+                  <span>{FACT_LABELS[key]}</span>
+                </span>
+              </th>
+              {columns.map(({ project, facts }) => (
+                <td key={project.id}>
+                  <FactValue fact={facts[key]} label={FACT_LABELS[key]} project={project.shortName} />
+                </td>
+              ))}
+            </tr>
+          ))}
+        </tbody>
+      </ResponsiveTable>
+    </div>
+  );
+}
+
+/** The same comparison as one card per project, for screens below 640 px. */
+function ComparisonCards() {
+  return (
+    <ul className={styles.matrixCards} aria-label="Comparison of the four projects, one card per project">
+      {columns.map(({ project, facts }) => (
+        <Card as="li" key={project.id} variant="accent" stage={project.stage} className={styles.compareCard}>
+          <div className={styles.tileHead}>
+            <StageBadge stage={project.stage} label={`${project.stageNumber}. ${project.stageLabel}`} />
+          </div>
+          <h3 className={styles.compareTitle}>
+            <Link to={projectPath(project.id)} className={styles.matrixName}>
+              <StageIcon project={project} />
+              <span>{project.name}</span>
+            </Link>
+          </h3>
+          <p className={styles.tileText}>
+            <strong>Best for:</strong> {project.bestFor}
+          </p>
+          <dl className={styles.compareFacts}>
+            {FACT_ROWS.map((key) => (
+              <FactStat
+                key={key}
+                label={FACT_LABELS[key]}
+                fact={facts[key]}
+                project={project.shortName}
+                icon={factIcon(key)}
+                noteMode="collapsed"
+              />
+            ))}
+          </dl>
+        </Card>
+      ))}
+    </ul>
+  );
+}
+
 export function WhichProjectPage() {
   return (
     <>
@@ -54,72 +159,39 @@ export function WhichProjectPage() {
       <div className="container">
         <StartNav />
 
-        <section className={styles.projectSection} aria-labelledby="compare-heading">
-          <h2 id="compare-heading">Compare the four projects</h2>
-          <p className={styles.lead}>
-            Columns are the projects and rows are the facts. On a narrow screen, scroll the table sideways; the fact
-            labels stay in view.
-          </p>
-          <ResponsiveTable className={styles.matrix}>
-            <caption>Comparison of the four projects. Each fact links to its source in the repository.</caption>
-            <thead>
-              <tr>
-                <th scope="col">Fact</th>
-                {columns.map(({ project }) => (
-                  <th scope="col" key={project.id}>
-                    <span className={styles.matrixProject}>
-                      <Link to={projectPath(project.id)}>{project.name}</Link>
-                      <StageBadge stage={project.stage} label={`${project.stageNumber}. ${project.stageLabel}`} />
-                    </span>
-                  </th>
-                ))}
-              </tr>
-            </thead>
-            <tbody>
-              <tr>
-                <th scope="row">Stage</th>
-                {columns.map(({ project }) => (
-                  <td key={project.id}>
-                    {project.stageNumber}. {project.stageLabel}
-                  </td>
-                ))}
-              </tr>
-              <tr>
-                <th scope="row">Best for</th>
-                {columns.map(({ project }) => (
-                  <td key={project.id}>{project.bestFor}</td>
-                ))}
-              </tr>
-              {FACT_ROWS.map((key) => (
-                <tr key={key}>
-                  <th scope="row">{FACT_LABELS[key]}</th>
-                  {columns.map(({ project, facts }) => (
-                    <td key={project.id}>
-                      <FactValue fact={facts[key]} label={FACT_LABELS[key]} project={project.shortName} />
-                    </td>
-                  ))}
-                </tr>
-              ))}
-            </tbody>
-          </ResponsiveTable>
+        <Section
+          id="compare"
+          title="Compare the four projects"
+          flush
+          lead="Columns are the projects and rows are the facts. On a narrow screen, scroll the table sideways; the fact labels stay in view."
+        >
+          <ComparisonTable />
+          <ComparisonCards />
           <p className={`${styles.meta} ${styles.matrixHint}`}>
             Prerequisites per project are on the <Link to={PATHS.prerequisites}>Prerequisites</Link> page; cost notes
             and teardown procedures are under <Link to={PATHS.costsAndCleanup}>Costs and cleanup</Link>.
           </p>
-        </section>
+        </Section>
 
-        <section className={styles.projectSection} aria-labelledby="paths-heading">
-          <h2 id="paths-heading">Four paths through the repository</h2>
-          <p className={styles.lead}>
-            Each path starts on one project and says who it is for, what you have at the end, and how long the first
-            result takes.
-          </p>
-          <ul className={`${styles.tileGrid} ${styles.tileGrid4}`}>
+        <Section
+          id="paths"
+          title="Four paths through the repository"
+          lead="Each path starts on one project and says who it is for, what you have at the end, and how long the first result takes."
+        >
+          <ul className={styles.pathGrid}>
             {sitePaths.map((path) => {
               const first = getProjectById(path.projects[0]);
               if (!first) return null;
               return (
-                <li key={path.id} className={styles.tile} data-stage={first.stage} data-reveal data-lift>
+                <Card
+                  as="li"
+                  key={path.id}
+                  variant="accent"
+                  stage={first.stage}
+                  interactive
+                  reveal
+                  className={styles.pathCard}
+                >
                   <div className={styles.tileHead}>
                     <StageBadge stage={first.stage} label={`${first.stageNumber}. ${first.stageLabel}`} />
                     <Link to={path.startRoute} className={styles.tileLink}>
@@ -136,19 +208,23 @@ export function WhichProjectPage() {
                     <strong>What you get:</strong> {path.whatYouGet}{' '}
                     <SmallSource source={path.source} context={`what you get: ${path.name}`} />
                   </p>
-                  <dl className={styles.facts}>
-                    <FactItem label="Time to first result" fact={path.timeToFirstResult} />
+                  <dl className={styles.pathFacts}>
+                    <FactStat
+                      label="Time to first result"
+                      fact={path.timeToFirstResult}
+                      icon={<Timer size={14} aria-hidden="true" />}
+                    />
                   </dl>
-                </li>
+                </Card>
               );
             })}
           </ul>
-        </section>
+        </Section>
 
-        <div className={`${styles.projectSection} ${styles.twoCol}`}>
+        <div className={`${styles.guidance} ${styles.twoCol}`}>
           <section aria-labelledby="role-heading">
-            <h2 id="role-heading">By role</h2>
-            <ul className={`${styles.plainList} ${styles.subSection}`}>
+            <SectionHeading id="role-heading" title="By role" />
+            <ul className={styles.plainList}>
               {roleGuidance.map((guidance) => {
                 const path = getSitePath(guidance.pathId);
                 if (!path) return null;
@@ -161,8 +237,8 @@ export function WhichProjectPage() {
             </ul>
           </section>
           <section aria-labelledby="time-heading">
-            <h2 id="time-heading">By time available</h2>
-            <ul className={`${styles.plainList} ${styles.subSection}`}>
+            <SectionHeading id="time-heading" title="By time available" />
+            <ul className={styles.plainList}>
               {timeGuidance.map((guidance) => {
                 const path = getSitePath(guidance.pathId);
                 if (!path) return null;
diff --git a/docs-site/src/pages/start/factIcons.tsx b/docs-site/src/pages/start/factIcons.tsx
new file mode 100644
index 0000000..b5a9b7b
--- /dev/null
+++ b/docs-site/src/pages/start/factIcons.tsx
@@ -0,0 +1,22 @@
+import type { ReactNode } from 'react';
+import { Activity, Clock, Coins, Layers, MapPin, Package, Timer, Trash2, Wrench, type LucideIcon } from 'lucide-react';
+import type { ProjectFacts } from '../../content/facts';
+
+/** Decorative icon for each fact key (always rendered aria-hidden beside the label). */
+export const FACT_ICONS: Partial<Record<keyof ProjectFacts, LucideIcon>> = {
+  regions: MapPin,
+  firstDeploy: Timer,
+  cost: Coins,
+  accountTopology: Layers,
+  iac: Wrench,
+  status: Activity,
+  teardown: Trash2,
+  handsOnTime: Clock,
+  deploys: Package,
+};
+
+/** The icon element for a fact key, or undefined when the key has none. */
+export function factIcon(key: keyof ProjectFacts, size = 14): ReactNode {
+  const Icon = FACT_ICONS[key];
+  return Icon ? <Icon size={size} aria-hidden="true" /> : undefined;
+}
diff --git a/docs-site/src/pages/start/shared.tsx b/docs-site/src/pages/start/shared.tsx
index 6da6166..461444e 100644
--- a/docs-site/src/pages/start/shared.tsx
+++ b/docs-site/src/pages/start/shared.tsx
@@ -1,92 +1,77 @@
 import type { ReactNode } from 'react';
+import { ChipNav } from '../../components/ChipNav';
+import { SectionHeading } from '../../components/SectionHeading';
 import { SectionNav, type SectionNavItem } from '../../components/SectionNav';
-import { SourceLink } from '../../components/SourceLink';
+import { SmallSource as SharedSmallSource } from '../../components/Sources';
 import { StageBadge } from '../../components/StageBadge';
+import { FactStat } from '../../components/StatTile';
 import type { Project } from '../../content/data';
 import { factText, type Fact } from '../../content/facts';
 import { PATHS } from '../../paths';
 import styles from './start.module.css';
 
 /**
- * A fact value followed by a small "source" link and, when the fact carries one,
- * its note in muted text. The link's accessible name names the fact and, when
- * given, the project as written ("source for cost, Self-Service") so repeated
- * links stay distinguishable. Facts marked `notDocumented` render the shared label.
+ * A fact value in running text or a table cell: the value, a small "source" link
+ * and, when the fact carries one, its note in muted text. The link's accessible
+ * name names the fact and, when given, the project as written ("source for cost,
+ * Self-Service") so repeated links stay distinguishable. Facts marked
+ * `notDocumented` render the shared label as a muted pill.
  */
-export function FactValue({
-  fact,
-  label,
-  project,
-  compactNote = false,
-}: {
-  fact: Fact;
-  label: string;
-  project?: string;
-  /** Show the note only from 640 px up (Home tiles, where the caveat repeats on the table and project pages). */
-  compactNote?: boolean;
-}) {
+export function FactValue({ fact, label, project }: { fact: Fact; label: string; project?: string }) {
   return (
     <>
       {fact.notDocumented ? <em className={styles.notDocumented}>{factText(fact)}</em> : factText(fact)}
       {fact.source && (
         <>
           {' '}
-          <SourceLink source={fact.source} className={styles.sourceSmall}>
-            source
-            <span className="visually-hidden">
-              {' '}
-              for {label.toLowerCase()}
-              {project ? `, ${project}` : ''}
-            </span>
-          </SourceLink>
+          <SharedSmallSource source={fact.source} context={`${label.toLowerCase()}${project ? `, ${project}` : ''}`} />
         </>
       )}
-      {fact.note && (
-        <span className={compactNote ? `${styles.factNote} ${styles.factNoteCompact}` : styles.factNote}>{fact.note}</span>
-      )}
+      {fact.note && <span className={styles.factNote}>{fact.note}</span>}
     </>
   );
 }
 
-/** One `dt`/`dd` pair for a compact facts list inside a tile. */
+/**
+ * One `dt`/`dd` pair for a compact facts list inside a tile. Delegates to the
+ * shared `FactStat`; `compactNote` (Home tiles) collapses the caveat behind the
+ * "Why this figure" disclosure.
+ */
 export function FactItem({
   label,
   fact,
   project,
   compactNote = false,
+  icon,
 }: {
   label: string;
   fact: Fact;
   project?: string;
   compactNote?: boolean;
+  icon?: ReactNode;
 }) {
-  return (
-    <div className={styles.fact}>
-      <dt className={styles.factLabel}>{label}</dt>
-      <dd className={styles.factValue}>
-        <FactValue fact={fact} label={label} project={project} compactNote={compactNote} />
-      </dd>
-    </div>
-  );
+  return <FactStat label={label} fact={fact} project={project} icon={icon} noteMode={compactNote ? 'collapsed' : 'inline'} />;
 }
 
 /** Section heading for a project: stage badge plus the full project name. */
 export function ProjectHeading({ project, id }: { project: Project; id: string }) {
   return (
-    <h2 id={id} className={styles.projectHeading}>
-      <StageBadge stage={project.stage} label={`${project.stageNumber}. ${project.stageLabel}`} />
-      <span>{project.name}</span>
-    </h2>
+    <SectionHeading
+      id={id}
+      title={project.name}
+      badge={<StageBadge stage={project.stage} label={`${project.stageNumber}. ${project.stageLabel}`} />}
+    />
   );
 }
 
+/** Stage badge used beside a project heading ("1. Learn"). */
+export function ProjectBadge({ project }: { project: Project }) {
+  return <StageBadge stage={project.stage} label={`${project.stageNumber}. ${project.stageLabel}`} />;
+}
+
 /** Small "source" link for a step or paragraph, with hidden context. */
 export function SmallSource({ source, context }: { source: Fact['source'] & object; context: string }) {
-  return (
-    <SourceLink source={source} className={styles.sourceSmall}>
-      source<span className="visually-hidden"> for {context}</span>
-    </SourceLink>
-  );
+  return <SharedSmallSource source={source} context={context} />;
 }
 
 const START_PAGES: SectionNavItem[] = [
@@ -102,7 +87,7 @@ export function StartNav() {
   return <SectionNav label="Start section" items={START_PAGES} />;
 }
 
-/** In-page jump links to sections further down the same page. */
+/** In-page jump links to sections further down the same page, as a chip rail. */
 export function JumpLinks({
   label,
   items,
@@ -113,17 +98,11 @@ export function JumpLinks({
   lead?: string;
 }) {
   return (
-    <nav aria-label={label} className={styles.jump}>
-      {lead && <span className={styles.jumpLabel}>{lead}</span>}
-      <ul className={styles.chips}>
-        {items.map(({ id, label: itemLabel }) => (
-          <li key={id}>
-            <a href={`#${id}`} className={styles.chip}>
-              {itemLabel}
-            </a>
-          </li>
-        ))}
-      </ul>
-    </nav>
+    <ChipNav
+      label={label}
+      lead={lead}
+      overflow="wrap"
+      items={items.map(({ id, label: itemLabel }) => ({ href: `#${id}`, label: itemLabel }))}
+    />
   );
 }
diff --git a/docs-site/src/pages/start/start.module.css b/docs-site/src/pages/start/start.module.css
index 45d7607..6450d91 100644
--- a/docs-site/src/pages/start/start.module.css
+++ b/docs-site/src/pages/start/start.module.css
@@ -1,49 +1,10 @@
 /*
- * Shared styles for the Home and Start pages: one band (section) style, one
- * tile style, buttons, chips, quickstart steps and the comparison matrix.
- * Colours come from tokens.css only; text inside `.on-dark` bands inherits the
- * on-dark token set.
+ * Styles for the Start section only: page-level layout (hero facts, guidance
+ * columns, path cards, the comparison matrix, FAQ cards) around the shared
+ * primitives. Colours come from tokens.css only; text inside `.on-dark` bands
+ * inherits the on-dark token set.
  */
 
-/* Bands: full-width sections with the token rhythm */
-.band {
-  padding: var(--section-padding-y) 0;
-}
-
-.bandAlt {
-  background: var(--color-bg-secondary);
-  border-top: 1px solid var(--color-border);
-  border-bottom: 1px solid var(--color-border);
-}
-
-.bandDark {
-  background: var(--color-midnight);
-}
-
-.bandTight {
-  padding-top: var(--space-6);
-}
-
-.sectionHead {
-  max-width: 72ch;
-  margin-bottom: var(--space-4);
-}
-
-@media (min-width: 640px) {
-  .sectionHead {
-    margin-bottom: var(--space-6);
-  }
-}
-
-.sectionHead h2 {
-  margin-bottom: var(--space-2);
-}
-
-.lead {
-  color: var(--color-text-secondary);
-  max-width: 72ch;
-}
-
 .prose {
   max-width: 72ch;
 }
@@ -53,7 +14,6 @@
 }
 
 /* Links inside running text carry an underline, not just a colour */
-.lead a,
 .meta a,
 .prose a,
 .stepNote a,
@@ -66,166 +26,6 @@
   text-underline-offset: 0.15em;
 }
 
-/* In-page section navigation (jump chips) */
-.jump {
-  display: flex;
-  flex-wrap: wrap;
-  align-items: center;
-  gap: var(--space-2);
-  margin: var(--space-4) 0;
-}
-
-.jumpLabel {
-  font-size: 0.875rem;
-  font-weight: 600;
-  color: var(--color-text-secondary);
-  margin-right: var(--space-1);
-}
-
-/* Chips: compact inline links or labels */
-.chips {
-  list-style: none;
-  display: flex;
-  flex-wrap: wrap;
-  gap: var(--space-2);
-}
-
-.chip {
-  display: inline-flex;
-  align-items: center;
-  gap: var(--space-1);
-  min-height: 32px;
-  padding: var(--space-1) var(--space-3);
-  border: 1px solid var(--color-border);
-  border-radius: 999px;
-  background: var(--color-bg-secondary);
-  color: var(--color-text-primary);
-  font-size: 0.875rem;
-  font-weight: 500;
-  text-decoration: none;
-}
-
-.chip:hover {
-  color: var(--color-blue-hover);
-  border-color: var(--color-blue);
-  text-decoration: underline;
-}
-
-/* Buttons (links styled as buttons) */
-.actions {
-  display: flex;
-  flex-wrap: wrap;
-  gap: var(--space-3);
-  align-items: center;
-}
-
-.btnPrimary,
-.btnSecondary {
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  gap: var(--space-2);
-  min-height: 44px;
-  padding: var(--space-2) var(--space-4);
-  border-radius: var(--radius-md);
-  font-weight: 600;
-  font-size: 1rem;
-  text-decoration: none;
-  transition:
-    background var(--transition-fast),
-    border-color var(--transition-fast),
-    color var(--transition-fast);
-}
-
-.btnPrimary {
-  background: var(--color-blue);
-  color: #ffffff;
-  border: 1px solid var(--color-blue);
-}
-
-.btnPrimary:hover {
-  background: var(--color-blue-hover);
-  border-color: var(--color-blue-hover);
-  color: #ffffff;
-  text-decoration: none;
-}
-
-.btnSecondary {
-  background: transparent;
-  color: var(--color-text-primary);
-  border: 1px solid var(--color-slate);
-}
-
-.btnSecondary:hover {
-  color: var(--color-blue-hover);
-  border-color: var(--color-blue-hover);
-  text-decoration: none;
-}
-
-:global(.on-dark) .btnSecondary {
-  color: var(--color-cloud);
-  border-color: var(--color-mist);
-}
-
-:global(.on-dark) .btnSecondary:hover {
-  color: var(--color-cloud);
-  border-color: var(--color-cloud);
-  background: rgba(255, 255, 255, 0.08);
-}
-
-:global(.on-dark) .btnPrimary:focus-visible,
-:global(.on-dark) .btnSecondary:focus-visible {
-  outline-color: var(--color-cloud);
-}
-
-/* Tile grid: the one card style used by Home and the Start section */
-.tileGrid {
-  list-style: none;
-  display: grid;
-  grid-template-columns: minmax(0, 1fr);
-  gap: var(--space-3);
-}
-
-@media (min-width: 640px) {
-  .tileGrid {
-    grid-template-columns: repeat(2, minmax(0, 1fr));
-  }
-}
-
-@media (min-width: 1100px) {
-  .tileGrid4 {
-    grid-template-columns: repeat(4, minmax(0, 1fr));
-  }
-}
-
-.tile {
-  display: flex;
-  flex-direction: column;
-  gap: var(--space-1);
-  padding: var(--space-3);
-  line-height: 1.4;
-  background: var(--color-bg-secondary);
-  border: 1px solid var(--color-border);
-  border-top: 4px solid var(--tile-accent, var(--color-border));
-  border-radius: var(--radius-lg);
-}
-
-.tile[data-stage='learn'] {
-  --tile-accent: var(--stage-learn-tint);
-}
-
-.tile[data-stage='build'] {
-  --tile-accent: var(--stage-build-tint);
-}
-
-.tile[data-stage='govern'] {
-  --tile-accent: var(--stage-govern-tint);
-}
-
-.tile[data-stage='scale'] {
-  --tile-accent: var(--stage-scale-tint);
-}
-
 .tileHead {
   display: flex;
   align-items: center;
@@ -238,32 +38,16 @@
   line-height: 1.3;
 }
 
-.tileTagline {
-  color: var(--color-text-secondary);
-  font-size: 0.875rem;
-}
-
 .tileText {
   font-size: 0.875rem;
 }
 
 @media (min-width: 640px) {
-  .tile {
-    gap: var(--space-2);
-    padding: var(--space-4);
-    line-height: 1.45;
-  }
-
   .tileTitle {
     font-size: 1.125rem;
   }
 }
 
-.tileFoot {
-  margin-top: auto;
-  padding-top: var(--space-2);
-}
-
 .tileLink {
   display: inline-flex;
   align-items: center;
@@ -272,44 +56,21 @@
   font-weight: 600;
 }
 
-/* Compact facts inside tiles and table cells */
-.facts {
-  display: grid;
-  gap: var(--space-1);
-  margin: var(--space-1) 0 0;
-  padding-top: var(--space-2);
-  border-top: 1px solid var(--color-border);
-  font-size: 0.8125rem;
-}
-
-@media (min-width: 640px) {
-  .facts {
-    gap: var(--space-2);
-    font-size: 0.875rem;
-  }
-}
-
-.fact {
-  margin: 0;
-}
-
-.factLabel {
-  display: inline;
-  font-weight: 600;
-  color: var(--color-text-secondary);
-}
-
-.factLabel::after {
-  content: ': ';
-}
-
-.factValue {
-  display: inline;
-  margin: 0;
-}
-
+/* "not documented" as a muted pill, so a gap reads as a state rather than a value */
 .notDocumented {
+  display: inline-flex;
+  align-items: center;
+  min-height: var(--target-min);
+  padding: 0 var(--space-2);
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-pill);
+  background: var(--color-surface-sunken);
   color: var(--color-text-secondary);
+  font-size: var(--text-xs);
+  font-style: normal;
+  font-weight: 600;
+  line-height: 1;
+  white-space: nowrap;
 }
 
 /* A fact's caveat, shown under the value in muted text */
@@ -321,17 +82,6 @@
   color: var(--color-text-secondary);
 }
 
-/* Opt-in variant for the Home tiles: the same caveats appear on the comparison table and the project pages, so keep them for wider screens only */
-.factNote.factNoteCompact {
-  display: none;
-}
-
-@media (min-width: 640px) {
-  .factNote.factNoteCompact {
-    display: block;
-  }
-}
-
 /* Compact row of related links under a quickstart */
 .linkRow {
   display: flex;
@@ -360,23 +110,18 @@
   color: var(--color-text-secondary);
 }
 
-/* Project sections on the Start pages */
-.projectSection {
-  padding: var(--space-8) 0;
-  border-top: 1px solid var(--color-border);
-  scroll-margin-top: calc(var(--header-height) + var(--space-4));
-}
-
-.projectSection:first-of-type {
-  border-top: none;
+/* First-deploy row on the Start header band: one StatTile per project */
+.heroFacts {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: var(--space-3) var(--space-6);
+  margin: 0;
 }
 
-.projectHeading {
-  display: flex;
-  flex-wrap: wrap;
-  align-items: center;
-  gap: var(--space-3);
-  margin-bottom: var(--space-3);
+@media (min-width: 1024px) {
+  .heroFacts {
+    grid-template-columns: repeat(4, minmax(0, 1fr));
+  }
 }
 
 .subSection {
@@ -395,57 +140,14 @@
   margin-top: var(--space-2);
 }
 
-/* Quickstart steps */
-.steps {
-  list-style: none;
-  counter-reset: step;
-  display: grid;
-  grid-template-columns: minmax(0, 1fr);
-  gap: var(--space-3);
-  margin: var(--space-4) 0;
-}
-
-.step {
-  counter-increment: step;
-  position: relative;
-  min-width: 0;
-  padding-left: var(--space-10);
-}
-
-.step::before {
-  content: counter(step);
-  position: absolute;
-  left: 0;
-  top: 0;
-  width: 28px;
-  height: 28px;
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  border-radius: 999px;
-  background: var(--color-midnight);
-  color: var(--color-cloud);
-  font-size: 0.875rem;
-  font-weight: 700;
-}
-
+/* Quickstart steps: title text followed by its small source link */
 .stepTitle {
-  font-weight: 600;
-  min-height: 28px;
-  display: flex;
-  align-items: center;
-  flex-wrap: wrap;
-  gap: var(--space-1) var(--space-2);
+  display: inline;
 }
 
 .stepNote {
   font-size: 0.9375rem;
   color: var(--color-text-secondary);
-  margin-top: var(--space-1);
-}
-
-.step :global(pre) {
-  margin: var(--space-2) 0;
 }
 
 /* Plain lists with a bold lead-in per item */
@@ -461,23 +163,102 @@
   gap: var(--space-3);
 }
 
+/* "By role" and "By time available" side by side from 1024 px up */
+.guidance {
+  padding: var(--space-10) 0;
+  border-top: 1px solid var(--color-border);
+}
+
 .twoCol {
   display: grid;
-  gap: var(--space-4) var(--space-8);
+  gap: var(--space-8);
 }
 
-@media (min-width: 768px) {
+@media (min-width: 1024px) {
   .twoCol {
     grid-template-columns: repeat(2, minmax(0, 1fr));
   }
 }
 
+/* Path cards on the comparison page: four accent cards */
+.pathGrid {
+  list-style: none;
+  display: grid;
+  grid-template-columns: minmax(0, 1fr);
+  gap: var(--space-4);
+}
+
+@media (min-width: 640px) {
+  .pathGrid {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+}
+
+@media (min-width: 1280px) {
+  .pathGrid {
+    grid-template-columns: repeat(4, minmax(0, 1fr));
+  }
+}
+
+.pathCard {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-2);
+}
+
+.pathFacts,
+.compareFacts {
+  display: grid;
+  gap: var(--space-3);
+  margin: auto 0 0;
+  padding-top: var(--space-3);
+  border-top: 1px solid var(--color-border);
+}
+
+.stageIcon {
+  flex-shrink: 0;
+  color: var(--stage-color, currentColor);
+}
+
 /*
  * Comparison matrix: columns are the four projects, rows are the facts. Fixed
  * layout gives the four project columns equal widths; the fact label column is
  * sticky so it stays in view when the table scrolls on narrow screens. At the
  * container's maximum width the table fits without horizontal scrolling.
+ * Below 640 px the table is replaced by one card per project (.matrixCards).
  */
+.matrixDesktop {
+  display: none;
+}
+
+.matrixCards {
+  list-style: none;
+  display: grid;
+  gap: var(--space-4);
+  margin: var(--space-4) 0;
+}
+
+@media (min-width: 640px) {
+  .matrixDesktop {
+    display: block;
+  }
+
+  .matrixCards {
+    display: none;
+  }
+}
+
+.compareCard {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-2);
+}
+
+.compareTitle {
+  font-size: 1.0625rem;
+  line-height: 1.3;
+}
+
 .matrix {
   width: 100%;
   min-width: 860px;
@@ -513,12 +294,37 @@
   left: 0;
   z-index: 1;
   width: 150px;
-  background: var(--color-bg-secondary);
+  background: var(--color-surface);
   box-shadow: 1px 0 0 var(--color-border);
 }
 
 .matrix thead th:first-child {
-  background: var(--color-cloud);
+  background: var(--color-surface-sunken);
+}
+
+/* Stage-coloured rule over each project column */
+.matrix thead th[data-stage] {
+  border-top: 3px solid var(--column-stage, var(--color-border));
+}
+
+.matrix thead th[data-stage='learn'] {
+  --column-stage: var(--stage-learn-tint);
+  --stage-color: var(--stage-learn);
+}
+
+.matrix thead th[data-stage='build'] {
+  --column-stage: var(--stage-build-tint);
+  --stage-color: var(--stage-build);
+}
+
+.matrix thead th[data-stage='govern'] {
+  --column-stage: var(--stage-govern-tint);
+  --stage-color: var(--stage-govern);
+}
+
+.matrix thead th[data-stage='scale'] {
+  --column-stage: var(--stage-scale-tint);
+  --stage-color: var(--stage-scale);
 }
 
 .matrixProject {
@@ -527,16 +333,61 @@
   justify-items: start;
 }
 
+.matrixName {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-2);
+  font-weight: 600;
+}
+
+/* The "Best for" row is the decision row; give it a sunken background, sticky label included */
+.matrix .bestForRow td,
+.matrix .bestForRow th {
+  background: var(--color-surface-sunken);
+}
+
+/* Fact icon beside each row label */
+.rowLabel {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-2);
+}
+
+.rowLabel > svg {
+  flex-shrink: 0;
+  color: var(--color-text-secondary);
+}
+
 .matrixHint {
   margin-top: var(--space-2);
 }
 
-/* Table cells hold a value plus a small source link */
-.cell {
-  display: block;
+/* FAQ: question chips wrap onto several lines, since questions are whole sentences */
+.faqNav a {
+  white-space: normal;
+  text-align: left;
 }
 
-.cell .sourceSmall {
-  display: inline-block;
-  margin-top: var(--space-1);
+/* FAQ: one card per question */
+.faqList {
+  display: grid;
+  gap: var(--space-4);
+  margin: var(--space-6) 0 var(--section-padding-y);
+}
+
+.faqCard {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-3);
+}
+
+.faqQuestion {
+  font-size: var(--font-size-h3);
+}
+
+.badgeRow {
+  list-style: none;
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--space-2);
 }
diff --git a/docs-site/src/stage.ts b/docs-site/src/stage.ts
index 17ee163..6586ba1 100644
--- a/docs-site/src/stage.ts
+++ b/docs-site/src/stage.ts
@@ -1,3 +1,4 @@
+import { Building2, GraduationCap, Hammer, ShieldCheck, type LucideIcon } from 'lucide-react';
 import type { JourneyStage } from './content/data';
 
 /** Default visible label for each stage; pages may override it (for example "1. Learn"). */
@@ -7,3 +8,11 @@ export const STAGE_LABELS: Record<JourneyStage, string> = {
   govern: 'Govern',
   scale: 'Scale',
 };
+
+/** One icon per stage, used beside stage labels (always rendered aria-hidden next to text). */
+export const STAGE_ICONS: Record<JourneyStage, LucideIcon> = {
+  learn: GraduationCap,
+  build: Hammer,
+  govern: ShieldCheck,
+  scale: Building2,
+};
diff --git a/docs-site/src/styles/designLint.test.ts b/docs-site/src/styles/designLint.test.ts
new file mode 100644
index 0000000..f9d5c71
--- /dev/null
+++ b/docs-site/src/styles/designLint.test.ts
@@ -0,0 +1,63 @@
+import { readdirSync, readFileSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+/**
+ * Design lint: keeps the design system from drifting back into per-page styles.
+ * Every CSS module must express colour through tokens (so the dark theme works),
+ * use the pill radius token, and never redefine buttons. tokens.css is the only
+ * place raw colours may appear.
+ */
+const SRC = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+function cssModules(dir: string): string[] {
+  return readdirSync(dir, { withFileTypes: true, recursive: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith('.module.css'))
+    .map((entry) => join(entry.parentPath ?? entry.path, entry.name));
+}
+
+/** Justified exceptions, each with the reason kept next to the rule in the CSS file. */
+const ALLOW: Record<string, RegExp[]> = {};
+
+const RULES: { name: string; pattern: RegExp; pagesOnly?: boolean }[] = [
+  { name: 'hex colour literal (use a token)', pattern: /#[0-9a-f]{3,8}\b/i },
+  { name: 'white keyword (use --color-surface or --color-on-accent)', pattern: /(?<![\w-])white(?![\w-])/ },
+  { name: 'rgba() literal (use a token or color-mix)', pattern: /\brgba?\(/ },
+  { name: '999px pill literal (use --radius-pill)', pattern: /\b999px\b/ },
+  { name: 'raw palette background (use --color-surface, --color-surface-sunken or --color-band)', pattern: /background(?:-color)?:\s*var\(--color-(?:cloud|mist|midnight|midnight-light)\)/ },
+  { name: 'button class outside Button.module.css', pattern: /\.(?:btn[A-Z]\w*|action(?:Primary|Secondary)|primary|secondary|homeLink|backButton)\b(?=[^;{]*\{)/ },
+  { name: ':global(.on-dark) in a page module (use tokens)', pattern: /:global\(\.on-dark\)/, pagesOnly: true },
+];
+
+// `npm test` sets DESIGN_LINT=1; a bare `vitest run` skips this suite so component-only runs stay fast.
+describe.skipIf(!process.env.DESIGN_LINT)('design lint over CSS modules', () => {
+  const files = cssModules(SRC);
+
+  it('finds the CSS modules', () => {
+    expect(files.length).toBeGreaterThan(10);
+  });
+
+  for (const file of files) {
+    const rel = relative(SRC, file);
+    it(rel, () => {
+      const css = readFileSync(file, 'utf8')
+        // Drop comments so documented exceptions and explanations do not trip the rules.
+        .replace(/\/\*[\s\S]*?\*\//g, '');
+      const isButton = rel.endsWith('components/Button.module.css');
+      const isPage = rel.startsWith('pages/');
+      const problems: string[] = [];
+      for (const rule of RULES) {
+        if (rule.pagesOnly && !isPage) continue;
+        if (isButton && rule.name.startsWith('button class')) continue;
+        const allowed = ALLOW[rel] ?? [];
+        for (const line of css.split('\n')) {
+          if (!rule.pattern.test(line)) continue;
+          if (allowed.some((ok) => ok.test(line))) continue;
+          problems.push(`${rule.name}: ${line.trim()}`);
+        }
+      }
+      expect(problems, `${rel} violates the design system`).toEqual([]);
+    });
+  }
+});
diff --git a/docs-site/src/styles/tokens.css b/docs-site/src/styles/tokens.css
index 68c6d93..e40ef9c 100644
--- a/docs-site/src/styles/tokens.css
+++ b/docs-site/src/styles/tokens.css
@@ -1,5 +1,8 @@
-/* CSS Design Tokens - Atlas Journey Theme */
+/* CSS Design Tokens - Atlas Journey Theme
+   Breakpoints used across the site: 640px (one to two columns), 1024px (desktop nav,
+   header figure column), 1280px (doc page rails). Component styles use these three only. */
 :root {
+  color-scheme: light dark;
   /* Primary palette */
   --color-midnight: #0B1220;
   --color-midnight-light: #1a2744;
@@ -65,6 +68,24 @@
   --color-border: var(--color-mist);
   --color-blue-hover: #1d4ed8;
 
+  /* Surfaces and roles. Components use these, never the raw palette above, so the
+     dark theme (see the prefers-color-scheme block) only has to remap this list. */
+  --color-surface: #ffffff;                 /* cards, tables, chips */
+  --color-surface-sunken: var(--color-cloud); /* table heads, inset fact boxes */
+  --color-band: var(--color-midnight);      /* page headers, footer, dark bands, code blocks */
+  --color-band-raised: var(--color-midnight-light);
+  --color-link: var(--color-blue);
+  --color-link-hover: var(--color-blue-hover);
+  --color-accent: var(--color-blue);        /* primary buttons */
+  --color-on-accent: #ffffff;
+  --color-focus: var(--color-blue);
+  --color-code-bg: var(--color-mist);
+  --color-code-text: inherit;
+  --color-overlay-hover: rgba(37, 99, 235, 0.06);
+  --color-overlay-strong: rgba(255, 255, 255, 0.12);
+  --color-figure-panel: #ffffff;            /* raster diagrams have white interiors */
+  --focus-ring: 2px solid var(--color-focus);
+
   /* Typography */
   --font-sans: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
   --font-mono: ui-monospace, SFMono-Regular, 'SF Mono', Menlo, monospace;
@@ -75,6 +96,13 @@
   --font-size-h3: clamp(1.125rem, 2.5vw, 1.5rem);
   --font-size-h4: 1.125rem;
 
+  /* Body text scale and the tracking used by every uppercase label */
+  --text-xs: 0.75rem;
+  --text-sm: 0.875rem;
+  --text-base: 1rem;
+  --text-lg: 1.125rem;
+  --label-tracking: 0.06em;
+
   /* Spacing scale */
   --space-1: 0.25rem;
   --space-2: 0.5rem;
@@ -98,11 +126,14 @@
   --radius-md: 0.5rem;
   --radius-lg: 0.75rem;
   --radius-xl: 1rem;
+  --radius-pill: 999px;
 
   /* Shadows */
   --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);
   --shadow-md: 0 4px 6px rgba(0, 0, 0, 0.1);
   --shadow-lg: 0 10px 15px rgba(0, 0, 0, 0.1);
+  /* Resting shadow for cards, so a hover lift starts from something */
+  --shadow-card: 0 1px 2px rgba(11, 18, 32, 0.06);
 
   /* Transitions */
   --transition-fast: 150ms ease;
@@ -140,9 +171,65 @@
   --stage-fill-text: var(--color-midnight);
   --color-text-primary: var(--color-cloud);
   --color-text-secondary: var(--color-text-inverse-muted);
+  --color-link: var(--stage-scale-on-dark);
+  --color-link-hover: var(--color-cloud);
+  --color-focus: var(--color-cloud);
+  --color-overlay-hover: rgba(255, 255, 255, 0.08);
   color: var(--color-text-inverse);
 }
 
+/*
+ * Dark theme: follows the operating system preference (no toggle, no storage). Only the
+ * semantic tokens are remapped; the palette above and every component stay the same.
+ * Header, footer and other `.on-dark` bands keep `--color-band`, which is darker than the
+ * page so they still read as bands. Stage colours resolve to the on-dark set everywhere.
+ */
+@media (prefers-color-scheme: dark) {
+  :root {
+    --color-bg-primary: #0F172A;
+    --color-bg-secondary: #16213A;
+    --color-surface: #16213A;
+    --color-surface-sunken: #0F172A;
+    --color-band: #070B14;
+    --color-band-raised: #1E2A47;
+    --color-text-primary: #F5F7FB;
+    --color-text-secondary: #A3B1C6;
+    --color-text-muted: #64748B;
+    --color-border: #2A3650;
+    --color-link: #93C5FD;
+    --color-link-hover: #BFDBFE;
+    --color-blue-hover: #BFDBFE;
+    --color-focus: #93C5FD;
+    --color-code-bg: #1E293B;
+    --color-code-text: #E2E8F0;
+    --color-overlay-hover: rgba(255, 255, 255, 0.08);
+    --shadow-card: 0 0 0 1px rgba(255, 255, 255, 0.02);
+    --shadow-lg: 0 10px 24px rgba(0, 0, 0, 0.5);
+    --tint-amber: #2C1A0B;
+    --tint-green: #0B2416;
+    --tint-violet: #1E1538;
+    --tint-blue: #0F1F3D;
+    --tint-heading-amber: var(--stage-learn-on-dark);
+    --tint-heading-green: var(--stage-build-on-dark);
+    --tint-heading-violet: var(--stage-govern-on-dark);
+    --tint-heading-blue: var(--stage-scale-on-dark);
+    --stage-learn: var(--stage-learn-on-dark);
+    --stage-build: var(--stage-build-on-dark);
+    --stage-govern: var(--stage-govern-on-dark);
+    --stage-scale: var(--stage-scale-on-dark);
+    --stage-fill-text: var(--color-midnight);
+  }
+
+  /* Inline code inside a link on a dark page: the chip is dark, so keep the light link colour. */
+  a code {
+    color: var(--color-link);
+  }
+
+  :where(.on-dark) a code {
+    color: var(--color-link);
+  }
+}
+
 /* Reset and base */
 *, *::before, *::after {
   box-sizing: border-box;
@@ -202,13 +289,13 @@ h5 { font-size: 1rem; }
 h6 { font-size: 1rem; }
 
 a {
-  color: var(--color-blue);
+  color: var(--color-link);
   text-decoration: none;
   transition: color var(--transition-fast);
 }
 
 a:hover {
-  color: var(--color-blue-hover);
+  color: var(--color-link-hover);
   text-decoration: underline;
 }
 
@@ -227,29 +314,19 @@ a:hover {
 }
 
 a:focus-visible {
-  outline: 2px solid var(--color-blue);
+  outline: var(--focus-ring);
   outline-offset: 2px;
   border-radius: var(--radius-sm);
 }
 
-/* Defaults for links on dark surfaces. `:where()` keeps them at element specificity so any
-   class (buttons, footer links) overrides them without having to know about `.on-dark`. */
-:where(.on-dark) a {
-  color: var(--stage-scale-on-dark);
-}
-
-:where(.on-dark) a:hover {
-  color: var(--color-cloud);
-}
-
-:where(.on-dark) a:focus-visible {
-  outline-color: var(--color-cloud);
-}
+/* Links on dark surfaces take their colours from the `.on-dark` token remap above
+   (`--color-link`, `--color-link-hover`, `--color-focus`), so no extra rules are needed. */
 
 code {
   font-family: var(--font-mono);
   font-size: 0.875em;
-  background: var(--color-mist);
+  background: var(--color-code-bg);
+  color: var(--color-code-text);
   padding: 0.125em 0.375em;
   border-radius: var(--radius-sm);
 }
@@ -258,7 +335,7 @@ code {
    link blue clears 4.5:1 on mist and on cloud. On dark surfaces the chip stays light,
    so the code text goes midnight. */
 a code {
-  color: var(--color-blue-hover);
+  color: var(--color-link-hover);
 }
 
 :where(.on-dark) a code {
@@ -282,7 +359,7 @@ pre code {
   top: -100%;
   left: 50%;
   transform: translateX(-50%);
-  background: var(--color-midnight);
+  background: var(--color-band);
   color: var(--color-cloud);
   padding: var(--space-2) var(--space-4);
   border-radius: var(--radius-md);
@@ -292,7 +369,7 @@ pre code {
 
 .skip-link:focus {
   top: var(--space-2);
-  outline: 2px solid var(--color-blue);
+  outline: var(--focus-ring);
   outline-offset: 2px;
 }
 
@@ -316,19 +393,6 @@ pre code {
   padding: 0 var(--page-padding-x);
 }
 
-/* Vertical rhythm for a page section */
-.page-section {
-  padding: var(--section-padding-y) 0;
-}
-
-.placeholder-page h1 {
-  margin-bottom: var(--space-4);
-}
-
-.placeholder-page p {
-  color: var(--color-text-secondary);
-}
-
 /* ---------------------------------------------------------------------------
    Motion utilities. Everything here is progressive enhancement: content is fully
    visible without JavaScript, in browsers without scroll-driven animations, and
diff --git a/docs-site/tests/browser/screenshots.spec.ts b/docs-site/tests/browser/screenshots.spec.ts
new file mode 100644
index 0000000..fddab45
--- /dev/null
+++ b/docs-site/tests/browser/screenshots.spec.ts
@@ -0,0 +1,57 @@
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { test } from '@playwright/test';
+import { DIST_DIR, href } from './routes';
+
+/**
+ * Full-page captures for review, not a gate. Skipped unless SCREENSHOTS=1.
+ *
+ *   SCREENSHOTS=1 SHOT_DIR=/tmp/shots npx playwright test screenshots
+ *
+ * Runs in every configured project (light and dark, desktop and mobile). Animations
+ * are disabled and reduced motion requested so captures are deterministic. Files land
+ * outside dist/ (default `screenshots/`, git-ignored).
+ */
+const ROUTES = [
+  '/',
+  '/start/',
+  '/start/which-project/',
+  '/start/faq/',
+  '/concepts/agent-factory/',
+  '/concepts/capability-contracts/',
+  '/concepts/architecture/',
+  '/concepts/glossary/',
+  '/projects/',
+  '/projects/blueprint/',
+  '/projects/workshop/',
+  '/projects/mcp-gateway/policies/',
+  '/reference/security/',
+  '/reference/support-envelope/',
+  '/projects/blueprint/readme/',
+  '/contributing/',
+];
+
+test.describe('screenshots', () => {
+  test.skip(!process.env.SCREENSHOTS, 'set SCREENSHOTS=1 to capture');
+
+  for (const route of ROUTES) {
+    test(`capture ${route}`, async ({ page }, testInfo) => {
+      const dir = process.env.SHOT_DIR ?? join(DIST_DIR, '..', 'screenshots');
+      mkdirSync(dir, { recursive: true });
+      await page.emulateMedia({ reducedMotion: 'reduce' });
+      await page.goto(href(route), { waitUntil: 'networkidle' });
+      await page.addStyleTag({ content: 'html { scroll-behavior: auto !important; }' });
+      // Lazy images load once scrolled into view.
+      await page.evaluate(async () => {
+        for (let y = 0; y <= document.documentElement.scrollHeight; y += 700) {
+          window.scrollTo(0, y);
+          await new Promise((resolve) => setTimeout(resolve, 60));
+        }
+        window.scrollTo(0, 0);
+      });
+      await page.waitForTimeout(300);
+      const name = `${testInfo.project.name}${route.replace(/\//g, '_') || '_'}.png`;
+      await page.screenshot({ path: join(dir, name), fullPage: true, animations: 'disabled' });
+    });
+  }
+});
diff --git a/docs-site/tests/browser/structure.spec.ts b/docs-site/tests/browser/structure.spec.ts
new file mode 100644
index 0000000..eae11cf
--- /dev/null
+++ b/docs-site/tests/browser/structure.spec.ts
@@ -0,0 +1,93 @@
+import { expect, test } from '@playwright/test';
+import { href, sweepRoutes } from './routes';
+
+/**
+ * Structural guardrails for the design system: every page has one dark page header
+ * with the single h1, colour is never the only cue in the posture matrices, the Home
+ * capability stack carries a text alternative for its dots, and doc pages carry the
+ * progress bar. Runs in the light and dark projects.
+ */
+const { routes } = sweepRoutes();
+
+test.describe('page header', () => {
+  for (const route of routes) {
+    test(`one dark page header with the single h1 on ${route}`, async ({ page }) => {
+      await page.goto(href(route));
+      await expect(page.locator('header.on-dark[data-page-header]')).toHaveCount(1);
+      await expect(page.locator('header.on-dark[data-page-header] h1')).toHaveCount(1);
+      await expect(page.locator('h1')).toHaveCount(1);
+    });
+  }
+});
+
+test.describe('theme', () => {
+  test('the page follows the colour scheme of the project', async ({ page }, testInfo) => {
+    await page.goto(href('/'));
+    const dark = testInfo.project.use.colorScheme === 'dark';
+    const state = await page.evaluate(() => {
+      const bg = getComputedStyle(document.body).backgroundColor;
+      const match = bg.match(/\d+/g)?.map(Number) ?? [255, 255, 255];
+      const luminance = (0.2126 * match[0] + 0.7152 * match[1] + 0.0722 * match[2]) / 255;
+      return { prefersDark: matchMedia('(prefers-color-scheme: dark)').matches, luminance };
+    });
+    expect(state.prefersDark).toBe(dark);
+    if (dark) expect(state.luminance, 'dark page background').toBeLessThan(0.2);
+    else expect(state.luminance, 'light page background').toBeGreaterThan(0.8);
+    const meta = page.locator('meta[name="color-scheme"]');
+    await expect(meta).toHaveAttribute('content', 'light dark');
+  });
+});
+
+test.describe('posture matrices keep icon and text alongside colour', () => {
+  for (const route of ['/concepts/capability-contracts/', '/reference/security/']) {
+    test(route, async ({ page }) => {
+      await page.goto(href(route));
+      const cells = page.locator('[data-posture-matrix] tbody td');
+      const count = await cells.count();
+      expect(count).toBeGreaterThan(0);
+      for (let i = 0; i < count; i += 1) {
+        const cell = cells.nth(i);
+        await expect(cell.locator('svg').first()).toBeAttached();
+        const text = (await cell.innerText()).trim();
+        expect(text.length, `cell ${i} has a text label`).toBeGreaterThan(0);
+      }
+    });
+  }
+});
+
+test.describe('home capability stack', () => {
+  test('exposes four posture dots per capability and a hidden sentence each', async ({ page }) => {
+    await page.goto(href('/'));
+    const stack = page.locator('[data-capability-stack]');
+    await expect(stack).toHaveCount(1);
+    await expect(stack.locator('[data-fill]')).toHaveCount(40);
+    await expect(stack.locator('[data-posture-text]')).toHaveCount(10);
+    const links = stack.locator('a[href*="/concepts/capability-contracts/#matrix-"]');
+    await expect(links).toHaveCount(10);
+  });
+
+  test('the journey strip lists the four stages in order', async ({ page }) => {
+    await page.goto(href('/'));
+    const items = page.locator('[data-stage-journey]').first().locator('li');
+    await expect(items).toHaveCount(4);
+    expect(await items.evaluateAll((els) => els.map((el) => el.getAttribute('data-stage')))).toEqual([
+      'learn',
+      'build',
+      'govern',
+      'scale',
+    ]);
+  });
+});
+
+test.describe('doc pages', () => {
+  test('carry an aria-hidden reading progress bar and a back-to-top link', async ({ page }) => {
+    await page.goto(href('/projects/blueprint/readme/'));
+    const bar = page.locator('[data-reading-progress]');
+    await expect(bar).toHaveCount(1);
+    await expect(bar).toHaveAttribute('aria-hidden', 'true');
+    const box = await bar.boundingBox();
+    // Fixed and transform-only: it never takes layout space.
+    expect(box === null || box.height <= 4).toBe(true);
+    await expect(page.getByRole('link', { name: /back to top/i })).toHaveAttribute('href', '#main-content');
+  });
+});