---
phase: 01-design-tokens-rams-foundation
plan: 01
subsystem: ui
tags: [tailwind-v4, design-tokens, css-custom-properties, self-hosted-fonts, rams, repo-hygiene]

# Dependency graph
requires:
  - phase: none (greenfield — first product-code plan in the repo)
    provides: n/a
provides:
  - "Telemetry Rams token package: theme/src/tokens.css — every color/spacing/font/radius token as CSS custom properties (importable as plain CSS by any later phase, incl. MapLibre basemap derivation)"
  - "Typography scale as :root compound vars (--type-* + -tracking companions, 13 tokens)"
  - "Compiled utility stylesheet: npm run build → theme/dist/rams.css (utilities wired via @theme, mockup vocabulary compiles 1:1)"
  - "Self-hosted typefaces: 7 woff2 files (Geist 400/500/600/700, Space Grotesk 400/600/700) under theme/fonts/"
  - "Telegram light/dark shell slots: --shell-bg / --shell-on-surface (D-04, consumed by Phase 3 PX-02)"
  - "npm workspace scaffold (root + @araharah/theme) with build/send scripts (D-15, D-17)"
  - "Repo hygiene: .gitignore policy, Zone.Identifier scrub, committed design baseline"
affects: [01-design-tokens-rams-foundation plans 02-04 (sheet, basemap, gallery), 03-mini-app-shell (PX-02 slots), all later UI phases (token consumption, DSGN-02 gallery pattern)]

# Tech tracking
tech-stack:
  added: [tailwindcss@4.3.3, "@tailwindcss/cli@4.3.3", playwright@1.64.1 (dep, browsers not yet installed)]
  patterns:
    - "CSS-first Tailwind v4 tokens: @theme static block (static forces all vars into dist; default tree-shakes unused)"
    - "@source registers the mockup dir as the class-candidate vocabulary (D-02/D-06 — mockups read-only, never edited)"
    - "@source inline(...) safelists family utilities the mockups don't name directly"
    - "Compound :root type vars: font shorthand + -tracking companion per typography token"
    - "Zero-radius enforcement: all --radius-* tokens = 0px (v4 rounded-none/rounded-full are literal built-ins)"

key-files:
  created:
    - theme/src/tokens.css
    - theme/src/theme.css
    - theme/package.json
    - package.json
    - package-lock.json
    - README.md
    - theme/fonts/geist/*.woff2 (4)
    - theme/fonts/space-grotesk/*.woff2 (3)
  modified:
    - .gitignore
    - DESIGN.md

key-decisions:
  - "@theme static (not plain @theme): Tailwind v4 tree-shakes unused theme variables by default; the plan's done-criterion 'dist contains all token names' requires static emission of the full 104-var vocabulary"
  - "@source ../../stitch_minimalist_route_navigator: the mockup screens are the class-candidate vocabulary, so dist compiles the mockup utility classes 1:1 (satisfies 'utilities wired via @theme' + signal-orange ≥3); @source inline safelists font-geist/font-space-grotesk (verify requires .font-geist; mockups don't name it)"
  - "Font aliases: --font-sans→Geist, --font-mono→Space Grotesk (plan's 'sans/mono aliasing (Geist/Space Grotesk)' — mockups' 55 font-mono label usages render self-hosted per D-10/D-16), plus verbatim --font-geist / --font-space-grotesk utilities"
  - "No --radius-full token: v4's rounded-full is a literal built-in (calc(infinity*1px)), not var-driven; defining a 0px var would be misleading. All 9 real --radius-* tokens incl. DEFAULT are 0px; mockup circular signets (position puck, speed medallion) stay circular pending the D-13 audit's rendered-output adjudication"
  - "Typography scale as :root compound vars (--type-* font shorthand + -tracking companions) per plan's explicit pick; later plans build text classes on them"
  - "Added --shell-on-surface alongside --shell-bg (D-04 defines the shell slots as 'background, on-surface text pair'; dark pair maps to surface-dark/inverse-on-surface)"
  - "Repo-local git identity araharah-executor (matches prior araharah-planner convention; git identity was unconfigured)"

patterns-established:
  - "Token vocabulary lives ONLY in theme/src/tokens.css; docs/tests never restate hex/px values (D-07)"
  - "Fonts self-hosted under theme/fonts/; no Google Fonts CDN anywhere in theme/ (D-16)"
  - "Mockup code.html files are read-only reference artifacts — scanned as class candidates, never edited (D-06)"

requirements-completed: [DSGN-01]

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

# Phase 01 Plan 01: Design Tokens Rams Foundation Summary

**Telemetry Rams token package: 104 verbatim CSS custom properties (55 colors, 10 spacing, 4 font aliases, 9 zero-radius, 26 typography vars) in a Tailwind v4 `@theme static` build with 7 self-hosted woff2 typefaces, mockup-vocabulary utility compilation, and the D-04/D-05 design-source conflict resolved**

## Performance

- **Duration:** ~13 min
- **Started:** 2026-10-21T23:27:37Z
- **Completed:** 2026-10-21T23:41:00Z (local)
- **Tasks:** 3/3
- **Files modified:** 15 (13 created, 2 modified)

## Accomplishments

- Single source of truth: every token from `telemetry_rams/DESIGN.md` frontmatter declared verbatim in `theme/src/tokens.css` — importable by any later phase as plain CSS (D-01, D-02)
- `npm run build --workspace theme` → `theme/dist/rams.css` (32KB minified): all token vars + the full mockup utility vocabulary compiled (`.bg-signal-orange`, `.px-margin`, `.gap-space-md`, `.font-geist`, …)
- Self-hosted Geist (400/500/600/700) + Space Grotesk (400/600/700) woff2 from Fontsource (both SIL OFL 1.1); zero `fonts.googleapis` references in `theme/` (D-16)
- Telegram light/dark shell slots pre-arranged (`--shell-bg`, `--shell-on-surface`) with map cartography untouched (D-04)
- Design-source conflict resolved: root `DESIGN.md` carries the SUPERSEDED-FOR-SPECIFICS banner (D-05); README points consumers at the package without restating any numeric value (D-07)
- Repo hygiene: `.gitignore` policy (deps/dist/secrets/OS junk), 9 `*:Zone.Identifier` artifacts scrubbed (count 0), previously-untracked design baseline committed so this plan's commits are meaningful diffs

## task Commits

Each task was committed atomically:

1. **task 1: Repo hygiene + package scaffold** — `506ff68` (chore: design baseline + .gitignore + zone scrub) + `8dea270` (chore: npm workspace scaffold)
2. **task 2: Token package (tokens.css + theme.css + fonts)** — `2b36b37` (feat)
3. **task 3: DESIGN.md superseding banner** — `0009cc4` (docs)

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

## Files Created/Modified

- `theme/src/tokens.css` — the token package: `@theme static` (55 `--color-*`, 10 `--spacing-*`, 4 `--font-*`, 9 `--radius-*` = 0px) + `:root` typography scale (13 `--type-*` compound vars + `-tracking` companions)
- `theme/src/theme.css` — entry: `@import tailwindcss` + `./tokens.css`, `@source` mockup dir + inline safelist, 7 `@font-face` blocks (self-hosted, `font-display: block`), D-04 shell slots
- `theme/fonts/geist/*.woff2`, `theme/fonts/space-grotesk/*.woff2` — 7 self-hosted typeface files
- `theme/package.json` — `@araharah/theme`: tailwindcss v4 + CLI devDeps, playwright dep, build/send scripts
- `package.json` — root workspace; scripts delegate to theme (sheet/gallery/audit/capture appended by plans 02–04)
- `package-lock.json` — pins tailwindcss 4.3.3, @tailwindcss/cli 4.3.3, playwright 1.64.1
- `.gitignore` — plan's 11 entries + `.planning/` (local-only) + `*:Zone.Identifier`
- `DESIGN.md` — 3-line SUPERSEDED banner (Rams philosophy prose kept)
- `README.md` — Design system section, descriptive only (no hex/px)

## Decisions Made

(See key-decisions in frontmatter — all implementation latitude stayed within D-01…D-17.) Notable execution choices:

- **`@theme static`** — v4's default tree-shaking of unused theme variables would have dropped never-referenced tokens (`--color-tertiary-fixed-dim`, …) from dist; `static` guarantees the package's plain-CSS consumption path (D-01) and the "all token names in dist" done-criterion. Verified: all spot-checked tokens present.
- **`@source` the mockups** — the plan requires dist to contain "Tailwind v4 utilities wired via @theme" and `.font-geist`; with cwd-scoped auto-detection (theme/ only) no utilities would generate. The mockups are the vocabulary (D-02/D-06), so scanning them compiles the 1:1 mapping directly; `@source inline` covers the family utilities mockups don't name.
- **`send` script corrected** — plan's verbatim `cp -r fonts/… dist/` copied dirs beside `dist/fonts/` (the `mkdir -p dist/fonts` betrayed intent); fixed to `dist/fonts/`, verified by running it.

## Deviations from Plan

### Auto-fixed Issues

**1. [Rule 1 - Bug] `send` script copied fonts to the wrong directory**
- **Found during:** task 1 (scaffold)
- **Issue:** `mkdir -p dist/fonts && cp -r fonts/geist fonts/space-grotesk dist/` — with multiple sources, `cp` targets `dist/`, yielding `dist/geist/`, `dist/space-grotesk/` and an empty `dist/fonts/`; intent was `dist/fonts/…`
- **Fix:** changed target to `dist/fonts/`
- **Files modified:** theme/package.json
- **Verification:** `npm run send --workspace theme` → 7 files under `theme/dist/fonts/{geist,space-grotesk}/`
- **Committed in:** `8dea270` (task 1 scaffold commit)

**2. [Rule 3 - Blocking] Extensionless `@import "tokens.css"` failed to resolve**
- **Found during:** task 2 (build)
- **Issue:** Tailwind v4's resolver treats the bare specifier as a package lookup (`Can't resolve 'tokens.css'`)
- **Fix:** `@import "./tokens.css";`
- **Files modified:** theme/src/theme.css
- **Verification:** build exits 0 in 80ms
- **Committed in:** `2b36b37` (task 2 commit)

**3. [Rule 3 - Blocking] Git identity unconfigured**
- **Found during:** task 1 (baseline commit)
- **Issue:** `empty ident name` — repo had no user.name/email (prior commits used a role identity)
- **Fix:** repo-local `araharah-executor <executor@araharah.local>` (matches `araharah-planner` convention; no global config touched)
- **Files modified:** .git/config (repo-local only)
- **Verification:** all 4 commits created
- **Committed in:** enabled `506ff68` onward

---

**Total deviations:** 3 auto-fixed (1 bug, 2 blocking)
**Impact on plan:** All necessary for correctness/buildability. No scope creep. Two orchestrator-sanctioned additions beyond the plan's file list: the **baseline commit** of pre-existing untracked design assets (per execution context — makes this plan's commits meaningful diffs) and **package-lock.json** (dependency hygiene for the reproducible build).

## Issues Encountered

- **Plan's literal verify counts lines, not occurrences:** `grep -c "signal-orange" dist/rams.css` returns 1 on the minified single-line output (≥3 was intended). Substantive check via `grep -o | wc -l` = **15 occurrences** — intent satisfied; plan's `--minify` build flag makes the literal command unsatisfiable. No code change (build script is plan-verbatim); documented here for the verifier.
- **npm allow-scripts warning** (`@parcel/watcher` install script blocked): harmless for one-shot builds (watcher only needed in watch mode); no action.
- **npm audit noise** on transitive dependencies: out of scope (deps pinned to latest); logged, not fixed.

## Known Stubs

- `package.json` root scripts `sheet` / `gallery` / `audit` / `capture` delegate to `theme` scripts that don't exist yet — **intentional per plan** ("later plans append their scripts"): plan 02 (sheet), plan 03 (basemap/capture), plan 04 (gallery/audit). They will fail with "missing script" until then.
- `--shell-bg` / `--shell-on-surface` slots are defined but not yet consumed — **intentional per D-04**; Phase 3 (PX-02) maps Telegram theme params onto them.

## User Setup Required

None — no external service configuration required.

## Next Phase Readiness

- **Plan 02 (component sheet):** consume `theme/dist/rams.css` + `--type-*` vars; append the `sheet` script to `theme/package.json`
- **Plan 03/04:** `playwright@1.64.1` is installed as a dependency but **browsers are not downloaded** — run `npx playwright install` before capture/gallery; `send` copies fonts to `dist/fonts/` for sheet/gallery pages
- Zone.Identifier scrub is one-time; `*:Zone.Identifier` stays gitignored against re-introduction
- STATE.md/ROADMAP.md updates deferred to the orchestrator (wave-parallel execution)

## Self-Check: PASSED

All 16 created/modified files exist; all 4 task commit hashes verified in git log (506ff68, 8dea270, 2b36b37, 0009cc4).

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