kvitt/docs/ux/directions/README.md

# Kvitt UX directions (U1)

Three visual directions, each one self-contained HTML file with every screen of SPEC §13.3 in light and dark, plus PNG exports. Open `index.html` in a browser: the top of each page is the direction's spec (palette with live contrast ratios, typography, shapes, motion, icons, the balance header in its three states, Expressive components with fallbacks); below are the phone frames (411 × 891 dp, Galaxy S26), light and dark side by side.

| # | Direction | Page | PNGs |
|---|---|---|---|
| 1 | **Skärgård** — calm Material 3 Expressive, big balance hero | `1-skargard/index.html` | `1-skargard/png/` (97) |
| 2 | **Kvitto** — till receipt and ledger, dense and list-first | `2-kvitto/index.html` | `2-kvitto/png/` (99) |
| 3 | **Kalas** — playful cards, strong category colour | `3-kalas/index.html` | `3-kalas/png/` (101) |

All three use the same household data (Jacob and Anna, Vardag / Huset / Japan 2027 / Gotland 2026, ICA, Willys, Systembolaget, SL, Vattenfall, Hyra), the same frame ids and the same Swedish copy, so a screen can be compared across directions by file name (`png/S-4-home-light.png`). One English Home frame (`S-4-home-en`) and two 200 % font-scale frames (`S-4-home-200`, `S-7-editor-200`) per direction. Extra frames beyond the common list: `S-11-analytics-scrolled` (all three; the three charts do not fit one screen), `S-5-account-menu` (Kvitto, Kalas), `S-5-account-archived-menu` (Kalas).

Re-export after a change: `docs/ux/directions/export-png.sh docs/ux/directions/<n>-<slug> [frame-id …]` (needs Google Chrome; fonts load from Google Fonts).

## Comparison

| | 1 Skärgård | 2 Kvitto | 3 Kalas |
|---|---|---|---|
| Character | Archipelago on a calm day: sea blue, granite, sand; generous whitespace; few elements per screen | Till receipt and ledger book: paper, ink, one ink-blue accent, mono amounts, dashed rules | Crayfish party: cream and white cards, coral primary, every expense a solid colour tile |
| Home balance | Hero card, words first, huge narrow figure, cookie-shaped avatars, faint islet drawing | Compact receipt block with "Saldo · alla konton", amount in mono, Gör upp beside it; "Kvitt" rubber stamp when settled | Seesaw: whoever owes sits lower, plank in the debt colour; bunting and yellow card when settled |
| Accounts / ledger | Grouped rounded list; 72 dp rows | Ledger table, 60 dp rows, date column, dotted leaders to month totals — most rows per screen | Colourful cards; account colour on a clover tile matches the account chart |
| Add expense | Amount in display size, in-app keypad with Expressive key shapes, default chips above the keypad | Register-style amount on a till keypad (has "00"), one-tap key/value rows | Big amount, keypad, row of the six most used category tiles, chips; split shown as a two-colour bar |
| Expense detail | Card with facts and a timeline | Printed receipt with zig-zag edges and an "audit trail" printout | Colour-tile header card and timeline |
| Analytics | Calm cards, tonal charts | Chart-first, every number in mono | Colourful stacked bars and tile breakdowns |
| Type | Roboto Flex (OFL) | IBM Plex Sans + Plex Mono (OFL) | Nunito (OFL) |
| Shape | Large radii, MaterialShapes for avatars/FAB | Square, 4–8 dp, receipt edges | Very round, MaterialShapes for tiles and avatars |
| Owed / owing colours | sea-green / coral | green / brick + square marker | green / purple |
| Dynamic colour | Offered (off by default) | No (paper palette is the identity) | No (colours carry meaning) |
| Expressive dependence | Highest (ShortNavigationBar, ButtonGroup, MaterialShapes, LoadingIndicator, wavy progress, expressive motion) — all with stable fallbacks | Lowest (ShortNavigationBar only) | Medium (MaterialShapes, ButtonGroup, ShortNavigationBar, expressive motion) |
| Strengths | Most Android-native; balance readable at a glance; survives dynamic colour; least surprising for both users | Densest; amounts line up perfectly; very calm; the name "Kvitt" and the receipt metaphor reinforce each other; strong dark theme | Expenses recognisable before reading; most personality; strong ten-second add flow with category tiles |
| Risks | Can read as generic Material if the shapes and decoration are dropped; the hero takes ~35 % of Home; the 80 dp FAB covers list content until it collapses | Can feel austere, "accounting software"; mono amounts are wide (wrap at 200 %); custom keypad and receipt shapes | Seesaw may feel gimmicky over time; coral primary is close to error red (errors always carry an icon); less dense; dark yellow containers read olive |
| Compose cost | Medium: keypad, hero Canvas, MaterialShapes, Roboto Flex variations, `KvittColors` | Medium: zig-zag `GenericShape`, dashed dividers, stamp, keypad, Canvas charts, print/roll motion | Medium: `RoundedPolygon.toShape()`, seesaw layout with spring, keypad, stacked bars |

## Recommendation

**Skärgård**, with one borrowing from Kalas: solid category-colour icon tiles in ledger rows (Skärgård's tinted 12 dp containers are the quieter fallback).

Why:

1. **The two jobs that matter most (§13.1) are done best.** The ten-second add flow is equally good in all three, but Skärgård's Home answers "who owes whom" with the least to read: one sentence, one number, one button.
2. **Lowest long-term risk.** It is the closest to stock Material 3, so Compose upgrades, M6's screenshot tests and future screens cost the least; every Expressive part has a stable fallback that still looks right.
3. **Works for both users.** It is neither austere (Kvitto's risk for the spouse) nor novelty-driven (Kalas's seesaw), and it is the only direction that can follow the wallpaper colours if either of you wants that.
4. **Category recognition** is Kalas's real advantage; it transplants cleanly into Skärgård's list rows without the rest of Kalas's playfulness.

Pick Kvitto if density and the receipt character matter more than warmth; pick Kalas if you both want the app to feel fun every day. Mixing is possible: tell me which parts of which direction you like (e.g. "Skärgård, but Kvitto's receipt detail screen").

## Known gaps in the mocks (not design decisions)

* `S-4-home` shows no pending count although the Vardag ledger has one pending row; real Home shows the count whenever `pendingCount > 0` (`screens.md` S-4).
* `S-11-analytics-week` uses a custom range (24 aug.–17 okt., v. 35–42) with invented weekly values; "Senaste 6 mån" by week would show ~26 bars.
* `S-8-expense-deleted` uses a different expense in each direction (no shared data for it).
* Kalas lets the per-account settle-up amount be edited (AC-11.4 says "defaults to"); Skärgård shows the swap control there too (per-account settle-ups go either way, §9.4). Both are allowed by the spec and should become the rule in U2.