feat(docs-portal): Phase 2a — the swatch page, and the first look at the token system

Closes the gap the Phase 1 handoff called its defining caveat: 35 tokens shipped
and verified entirely by static analysis and contrast arithmetic, with not one
rendered in a browser. Spec: context-v/specs/Design-System-Portal.md §3.

A standalone app at apps/docs-portal on :3020 — deliberately not a federation
remote, since it is not in DESIGN.md's member registry and needs the full
theme.css for its mode toggle to have anything to switch between. Its own chrome
is built only from Tier-2 tokens, so a broken token cannot hide behind a colour
the page smuggled in.

Two rules keep it honest. It never paints from the manifest's recorded values —
it sets data-mode and lets the browser resolve var() through the real cascade,
because a page painted from JSON proves the JSON is well-formed and nothing
about the stylesheet. And contrast is measured from the painted cell, not
computed from the theme source.

design-manifest.json is now generated alongside token-baseline.css from the same
theme.css parse. DESIGN.md's frontmatter already named it as `full_manifest` and
the spec already read from it; it just did not exist. `tokens:check` now guards
both, so the portal cannot disagree with the theme about which tokens exist.

WHAT LOOKING AT IT FOUND, INCLUDING IN ITSELF

Three defects in the page, each invisible to a build and a typecheck:

Every contrast cell read as unmeasured. getPropertyValue on a custom property
returns the substituted value, which in this theme is a hex string, and a naive
rgb parse matched the digits inside the hex. Measuring the painted cell fixes it
and makes the code match what its own comment claimed.

Every reading was taken mid-transition. theme.css:289 animates colour over 75ms
on a mode swap, so a measurement two frames after the switch caught colours
still moving — it reported the dark page background as light grey and every
vibrant foreground token as failing. Measurement now suppresses transitions and
forces a style flush first.

Grading the full cross-product produced 75 failures, none real: the grid pairs
every token with every surface, and most pairings the product never makes. Only
foreground tokens are graded now; structural ones show a measurement without a
verdict. A checker that cries wolf is one nobody reads.

Two findings that were the page misclassifying, not the theme:

--color-thread was graded as text at 4.5:1. DESIGN.md classifies it as a line
that tracks --color-border, target 3. Moved to the boundary rule.

--color-on-accent was graded against surfaces it never touches, producing 15
phantom failures. DESIGN.md calls it mandatory on accent fills, so it now has
its own accent-fill section testing it where it is actually used. It passes
comfortably — 5.19 to 14.11 across every fill and mode.

WHAT IT FOUND IN THE THEME

A22 reproduced visually: --color-border misses 3:1 on all five surfaces in all
three modes, 1.0 to 1.29 in dark.

A22 is wider than recorded: --color-thread carries the border value, so the chat
thread rail sits below the boundary bar too. The gate names only the border.

A3's solve does not hold: --color-border-strong was introduced with a new Tier-1
step per ramp "solved for >=3:1 against every surface in its mode". Measured, it
fails on surface in dark (2.73), on bg-elevated in vibrant, and on ALL FIVE
surfaces in light. Raised separately rather than folded in here.

Verified: 20 packages build, portal 74 files typecheck clean, all three modes
render distinct and correct backgrounds, toggle stays in sync with data-mode via
onModeChange.

Files changed:
- apps/docs-portal/** (new)
- design-manifest.json (new, generated)
- scripts/generate-token-baseline.mjs

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019a8tSPbFdvF1pKtADnWyDg

Author: mpstaton

apps/docs-portal/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@augment-it/docs-portal",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "rsbuild dev",
+    "build": "rsbuild build",
+    "preview": "rsbuild preview",
+    "check": "svelte-check --tsconfig ./tsconfig.json"
+  },
+  "dependencies": {
+    "@augment-it/theme": "workspace:*",
+    "svelte": "^5.56.4"
+  },
+  "devDependencies": {
+    "@rsbuild/core": "^2.1.2",
+    "@rsbuild/plugin-svelte": "^2.0.0",
+    "svelte-check": "^4.7.1",
+    "typescript": "^6.0.3"
+  }
+}

apps/docs-portal/rsbuild.config.ts

@@ -0,0 +1,19 @@
+import { defineConfig } from '@rsbuild/core';
+import { pluginSvelte } from '@rsbuild/plugin-svelte';
+
+// The design-system portal. Deliberately NOT a federation remote — it is not in
+// DESIGN.md's member registry, it is a development surface for looking at the
+// token system, and it must load the FULL theme.css (all three mode blocks) so
+// the mode toggle has something to switch between.
+export default defineConfig({
+  plugins: [pluginSvelte()],
+  source: { entry: { index: './src/index.ts' } },
+  output: {
+    target: 'web',
+    overrideBrowserslist: ['last 2 Chrome versions', 'last 2 Firefox versions', 'last 2 Safari versions'],
+  },
+  tools: { swc: { jsc: { target: 'es2022' } } },
+  html: { title: 'augment-it · design system' },
+  server: { port: 3020 },
+  dev: { assetPrefix: 'http://localhost:3020' },
+});

apps/docs-portal/src/App.svelte

@@ -0,0 +1,251 @@
+<script lang="ts">
+  // Phase 2a — the P0 swatch page.
+  // Spec: context-v/specs/Design-System-Portal.md §3
+  //
+  // The point of this page is that it is the FIRST surface on which the token
+  // system has ever been looked at. Phases 0 and 1 shipped 35 tokens verified
+  // entirely by static analysis and contrast arithmetic; not one had been
+  // rendered in a browser. Everything here is deliberately shallow so that what
+  // you are judging is the tokens, not the page.
+  //
+  // Two rules keep it honest:
+  //
+  //  1. It NEVER paints from the manifest's recorded values. It sets data-mode
+  //     and lets the browser resolve `var(--token)` through the real cascade.
+  //     A page that painted from JSON would prove the JSON is well-formed and
+  //     nothing about the stylesheet.
+  //  2. Contrast is measured from getComputedStyle AFTER paint, not computed
+  //     from the theme source. Same reason.
+  import { onMount } from 'svelte';
+  import { MODES, getMode, setMode, onModeChange, type Mode } from '@augment-it/theme/mode-switcher';
+  import manifest from '../../../design-manifest.json';
+
+  const SURFACES: string[] = manifest.surfaces;
+  const COLOR_TOKENS: string[] = manifest.groups.color;
+  const EFFECT_TOKENS: string[] = manifest.groups.effect;
+  const TIER1 = Object.entries(manifest.tier1 as Record<string, string>)
+    .filter(([n]) => n.startsWith('--color__'));
+
+  let mode = $state<Mode>('dark');
+  let ratios = $state<Record<string, number>>({});
+  let probe: HTMLDivElement;
+
+  function luminance(rgb: number[]): number {
+    const a = rgb.map((v) => {
+      const s = v / 255;
+      return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
+    });
+    return 0.2126 * a[0] + 0.7152 * a[1] + 0.0722 * a[2];
+  }
+
+  function parseRgb(s: string): number[] | null {
+    const m = s.match(/\d+(\.\d+)?/g);
+    return m && m.length >= 3 ? m.slice(0, 3).map(Number) : null;
+  }
+
+  /**
+   * Measure every (token, surface) pair from the PAINTED cell.
+   *
+   * Not from the custom-property values: getPropertyValue('--color-text')
+   * returns the substituted token value, which in this theme is a hex string
+   * (`#e8eaf0`), and a naive rgb parse silently matches the digits inside the
+   * hex and returns nonsense. Reading `color` / `backgroundColor` off the cell
+   * always yields `rgb(...)`, and — more importantly — it measures what the
+   * browser actually rendered rather than what the stylesheet says it should.
+   * That distinction is the whole reason this page exists.
+   */
+  function measure(): void {
+    if (!probe) return;
+    // theme.css:289 transitions background-color/color/border-color over 75ms
+    // on the theme swap. Measuring inside that window reads colours that are
+    // still animating — it reported the dark page background as a light grey
+    // and every vibrant foreground token as failing, none of which was real.
+    // Suppress transitions, force a synchronous style flush, measure the
+    // settled values, then restore.
+    document.documentElement.classList.add('measuring');
+    void document.documentElement.offsetHeight;
+    const next: Record<string, number> = {};
+    for (const cell of probe.querySelectorAll<HTMLElement>('.swatch[data-token]')) {
+      const token = cell.dataset.token;
+      const surface = cell.dataset.surface;
+      if (!token || !surface) continue;
+      const cs = getComputedStyle(cell);
+      const fg = parseRgb(cs.color);
+      const bg = parseRgb(cs.backgroundColor);
+      if (!fg || !bg) continue;
+      const l1 = luminance(fg);
+      const l2 = luminance(bg);
+      next[`${token}|${surface}`] = Math.round(((Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05)) * 100) / 100;
+    }
+    const acc: Record<string, number> = {};
+    for (const cell of probe.querySelectorAll<HTMLElement>('.accent-cell[data-fill]')) {
+      const cs = getComputedStyle(cell);
+      const fg = parseRgb(cs.color);
+      const bg = parseRgb(cs.backgroundColor);
+      if (!fg || !bg) continue;
+      const l1 = luminance(fg);
+      const l2 = luminance(bg);
+      acc[cell.dataset.fill!] = Math.round(((Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05)) * 100) / 100;
+    }
+    document.documentElement.classList.remove('measuring');
+    ratios = next;
+    accentRatios = acc;
+  }
+
+  function pick(next: Mode): void {
+    // setMode dispatches mode-change, which the onModeChange subscription above
+    // turns into the state update + remeasure. One path, so a click and an
+    // external change behave identically.
+    setMode(next);
+  }
+
+  onMount(() => {
+    mode = getMode();
+    remeasure();
+    // The mode can change from outside this component — another tab, or (once
+    // the portal is federated) the shell, which owns data-mode for every
+    // remote. Without this the toggle keeps showing whatever was last clicked
+    // here while the page renders something else entirely.
+    return onModeChange((next) => {
+      mode = next;
+      remeasure();
+    });
+  });
+
+  /** Two frames: one for the attribute to land, one for the cascade to settle. */
+  function remeasure(): void {
+    requestAnimationFrame(() => requestAnimationFrame(measure));
+  }
+
+  // Only FOREGROUND tokens get a pass/fail grade.
+  //
+  // The grid is a full cross-product, so most cells are pairings the product
+  // never makes — `--color-surface` painted as text on `--color-surface-2` is
+  // not a thing. Grading all 150 produced 75 "failures", none of which were
+  // real, and a checker that cries wolf is one nobody reads. Structural tokens
+  // still show their measured ratio (useful for spotting a token that has
+  // collided with a surface), just without a verdict attached.
+  // --color-on-accent is deliberately absent: DESIGN.md calls it "mandatory on
+  // any accent fill — never assume white", so it belongs ON the accent, never
+  // on a surface. Grading it against surfaces reported 15 failures that were
+  // purely an artefact of testing it somewhere it is never used. It gets its
+  // own accent-fill check below instead.
+  const FOREGROUND = /^--color-(text|link|accent|accent-2|accent-warm|ok-text|error-text|warn-text|confidence-)/;
+  const isForeground = (token: string) => FOREGROUND.test(token);
+
+  // Structural tokens are meant to be seen AS a surface or a line, not read
+  // through. 3:1 is the WCAG 1.4.11 bar for a UI boundary.
+  // --color-thread is here on DESIGN.md's own classification: "Connector lines
+  // — the chat thread rail. A line, so it tracks --color-border", target 3.
+  const BOUNDARY = /^--color-(border|border-strong|focus|thread)/;
+
+  // The one pairing DESIGN.md makes mandatory, tested where it actually occurs.
+  const ACCENT_FILLS = ['--color-accent', '--color-accent-2', '--color-accent-warm'];
+  let accentRatios = $state<Record<string, number>>({});
+
+  // WCAG AA: 4.5:1 for body text, 3:1 for large text and UI boundaries.
+  function grade(token: string, r: number | undefined): string {
+    if (r === undefined) return 'unknown';
+    if (BOUNDARY.test(token)) return r >= 3 ? 'pass' : 'fail';
+    if (!isForeground(token)) return 'ungraded';
+    if (r >= 4.5) return 'pass';
+    if (r >= 3) return 'large';
+    return 'fail';
+  }
+</script>
+
+<div class="portal" bind:this={probe}>
+  <header class="head">
+    <div>
+      <h1>augment-it design system</h1>
+      <p class="sub">
+        {COLOR_TOKENS.length} colour tokens × {SURFACES.length} surfaces, resolved by the browser in
+        <strong>{mode}</strong> mode. Contrast measured from what actually painted.
+      </p>
+    </div>
+    <nav class="modes" aria-label="Theme mode">
+      {#each MODES as m}
+        <button class:active={mode === m} onclick={() => pick(m)} aria-pressed={mode === m}>{m}</button>
+      {/each}
+    </nav>
+  </header>
+
+  <section aria-labelledby="swatches-h">
+    <h2 id="swatches-h">Semantic tokens on every surface</h2>
+    <p class="note">
+      Each cell paints <code>color: var(--token)</code> over <code>background: var(--surface)</code>.
+      A cell that vanishes is a token that does not resolve on that surface — the P2/P3 failure this
+      page exists to catch. The number is the measured contrast ratio.
+    </p>
+
+    <div class="grid" style="--cols: {SURFACES.length}">
+      <div class="cell head-cell">token</div>
+      {#each SURFACES as surface}
+        <div class="cell head-cell">{surface.replace('--color-', '')}</div>
+      {/each}
+
+      {#each COLOR_TOKENS as token}
+        <div class="cell token-name"><code>{token}</code></div>
+        {#each SURFACES as surface}
+          {@const r = ratios[`${token}|${surface}`]}
+          <div
+            class="cell swatch"
+            data-token={token}
+            data-surface={surface}
+            style="background: var({surface}); color: var({token});"
+          >
+            <span class="sample">Aa</span>
+            <span class="ratio {grade(token, r)}">{r ?? '—'}</span>
+          </div>
+        {/each}
+      {/each}
+    </div>
+  </section>
+
+  <section aria-labelledby="accent-h">
+    <h2 id="accent-h">Accent fills — <code>--color-on-accent</code></h2>
+    <p class="note">
+      DESIGN.md makes this pairing mandatory: <code>--color-on-accent</code> on any accent fill,
+      never assumed white. Tested where it is actually used rather than against surfaces it never
+      touches.
+    </p>
+    <div class="effects">
+      {#each ACCENT_FILLS as fill}
+        {@const r = accentRatios[fill]}
+        <div class="accent-cell effect-card" data-fill={fill}
+             style="background: var({fill}); color: var(--color-on-accent);">
+          <code>on-accent / {fill.replace('--color-', '')}</code>
+          <span class="ratio {r === undefined ? 'unknown' : r >= 4.5 ? 'pass' : r >= 3 ? 'large' : 'fail'}">{r ?? '—'}</span>
+        </div>
+      {/each}
+    </div>
+  </section>
+
+  <section aria-labelledby="effects-h">
+    <h2 id="effects-h">Effect tokens</h2>
+    <div class="effects">
+      {#each EFFECT_TOKENS as token}
+        <div class="effect-card" style="box-shadow: var({token});">
+          <code>{token}</code>
+        </div>
+      {/each}
+    </div>
+  </section>
+
+  <section aria-labelledby="palette-h">
+    <h2 id="palette-h">Tier 1 — the palette</h2>
+    <p class="note">
+      Raw named values. Components never read these; Tier-2 tokens point at them. Shown so a
+      renamed or re-pointed step is visible rather than inferred.
+    </p>
+    <div class="palette">
+      {#each TIER1 as [name, value]}
+        <div class="chip">
+          <div class="chip-color" style="background: {value};"></div>
+          <code>{name.replace('--color__', '')}</code>
+          <span class="hex">{value}</span>
+        </div>
+      {/each}
+    </div>
+  </section>
+</div>