118 lines
8.7 KiB
Markdown
118 lines
8.7 KiB
Markdown
# 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*
|