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.  (stitch_minimalist_route_navigator/active_route_guidance/code.html:10,  at line 44).
Fine-grained comments use PascalCase-ish descriptive 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

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

7.5 KiB Raw Blame History Unescape Escape