Merge pull request #82 — federated design system Phase 0/1

Brings in the instrumentation and colour tier that had been stranded on one
laptop since 2026-08-01: scripts/design-drift.mjs, the Phase 1 theme.css, the
shell's FOUC guard, the strategy-curator focus fix, and the four context-v
documents the handoff depends on. Issue #81.

package.json was the only conflict, exactly as predicted when that issue was
raised: Phase 0 adds design:drift and design:contrast, and the turbo removal had
rewritten the surrounding scripts. Both sets kept; the turbo-free `pnpm -r build`
survives.

token-baseline.css regenerated against the Phase 1 theme — the A20 floor grows
from 24 registrations to 35, picking up --color-border-strong, --focus-ring, the
unified warn dialect, --color-surface-2, --color-bg-elevated, --color-link,
--color-thread, --color-accent-warm, --fx-popover-shadow, and the deprecated
--color-bg alias.

`pnpm tokens:check` caught the staleness before the regeneration, which is what
it exists for: the generated floor cannot silently drift from the theme it is
derived from.

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

Author: mpstaton

.gitignore

@@ -62,3 +62,4 @@ history.txt
 # GRAPH_REPORT.md, AST cache, manifest). Rebuild with `graphify --update`.
 # Corpus scope is committed in .graphifyignore, not here.
 graphify-out/
+tools/

apps/strategy-curator/src/app.css

@@ -94,7 +94,7 @@
 .sc-app .sc-value { color: var(--color-text); }
 .sc-app .sc-muted { color: var(--color-text-muted); }
 .sc-app .sc-mini { font-size: 12px; }
-.sc-app .sc-mono { font-family: var(--font__mono, ui-monospace, monospace); }
+.sc-app .sc-mono { font-family: var(--font-mono); }
 .sc-app .sc-pad { padding: 1rem; }
 
 /* ---- inputs / buttons ---- */
@@ -109,9 +109,9 @@
   padding: 0.35rem 0.5rem;
   width: 100%;
 }
-.sc-app input:focus,
-.sc-app textarea:focus,
-.sc-app select:focus { outline: none; border-color: var(--color-field-focus); box-shadow: var(--fx-accent-glow); }
+.sc-app input:focus-visible,
+.sc-app textarea:focus-visible,
+.sc-app select:focus-visible { outline: none; border-color: var(--color-accent); box-shadow: var(--focus-ring); }
 
 /* Saved-confirmation pulse: border glows green on commit, then fades back. */
 @keyframes sc-save-flash {

context-v/README.md

@@ -22,6 +22,7 @@ Subdirectories appear as content arrives:
 - `reminders/` — short notes future-you will be glad past-you wrote
 - `explorations/` — open questions, partially-answered
 - `issues/` — known problems, not yet fixed
+- `loops/` — repeatable fidelity sweep procedures. See `loops/references/` for supporting rationale.
 
 The splash at `splash/` renders every `.md` in this tree (and `changelog/`)
 on push to `main`.

context-v/explorations/Design-Language-Audit-2026-07.md

@@ -0,0 +1,77 @@
+---
+title: "Design Language Audit — July 2026"
+lede: "The hand-counted baseline audit that measured the state of augment-it's CSS before the design system shipped. Superseded as the counting mechanism by design-drift.mjs."
+date_created: 2026-07-16
+date_modified: 2026-08-01
+semantic_version: 0.0.1.0
+status: Superseded
+superseded_by: "scripts/design-drift.mjs"
+tags:
+  - Audit
+  - Design-System
+  - Historical
+---
+
+# Design Language Audit — July 2026
+
+## Status: Superseded
+
+**This document is superseded as the counting mechanism.** The drift script
+(`scripts/design-drift.mjs`) is now the source of truth. Where the script and
+this document disagree, the script is right. Every disagreement was in the
+direction this document's own lede predicted: understated.
+
+This document remains in the record as the baseline measurement — the state
+of the product before Phases 0 and 1 landed. It is the "before" column in the
+verification table in the Phase 1 handoff.
+
+## The July 2026 baseline
+
+Measured by hand against the full codebase on 2026-07-16, before any token
+work began.
+
+### What was measured
+
+- 74 stylesheets across 16 remotes plus the shell
+- 432 font-size declarations (35 distinct sizes)
+- 158 button rule-sets across 13 recipes
+- 34 badge treatments
+- 6 spinner implementations with 4 different @keyframes names
+- 30 box-shadow declarations (47% hardcoded, none mode-reactive)
+- 25 z-index values spanning 0→200 with no scheme
+- 99 unnamespaced selectors leaking across remote boundaries
+- 33 dead fallback colours (fallbacks for tokens defined since May)
+- 43 `--color-bg` declarations painting nothing on the live deploy
+- 10 `outline: none` sites
+- 123 native `title=` attributes (7 accessible)
+- 11 product-wide accessibility defects
+
+### Key findings that shaped Phases 0 and 1
+
+1. **The ramps lied.** `--color__graphite-700` was darker than `-900` on three
+   of six greyscale ramps. Step numbers did not track luminance. This became
+   gate A19, resolved in Phase 1.
+
+2. **Five light-mode contrast failures.** `--color-text-muted` at 4.37–4.49:1
+   fell below 4.5:1 against two surfaces. This was gate R11, resolved in Phase 1.
+
+3. **Four phantom warn dialects.** 22 declarations had independently invented
+   `--color-warning-*`, `--color-warn`, and other variants for one concept.
+
+4. **Three competing focus treatments.** Zero custom `:focus-visible` rings
+   across the product.
+
+5. **Federation was a documentation convention.** F1 forbade members from
+   declaring tokens, but every member imported `theme.css` independently —
+   the same race condition at runtime.
+
+### What the audit missed
+
+- The Tier 1 consumption violations (F1a) — three files reading `var(--font__mono)`
+  directly. The audit grepped `--color__` only.
+- The two script bugs (CRLF and argv indexing) that would later produce
+  confidently wrong output.
+- The CRLF frontmatter parse failure that silently emptied the member registry.
+
+These are recorded in the Phase 1 handoff (§4) — they were found by the drift
+script that this audit's findings made necessary.

context-v/loops/Sweep-Local-Federated-Design-System-for-Fidelity.md

@@ -0,0 +1,86 @@
+---
+title: "Sweep — Local & Federated Design System for Fidelity"
+lede: "The repeatable procedure for checking a member's CSS against the federal contract. The one sanctioned exception to the two-file rule."
+date_created: 2026-08-01
+date_modified: 2026-08-01
+semantic_version: 0.0.1.0
+status: Active
+tags:
+  - Loop
+  - Design-System
+  - Fidelity
+  - Enforcement
+---
+
+# Sweep — Local & Federated Design System for Fidelity
+
+## Purpose
+
+This loop checks a single member's CSS surface against the federal token
+contract. It catches what the drift script cannot: visual fidelity, token
+appropriateness (right token for the right job), and undocumented deviations.
+
+## When to run
+
+**By a developer:** after finishing a feature that touches CSS or adds a
+component. After changing a token's value in `packages/theme`. Before a release.
+
+**By an AI coding agent, self-directed:** when the diff touches CSS, Svelte
+style blocks, or token references. When the task description mentions colour,
+spacing, or typography. When the agent changes a member's `DESIGN.md`. The agent
+runs this loop as a *task*, not as a preamble before every edit.
+
+## Procedure
+
+### 1. Read the federal contract
+
+Read `packages/theme/theme.css` — the Tier 1 and Tier 2 blocks only. Note the
+tokens available. Read `DESIGN.md` §The federation contract — F1 through F11.
+
+### 2. Read the member's design surface
+
+Read every `.css` and `.svelte` file in the member's `src/` directory. Also
+read the member's `DESIGN.md`, including *Deviations* — deviations are declared
+exceptions, not bugs to "fix."
+
+### 3. Check each rule
+
+For each federal rule F1–F11, answer: does this member violate it?
+
+Key checks:
+- **F1 + F1a:** Grep for `--color__`, `--font__`, `--color-` (member declaring
+  federal tokens or consuming Tier 1 directly).
+- **F3:** Does every selector descend from the member's root class?
+- **F4:** Any raw `z-index` number? Should be `var(--z-*)`.
+- **F8:** Any `#hex` or raw `box-shadow`? Should be a token.
+- **F10:** Does `mount.ts` import `theme.css`? It should not.
+
+### 4. Check token appropriateness
+
+For each token reference, ask: is this the right token for the job?
+
+- `--color-text` for body text, `--color-text-muted` for secondary.
+- `--color-accent` for the brand accent, `--color-accent-warm` for emphasis.
+- `--color-border` for decorative dividers, `--color-border-strong` for control
+  boundaries.
+- `--color-error-text` for error states, `--color-warn-text` for warnings.
+
+### 5. Record findings
+
+Record every violation with file, line, and rule reference. A deviation already
+declared in the member's `DESIGN.md` is not a finding — it is a known exception.
+
+## Hard rules for agents
+
+1. **This loop is a task, not a preamble.** An agent that sweeps before every
+   small edit has spent its context window on ceremony.
+
+2. **Never self-authorise implement mode.** An agent that finds a violation
+   *reports* it. Fixing it is a separate task with its own scope.
+
+3. **Diff-scoped, not member-scoped.** When running on a code change, sweep
+   only the files the change touches plus any files that reference the changed
+   tokens.
+
+4. **Read the member's Deviations before reporting.** A declared deviation is
+   not a finding.

context-v/specs/Design-System-Portal.md

@@ -0,0 +1,96 @@
+---
+title: "Design System Portal"
+lede: "Specification for the portal that renders the federated design system — the swatch page, the token catalogue, the member index."
+date_created: 2026-08-01
+date_modified: 2026-08-01
+semantic_version: 0.0.1.0
+status: Draft
+tags:
+  - Design-System
+  - Portal
+  - Swatch-Page
+  - Phase-2a
+---
+
+# Design System Portal
+
+## 1. Purpose
+
+The portal is the single surface where every federal token can be seen — in all
+three modes, on one page, against every surface it will ever sit on. It is the
+answer to "nothing has been seen in a browser."
+
+## 2. Two jobs
+
+1. **The swatch page (Phase 2a, P0).** Render every Tier-2 token against every
+   surface, in all three modes. A stylesheet and a loop.
+
+2. **The token catalogue (Phase 2a, post-P0).** The full federal vocabulary,
+   with resolved values per mode, the member index, and the deviation registry.
+   Generated from `design-manifest.json`.
+
+## 3. Phase 2a — P0 swatch page
+
+### The bare minimum
+
+A single page at `apps/docs-portal` with one stylesheet and one loop.
+
+```svelte
+{#each tokens as token}
+  <div class="swatch-row">
+    <span class="token-name">{token.name}</span>
+    {#each surfaces as surface}
+      <div class="swatch" style="background: var({surface}); color: var({token.name})">
+        {token.name}
+      </div>
+    {/each}
+  </div>
+{/each}
+```
+
+The token list comes from `design-manifest.json`. The surface list is:
+`--color-background`, `--color-surface`, `--color-surface-2`,
+`--color-surface-raised`, `--color-bg-elevated`.
+
+### Mode toggle
+
+Three buttons cycling `data-mode` on `<html>`. The portal imports `mode-switcher`
+from `@augment-it/theme`.
+
+### What it proves
+
+- Every token resolves in all three modes
+- No token disappears on a surface (P2, P3)
+- Contrast numbers are visible in context
+- Phase 2 can pick typography, spacing and radius values by eye
+
+## 4. Portal v1 (post-P0)
+
+### Pages
+
+| Page | Source |
+|---|---|
+| Token catalogue | `design-manifest.json` |
+| Member index | `design-manifest.json` |
+| Deviation registry | `design-manifest.json` |
+| Contrast matrix | `design-drift --contrast --json` |
+
+### Generation
+
+The portal build runs `design-drift --json` and reads `design-manifest.json`.
+Nothing is hand-maintained. The manifest is generated from the frontmatter of
+the 20 documents.
+
+## 5. Deployment
+
+The portal lives at `apps/docs-portal`. It is one more federation remote —
+it mounts into the shell like any other member. It imports `theme.css` and
+`mode-switcher`, and its `mount.ts` follows F10 (no theme import in the
+federated mount).
+
+## 6. Why the portal is load-bearing
+
+The swatch page is the only surface where every token's rendered appearance
+can be verified. Until it exists, "108/108 contrast pairs pass" is a number
+in a terminal — accurate, but not eye-verified. The portal closes that gap
+for colour in Phase 2a, and for typography, spacing and radius in Phase 2.