Files

T

araharah-executor 95fe82b04e docs(01-design-tokens-rams-foundation-01): complete design-tokens foundation plan 01-01

- 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)

2026-10-22 07:39:00 +08:00

12 KiB

Raw Permalink Blame History

phase, plan, subsystem, tags, requires, provides, affects, tech-stack, key-files, key-decisions, patterns-established, requirements-completed, duration, completed

phase

plan

subsystem

tags

requires

provides

affects

tech-stack

key-files

key-decisions

patterns-established

requirements-completed

duration

completed

01-design-tokens-rams-foundation

tailwind-v4

design-tokens

css-custom-properties

self-hosted-fonts

rams

repo-hygiene

phase	provides
none (greenfield — first product-code plan in the repo)	n/a

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

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)

added

patterns

tailwindcss@4.3.3

@tailwindcss/cli@4.3.3

playwright@1.64.1 (dep

browsers not yet installed)

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)

created

modified

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)

.gitignore

DESIGN.md

@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)

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)

DSGN-01

13min

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:

task 1: Repo hygiene + package scaffold — 506ff68 (chore: design baseline + .gitignore + zone scrub) + 8dea270 (chore: npm workspace scaffold)
task 2: Token package (tokens.css + theme.css + fonts) — 2b36b37 (feat)
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

12 KiB Raw Permalink Blame History Unescape Escape