# PLAN-U1: UX directions

## 1. Goal
Produce two or three clearly different visual directions for Kvitt as self-contained HTML phone mock-ups with PNG exports, so the owner can pick one. Each direction shows the six key screens in light and dark, in Swedish, with realistic household data, and states its palette, typography, shape, motion and iconography.

## 2. Read first
Read these, in this order, and nothing else before starting. Everything the UX work needs is in SPEC §13 and the sections it cites.
1. SPEC §13 UX sprint: §13.1 Context the UX agent must design for, §13.2 Navigation model, §13.3 Screens and what each must show, §13.4 Deliverables (Phase 1), §13.5 Out of scope for the UX sprint.
2. SPEC §9.7 Icon and colour tokens.
3. SPEC §9.8 Formatting.
4. SPEC §9.2 Effect line from the viewer's side (lists) and §9.3 Balances (the wording rules).
5. SPEC §4 FR-8 Expenses (AC-8.10), FR-10 Balances, FR-11 Settlements, FR-12 Audit log and timeline (AC-12.4, AC-12.5), FR-14 Analytics (AC-14.2 to AC-14.6): the copy and content the six screens must carry.
6. SPEC §2 Non-goals (so no direction shows a non-goal).
7. `CLAUDE.md` sections ORCHESTRATION (worktrees), ANTI-PATTERNS (no placeholder text), EXECUTION PROTOCOLS.

## 3. Already established
- Two adults in Sweden, Samsung Galaxy S26 and S26+, about 411 × 891 dp viewport, portrait only, Android 16; Material 3 (Expressive where stable), must not imitate One UI (§13.1).
- The add-expense flow is the most important flow: open app, tap add, type amount, type description, tap save (§13.1, AC-8.6). "Who owes whom" on Home is second (§13.1).
- Swedish is primary; designs must survive long Swedish words at 200 % font scale (§13.1).
- Light and dark follow the system; dynamic colour only as a per-direction option if the direction still works with it (§13.1).
- Amounts in tabular figures; direction always in words plus colour, never colour alone (§13.1); money never shown with a minus sign (§9.8).
- Accessibility: touch targets ≥ 48 dp, text contrast ≥ 4.5:1, TalkBack labels for icon-only controls, reflow at 200 % (§13.1).
- Category icons only from the 30 Material Symbols tokens of §9.7; 12 colour token names fixed, hex values may change, light and dark values with contrast checked against both surfaces (§9.7, §13.1).
- Users shown by avatar (picture or initials on a colour derived from the user id, AC-4.5) and name; the viewer is always "you"/"du" (§13.1).
- Navigation: bottom navigation Home (Översikt), Analytics (Statistik), Settings (Inställningar); FAB "Add expense" (Lägg till utgift) on Home and Account detail; pushed screens with top app bar and back; full-screen expense editor, not a bottom sheet. Binding unless a direction proposes a better one with reasons (§13.2).
- Money format sv `1 234,50 kr` with U+00A0; dates in lists `3 okt.`, detail `lördag 3 oktober 2026`, times `14:02` (§9.8).
- Balance wording: "<Other> owes you X", "You owe <Other> X", "All settled up" (account screens "Settled up") (§9.3); effect lines "You lent", "You borrowed", "Not involved", "Paid for yourself" (§9.2).
- Phase 1 screens per direction: S-4 Home, S-7 Expense editor, S-5 Account detail, S-9 Settle up, S-11 Analytics, S-8 Expense detail with timeline, each light and dark, Swedish, names "Jacob" and "Anna", Swedish shops and amounts, no lorem ipsum (§13.4).
- No external requests except Google Fonts (§13.4). The app bundles no font and uses the Material 3 default typeface (D-020); a direction may preview another typeface, but U2's design spec replaces it with the default.
- Suggested starting points "Kvitto", "Skärgård", "Kontor" may be used, replaced or merged; at least two clearly different directions (§13.4).
- The UX agent writes no Kotlin (§13, §13.5).

## 4. Owned paths
From SPEC §14.7, verbatim: `docs/ux/**` (owner: U1, U2).

Edit nothing outside these paths; a needed change elsewhere is a contract request to the orchestrator.

## 5. Deliverables
- `docs/ux/directions/<n>-<slug>/index.html` for each of 2 or 3 directions: self-contained page rendering a 411 dp phone frame with S-4, S-7, S-5, S-9, S-11, S-8 in light and dark, Swedish, realistic data.
- In each `index.html` (or a section of it): name and one-line idea; palette (primary, secondary, tertiary, surfaces, error, "owed" and "owing" semantic colours, the 12 category colours) light and dark with contrast ratios; typography (M3 type scale, typeface and why, tabular figures); shape (corner radii per component size); elevation and motion principles; iconography (Material Symbols style, weight, fill rules); balance header in its three states; one 200 % font-scale screenshot.
- `docs/ux/directions/<n>-<slug>/png/*.png`: one PNG per screen per theme of that direction, plus the 200 % font-scale screenshot.
- `docs/ux/directions/README.md`: comparison table (character, strengths, risks, implementation cost in Compose) and the recommendation with reasons.

## 6. Steps
1. Worktree. The owner runs the UX sprint in a separate session in the worktree `~/orca/workspaces/kvitt/UX-sprint` on branch `UX-sprint`; work only there and `git rebase main` before reporting. No git-ignored files are needed for this plan; do not copy any.
2. Read §2 of this plan in order.
3. Choose 2 or 3 directions (start from §13.4's suggestions or replace them) and write one paragraph each in `docs/ux/directions/README.md` before drawing anything.
4. Build the realistic Swedish data set once (shared by all directions): users Jacob and Anna; accounts such as "Vardag", "Huset", "Japan 2027" plus one archived account; expenses at Swedish shops (ICA, Coop, Systembolaget, SJ, Clas Ohlson) with amounts that exercise thousands separators; one recurring expense; a settlement with two allocations; a timeline with create and change lines per AC-12.4 and a pending line per AC-12.5; analytics over `last_6_months` by category.
5. For each direction write `index.html` with all six screens in light and dark. Copy follows §9.2, §9.3, §9.8 and the AC wording of FR-8, FR-10 to FR-12, FR-14, in Swedish (the UX agent writes the Swedish). Check every text/background pair for ≥ 4.5:1 and record the ratios.
6. Add the direction's statement block (palette, typography, shape, elevation/motion, iconography, balance header three states, 200 % screenshot) as listed in §5.
7. Export PNGs of every screen of every direction into `png/`. Use a headless browser already installed on this Mac (check with `command -v`; for example Google Chrome's `--headless --screenshot`). If none is installed, stop and ask; do not install tools without the owner's yes.
8. Write the comparison table and recommendation in `docs/ux/directions/README.md`.
9. Self-check the gate (§7): open each `index.html` (file loads with no external request other than Google Fonts), every screen listed for phase 1 appears in each direction, all copy Swedish, no placeholder text. Grep the HTML for `lorem`, `TODO`, `XXX`, `placeholder`.
10. Commit on `UX-sprint` (only files under `docs/ux/`), then `git rebase main`. Never merge, push or remove the worktree.

## 7. Gate
From SPEC §11.2 (v0.3), verbatim: "Files exist and open; each direction shows the six phase-1 screens of §13.4 (S-4, S-7, S-5, S-9, S-11, S-8) in light and dark; Swedish copy, no placeholder text".
Green means: every deliverable of §5 exists; each `index.html` opens in a browser offline (Google Fonts excepted); each direction shows each phase-1 screen of §13.4 (S-4, S-7, S-5, S-9, S-11, S-8) in light and dark; every visible string is Swedish; a grep for `lorem|TODO|XXX` in `docs/ux/` returns nothing.

## 8. HUMAN steps
From SPEC §11.2, verbatim: "Review 2-3 directions, pick one, give comments".
Where in the flow: after this plan's report, the orchestrator shows the owner the PNGs; the owner's pick and comments are the input to U2. Nothing in this plan waits on the owner.

## 9. Out of scope
- Phase 2 work (U2): `docs/ux/design-spec.md`, `docs/ux/strings.csv`, `docs/ux/screens/`, the §9.7 hex proposal.
- Screens beyond the six of §13.4 phase 1 (other than sketches the direction needs to explain itself).
- New features, changes to flows required by §4, changes to enums or limits, app icon production (a direction may sketch one), animations beyond descriptions, Kotlin code (§13.5).
- Anything in §2 Non-goals (receipt photos, other currencies, widgets, landscape layouts, language picker).
- Editing `SPEC.md`, `CLAUDE.md` or any file outside `docs/ux/`.
- M6 design system work and any Android code.

## 10. Report
- Branch `UX-sprint` and the head commit hash after rebasing on `main`.
- Gate: the list of files produced (per direction, count of PNGs) and the result of the placeholder grep.
- Fonts chosen per direction with their licence and whether they bundle as Android font resources; any other external dependency.
- The recommendation in one line.
- Open questions and spec gaps with section numbers.
- Numbering used (none expected; say `none`).
- HUMAN step to relay: "Review 2-3 directions, pick one, give comments", with the PNG paths.

## 11. Numbering
Decision ids, spec version and schema version are assigned by the orchestrator in the start prompt; use `TODO(spec)` if none was given.