arah2/.planning/phases/01-design-tokens-rams-foundation/01-04-SUMMARY.md

---
phase: 01-design-tokens-rams-foundation
plan: 04
subsystem: ui
tags: [rams, design-tokens, audit, playwright, gallery, dsgn-02, d-12, d-13, d-14]

# Dependency graph
requires:
  - phase: 01-design-tokens-rams-foundation plan 01 (wave 1)
    provides: "theme/src/tokens.css (55 colors / 10 spacing / 4 fonts / 9 zero-radius tokens + 13 --type-* compound vars), theme/dist/rams.css build (npm run build --workspace theme), root audit/capture script delegates"
  - phase: 01-design-tokens-rams-foundation plan 02 (wave 2)
    provides: "theme/src/sheet.html + components.css (all-13 text-* helpers, pure var() component layer) — the audit's real-build integration target + the gallery's right-column capture; Playwright chromium-1248 installed"
  - phase: 01-design-tokens-rams-foundation plan 03 (wave 3)
    provides: "theme/basemap/index.html proof page (RAMS-BASEMAP-READY console signal) + committed screen.png fallback inputs per mockup screen"
provides:
  - "Automated off-token audit (D-13): theme/scripts/audit.mjs — rendered-CSS scanner over dist + implementation pages (incl. <style> blocks, inline style attributes, used @layer utilities), hex/rgb()/hsl() literal token checks, font-family allowlist, zero-radius + circle-primitive adjudication, shadow/blur/glass ban, drift guards (exit 2: <40 color tokens, non-zero --radius-* token, missing token sheet/page/input); violations as file:line: declaration (exit 1); wired as `npm run audit`"
  - "Audit TDD harness: theme/scripts/audit.test.mjs (16 checks / 8 groups, incl. real-build integration) — `npm run test --workspace theme`"
  - "Playwright capture toolchain (D-14): theme/scripts/screenshot.mjs — real-browser captures of the sheet (390 fullPage), the 4 mockups via file:// (CDN network renders, committed screen.png fallback — mockups never edited, D-06), the basemap (READY-signal-gated); ≥10KB blank gate; wired as `npm run capture`"
  - "DSGN-02 approval gallery (D-12): theme/gallery.html — the mechanism template every later UI phase extends (4 mockup-vs-sheet comparison rows + basemap direction row + token ledger of 13 typography specimens + 6 hero color swatches, names only per D-07 + approval scope strip); CDN-free, tokens-only"
  - "6 regenerated captures under theme/screenshots/ (gitignored by policy): sheet-full.png, mockup-<screen>.png ×4, basemap-kl.png — all network renders, zero fallbacks needed"
  - "DSGN-02 approval record: .planning/phases/01-design-tokens-rams-foundation/01-04-DSGN-02-APPROVAL.md — verbatim \"approved\" (2026-10-22T00:51:39Z), full provenance (reviewed URLs, approved artifact commits waves 1-3 + 01-04, capture manifest), evidence re-verified at record time; gate consequence: DSGN-02 PASSED for Phase 1"
  - "One-command DSGN-02 review loop: `npm run gallery` (root delegate → theme) = build → capture → serve theme/ on :8123 — repairs the root delegate that had pointed at a missing theme script since wave 1 (01-01 contract: plan 04 wires the gallery slot)"
affects: [every later UI phase (DSGN-02 gallery extension + `npm run audit`/`npm run capture` standing gates), 02-telegram-bot-worker (fidelity bar applies to bot-adjacent UI), 03-mini-app-shell, 05-guidance]

# Tech tracking
tech-stack:
  added: [] (playwright@1.64.1 + chromium-1248 already installed by waves 1–2; screenshot.mjs/audit.mjs are node-builtins-only ESM)
  patterns:
    - "Rendered-vs-vocabulary scope adjudication: framework layers (@layer properties/theme/base, @property --tw-*) skipped; @layer utilities audited ONLY for classes used by implementation pages (mockup-compiled vocabulary is reference material per D-06) — later phases' off-token utility usage gets caught the moment their pages wear it"
    - "Drift guards fail loud (exit 2) — no silent passes (T-1-07): token floor, radius-token invariant, missing registered page/token sheet/CSS input"
    - "Evasion-proof evidence surface: <style> blocks + inline style=\"…\" attributes + rgb()/hsl() literals all checked, not just hex"
    - "Capture fallback contract: failed/blank mockup capture → committed screen.png copied in (gallery refs stay stable; D-06 read-only mockups)"
    - "Gallery-as-mechanism: one static page, extended per phase; token ledger + approval strip unchanged; `npm run audit` stays the automated evidence"

key-files:
  created:
    - theme/scripts/audit.mjs
    - theme/scripts/audit.test.mjs
    - theme/scripts/screenshot.mjs
    - theme/gallery.html
    - .planning/phases/01-design-tokens-rams-foundation/01-04-DSGN-02-APPROVAL.md (task 3 — DSGN-02 approval record)
  modified:
    - theme/package.json (audit + capture + test + gallery scripts)

key-decisions:
  - "Rendered-CSS audit scope (D-13's own words: 'scans rendered CSS/classes'): dist compiles the mockup vocabulary 1:1 per wave-1's @source requirement — including utilities the design doc REJECTS (shadow-*, blur, backdrop-blur, bg-[#…]). Auditing raw dist would flag reference vocabulary no implementation page wears; the audit therefore filters @layer utilities to classes harvested from implementation pages (registry: IMPLEMENTATION_PAGES in audit.mjs — later phases append) and audits everything else implementation-owned fully. A used off-token utility (T7) or shadow utility still flags — proven by tests"
  - "rounded-full adjudicated as circle primitive (the wave-1-anticipated call): design doc Shapes enumerates rect families (cards/buttons/banners/badges/containers) at absolute zero — mockups' circular signets (position puck, speed medallion, status dots, 11 uses) are drawn circles = spec geometry like the 18×18 checkbox. Audit sanctions exactly calc(infinity*1px) + its ≥1e30px minified form; 50% and every other non-zero radius stay flagged"
  - "Token-hue + alpha sanctioned (8-digit hex whose 6-digit prefix is a token value — mockups' text-matte-black/60 family); Tailwind's own black (#000000xx) is NOT a token and stays flagged"
  - "rgb()/rgba()/hsl()/hsl() literals audited too — hex is not the only literal form; var() references pass by construction"
  - "how-to-verify's npx http-server replaced by the workspace's existing npm run basemap:preview (serves theme/ identically; no ad-hoc npx dependency — D-17 minimal tooling)"
  - "Gallery rows use the full sheet capture per row (plan-allowed) + per-row compare notes naming the corresponding sheet sections — honest, complete, no opinionated crop mapping"

patterns-established:
  - "DSGN-02 mechanism: extend theme/gallery.html with one comparison row per product screen; token ledger + approval strip unchanged; approval recorded in the phase SUMMARY"
  - "Evidence gates as npm scripts: `npm run audit` (exit-code truth) + `npm run capture` (≥10KB blank gate) — CI-able in Phase 2's deploy pipeline (D-17)"
  - "Implementation pages registry (audit.mjs IMPLEMENTATION_PAGES) is the rendered-surface contract — every page that renders Rams components must be registered there"

requirements-completed: [DSGN-02] # approved 2026-10-22 (task 3 checkpoint passed — record committed); REQUIREMENTS.md/STATE.md/ROADMAP.md marking deferred to the orchestrator (wave-parallel execution; DSGN-01 equally still unmarked on disk)

# Metrics
duration: 22min total (12min pre-checkpoint 2026-10-22T00:20:01Z→00:32:00Z + ~10min continuation 00:45Z→00:56Z: approval record, gallery wiring, verification, summary)
completed: 2026-10-22
---

# Phase 01 Plan 04: Audit + Gallery + DSGN-02 Checkpoint Summary

**Automated off-token audit as a rendered-CSS scanner with drift guards and evasion-proof checks (16/16 TDD green, real build `AUDIT CLEAN — 354 declarations, 0 off-token values`), a committed Playwright capture toolchain producing 6/6 non-blank real-browser captures, the DSGN-02 side-by-side approval gallery (mockup-vs-sheet rows + basemap direction + names-only token ledger) — and the user's APPROVED verdict on both, recorded with full provenance as the Phase-1 fidelity gate**

> **STATUS: COMPLETE — tasks 3/3. DSGN-02 APPROVED by the user on 2026-10-22 (verbatim "approved"; no fix list), recorded in `01-04-DSGN-02-APPROVAL.md` (commit `f51e714`). Evidence re-verified post-approval: AUDIT CLEAN, CAPTURE OK 6/6 — the approved capture set reproduced with sheet-full.png and basemap-kl.png byte-identical. Later UI phases may build on the approved fidelity bar; `npm run gallery` (wired this plan, `7d6845a`) is their review mechanism.**

## Performance

- **Duration:** ~22 min total (00:20:01Z → 00:32:00Z pre-checkpoint tasks 1–2; ~00:45Z → 00:56Z continuation: prior-work verification, approval record, gallery wiring, evidence re-runs, summary)
- **Tasks:** 3/3 complete (task 3 checkpoint passed — user approved)
- **Files:** 5 created, 1 modified (+ this SUMMARY)

## Accomplishments

- **D-13 evidence, not assertion:** `npm run audit` exits 0 on the real build — 354 declarations checked across 4 inputs (97 rules audited, 298 compiled-vocabulary utility rules out of scope, 49 classes harvested from 3 implementation pages), zero off-token values; violations (when present) print as `file:line: declaration — reason`; drift conditions exit 2 loud (color-token floor 40, non-zero `--radius-*` token, missing token sheet / registered page / CSS input)
- **D-14 toolchain committed:** `npm run capture` → 6/6 non-blank captures — sheet-full.png (116KB, 390px fullPage), 4 mockup network renders via file:// (45–64KB, CDN Tailwind + fonts), basemap-kl.png (1.2MB, gated on the proof page's RAMS-BASEMAP-READY signal + 2s settle); fallback contract (committed screen.png) wired but not needed
- **D-12 gallery as durable mechanism:** theme/gallery.html (290 lines) — leading comment documents the per-phase extension pattern; 4 mockup-vs-sheet comparison rows with per-row family notes; basemap direction row; token ledger (13 typography specimens rendered in their own tokens + 6 hero color swatches — names only, zero numeric restatement per D-07); approval scope strip (fidelity bar + basemap direction in scope; interactive flows out of scope); CDN-free, built only from `dist/rams.css` + var()-only page shell
- **Audit covers the gallery itself:** gallery.html registered as an implementation page — its `<style>` block, inline style attributes, and class harvest are inside the evidence surface (that registration is what motivated closing the style-attribute evasion path)

## task Commits

Each task was committed atomically (TDD tasks have RED/GREEN pairs):

1. **task 1: Off-token audit script (D-13)** — `6a7c256` (test: RED, 13 failing checks) → `b39317d` (feat: GREEN, 13/13)
2. **task 2: Playwright capture script + gallery page (D-14, D-12)** — `9ba73f2` (test: RED for the style-attr evasion hole found while building the gallery) → `0b3eebf` (feat: GREEN, audit surface extension) → `b462936` (feat: capture toolchain + gallery + audit registry)
3. **task 3: DSGN-02 approval checkpoint** — **PASSED**: user approved (verbatim "approved"; no fix list). `f51e714` (docs: DSGN-02 approval record — date, verbatim response, reviewed URLs, approved artifact commits, re-verified evidence, gate consequence) → `7d6845a` (fix: theme `gallery` script — post-approval wiring repairing the broken root delegate, the 01-01 contract's "plan 04 (gallery)" slot)

**Plan metadata:** (see final commit below — docs: SUMMARY)

## Files Created/Modified

- `theme/scripts/audit.mjs` (583 lines) — the D-13 audit: token-sheet parser (allowlist + drift guards), CSS block parser (layers/media/nesting, comment-stripping with line-preserving offsets), rendered-scope filter, declaration checks (hex/rgb/hsl literals, font families, radius incl. circle-primitive adjudication, box-shadow/backdrop-filter/blur ban, `--tw-*` plumbing skip), implementation-pages registry (class harvest + `<style>` + style-attribute audit)
- `theme/scripts/audit.test.mjs` (233 lines) — TDD harness: 16 checks / 8 groups (clean/dirty/drift-colors/drift-radius/real-build/components-layer/used-utilities/style-attributes), fixtures under /tmp/opencode
- `theme/scripts/screenshot.mjs` (191 lines) — D-14 capture tool: loopback static server (theme/ docroot, traversal-guarded), sheet/mockup/basemap captures, blank gate, screen.png fallback, per-capture log
- `theme/gallery.html` (290 lines) — the DSGN-02 mechanism page (see Accomplishments)
- `theme/package.json` — `"audit": "node ./scripts/audit.mjs ./dist/rams.css"`, `"capture": "node ./scripts/screenshot.mjs"`, `"test": "node ./scripts/audit.test.mjs"`, and (continuation, task 3) `"gallery": "npm run build && npm run capture && echo 'DSGN-02 gallery serving: http://localhost:8123/gallery.html + /basemap/' && npm run basemap:preview"` (root delegates `audit`/`capture`/`gallery` verified resolving)
- `.planning/phases/01-design-tokens-rams-foundation/01-04-DSGN-02-APPROVAL.md` (56 lines) — the DSGN-02 approval record: verbatim response, provenance, re-verified evidence, gate consequence
- `theme/screenshots/*` — 6 regenerated captures, gitignored by policy (re-run `npm run capture` after fresh checkout)

## Decisions Made

(See key-decisions in frontmatter for the full set — all within D-12/D-13/D-14 latitude.) The consequential ones:

- **Rendered-vs-vocabulary scope** — the plan's required behavior ("audit of theme/dist/rams.css (real build) → exit 0") collides with wave-1's own requirement that dist compile the mockup utility vocabulary 1:1 — which includes shadow/blur/glass/`bg-[#222222]` utilities the design doc rejects and the implementation never wears. D-13's own wording ("scans rendered CSS/classes") resolves it: the audit's unit of truth is what implementation pages render. Utilities-layer rules are audited exactly for harvested used classes; framework layers and `@property --tw-*` plumbing are skipped; everything implementation-owned is fully audited. Tests T5/T6/T7 lock all three behaviors.
- **Circle primitive adjudication** (wave-1's deferred call) — `rounded-full` sanctioned only as the full-circle primitive for signets; the audit quotes the design doc's Shapes enumeration (rect families at absolute zero) in its header; 50%/9999px/any other non-zero radius stays a violation.
- **Gallery serving** — the checkpoint how-to uses the workspace's existing preview server rather than `npx http-server` (equivalent docroot, one less ad-hoc package, D-17).
- **Gallery script as the full review loop (continuation, task 3 wiring)** — `npm run gallery` chains build → capture → serve rather than serve-only: fresh-checkout-safe (dist/ + captures are regenerated artifacts — an unstyled-sheet capture would otherwise pass the ≥10KB blank gate silently), encodes the documented user-setup flow as one command, and matches 01-01's own anticipation ("run `npx playwright install` before capture/gallery"). Each link individually verified; the serve link is `basemap:preview` — proven live by the checkpoint server itself.

## Deviations from Plan

### Auto-fixed Issues

**1. [Rule 1 - Bug] Plan's task-2 verify command always exits 1 when the size checks pass**
- **Found during:** task 2 verification
- **Issue:** `for f in …; do [ "$(stat -c%s "$f")" -lt 10240 ] && exit 1; done && …` — when the test is false the compound `[ … ] && exit 1` leaves status 1; the for statement's last status propagates, breaking the `&&` chain on every passing run
- **Fix:** intent-correct loop (`if [ … ]; then exit 1; fi`); the substantive checks themselves were re-run and pass
- **Files modified:** none (verification command only)
- **Verification:** all 6 captures ≥ 10240B (45KB–1.2MB), gallery refs + audit verified → `GALLERY-TOOLS-OK`
- **Committed in:** n/a (verify-command fix, documented here)

**2. [Rule 2 - Missing critical] Inline `style="…"` attributes were an unaudited evasion path**
- **Found during:** task 2 (designing the gallery's swatches)
- **Issue:** the audit scanned `<style>` blocks but not style attributes — any page could pass `style="color: #00ff00"` with a CLEAN verdict, undermining the D-13 evidence (the gallery itself uses style-attribute values)
- **Fix:** TDD — RED `9ba73f2` (T8 proves the hole), GREEN `0b3eebf` (style attributes audited as rendered CSS, violations reported as `file:line: style attribute { prop: value }`)
- **Files modified:** theme/scripts/audit.mjs, theme/scripts/audit.test.mjs
- **Verification:** 16/16 tests green; real build still AUDIT CLEAN
- **Committed in:** `9ba73f2` + `0b3eebf`

**3. [Rule 3 - Tooling] Plan's how-to-verify server command replaced with the existing workspace server**
- **Found during:** task 3 checkpoint preparation
- **Issue:** `npx http-server theme -p 4444` pulls an ad-hoc npx package for a docroot the workspace already serves (`npm run basemap:preview --workspace theme` → theme/ on :8123) — against D-17's minimal-tooling spirit
- **Fix:** checkpoint instructions use the existing preview script; gallery + screenshots + basemap + dist CSS all verified 200 over it
- **Files modified:** none
- **Committed in:** n/a (checkpoint instructions)

**4. [Rule 1 - Bug] Root `npm run gallery` delegate was broken — theme-side script never wired**
- **Found during:** task 3 (post-approval wiring check, continuation session)
- **Issue:** root `gallery` → `npm run gallery --workspace theme` failed with "Missing script: gallery" — 01-01 created the root delegate and explicitly assigned plan 04 the theme-side slot ("plan 04 (gallery/audit)"), but 01-04's tasks 1–2 wired only `audit`/`capture`/`test`
- **Fix:** added theme `"gallery": "npm run build && npm run capture && echo '…' && npm run basemap:preview"` — the one-command DSGN-02 review loop; root delegate untouched (already correct)
- **Files modified:** theme/package.json
- **Verification:** JSON valid in both manifests; resolution listed from root + theme; build 114ms; CAPTURE OK 6/6 (approved capture set reproduced — sheet + basemap byte-identical, mockups ≤107B variance, zero fallbacks); AUDIT CLEAN; serve link live-proven (`:8123` serving gallery.html 200)
- **Committed in:** `7d6845a`

---

**Total deviations:** 4 auto-fixed (2 bugs, 1 missing critical, 1 tooling)
**Impact on plan:** All fix-level; no scope changes. The style-attribute extension made the D-13 evidence strictly stronger than the plan's letter; the gallery-script repair closed the 01-01 contract's last open slot.

## Issues Encountered

- **GREEN debug iterations (normal TDD, in-task):** (a) RADIUS_PROPS regex initially matched the `border:` shorthand (both optional groups skipped → bare `border` matched) — fixed to require the `-radius` suffix; (b) Tailwind v4.3.3 emits real `@property --tw-*` registration at-rules (unlayered, carrying the `#0000` default values) — added the rule-level plumbing skip alongside the declaration-level one. Both caught by the TDD harness before commit.
- **Mockup vocabulary provenance (investigated, not a bug):** dist's off-token literals (`#222222` from `bg-[#222222]`, `#000000xx` inside `.shadow-*` internals, `#1a1a1a99`-family token-hue+alpha from mockup `/60`-style utilities) all traced to mockup-derived compiled vocabulary or framework plumbing — none worn by implementation pages; the audit's scope adjudication handles them by design, with T7 proving a used off-token utility still flags.
- `.gitignore` already excluded `theme/screenshots/` (wave-1 entry) — verified, no change needed (plan asked to "ensure").

## Known Stubs

None in this plan's artifacts — the audit, capture script, and gallery are complete implementations. (The basemap's route vector remains wave-3's documented intentional placeholder for Phase 5; the gallery references it as such.)

## Threat Flags

None — no new trust surface beyond the plan's register: audit.mjs reads local files only (plan's boundary "audit.mjs → local files"); screenshot.mjs's static server is loopback-bound + traversal-guarded, and its CDN fetches are exactly the plan's boundary row "workstation browser → CDN Tailwind (mockup pages only)" (T-1-05 accept — only the captured mockup pages use CDN; the gallery itself is CDN-free per D-16). T-1-06 (gallery as durable committed mechanism) and T-1-07 (fail-loud drift guards, no silent passes) mitigations implemented and tested.

## User Setup Required

None — no external service configuration. Re-reviewing the gallery (any later phase) is now one command: `npm run gallery` (root) = build → capture → serve, then open http://localhost:8123/gallery.html and /basemap/. Captures regenerate automatically (fresh-checkout safe). The checkpoint itself required no user setup beyond the two URLs.

## Next Phase Readiness

- **Task 3: CLOSED — DSGN-02 APPROVED** (record: `01-04-DSGN-02-APPROVAL.md`, commit `f51e714`). No fix list; no aspects flagged for iteration. Product screens (Phase 2+) may build against the approved fidelity bar
- **Every later UI phase:** extend theme/gallery.html (one comparison row per new product screen), append pages to audit.mjs IMPLEMENTATION_PAGES, then `npm run gallery` regenerates evidence and serves the review; `npm run audit` + `npm run capture` remain the standing DSGN-01/DSGN-02 gates; CI wiring lands with Phase 2's deploy pipeline (D-17)
- **Fresh checkouts:** `npm run gallery` does it all (build → capture → serve); `npm run build --workspace theme` before standalone `npm run audit`
- STATE.md/ROADMAP.md/REQUIREMENTS.md updates deferred to the orchestrator (wave-parallel execution — DSGN-01 remains "Pending" on disk for the same reason; this frontmatter's `requirements-completed` list is the durable record, matching plans 01-01/02/03's convention)

## Self-Check: PASSED

All 5 created files exist (audit.mjs 583 · audit.test.mjs 233 · screenshot.mjs 191 · gallery.html 290 ≥ 80 · 01-04-DSGN-02-APPROVAL.md 56 lines); all 7 plan commit hashes verified in git log (6a7c256, b39317d, 9ba73f2, 0b3eebf, b462936, f51e714, 7d6845a); must-have markers verified (gallery.html `screenshots/` ×10; package.json `audit` + `gallery` wired; audit.mjs → `tokens.css`/`rams.css`; screenshot.mjs → `screenshots`); no deletions in any commit; working tree shows only this SUMMARY modified — STATE.md/ROADMAP.md/REQUIREMENTS.md untouched; no stub markers in the new artifacts.

---
*Phase: 01-design-tokens-rams-foundation*
*Completed: 2026-10-22 (3/3 tasks; DSGN-02 approved and recorded — 01-04-DSGN-02-APPROVAL.md, commit f51e714)*