Arah2/.planning/phases/01-design-tokens-rams-foundation/01-02-SUMMARY.md

---
phase: 01-design-tokens-rams-foundation
plan: 02
subsystem: ui
tags: [rams, component-sheet, tailwind-v4, css-custom-properties, design-tokens, d-03, d-11]

# Dependency graph
requires:
  - phase: 01-design-tokens-rams-foundation plan 01 (wave 1)
    provides: "theme/src/tokens.css (104 verbatim tokens), theme/src/theme.css (@theme static build → dist/rams.css), self-hosted woff2 fonts, --type-* compound typography vars, npm workspace + build/send scripts"
provides:
  - "Component layer: theme/src/components.css — .btn-primary/.btn-secondary, .input-field, .card/.card-header/.card-ref/.card-content, .chip-traffic/.chip-hazard/.chip-safe, .maneuver-banner/.maneuver-arrow, .checkbox, .toggle/.toggle-option, all 13 .text-* typography helpers — every value a token reference"
  - "Rendered component sheet: theme/src/sheet.html — the D-03 proof artifact and the audit-sweep + gallery input target for plan 04"
  - "sheet npm script (theme + root delegation now resolves)"
  - "Real-browser verification evidence: 41/41 computed-style checks render from tokens; Playwright chromium 1248 installed (unblocks plans 03/04 captures)"
affects: [01-design-tokens-rams-foundation plan 04 (gallery side-by-side + D-13 audit target), 03-mini-app-shell + later UI phases (component class API), plan 03 (chromium already installed)]

# Tech tracking
tech-stack:
  added: [] (playwright@1.64.1 was already a dep from wave 1; chromium-1248 browser binary downloaded this plan)
  patterns:
    - "Component classes in @layer components built ONLY from var(--color-*)/var(--spacing-*)/var(--type-*) references (D-11 hard requirement, audit-greppable)"
    - "Sub-element classes follow the plan's own .card-header precedent: .card-ref, .card-content, .toggle-option"
    - "Inline SVG iconography (stroke-linecap square, 3px stroke) instead of icon-font CDNs (D-16)"
    - "Sheet furniture reuses component classes (.card-header plate pattern) + minimal token-only page-shell style consuming the D-04 --shell-* slots"

key-files:
  created:
    - theme/src/components.css
    - theme/src/sheet.html
  modified:
    - theme/src/theme.css (@import ./components.css appended as last import)
    - theme/package.json (sheet script)
    - theme/dist/rams.css (rebuilt; gitignored build output — verified, not committed)

key-decisions:
  - "Icons are inline SVG only: Material Symbols is a fonts.googleapis.com CDN link — forbidden by D-16; mockups themselves draw the maneuver arrow as inline SVG"
  - "Checkbox 18x18 kept as a spec-geometry literal: the D-02 verbatim vocabulary has no 18px spacing token; every other dimension is token-derived (8px fill = space-sm, 32px arrow = space-xl) and border widths 1/2/3px are the plan's own sanctioned geometry"
  - "Typography helpers cover all 13 scale entries incl. mobile variants (plan interfaces: 'every scale entry') — not just the 11 in the class-list shorthand"
  - "Section header plates reuse .card-header + .card-ref ('matching card-header pattern') with a two-rule page-level adaptation so sheet furniture ink rides the --shell-* slots (legible under dark scheme); the .card demo itself stays pure component"
  - "Visual verification done as a real-browser computed-style audit (41/41 PASS): every rendered value equals the design-doc verbatim value carried through the token chain — D-13's 'evidence, not eyeball claim' spirit; woff2 load + 0 failed requests confirmed"
  - "Sheet href ../dist/rams.css (plan wrote ./dist/rams.css; from theme/src/ the correct relative path contains the same verify-required substring)"
  - "dist CSS url('../fonts/...') resolves from theme/dist/ to the source theme/fonts/ — verified by the audit (fonts loaded, zero 404s), so the plan-verbatim sheet script (build + echo) is sufficient without send"

patterns-established:
  - "Component class API: kebab-case classes in @layer components, sub-elements as named members (.card-header/.card-ref/.card-content), never utility soup in consuming markup"
  - "Focus brackets = border swaps to 3px signal-orange (bordered elements) or a 3px signal-orange outline (border-less toggle options); outline suppressed only where the bracket replaces it"
  - "Two-way toggle active state via aria-pressed — semantics first, styling keyed off it"

requirements-completed: [DSGN-01]

# Metrics
duration: 13min
completed: 2026-10-22
---

# Phase 01 Plan 02: Rams Component Sheet Summary

**Mockup-derived Rams component sheet (D-11: buttons, inputs, chips, telemetry card, maneuver banner, checkbox/toggle, full typography specimen) styled exclusively by the token package — proven in a real browser by a 41/41 computed-style audit where every rendered value resolves through var() to the design-doc's verbatim tokens**

## Performance

- **Duration:** ~13 min
- **Started:** 2026-10-21T23:40:00Z
- **Completed:** 2026-10-21T23:53:14Z (local)
- **Tasks:** 2/2
- **Files:** 2 created, 2 modified (+1 rebuilt build output, gitignored)

## Accomplishments

- `theme/src/components.css`: all 14 required component/typography families + sub-element members, built ONLY from `var(--color-*)` / `var(--spacing-*)` / `var(--type-*)` references — 104 lines carrying token refs, zero hex literals, zero non-zero border-radius (grep-verified)
- `theme/src/sheet.html`: rendered component sheet in the plan's 7-section order (typography specimen → buttons → inputs → chips → card → maneuver banner → checkbox/toggle), each with a label-sm section header + reference badge matching the card-header pattern; markup uses component classes only — no utility soup, no JS, no icon-font CDN
- Component sheet consumes the built `dist/rams.css` directly (`npm run build` then open — the `sheet` script wires exactly this); the D-04 shell slots drive the page shell and demonstrably re-theme under OS scheme while components stay Rams-constant
- Real-browser verification: 41/41 computed-style checks — chips/card/banner/checkbox/toggle render the design-doc verbatim values (signal-orange, matte-black, soft-beige, functional-red, olive-green, chassis-subtle, 18×18 checkbox with 8×8 fill, 32×32 arrow, 3px focus brackets), Space Grotesk/Geist woff2 actually load, zero failed requests
- Playwright chromium-1248 installed — unblocks plan 03/04 captures (D-14)

## task Commits

Each task was committed atomically:

1. **task 1: components.css — component layer built only from tokens** — `84066fd` (feat)
2. **task 2: sheet.html — rendered component sheet page** — `e95f404` (feat) + `baab797` (fix: must-have "signal-orange" marker via doc comment, see deviation 4)

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

## Files Created/Modified

- `theme/src/components.css` — the component layer: `.btn-primary`/`.btn-secondary` (invert + 3px signal-orange focus brackets), `.input-field` (2px frame → 3px focus, zero glow), `.card` + `.card-header`/`.card-ref`/`.card-content` (1px perimeter, header plate divider, telemetry-num content), `.chip-traffic`/`.chip-hazard`/`.chip-safe`, `.maneuver-banner`/`.maneuver-arrow`, `.checkbox` (18×18, 8×8 checked fill), `.toggle`/`.toggle-option` (aria-pressed active inversion), 13 `.text-*` helpers consuming the `--type-*` scale
- `theme/src/sheet.html` — the sheet: masthead + 7 sections; representative content mockup-verbatim (BISMARCKSTRASSE, SEC-04 // SPEED, 250 M, CONGESTION / CRASH / BLOCK / POLICE RADAR, 18:42); token-only page-shell style on the D-04 `--shell-*` slots
- `theme/src/theme.css` — `@import "./components.css";` appended as last import
- `theme/package.json` — `"sheet": "npm run build && echo 'open theme/src/sheet.html in browser ( Consumes theme/dist/rams.css )'"` (plan-verbatim)
- `theme/dist/rams.css` — rebuilt; verified to contain all component classes, all 26 `--type-*` properties, shell slots

## Verification Evidence

- Task 1: `npm run build` exit 0 (93ms); `grep -cE "var\(--" src/components.css` = **104** (≥15); hex grep = **empty**; radius grep (intent-correct, see deviation 1) = **empty**; `fonts.googleapis` in theme/src = **empty**
- Task 2: build exit 0; `test -f theme/src/sheet.html` ✓; link grep `dist/rams.css` ✓; component-family grep = **40 lines** (≥7); `npm run sheet` runs end-to-end ✓
- Visual (plan's `<verification>`): real-browser computed-style audit **41/41 PASS** (screenshots at 390px/1280px captured as scratch artifacts in /tmp/opencode; plan 04 owns the committed capture tooling)

## Deviations from Plan

### Auto-fixed Issues

**1. [Rule 1 - Bug] Plan's radius verify regex is doubly broken**
- **Found during:** task 1 verification
- **Issue:** (a) `grep -E "…" -P` → "conflicting matchers specified" (grep errors, no result); (b) even `-P`-alone, `\s*(?!0)` backtracks to an empty `\s*` match, so the lookahead succeeds at the colon and flags even `border-radius: 0` — the check can never pass on any file that declares an explicit zero radius
- **Fix:** intent-correct check `grep -nP "border-radius:\s*+(?!0)"` (possessive quantifier forbids backtracking); sanity-tested that it flags non-zero values and passes zero values
- **Files modified:** none (components.css was already correct; the verify command was fixed)
- **Verification:** all 9 `border-radius` declarations in components.css are `0`; sanity test correctly caught a planted `4px`

**2. [Rule 3 - Blocking] Playwright browser binary missing for the visual check**
- **Found during:** task 2 visual verification
- **Issue:** cached `chromium-1217` didn't match playwright 1.64.1's expected `chromium_headless_shell-1248` — `browserType.launch` failed
- **Fix:** `npx playwright install chromium` (anticipated by wave-1's readiness note; also unblocks plans 03/04)
- **Verification:** capture + 41/41 audit ran clean; fonts loaded, zero failed requests

**3. [Rule 1 - Bug] Plan's sheet link path `./dist/rams.css` resolves wrong from theme/src/**
- **Found during:** task 2
- **Issue:** plan wrote `href="./dist/rams.css"`; from `theme/src/sheet.html` that resolves to `theme/src/dist/` (nonexistent)
- **Fix:** `href="../dist/rams.css"` (contains the verify-required `dist/rams.css`; verified rendering in the audit — 0 failed requests)
- **Files modified:** theme/src/sheet.html
- **Committed in:** `e95f404`

**4. [Rule 2 - Missing artifact requirement] must_haves marker "signal-orange" absent from sheet.html**
- **Found during:** self-check (post task 2)
- **Issue:** the plan's artifact spec requires sheet.html to contain "signal-orange"; the sheet's markup is component-classes-only (no color names appear), so the marker was missing
- **Fix:** the sheet's head documentation comment now names `--color-signal-orange` (token name only, no values — D-07; markup untouched)
- **Files modified:** theme/src/sheet.html
- **Verification:** marker grep = 1; full 41/41 computed-style audit re-run → PASS
- **Committed in:** `baab797`

---

**Total deviations:** 4 auto-fixed (2 bugs, 1 blocking, 1 missing requirement)
**Impact on plan:** All fix-level; no scope changes. `theme/src/theme.css` was modified (plan's files_modified missed it) — required by task 1's own action item 3 (add the components import).

## Issues Encountered

- The model cannot read PNG images directly, so the plan's "visual: open in a browser" check was executed as a stronger computed-style audit (D-13 spirit: evidence over eyeballing) — every rendered value matched its design-doc token verbatim; screenshots still captured at 390/1280px for plan 04's gallery flow
- `theme/dist/rams.css` is gitignored by wave-1 policy (regenerable); the plan's files_modified listing it was treated as the build target — rebuilt and verified, not committed

## Known Stubs

None — every component class is fully implemented against tokens, and the sheet renders real content through them. (Wave-1's root `sheet` script stub now resolves to a working theme script.)

## Threat Flags

None — static dev-only artifact, no network input, no new endpoints/auth/file-access surface beyond the plan's "none cross-user" boundary.

## User Setup Required

None.

## Next Phase Readiness

- **Plan 04 (gallery/audit):** sheet.html is the side-by-side input + audit target; sanctioned spec-geometry literals to allow in the D-13 sweep thresholds: 1px/2px/3px border widths, 18×18 checkbox, 3px svg stroke; the sheet's inline page-shell style uses only var() references
- **Plans 03/04:** chromium-1248 for playwright 1.64.1 is installed — captures unblocked; `npm run send` still available if a deployable standalone dist is wanted
- STATE.md/ROADMAP.md updates deferred to the orchestrator (wave-parallel execution)

## Self-Check: PASSED

All 4 created/modified files exist (theme/src/components.css, theme/src/sheet.html, theme/src/theme.css, theme/package.json); all 3 task commit hashes verified in git log (84066fd, e95f404, baab797); must-have markers verified (components.css → var(--color-signal-orange) ×14, sheet.html → signal-orange marker, package.json → "sheet").

---
*Phase: 01-design-tokens-rams-foundation*
*Completed: 2026-10-22*