docs/FRONTEND.md

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