docs(01-design-tokens-rams-foundation): create phase plan (4 plans, 3 waves)
This commit is contained in:
araharah-planner
@@ -0,0 +1,116 @@
|
||||
# Codebase Structure
|
||||
|
||||
**Analysis Date:** 2026-10-21
|
||||
|
||||
## Directory Layout
|
||||
|
||||
```
|
||||
araharah/
|
||||
├── .planning/ # GSD planning artifacts (this analysis)
|
||||
│ └── codebase/ # Codebase map documents
|
||||
├── DESIGN.md # Design philosophy: palette, typography, iconography, flows
|
||||
├── IDEAS.md # Product vision, principles, implied target stack
|
||||
└── stitch_minimalist_route_navigator/ # UI mockup suite ("Telemetry Rams" screens)
|
||||
├── active_route_guidance/
|
||||
│ ├── code.html # Turn-by-turn navigation HUD mockup
|
||||
│ └── screen.png # Visual capture of the screen
|
||||
├── community_incident_reporter/
|
||||
│ ├── code.html # Incident report flow mockup
|
||||
│ └── screen.png # Visual capture
|
||||
├── navigate_map_overview/
|
||||
│ ├── code.html # Full-map navigation overview mockup
|
||||
│ └── screen.png # Visual capture
|
||||
├── telegram_live_traffic_feed/
|
||||
│ ├── code.html # Telegram bot traffic feed mockup
|
||||
│ └── screen.png # Visual capture
|
||||
├── telemetry_rams/
|
||||
│ └── DESIGN.md # Formal design system spec (tokens + component rules)
|
||||
│ # (no screen.png — this is the design system, not a screen)
|
||||
└── */:Zone.Identifier # Windows download metadata — ignore everywhere
|
||||
```
|
||||
|
||||
## Directory Purposes
|
||||
|
||||
**Root (`/`):**
|
||||
- Purpose: Planning documents for a not-yet-implemented product
|
||||
- Contains: `DESIGN.md` (85 lines, design philosophy) and `IDEAS.md` (95 lines, vision + implied target stack)
|
||||
- Key files: `DESIGN.md`, `IDEAS.md`
|
||||
|
||||
**`stitch_minimalist_route_navigator/`:**
|
||||
- Purpose: Self-contained static HTML mockups of the app's four key screens, generated with the "Telemetry Rams" design system (Rams-minimalist telemetry aesthetic)
|
||||
- Contains: One subdirectory per screen; each screen dir holds `code.html` + `screen.png`
|
||||
- Key files: `active_route_guidance/code.html` (189 lines), `navigate_map_overview/code.html` (344 lines), `telegram_live_traffic_feed/code.html` (302 lines), `community_incident_reporter/code.html` (274 lines)
|
||||
|
||||
**`stitch_minimalist_route_navigator/telemetry_rams/`:**
|
||||
- Purpose: Canonical design-system definition (YAML front matter with `colors`, `typography`, `spacing`; then component specs)
|
||||
- Contains: `DESIGN.md` (241 lines) — the only non-root, non-screen documentation
|
||||
- Key files: `stitch_minimalist_route_navigator/telemetry_rams/DESIGN.md`
|
||||
|
||||
**`.planning/`:**
|
||||
- Purpose: GSD planning artifacts; hosts `.planning/codebase/` documents (written by this analysis)
|
||||
- Generated: Yes (GSD tooling)
|
||||
- Committed: Yes (treat as project documentation)
|
||||
|
||||
## Key File Locations
|
||||
|
||||
**Entry Points:**
|
||||
- `stitch_minimalist_route_navigator/{screen}/code.html`: Open directly in a browser; each is a standalone mockup. No build step required (Tailwind/fonts load from CDN).
|
||||
- No application entry points exist (`no src/`, no `index.*`, no `main.*`, no package manifest).
|
||||
|
||||
**Configuration:**
|
||||
- No config files exist (no `package.json`, `tsconfig.json`, `.eslintrc`, `.env*`, lockfile, or CI config detected).
|
||||
- Design configuration lives in prose/YAML: `stitch_minimalist_route_navigator/telemetry_rams/DESIGN.md`.
|
||||
|
||||
**Core Logic (current):**
|
||||
- All interactivity is inline demo JS inside each `code.html` (e.g., `insertCommand('/hazard ...')`, `toggleLayers()`, `confirmDispatch()`, `closeHazardDrawer()`). See `navigate_map_overview/code.html` and `telegram_live_traffic_feed/code.html` for the richest handler sets.
|
||||
|
||||
**Testing:**
|
||||
- No test files or test framework present. Not applicable yet.
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
**Files:**
|
||||
- Screens use lowercase `snake_case` directory names naming the screen purpose: `active_route_guidance`, `navigate_map_overview`, `telegram_live_traffic_feed`, `community_incident_reporter`
|
||||
- Fixed per-screen filenames: `code.html` (mockup source) and `screen.png` (capture)
|
||||
- Top-level docs use `UPPER-SNAKE.md`: `DESIGN.md`, `IDEAS.md`
|
||||
|
||||
**Directories:**
|
||||
- `snake_case` throughout (`stitch_minimalist_route_navigator`, `telemetry_rams`, `.planning/codebase`)
|
||||
|
||||
**In-code naming (mockups):**
|
||||
- CSS utility classes map to design tokens: `signal-orange`, `matte-black`, `soft-beige`, `functional-red`, `olive-green`, `chassis-subtle`, `surface-*` variants
|
||||
- JS demo functions use camelCase: `insertCommand`, `toggleLayers`, `confirmDispatch`, `closeHazardDrawer`, `updatePreview`
|
||||
- Section reference badges follow an uppercase `SEC-XX // LABEL` convention (e.g., `SEC-STACK // EXEC`, `CH-08`)
|
||||
|
||||
## Where to Add New Code
|
||||
|
||||
**New mockup screen:**
|
||||
- Create `stitch_minimalist_route_navigator/<screen_name_snake_case>/` containing `code.html` (self-contained, Tailwind CDN + inline `tailwind.config` with the Telemetry Rams tokens + inline SVG glyphs) and a `screen.png` capture
|
||||
- Follow the register-band layout documented in `telemetry_rams/DESIGN.md` (top/center/lower registers, 8px grid, 0px radius)
|
||||
|
||||
**Applying design tokens:**
|
||||
- Copy token values from `stitch_minimalist_route_navigator/telemetry_rams/DESIGN.md` (colors, typography, spacing) into the new screen's inline `tailwind.config`; keep the five core colors verbatim (`signal-orange: #EB8008`, `functional-red: #ED3F1C`, `olive-green: #736B1E`, `soft-beige: #D9D2C6`, `matte-black: #1A1A1A`)
|
||||
|
||||
**Documentation:**
|
||||
- Product-level ideas/stack changes → `IDEAS.md` (root)
|
||||
- Design philosophy changes → `DESIGN.md` (root)
|
||||
- Formal token/component spec changes → `stitch_minimalist_route_navigator/telemetry_rams/DESIGN.md`
|
||||
|
||||
**Future implementation code (when project leaves design phase):**
|
||||
- No conventional locations exist yet. The implied target stack in `IDEAS.md` (Telegram bot backend, Neon Postgres, OSRM, Cloudflare Pages/R2) will need a conventional `src/` or service layout to be established by the first planning phase.
|
||||
|
||||
## Special Directories
|
||||
|
||||
**`.planning/`:**
|
||||
- Purpose: GSD planning/orchestration artifacts
|
||||
- Generated: Yes, by GSD commands
|
||||
- Committed: Yes
|
||||
|
||||
**`*:Zone.Identifier` files:**
|
||||
- Purpose: None (Windows download metadata attached to every HTML/PNG/MD file)
|
||||
- Generated: Yes (OS artifact)
|
||||
- Committed: Accidentally present — should be excluded from version control and any future lint/build globbing (add to `.gitignore`: `*:Zone.Identifier`)
|
||||
|
||||
---
|
||||
|
||||
*Structure analysis: 2026-10-21*
|
||||
Reference in New Issue
Block a user