diff --git a/.planning/phases/01-design-tokens-rams-foundation/01-01-SUMMARY.md b/.planning/phases/01-design-tokens-rams-foundation/01-01-SUMMARY.md new file mode 100644 index 0000000..b4acf59 --- /dev/null +++ b/.planning/phases/01-design-tokens-rams-foundation/01-01-SUMMARY.md @@ -0,0 +1,178 @@ +--- +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 ` (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*