134 lines
7.5 KiB
Markdown
134 lines
7.5 KiB
Markdown
# 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*
|