forked from c-fu/arah2
araharah-executor
95fe82b04e
- Token package (104 verbatim tokens) + self-hosted fonts + v4 build verified - 3/3 tasks, 4 task commits, 3 auto-fixed deviations (send cp target, ./tokens.css import, git identity) - STATE.md/ROADMAP.md intentionally untouched (orchestrator owns wave-parallel writes)
179 lines
12 KiB
Markdown
179 lines
12 KiB
Markdown
---
|
||
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*
|