Arah2/.planning/phases/01-design-tokens-rams-foundation/01-CONTEXT.md

# Phase 1: Design Tokens + Rams Foundation - Context

**Gathered:** 2026-10-22
**Status:** Ready for planning

<domain>
## Phase Boundary

Distill the Telemetry Rams design system into a single centralized, importable token package — including a Rams-styled MapLibre basemap derived from OpenFreeMap `liberty` — proven with a rendered component sheet and a user-approved mockup-vs-implementation side-by-side gallery, before any product screen is built. Ends the inline-Tailwind-duplication and design-source conflict. Bot, Mini App shell, search, and routing are separate phases; this phase builds no product screens.

</domain>

<decisions>
## Implementation Decisions

### Token package format
- **D-01:** Tailwind v4 CSS-first package: tokens declared as CSS custom properties plus the `@theme` directive. No v3-style JS config. CSS variables double as the consumption path for MapLibre basemap styles and later phases.
- **D-02:** Token naming mirrors the mockup vocabulary verbatim (~40-token Material-style scale: `signal-orange`, `matte-black`, `space-md`, `display-lg`, ...) so mockup-derived markup maps 1:1 and fidelity comparison stays direct.
- **D-03:** The token package ships together with a rendered component sheet that consumes it — the sheet itself proves token completeness (DSGN-01's "every rendered component derives from tokens" is demonstrated, not asserted).
- **D-04:** Pre-slot the dual Telegram light/dark theme boundary now (themeable shell surfaces as token slots), while map cartography stays Rams-constant. Phase 3 (PX-02) then maps two background values onto slots instead of restructuring tokens.

### Source-of-truth resolution
- **D-05:** Root `DESIGN.md` is superseded for specifics: keep it as Rams philosophy prose with a header banner pointing to the token package. `telemetry_rams/DESIGN.md` content (the mockup-matching system) flows into the package; the losing typography claim (Helvetica/Inter + 5 colors) is explicitly marked superseded.
- **D-06:** The four mockup `code.html` files stay untouched, read-only generated reference artifacts (fine as-is per CONCERNS.md). Their inline `tailwind.config` blocks are superseded but NOT edited. Fidelity comparison targets rendered output, not markup.
- **D-07:** The token package owns all numeric values (hex, px, rgba, font sizes). Design docs describe principles and link to the package; docs never restate hex codes or dimensions — the drift that caused the conflict cannot recur.

### Basemap styling depth
- **D-08:** Full Rams pass on the OpenFreeMap `liberty` fork in this phase: grayscale/muted land + water grounding, desaturated roads, muted label styling; `signal-orange` accent reserved exclusively for the route line (rendered in Phase 5). Orange remains navigation-only semantics.
- **D-09:** Basemap colors are derived from the token package (values read/synced from the package), not hand-tuned in the style JSON — honoring DSGN-01's "map cartography follows the same tokens". Exact derivation mechanism (generation script vs synced values file) is planner/researcher's choice.
- **D-10:** Map labels adopt Rams typography (Space Grotesk / Geist), coherent with the HUD, using the same font assets.

### Component sheet + gallery
- **D-11:** Component sheet scope is mockup-derived: everything the 4 mockup screens actually show — buttons, cards, chips/badges, the maneuver banner, inputs, and a typography specimen. No invention of unseen components.
- **D-12:** The approval gallery is a static side-by-side HTML page: rendered implementation components against the four mockup screens' renders, token-by-token. This page is the DSGN-02 mechanism template — every later UI phase extends the same pattern.
- **D-13:** DSGN-01's audit sweep is automated: a script that scans rendered CSS/classes and flags any color/spacing/typography/radius value not in the token set. "Zero off-token values" is evidence, not eyeball claim.
- **D-14:** Gallery renders are produced with Playwright real-browser screenshots (script committed for reuse by later UI phases under the design-taste-frontend skill's real-browser inspection rule).

### Build pipeline
- **D-15:** Minimal `package.json` + Tailwind v4 CLI and npm scripts; design gallery/sheet + basemap style packaged in one design folder consumed by later phases. No app framework scaffold — the Mini App shell shape is decided in Phase 3.
- **D-16:** Self-host Geist + Space Grotesk woff2 in the repo as part of the token package; Google Fonts CDN links are removed going forward (may remain in mockups).
- **D-17:** Local npm scripts only (build / gallery / audit) in Phase 1; CI workflows come with Phase 2's deploy pipeline. Keep tooling minimal.

### OpenCode's Discretion
- Exact derivation/refresh mechanism basemap ← tokens (script vs synced file)
- Gallery page file layout within the design folder
- Audit script implementation details and threshold handling
- Icon strategy details within the sheet (Material Symbols vs inline SVG usage observed in mockups)

</decisions>

<specifics>
## Specific Ideas

- "Map cartography stays Rams-constant" — the map background must look identical under Telegram light and dark themes; only shell surfaces re-theme.
- Mockup screens are the spec — the gallery side-by-side against their rendered output is the fidelity bar.
- Scope creep avoided by design: motion/animation polish, incident components (reporter screen's modal flow) render only as static sheet entries where the mockups show them; full interactive flows belong to later phases.

</specifics>

<canonical_refs>
## Canonical References

**Downstream agents MUST read these before planning or implementing.**

### Design system (binding)
- `stitch_minimalist_route_navigator/telemetry_rams/DESIGN.md` — canonical token vocabulary, component rules, zero-radius / no-blur constraints
- `DESIGN.md` — Rams philosophy (kept for principles; its typography/palette specifics are superseded per D-05)
- `stitch_minimalist_route_navigator/active_route_guidance/code.html` — markup/layout reference (read-only) for maneuver banner and incident telemetry band
- `stitch_minimalist_route_navigator/navigate_map_overview/code.html` — layout reference for map screen + layer controls
- `stitch_minimalist_route_navigator/community_incident_reporter/code.html` — layout reference for incident card components
- `stitch_minimalist_route_navigator/telegram_live_traffic_feed/code.html` — layout reference for chip/badge components

### Planning inputs
- `.planning/ROADMAP.md` §Phase 1 — goal, success criteria, notes (repo hygiene, skill usage, no research phase)
- `.planning/REQUIREMENTS.md` — DSGN-01, DSGN-02 (this phase's requirements)
- `.planning/codebase/CONCERNS.md` — Zone.Identifier debt, design-source conflict, mockup fragility (Phase 1 resolves these)
- `.planning/codebase/STACK.md` — token duplication, Play-CDN caveat, design constraints
- `.agents/skills/design-taste-frontend/SKILL.md` — applies in existing-brand special case: keep Rams palette/type/dashboard house rules; real-browser inspection for the gallery artifact

</canonical_refs>

<code_context>
## Existing Code Insights

### Reusable Assets
- Inline `tailwind.config` block in each `code.html` — byte-identical token source to extract into the v4 package (matches `telemetry_rams/DESIGN.md:2-148`)
- Mockup `<screen>/code.html` + `<screen>/screen.png` pairs — ready-made inputs for the side-by-side gallery
- SVG patterns in mockups (route vectors, `stroke-linecap="square"`, 2px strokes) — reuse for sheet icon components

### Established Patterns
- kebab-case token/class names (`bg-matte-black`, `text-signal-orange`) — carry into the v4 package
- 8px baseline grid, 4px/8px multiples for every dimension
- Uppercase labels with expanded tracking; Material Symbols Outlined iconography
- Color semantics: orange = navigation/primary, red = hazards/errors, green = police-only (per mockups); keep strict

### Integration Points
- The token package is consumed by: the rendered sheet + gallery (Phase 1), the Mini App shell (Phase 3), every UI phase's Tailwind build
- The basemap style JSON becomes the MapLibre style loaded by Phase 3/5/6's map views
- Playwright capture script becomes the DSGN-02 gallery evidence toolchain for all UI phases

</code_context>

<deferred>
## Deferred Ideas

- Interactive mockup/implementation compare tool — a static page suffices for v1; revisit if gallery review becomes painful
- Full incident-report interaction flows — Phase 1 renders reporter-screen components statically only; the privacy boundaries of incident reporting ship post-v1 (v2 cluster REP-01/02, per REQUIREMENTS.md)
- CI workflow for gallery + audit — deferred to Phase 2 deploy pipeline (D-17)

None — discussion stayed within phase scope.

</deferred>

---

*Phase: 01-design-tokens-rams-foundation*
*Context gathered: 2026-10-22*