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