forked from c-fu/arah2
147 lines
11 KiB
Markdown
147 lines
11 KiB
Markdown
---
|
||
phase: 01-design-tokens-rams-foundation
|
||
plan: 01
|
||
type: execute
|
||
wave: 1
|
||
depends_on: []
|
||
files_modified:
|
||
- package.json
|
||
- .gitignore
|
||
- DESIGN.md
|
||
- theme/package.json
|
||
- theme/src/tokens.css
|
||
- theme/src/theme.css
|
||
- theme/fonts/geist/Geist-Regular.woff2
|
||
- theme/fonts/geist/Geist-Medium.woff2
|
||
- theme/fonts/geist/Geist-SemiBold.woff2
|
||
- theme/fonts/geist/Geist-Bold.woff2
|
||
- theme/fonts/space-grotesk/SpaceGrotesk-Bold.woff2
|
||
- theme/fonts/space-grotesk/SpaceGrotesk-SemiBold.woff2
|
||
- theme/fonts/space-grotesk/SpaceGrotesk-Regular.woff2
|
||
autonomous: true
|
||
requirements: [DSGN-01]
|
||
user_setup: []
|
||
must_haves:
|
||
decisions: [D-01, D-02, D-04, D-05, D-06, D-07, D-15, D-16, D-17]
|
||
truths:
|
||
- "Tokens exist as CSS custom properties importable by any later phase (npm script or plain CSS import)"
|
||
- "Building the theme produces a compiled dist CSS containing Tailwind v4 utilities wired via @theme"
|
||
- "Zero Google Fonts CDN references in the package self-hosted fonts serve both typefaces"
|
||
- "Root DESIGN.md declares itself superseded for specific values and points to the token package"
|
||
artifacts:
|
||
- path: "theme/src/tokens.css"
|
||
provides: "All color/spacing/typography tokens as CSS variables + @theme (D-01, D-02)"
|
||
contains: "signal-orange"
|
||
- path: "theme/src/theme.css"
|
||
provides: "Fonts @font-face declarations + @import of tokens (D-16, D-10)"
|
||
contains: "@font-face"
|
||
- path: "theme/package.json"
|
||
provides: "tailwindcss v4 CLI deps + build/audit/gallery scripts (D-15, D-17)"
|
||
contains: "@tailwindcss/cli"
|
||
- path: ".gitignore"
|
||
provides: "OS junk, node_modules, secrets exclusions"
|
||
contains: "node_modules"
|
||
key_links:
|
||
- from: "theme/src/theme.css"
|
||
to: "theme/src/tokens.css"
|
||
via: "CSS @import"
|
||
pattern: "@import.*tokens\\.css"
|
||
- from: "theme/package.json"
|
||
to: "theme/src/theme.css"
|
||
via: "build script"
|
||
pattern: "@tailwindcss/cli"
|
||
---
|
||
|
||
<objective>
|
||
Create the centralized Telemetry Rams token package (Tailwind v4 CSS-first), self-host the two typefaces, and resolve the repo's design-source conflict. This is the single source of truth every later phase imports.
|
||
|
||
Purpose: DSGN-01 requires all screens render from one token set; today tokens are hand-duplicated into 4 mockup `tailwind.config` blocks and two conflicting DESIGN.md typography claims (per CONTEXT.md D-05, D-06).
|
||
Output: `theme/` package with tokens + fonts + build scripts, repo hygiene (.gitignore, Zone.Identifier scrub), superseded-designation banner on root DESIGN.md.
|
||
</objective>
|
||
|
||
<read_first>
|
||
@planning/phases/01-design-tokens-rams-foundation/01-CONTEXT.md
|
||
@planning/codebase/STACK.md
|
||
@planning/codebase/CONCERNS.md
|
||
@stitch_minimalist_route_navigator/telemetry_rams/DESIGN.md
|
||
@DESIGN.md
|
||
</read_first>
|
||
|
||
<interfaces>
|
||
Token vocabulary (Copy VERBATIM from the frontmatter of `stitch_minimalist_route_navigator/telemetry_rams/DESIGN.md` — D-02 requires 1:1 mockup mapping):
|
||
|
||
Core brand colors: `signal-orange: #EB8008`, `matte-black: #1A1A1A`, `soft-beige: #D9D2C6`, `functional-red: #ED3F1C`, `olive-green: #736B1E`, `chassis-subtle: #CCC4B5`, `surface-dark: #121212`, `pure-white: #FFFFFF`
|
||
Material neutrals: surface #fff8f0 / on-surface #1e1b14 / on-surface-variant #564335 / outline #897363 / outline-variant #dcc1af / transparent variants per frontmatter (copy all keys from lines 3–49)
|
||
Spacing: `space-xs 0.25rem` … `space-2xl 3rem` + `gutter` / `gutter-desktop` / `margin` / `margin-desktop` (lines 138–148)
|
||
Typography scale: `display-lg`, `display-lg-mobile`, `headline-lg`, `headline-lg-mobile`, `headline-md`, `headline-sm`, `body-lg`, `body-md`, `body-sm`, `label-lg`, `label-md`, `label-sm`, `telemetry-num` with exact px/weight/tracking values (lines 59–137)
|
||
No-radius rule: all `--radius-*: 0px` (Shapes section)
|
||
</interfaces>
|
||
|
||
<tasks>
|
||
|
||
<task type="auto">
|
||
<name>task 1: Repo hygiene + package scaffold</name>
|
||
<files>.gitignore, package.json, theme/package.json</files>
|
||
<action>
|
||
1. Scrub Zone.Identifier artifacts (CONCERNS.md debt): `find . -name "*:Zone.Identifier" -type f -delete` (run from repo root). Confirm count 0 afterward.
|
||
2. Create root `.gitignore` containing (exact entries): `node_modules/`, `dist/`, `theme/dist/`, `.env`, `.env.*`, `!*.example`, `*.local`, `theme/screenshots/`, `OS junk`: `.DS_Store`, `Thumbs.db`, `desktop.ini`.
|
||
3. Create root `package.json`: name `araharah`, private true, type `module`, workspaces `["theme"]`, scripts delegating to theme (`"build": "npm run build --workspace theme"`, `"sheet": "npm run sheet --workspace theme"`, `"gallery": "npm run gallery --workspace theme"`, `"audit": "npm run audit --workspace theme"`, `"capture": "npm run capture --workspace theme"`).
|
||
4. Create `theme/package.json`: name `@araharah/theme`, type `module`, devDependencies `tailwindcss@^4` and `@tailwindcss/cli@^4`, dependencies `playwright` (needed by plan 03), plus scripts:
|
||
- `"build": "tailwindcss -i ./src/theme.css -o ./dist/rams.css --minify"` (D-17 local-only)
|
||
- `"send": "mkdir -p dist/fonts && cp -r fonts/geist fonts/space-grotesk dist/"` (fonts copied alongside build so sheet.css/font paths resolve)
|
||
- `"gallery", "audit", "capture", "sheet" script stubs are created by later plans 02–04 — do NOT add them here except as documented below in tasks of those plans.` (Correction: create only `build` and `send` in this plan; later plans append their scripts.)
|
||
</action>
|
||
<verify><automated>test ! -f .gitignore || grep -q "node_modules" .gitignore; test -f theme/package.json && grep -q "@tailwindcss/cli" theme/package.json && find . -name "*:Zone.Identifier" | grep -c . || echo "zone-files=0"</automated></verify>
|
||
<done>.gitignore exists with node_modules/.env entries; theme/package.json declares tailwindcss v4 CLI; zero `*:Zone.Identifier` files remain in the repo.</done>
|
||
</task>
|
||
|
||
<task type="auto">
|
||
<name>task 2: Token package (tokens.css + theme.css + fonts)</name>
|
||
<files>theme/src/tokens.css, theme/src/theme.css, theme/fonts/**</files>
|
||
<read_first>@stitch_minimalist_route_navigator/telemetry_rams/DESIGN.md</read_first>
|
||
<action>
|
||
1. Download Geist and Space Grotesk woff2 (weights: Geist 400/500/600 + Space Grotesk 700 needed by D-10/labels; Geist Regular, Medium, SemiBold, Bold + Space Grotesk Regular, SemiBold, Bold) from the `fontsource` npm CDN unpkg distribution (`npm i @fontsource-variable/geist @fontsource-variable/space-grotesk` to fetch then extract woff2 files, OR direct unpkg `.woff2` fetches). Place files under `theme/fonts/geist/` and `theme/fonts/space-grotesk/` with names recorded in frontmatter.
|
||
2. Write `theme/src/tokens.css` (per D-01, D-02, D-04, D-07): one `@theme` block declaring EVERY token from telemetry_rams/DESIGN.md frontmatter, names verbatim: colors as `--color-*`, spacing as `--spacing-*`, typography via `--font-sans/mono` aliasing (Geist/Space Grotesk), radius `--radius-DEFAULT: 0px` (zero roundedness per design doc Shapes), and label type scale preserved as Tailwind v4 text custom classes via `@utility` or as plain CSS custom properties under `:root` — pick `@theme` for colors/spacing/fonts, `:root`-level custom properties for the typography scale entries (each as a compound var, e.g. `--type-display-lg` composed of font/size/weight/line-height/tracking).
|
||
3. Enforce the 8px-base rule: spacing values in the frontmatter are already grid-conformant; copy verbatim (D-07 forbids recomputation).
|
||
4. Write `theme/src/theme.css`:
|
||
- `@import "tailwindcss";`
|
||
- `@import "tokens.css";`
|
||
- seven `@font-face` blocks (font-family Geist / Space Grotesk, font-weight per file, `src: url(../fonts/…/*.woff2) format('woff2')`, `font-display: block;` non-flash per Rams aesthetics).
|
||
- Dual Telegram light/dark slot pre-slotting (D-04): add `:root { --shell-bg: var(--color-surface); }` and `@media (prefers-color-scheme: dark) { :root { --shell-bg: var(--color-surface-dark); } }` — only shell-level slots (background, on-surface text pair) are themeable, map cartography stays Rams-constant.
|
||
5. Run `npm run build --workspace theme` and verify `theme/dist/rams.css` exists and contains `signal-orange` and `.font-geist` font stack.
|
||
</action>
|
||
<verify><automated>npm run build --workspace theme && test -f theme/dist/rams.css && grep -c "signal-orange" theme/dist/rams.css | awk '$1>=3{exit 0}{exit 1}' && grep -q "@font-face" theme/dist/rams.css</automated></verify>
|
||
<tdd>false</tdd>
|
||
<done>tokens.css declares ~40-token vocabulary verbatim from mockup config (D-02), theme.css @font-faces self-hosted Geist + Space Grotesk (D-16), shell theme slots pre-arranged (D-04), and `npm run build --workspace theme` produces dist/rams.css containing all token names with no console errors.</done>
|
||
</task>
|
||
|
||
<task type="auto">
|
||
<name>task 3: DESIGN.md superseding banner</name>
|
||
<files>DESIGN.md, README.md</files>
|
||
<read_first>@DESIGN.md</read_first>
|
||
<action>
|
||
1. Insert at the very top of root `DESIGN.md` a 3-line banner (before any existing heading, no H1 style change so prose stays visible):
|
||
`> ⚠ SUPERSEDED FOR SPECIFICS — the centralized token set is the single source of truth for all numeric values (colors, sizes, spacing). This document is kept for Rams design philosophy only. Consult the token package (see README.md) for specific value definitions. Conflicting typography claims in this document (Helvetica/Inter, 5-color palette) are superseded by the token package.` (per D-05)
|
||
2. Create or append to `README.md` a one-paragraph "Design system" section: live in `theme/`, consume via `@import 'theme/src/tokens.css'`, build via `npm run build`. Do NOT restate hex codes or px sizes in the README (D-07: docs never restate numeric values — write "palette" and "the token set" descriptively, with no hex/px numbers).
|
||
</action>
|
||
<verify><automated>head -5 DESIGN.md | grep -q "SUPERSEDED" && ! grep -qE '#[0-9A-Fa-f]{6}|(\d+px)' README.md</automated></verify>
|
||
<done>DESIGN.md first line declares supersession; README references the package without numerically restating any design value (D-07).</done>
|
||
</task>
|
||
|
||
</tasks>
|
||
|
||
<verification>
|
||
- `npm run build --workspace theme` exits 0 and emits `theme/dist/rams.css`
|
||
- `grep -c "signal-orange" theme/dist/rams.css` ≥ 3
|
||
- `find . -name "*:Zone.Identifier" | wc -l` = 0
|
||
- `head -3 DESIGN.md` mentions SUPERSEDED
|
||
- `grep -r "fonts.googleapis" theme/` returns no matches (D-16)
|
||
</verification>
|
||
|
||
<success_criteria>
|
||
Token package exists, builds, and is importable by any later phase; fonts self-hosted; design-source conflict resolved via superseding banner + non-numeric README; repo git hygiene established. Unblocks component sheet (02), basemap (03).
|
||
</success_criteria>
|
||
|
||
<output>
|
||
After completion, create `.planning/phases/01-design-tokens-rams-foundation/01-01-SUMMARY.md`
|
||
</output> |