kvitt/PLAN-U1.md

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: " owes you X", "You owe 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.