# 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
```