Spaces:
Sleeping
Sleeping
| # Frontend Design Document v2 | |
| ## Habit Journal PWA — Apple-fluid UI + existing API | |
| **Depends on:** Backend live on HF (`docs/BACKEND.md` v2). No new backend features unless blocked. | |
| **Version:** 2.0 | |
| **Scope:** Mobile-first iPhone Safari PWA consuming the Habit Journal API. | |
| --- | |
| ## 0. Composer instructions | |
| 1. Spec wins. Small slices **F0→F8**. | |
| 2. **Mobile-first iPhone Safari PWA**; desktop acceptable, not primary. | |
| 3. Stack: **Vite + Preact + Motion (`motion`)** + plain CSS variables. No heavy component library. | |
| 4. `credentials: 'include'` on all API calls; `401` → login. | |
| 5. SW: **shell only**; **`/api/*` network-only** — never cache API. | |
| 6. Time-to-first-log **< 20s** after login. | |
| 7. Coach: show **SERVER_PICKS** + badge **Rules** | **Model** (not “AI failed”). | |
| 8. Discrete copy only (“Habit Journal”). | |
| 9. **Apple motion rules are mandatory** for sheets, nav, presses, toasts. | |
| 10. Respect `prefers-reduced-motion`, `prefers-reduced-transparency`, `prefers-contrast`. | |
| 11. Prototype interactions in code; no static-only “design phase.” | |
| 12. Do not block Log on Coach. | |
| 13. Deploy engine first if not already: backend on Space with `/data` before polishing pixels. | |
| --- | |
| ## 1. Product principles | |
| | Apple need | Habit Journal meaning | | |
| |------------|------------------------| | |
| | Safety / predictability | Same controls same place; undo-friendly edits; confirm only on delete | | |
| | Understanding | Every screen: where am I, what next, how out | | |
| | Achievement | One Primary brick / one log feels complete | | |
| | Joy | Calm confidence from craft — not gamification spam | | |
| **Refuse:** social feed, public profiles, coach that replaces tapping **Result**. | |
| **Agency:** User owns `result`. Model suggests; Rules backup never shames. | |
| --- | |
| ## 2. Stack | |
| ``` | |
| frontend/ | |
| package.json | |
| index.html | |
| src/ | |
| main.tsx | |
| api.ts | |
| router.tsx | |
| styles/ tokens.css, reset.css, materials.css | |
| motion/ springs.ts, gestures.ts | |
| components/ Button, Pressable, Toast, … | |
| pages/ Login, Home, Log, … | |
| pwa/ (F8) | |
| dist/ → FastAPI static/ | |
| ``` | |
| --- | |
| ## 3. Routes | |
| | Route | Page | Role | | |
| |-------|------|------| | |
| | `#/login` | Login | Password | | |
| | `#/` | Home | Today + CTA | | |
| | `#/log` | Log | Fast create | | |
| | `#/history` | History | List/filter | | |
| | `#/entry/:id` | Entry | Detail / edit / coach | | |
| | `#/daily` | Daily | Scoreboard | | |
| | `#/stats` | Stats | Server probs | | |
| | `#/coach` | Coach | Suggest + picks | | |
| | `#/remedies` | Remedies | Leaderboard | | |
| | `#/settings` | Settings | Export, install, logout | | |
| **Tab bar (F2+):** Home · Log · Daily · Stats · Coach | |
| **Overflow:** History · Remedies · Settings · Logout | |
| --- | |
| ## 4. Design tokens | |
| Dark-first system tokens (`--bg`, `--accent`, materials with blur). | |
| Min tap **44×44px**. Screen padding **16–20px**. Card radius **12–16px**. | |
| `prefers-reduced-transparency` → solid surfaces, no blur. | |
| `prefers-contrast: more` → stronger borders. | |
| --- | |
| ## 5. Motion (mandatory) | |
| 1. Feedback on **pointer-down**, not click-up. | |
| 2. 1:1 drag with pointer capture. | |
| 3. Interruptible springs; velocity handoff; project momentum; rubber-band. | |
| 4. Springs for touchable UI; CSS only for trivial color/opacity. | |
| 5. Tab switches: cross-fade; stack: short horizontal spring; reduced-motion → opacity only. | |
| Spring presets: `ui`, `snap`, `flick`, `sheet`, `press`. | |
| Gestures: `project()`, `rubberband()`, velocity samples. | |
| --- | |
| ## 6–7. Components & screens | |
| **F0–F1 required:** Login, me gate, Pressable/Button, Log (happened, emotions, intensity, result, remedy, Save), Toast. | |
| Home may be a minimal CTA shell until F2 TabBar. | |
| Later: History, Entry, Daily, Stats, Coach, Remedies, Settings, Sheet, PWA. | |
| **Log goal:** <20s to save. Secondary fields (activity, tags, notes) collapsed under More. | |
| **Coach badge map:** `backup` / `model_unparsed_fallback` → Rules; `model` → Model. | |
| --- | |
| ## 8. API wrapper | |
| `fetch` with `credentials: 'include'`; `401` → `#/login`; envelope `{ok, data, error}`. | |
| --- | |
| ## 9. PWA (F8) | |
| Manifest + SW shell cache; **never** cache `/api/*`. | |
| Apple meta: capable, black-translucent, viewport-fit=cover. | |
| --- | |
| ## 10–11. Feedback & a11y | |
| Toast for save/copy/error. Focus rings, labels, result chip text (not color alone). | |
| Reduced motion / transparency / contrast wired in components. | |
| --- | |
| ## 12. Implementation slices | |
| | Slice | Deliverable | | |
| |-------|-------------| | |
| | **F0** | Vite+Preact, tokens, materials, router, api, Login, me gate | | |
| | **F1** | Pressable/Button, Log page, save, toast | | |
| | **F2** | Home + TabBar material + safe areas | | |
| | **F3** | History + Entry edit/delete | | |
| | **F4** | Daily | | |
| | **F5** | Stats + Remedies | | |
| | **F6** | Coach + ServerPicks + Badge + copy debug | | |
| | **F7** | Sheet gestures, More menu | | |
| | **F8** | PWA + Settings install + reduced-motion pass | | |
| --- | |
| ## 13. Acceptance (F0–F1 subset) | |
| - [ ] Login cookie works; unauth → login | |
| - [ ] Log entry saves via API; toast on success | |
| - [ ] Buttons react on **press** | |
| - [ ] `prefers-reduced-motion` respected on press/toast | |
| - [ ] FastAPI serves frontend without breaking `/api` | |
| --- | |
| ## 14. Anti-patterns | |
| No press-on-click-only; no API caching in SW; no blocking Log on Coach; no pep-talk empty states. | |
| --- | |
| ## 16. Mental model | |
| ``` | |
| Apple: response → direct manipulation → interruptible springs → materials → type | |
| App: fast Log → honest Result → server math visible → coach optional → debug paste | |
| ``` | |