Spaces:
Sleeping
Sleeping
File size: 5,451 Bytes
5e0e982 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 | # 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
```
|