Parent Epic
#104
Problem
The README describes what the app does but not the design philosophy behind it. Readers can infer principles from the code, but stating them explicitly frames every technical choice as intentional design — the difference between "they didn't add a backend" and "they deliberately chose a local-only architecture."
Current State
No design principles or philosophy section in README.
Desired State
Add a "Design Principles" section to README.md between the Features list and Tech Stack table. Keep it concise — 5-6 principles, one sentence each.
Suggested Content
## Design Principles
- **Offline-first** — The app must work without connectivity. GPS, recording, and cached tiles function offline; only search requires internet.
- **Local-only data** — All GPS data, trails, and settings stay in the browser. No accounts, no server-side storage, no tracking.
- **Progressive enhancement** — Core features (map, GPS, recording) work on any modern browser. Advanced features (offline download, battery estimation) activate when APIs are available.
- **Mobile-native UX** — Bottom sheets, snap points, safe-area insets, touch-optimized controls. The web app should feel as natural as a native app.
- **Minimal dependencies** — Leaflet for maps, ESRI for geocoding, Workbox for offline. No React, no state management library, no CSS framework.
- **Transparent architecture** — Single shared state, no magic. Every data flow is traceable through explicit function calls.
Suggested Prompt
Add a "Design Principles" section to README.md between the Features
list and the Tech Stack table. Include 5-6 concise principles (one
sentence each) that frame the project's key architectural choices:
- Offline-first (app works without connectivity)
- Local-only data (no server storage, no accounts, no tracking)
- Progressive enhancement (core works everywhere, advanced features
activate when APIs available)
- Mobile-native UX (bottom sheets, safe-area insets, touch controls)
- Minimal dependencies (no framework, no CSS lib, no state management)
- Transparent architecture (single state, explicit data flow)
Read the actual codebase to verify each principle is accurate — don't
claim something that isn't true. Commit and push.
Acceptance Criteria
Parent Epic
#104
Problem
The README describes what the app does but not the design philosophy behind it. Readers can infer principles from the code, but stating them explicitly frames every technical choice as intentional design — the difference between "they didn't add a backend" and "they deliberately chose a local-only architecture."
Current State
No design principles or philosophy section in README.
Desired State
Add a "Design Principles" section to README.md between the Features list and Tech Stack table. Keep it concise — 5-6 principles, one sentence each.
Suggested Content
Suggested Prompt
Acceptance Criteria