docs(01-design-tokens-rams-foundation): create phase plan (4 plans, 3 waves)

2026-10-22 02:33:01 +08:00
commit 16eb089cc3
13 changed files with 1825 additions and 0 deletions
@@ -0,0 +1,133 @@
+# Coding Conventions
+
+**Analysis Date:** 2026-10-21
+
+> **Scope caveat:** This is a pre-implementation design repository. There is **no source code,
+> no package manifest, no linter/formatter config, and no build system** in the repo yet
+> (no `package.json`, `.eslintrc*`, `.prettierrc*`, `tsconfig.json`, or `.gitignore` exists).
+> The only code is static HTML/Tailwind mockups under
+> `stitch_minimalist_route_navigator/`. Conventions below are extracted from those mockups
+> and the design-system docs, and should be treated as the de-facto starting point for any
+> future implementation code.
+
+## Established Document Conventions
+
+**Design system declaration:**
+- The design system lives in `stitch_minimalist_route_navigator/telemetry_rams/DESIGN.md`
+  as a YAML frontmatter block (`name`, `colors`, `typography`, `spacing`) followed by
+  prose sections (Brand & Style, Colors, Typography, Layout & Spacing, Elevation & Depth,
+  Shapes, Components).
+- Core philosophy docs are plain prose at repository root: `DESIGN.md` (Rams principles,
+  8px grid, color palette, component rules) and `IDEAS.md` (vision, architecture targets,
+  gamification ideas). Both end with the motto line
+  "Good design is as little design as possible." — Dieter Rams.
+
+**Token vocabulary (use these names verbatim in any new code):**
+- Colors, kebab-case: `signal-orange` (#EB8008), `functional-red` (#ED3F1C),
+  `olive-green` (#736B1E), `soft-beige` (#D9D2C6), `matte-black` (#1A1A1A),
+  `chassis-subtle` (#CCC4B5), `surface-dark` (#121212), `pure-white` (#FFFFFF).
+  Full Material-style surface/on-surface scale is declared in the frontmatter of
+  `stitch_minimalist_route_navigator/telemetry_rams/DESIGN.md`.
+- Typography scale, kebab-case: `display-lg`, `headline-lg`, `headline-md`, `headline-sm`,
+  `body-lg`, `body-md`, `body-sm`, `label-lg`, `label-md`, `label-sm`, `telemetry-num`.
+- Spacing, kebab-case: `gutter`, `gutter-desktop`, `margin`, `margin-desktop`,
+  `space-xs` … `space-2xl`. All dimensions MUST be multiples of 4px/8px.
+
+## Naming Patterns
+
+**Directories:**
+- `snake_case`, name = the screen/feature being mocked up:
+  `stitch_minimalist_route_navigator/active_route_guidance/`,
+  `stitch_minimalist_route_navigator/navigate_map_overview/`,
+  `stitch_minimalist_route_navigator/community_incident_reporter/`,
+  `stitch_minimalist_route_navigator/telegram_live_traffic_feed/`.
+
+**Files (fixed within every screen directory):**
+- `code.html` — the generated mockup markup for that screen.
+- `screen.png` — the rendered screenshot of the same screen. Never rename these;
+  tooling and review flows key on the pair `<screen_dir>/code.html` + `<screen_dir>/screen.png`.
+- `DESIGN.md` (where present) — design-system doc for that screen group.
+
+**Design tokens / classes:** kebab-case (`bg-matte-black`, `text-signal-orange`,
+`border-functional-red`). Do not introduce camelCase or snake_case class names.
+
+## HTML Mockup Style (observed in `code.html` files)
+
+**Structure:**
+- One self-contained HTML file per screen; first `<head>` line is a dense set of
+  `<meta>`/preconnect/font links, incl. Google Fonts `Geist` + `Space Grotesk` and
+  `Material Symbols Outlined`.
+- Tailwind is loaded via CDN (`https://cdn.tailwindcss.com`) with an inline
+  `tailwind.config` script that extends `colors`, `borderRadius`, `spacing`, fonts.
+  Every one of the four `code.html` files duplicates this exact config block — keep it
+  in sync if tokens change.
+- Body uses semantic structure: `<header>` (fixed, h-16), `<main>` (flex-1), with content
+  sections as `<section>` blocks; each major section preceded by an UPPER_SNAKE
+  descriptive comment, e.g. `<!-- Turn-by-Turn Maneuver HUD (Matte Black Primary Chassis) -->`
+  (`stitch_minimalist_route_navigator/active_route_guidance/code.html:10`,
+  `<!-- Incident Telemetry Band -->` at line 44).
+- Fine-grained comments use PascalCase-ish descriptive style:
+  `<!-- Lane Assignment Matrix -->`, `<!-- Position Puck (Dieter Rams Instrument Style) -->`.
+
+**Visual rules enforced by the design system (from `telemetry_rams/DESIGN.md`):**
+- Zero border radius (`0px`) on all containers, buttons, cards, badges, inputs.
+- No shadows-with-blur, no frosted glass, no faux 3D; hierarchy via `1px`/`2px` solid
+  `#1A1A1A` rules and background shifts (`soft-beige` → `chassis-subtle`).
+- Uppercase labels with expanded tracking (`tracking-wider`/`tracking-widest` on
+  `label-*` classes); alphanumeric reference badges in the form `SEC-04 // SPEED`,
+  `CH-08`, `NEXT MANEUVER // T-01`.
+- Icons: Material Symbols or inline `<svg>` with uniform stroke weights (2px standard,
+  3–4px in HUD), `stroke-linecap="square"`, `stroke-linejoin="miter"`.
+- Color semantics are strict: orange = navigation/primary action, red = hazards/errors only,
+  olive green = safe/confirmation, map imagery grayscale.
+
+**Comment density:** section-level comments only — no per-element commentary. Keep this.
+
+## JavaScript (inline in mockups only)
+
+- Vanilla, no framework, small inline `<script>` block at end of body.
+- Functions are `camelCase`, verb-first, one per interaction:
+  `initBraunConsole`, `updatePreview`
+  (`stitch_minimalist_route_navigator/community_incident_reporter/code.html:159-177`);
+  `toggleHazardCard`, `reportHazardModal`, `closeHazardDrawer`, `confirmDispatch`,
+  `triggerQuickDispatch`, `pulseRecenter`, `toggleLayers`
+  (`stitch_minimalist_route_navigator/navigate_map_overview/code.html:266-323`);
+  `insertCommand` (`stitch_minimalist_route_navigator/telegram_live_traffic_feed/code.html:235`).
+- Interaction is triggered via inline `onclick="…"` on buttons (mockups are
+  demonstration-only; do not carry this pattern into production code — use real event
+  listeners/framework handlers when real code exists).
+
+## Where Conventions Are NOT Yet Established
+
+The following have no governance in the repo and must be decided/pinned when real code
+starts:
+
+- **Languages/runtime:** no manifest declares TypeScript/JavaScript versions, Node, or
+  package manager (no `package.json`, `go.mod`, `pyproject.toml` anywhere).
+- **Formatting & linting:** no Prettier/ESLint/Biome/editorconfig. HTML mockups are
+  generated with minified head lines and expanded body lines; treat as generator output,
+  not hand-formatted style.
+- **Module layout / imports:** no application code, no `src/`, no import graph.
+- **Error handling, logging, validation:** no code exists to define patterns for these.
+- **Git hygiene:** the workspace directory is not yet a git repository; when initialized,
+  add a `.gitignore` and commit `DESIGN.md`, `IDEAS.md`, `stitch_minimalist_route_navigator/*`.
+- **Path casing:** any backend service (Telegram bot, OSRM, Neon/Postgres — the stack
+  sketched in `IDEAS.md:55-73`) should follow the existing `snake_case` directory naming
+  for consistency.
+
+## Prescriptive Guidance for New Code
+
+1. **New mockup screen:** create `stitch_minimalist_route_navigator/<new_screen_snake_case>/`
+   with `code.html` and `screen.png`. State which design tokens it uses; do not invent
+   new colors without adding them to the frontmatter of
+   `stitch_minimalist_route_navigator/telemetry_rams/DESIGN.md` first.
+2. **New design token:** update the YAML block in
+   `stitch_minimalist_route_navigator/telemetry_rams/DESIGN.md`, then replicate the token
+   into the inline `tailwind.config` of **all four** existing `code.html` files.
+3. **First real implementation code:** before writing it, codify the above — add a package
+   manifest, formatter/linter config, and a source directory; mirror `camelCase` for
+   functions, `kebab-case` for classes/CSS tokens, `snake_case` for directories.
+
+---
+
+*Convention analysis: 2026-10-21*