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

## 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.

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

## 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.

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

---

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