docs(01-design-tokens-rams-foundation): create phase plan (4 plans, 3 waves)
This commit is contained in:
araharah-planner
@@ -0,0 +1,148 @@
|
||||
# Codebase Concerns
|
||||
|
||||
**Analysis Date:** 2026-10-21
|
||||
|
||||
**Repo state:** Early-stage design-only project. No git repo, no package manifest, no tests, no backend. Content is two planning docs (`DESIGN.md`, `IDEAS.md`) plus the `stitch_minimalist_route_navigator/` directory of Stitch-generated HTML UI mockups (4 screens with `code.html` + `screen.png`, 1 design-system doc).
|
||||
|
||||
---
|
||||
|
||||
## Tech Debt
|
||||
|
||||
**Directory hygiene: Windows `*:Zone.Identifier` metadata files committed alongside assets**
|
||||
- Issue: Every downloaded asset carries an NTFS Alternate Data Stream export (`*:Zone.Identifier` files) from unzipping on Windows. Top-level `DESIGN.md` and `IDEAS.md` have no counterparts, but 10 of the mockup assets do (e.g., `stitch_minimalist_route_navigator/active_route_guidance/code.html:Zone.Identifier`).
|
||||
- Files: all `stitch_minimalist_route_navigator/*/*:Zone.Identifier` (10 files — one per `code.html` and per `screen.png` in the four screen directories)
|
||||
- Impact: Noise pollution in every glob/grep operation, misleading file listings, and potential pipeline breakage when tooling glob patterns accidentally match these files as HTML/PNG sources. Their one-time content even leaked a local Windows path (`X:\Donlod\...zip`) — a minor information-disclosure artifact.
|
||||
- Fix approach: Delete all `*:Zone.Identifier` files now (`find . -name "*:Zone.Identifier" -delete`). Once a git repo is initialized, add a `.gitignore` blocking the pattern and add a pre-commit or CI hygiene check. Never treat these files as content sources.
|
||||
|
||||
**No version control, no ignores file**
|
||||
- Issue: There is no `.git` directory and no `.gitignore` at the repo root. All work exists only on disk.
|
||||
- Files: repo root (`/home/C-Fu/araharah/`)
|
||||
- Impact: Any accidental delete loses the only copy of the mockups and design docs; no change history for iterating on screens; the Zone.Identifier debt described above has no automated guard.
|
||||
- Fix approach: `git init` as the very first implementation step, with a `.gitignore` covering `*:Zone.Identifier`, OS junk (`.DS_Store`, `Thumbs.db`), and future `node_modules/` / secrets.
|
||||
|
||||
**Four copies of the same ~5KB inline Tailwind theme config**
|
||||
- Issue: Each `code.html` embeds the full `tailwind.config={...}` design-token block (colors, fontSize, spacing, fontFamily) as a duplicate inline `<script id="tailwind-config">`. It is byte-for-byte identical across all four screens (tokens match `stitch_minimalist_route_navigator/telemetry_rams/DESIGN.md:2-148`), so ~20KB of the 94KB total is pure duplication.
|
||||
- Files: `stitch_minimalist_route_navigator/active_route_guidance/code.html`, `stitch_minimalist_route_navigator/community_incident_reporter/code.html`, `stitch_minimalist_route_navigator/navigate_map_overview/code.html`, `stitch_minimalist_route_navigator/telegram_live_traffic_feed/code.html`
|
||||
- Impact: Any token change (e.g., palette tweak) must be edited in four places; a single missed copy silently diverges the visual system between screens.
|
||||
- Fix approach: When prototype-grade tooling is introduced, extract the token block to a single shared config (Tailwind `.js` config or CSS custom properties) and reference it from a built stylesheet. Until then, enforce a note that these are throwaway artifacts not to be edited in place.
|
||||
|
||||
**Single-line minified HTML in mockups**
|
||||
- Issue: The `code.html` files are Stitch exports with entire documents collapsed onto one or two extremely long lines (e.g., head + body markup as a single line), only the `<style>` and comment blocks are broken out.
|
||||
- Files: all four `stitch_minimalist_route_navigator/*/code.html`
|
||||
- Impact: Impossible to diff meaningfully, painful to hand-edit, and grep context output is unusable (one "line" contains the whole document).
|
||||
- Fix approach: Treat these as generated, read-only reference artifacts. If they must be edited, run them through a formatter (Prettier) once and keep the formatted copy under version control going forward.
|
||||
|
||||
---
|
||||
|
||||
## Design-Source-of-Truth Conflicts (Fragile Areas)
|
||||
|
||||
**Two competing design systems in the same repo**
|
||||
- Issue: Root `DESIGN.md` specifies Helvetica Neue/Inter, 14px body / 18px headings / 24px titles, and a 5-color palette (`DESIGN.md:17-35`). Meanwhile `stitch_minimalist_route_navigator/telemetry_rams/DESIGN.md:59-148` specifies Space Grotesk + Geist, an entire Material-style token set (surface containers, fixed/variant colors), and the actual mockups implement the *latter* (their inline Tailwind config uses `Space Grotesk`/`Geist` and ~40 token colors, not Helvetica/Inter with 5 colors).
|
||||
- Files: `DESIGN.md`, `stitch_minimalist_route_navigator/telemetry_rams/DESIGN.md`
|
||||
- Impact: A future implementer reading the top-level `DESIGN.md` will code against the wrong typography and palette. The repo's "canonical" design doc contradicts its own reference implementation.
|
||||
- Safe modification: Decide which doc wins (recommend promoting `telemetry_rams/DESIGN.md` to root design authority since the mockups match it), mark the loser as superseded or delete it, and state a single-file-of-truth rule before any UI phase.
|
||||
|
||||
**Mockups violate their own zero-roundedness / anti-flat-glow rules**
|
||||
- Issue: `telemetry_rams/DESIGN.md:206-208` mandates "absolute zero roundedness (0px corner radius)" and rejects blurs/frosted glass (`DESIGN.md:196`), yet the mockups contain `rounded-full`/rounded classes (e.g., avatar circles, chips in `active_route_guidance/code.html`, ~5 occurrences) and a `backdrop-blur-xl shadow-[0_1px_8px_rgba(0,0,0,0.04)]` header in `active_route_guidance/code.html`.
|
||||
- Files: `stitch_minimalist_route_navigator/active_route_guidance/code.html` (header, avatar), `stitch_minimalist_route_navigator/community_incident_reporter/code.html`
|
||||
- Impact: Screens are a compromised reference; copying markup into the real app would import non-Rams ornament that the design doc forbids.
|
||||
- Safe modification: When implementing, treat the *design doc* token rules as binding and the *mockup markup* as layout reference only; scrub rounded/blur utilities during implementation.
|
||||
|
||||
---
|
||||
|
||||
## Mockup Fragility / Runtime Dependencies
|
||||
|
||||
**Runtime Tailwind CDN + third-party CDN single points of failure**
|
||||
- Issue: Every screen loads Tailwind as an uncompiled runtime script from `https://cdn.tailwindcss.com` (officially "not for production"), plus Google Fonts (Geist, Space Grotesk), Material Symbols Outlined, and a `lh3.googleusercontent.com` logo image. There is no vendoring, no build step, and no `package.json`; the screens render correctly only with internet access to these CDNs.
|
||||
- Files: `<head>` of all four `stitch_minimalist_route_navigator/*/code.html`
|
||||
- Trigger: Open offline, or when the ephemeral Google-hosted logo URL expires.
|
||||
- Workaround: None in-repo. This is fine for mockups but disqualifies the files from production use as-is.
|
||||
- Fix approach: For the real app, use a compiled Tailwind build (this happens naturally once any framework/tooling phase runs). Download the logo asset locally if it is to be reused.
|
||||
|
||||
**Hardcoded mock data and dead-end interactions**
|
||||
- Issue: Navigation/route data, telemetry numbers, hazard cards, and traffic feed messages are hardcoded `const` arrays/objects inside each screen; handlers are inline `onclick` stubs (`confirmDispatch('CONGESTION')`, `toggleHazardCard('ACCIDENT')` in `navigate_map_overview/code.html`; `insertCommand('/hazard ')` and `alert('Reroute broadcast loaded.')` in `telegram_live_traffic_feed/code.html`). No fetch calls, no map tiles, no routing engine — the "map" is a static styled panel.
|
||||
- Files: all four `stitch_minimalist_route_navigator/*/code.html` (`<script>` block at end of each file)
|
||||
- Impact: The mockups give no signal about the hard part (OSRM routing, live Telegram feed, geographic event storage in PostGIS); estimating implementation effort from these screens alone will be badly optimistic.
|
||||
- Fix approach: Treat mock data shapes as informal UI contracts (the `const` structures are a reasonable starting point for real data models) but plan backend/integration phases before promising any of the flows in `DESIGN.md:69-73`.
|
||||
|
||||
**Shell-specific assumptions baked in**
|
||||
- Issue: The screens carry `<meta name="shell-type" content="mobile_stack">`, `user-scalable=no`, fixed `884px`-min-height bodies, and hidden scrollbars (`::-webkit-scrollbar{display:none}`) — targeting a specific mobile embed/stitch render shell rather than standalone browsers.
|
||||
- Files: `<head>`/`<style>` of all four `stitch_minimalist_route_navigator/*/code.html`
|
||||
- Impact: Accessibility regression (`user-scalable=no` blocks pinch zoom; contrast and zoom rules conflict), and layout breaks if opened directly on desktop or inside a nonstandard webview.
|
||||
- Fix approach: Strip `user-scalable=no` and shell-only metas when porting; these are mockup artifacts, not app requirements.
|
||||
|
||||
---
|
||||
|
||||
## Architecture / Roadmap Reality Gaps
|
||||
|
||||
**Heavyweight target stack vs. zero implemented code**
|
||||
- Issue: `IDEAS.md:55-73` specifies a full production architecture: Telegram Bot + PWA, Neon Postgres+PostGIS, OSRM with dynamic traffic weighting, Maptiler tiles, RabbitMQ queue, Cloudflare R2, Prometheus/Grafana, Resend email. Nothing in the repo implements even one of these components — there is no source code at all, no `package.json`, and no CI.
|
||||
- Files: `IDEAS.md`, repo root
|
||||
- Impact: Highest-value concern: the gap between the mockups (static UI shells) and the vision (distributed multi-service system) is the entire engineering project. Prioritizing infrastructure (RabbitMQ, Grafana, R2) before a walking-skeleton bot + OSRM round-trip would be premature.
|
||||
- Fix approach: Sequence phases as: git init → walking-skeleton Telegram bot echoing commands → OSRM route round-trip → PostGIS event storage → then queue/monitoring/storage. Treat unneeded services (RabbitMQ, Resend, Prometheus) as explicitly deferred, not part of an MVP.
|
||||
|
||||
**Undefined design ambiguity: "minimal single-file" vs. scalable app**
|
||||
- Issue: Nothing in the repo states what runtime the eventual product uses (plain web app?, PWA?, Telegram WebApp embed?). The mockups' inline CSS/JS monolith pattern will not scale: 4 screens already total ~98KB of duplicated tokens and copy-pasted utility classes; at 10–20 screens this pattern guarantees drift described in the Tailwind-duplication section.
|
||||
- Files: `IDEAS.md:57-58` ("Telegram-first: ... optional PWA"), `stitch_minimalist_route_navigator/*`
|
||||
- Impact: Blocks any implementation phase from starting correctly; the first framework decision will retroactively invalidate markup assumptions from all mockups.
|
||||
- Fix approach: Make the runtime/format decision (e.g., Next.js PWA served in Telegram WebApp, React + compiled Tailwind, shared token file) in a dedicated setup phase before porting any mockup.
|
||||
|
||||
---
|
||||
|
||||
## Security Considerations
|
||||
|
||||
**Leaked local path in committed metadata**
|
||||
- Risk: `*:Zone.Identifier` files record source download URLs; the one inspectable case contains `ReferrerUrl=X:\Donlod\...zip`, disclosing a filesystem path pattern.
|
||||
- Files: `stitch_minimalist_route_navigator/*/*:Zone.Identifier`
|
||||
- Current mitigation: None (no git repo, no CI, no scrubbing step).
|
||||
- Recommendations: Delete the files (see Tech Debt #1); if a git repo is initialized without cleaning, this path is forever in history.
|
||||
|
||||
**No secrets to leak — but no key management either**
|
||||
- Risk: Trivially low today (no code), but the target stack requires Telegram bot tokens, Maptiler keys, and Neon credentials with no designed home for them.
|
||||
- Files: none yet
|
||||
- Current mitigation: None.
|
||||
- Recommendations: Establish `.env` + `.env.example` + `secretlint` toggle in `.gitignore` during the first setup phase, *before* any real credentials exist.
|
||||
|
||||
**Nondeterministic third-party scripts running on every mockup open**
|
||||
- Risk: `cdn.tailwindcss.com` bundles and executes a JIT compiler in-page; any CDN compromise or the service's eventual shutdown changes/breaks behavior silently. Low stakes while these are mockups, but relevant the moment anyone shares them with stakeholders as "the product."
|
||||
- Files: all four `stitch_minimalist_route_navigator/*/code.html` `<head>`
|
||||
- Recommendations: Keep communicating they are mockups; for any public demo, pin/snapshot the CDN output locally first.
|
||||
|
||||
## Performance Bottlenecks
|
||||
|
||||
Not yet applicable — no runtime code exists. For the record: the mockups render fine despite the runtime-Tailwind approach, but that approach bleeds ~300KB of compiler JS before first paint, which would be a bottleneck in the real app and is eliminated by compiled Tailwind.
|
||||
|
||||
## Scaling Limits
|
||||
|
||||
**Mockup pattern scales to zero screens**
|
||||
- Problem: Per-file token duplication on 4 screens is already at the maintainability ceiling; the repo cannot accommodate 10+ screens without guaranteed divergence.
|
||||
- Cause: No shared stylesheet/config; Stitch exports are atomic single files.
|
||||
- Files: all four `stitch_minimalist_route_navigator/*/code.html`
|
||||
- Improvement path: Extract tokens and shared chrome into the real app's component/config layer during the first implementation phase.
|
||||
|
||||
## Dependencies at Risk
|
||||
|
||||
**`cdn.tailwindcss.com` (runtime CDN)**
|
||||
- Risk: Unpinned, production-discouraged, service availability not guaranteed; a change or outage breaks all four mockups at once.
|
||||
- Impact: Mockups stop rendering properly; no local fallback exists.
|
||||
- Migration plan: Compiled Tailwind via any JS tooling in the first build phase; for the repo's mockups, snapshot locally if they need to survive long-term.
|
||||
|
||||
**Google Fonts + `lh3.googleusercontent.com` assets**
|
||||
- Risk: Fonts load only online; the AI-generated logo URL is ephemeral and is referenced identically in all four files — if it dies, branding breaks everywhere simultaneously with no local replacement.
|
||||
- Files: `stitch_minimalist_route_navigator/active_route_guidance/code.html` and the three sibling `<head>`s
|
||||
- Migration plan: Download the logo into the repo asset tree; self-host fonts (or subset) in the real app.
|
||||
|
||||
## Missing Critical Features
|
||||
|
||||
**Everything is missing by design** — no code, no tests, no CI, no manifest, no git, no `README`. The notable early gaps to plan explicitly:
|
||||
- Problem: No `README.md` explaining the repo's purpose, no license, no git history, no developer tooling config (editor/lint/format), no `package.json` even for tooling.
|
||||
- Blocks: Onboarding anyone (or any future agent session) requires re-deriving context from `IDEAS.md`/`DESIGN.md` every time; the Zone.Identifier debt and doc conflicts above go unnoticed indefinitely.
|
||||
- Fix approach: Preface the first phase with "project setup": git init, README capturing the Rams design intent and pointing to the authoritative design doc, `.gitignore`, and license.
|
||||
|
||||
## Test Coverage Gaps
|
||||
|
||||
Not applicable — there is nothing to test yet. When the first real code lands, note that the repo has zero testing conventions to inherit from; `TESTING.md` will need to be generated fresh alongside the first implementation phase.
|
||||
|
||||
---
|
||||
|
||||
*Concerns audit: 2026-10-21*
|
||||
Reference in New Issue
Block a user