strdst7/Arah2

Fork 0

forked from c-fu/arah2

Files

T

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

2026-10-22 02:33:01 +08:00

6.6 KiB

Raw Blame History

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