c-fu/arah2
1
0
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
36679468c8f3e2f895f60f515091e7832e0b85f1
arah2/.planning/phases/01-design-tokens-rams-foundation/01-01-SUMMARY.md
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 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 01 ui
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:

  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

Reference in New Issue View Git Blame Copy Permalink