kvitt/docs/ux/README.md

# Kvitt UX (sprint U1)

The UX deliverables for Kvitt v1 (SPEC §13), produced 2026-10-17. Phase 1 (U1) is here: three visual directions plus the direction-independent design documents. After the owner picks a direction, phase 2 (U2) consolidates `tokens.md`, `components.md` and `screens.md` into `design-spec.md` for the chosen direction (SPEC §13.4) and deletes what it supersedes.

## How to read

1. **Look first:** open `directions/1-skargard/index.html`, `directions/2-kvitto/index.html` and `directions/3-kalas/index.html` in a browser (or the PNGs in each `png/` folder). Every screen S-1 to S-22 is there in light and dark, in Swedish, with the same household data, so the same file name compares one screen across directions.
2. **Compare and decide:** `directions/README.md` has the comparison table and the recommendation.
3. **Then the structure,** which holds whichever direction wins:

| File | What it is |
|---|---|
| `ia.md` | Bottom navigation (three destinations, argued), screen inventory S-1…S-22 with modules and state sources, session routing, navigation map, which screen owns which data, admin vs member |
| `screens.md` | Every screen: purpose, content in priority order, empty/loading/offline/error/long-content states, actions; the add-expense flow in detail |
| `flows.md` | F-1 … F-11: first run as admin, join as partner, add expense online and offline, edit the other's expense, global and per-account settle-up, recurring, archive, in-app update, remove a lost phone |
| `components.md` | The `:core:design` component list: anatomy, variants, states, semantics |
| `tokens.md` | Token names and their values in all three directions (colour roles light/dark, semantic and category colours with contrast, charts, type, spacing, shapes, elevation, motion, icons) |
| `strings.csv` | Every UI string, `key,en,sv,notes` (SPEC §13.4 format). Placeholders are Android format arguments (`%1$s`, `%d`); plurals are two rows `<key>:one` and `<key>:other`, which become one `<plurals name="<key>">`. Notification copy (SPEC §13.3, Swedish written here) has the prefix `notif_`. |
| `directions/` | The three directions, their PNGs and `export-png.sh` |
| `proposed-decisions.md` | The owner's answers (direction pick: Kalas, muted), findings, and the decisions and spec text a docs agent should record on `main` |

## The three directions

**1 Skärgård** — the Stockholm archipelago on a calm day. Material 3 Expressive in sea blue, granite and sand, with large rounded shapes and generous whitespace. Home is a hero: "Du är skyldig Anna" above a large, narrow Roboto Flex figure and a single "Gör upp" button; accounts are a calm grouped list. The editor puts the amount in display size over an in-app keypad with Expressive key shapes. The most Android-native of the three, and the only one that can follow Material You wallpaper colours.

**2 Kvitto** — a till receipt and a household ledger. Warm paper and ink, one ink-blue accent, every amount in IBM Plex Mono, dashed rules between groups. Home opens with a compact receipt block and then a dense ledger table; account detail reads like a bank statement; an expense is a printed receipt with an "audit trail" below; "Ni är kvitt" is a rubber stamp. The densest and calmest direction; its risk is feeling austere.

**3 Kalas** — a crayfish party. Cream and white cards, a coral primary, very round shapes, and a solid category-colour tile on every expense so you recognise it before reading it. The balance is a seesaw (whoever owes sits lower, and the words always say it); settling up raises bunting. The editor shows the six most used categories as big tiles under the amount. The most personality; its risk is wearing thin over years of daily use.

## Where this follows the spec instead of the U1 brief

The owner's brief for this sprint and SPEC.md differ in places; the spec wins (CLAUDE.md › Source of truth):

| Brief | Spec (followed) |
|---|---|
| Screen ids `S-01 …` | `S-1 … S-22` as in SPEC §13.3 |
| Bottom nav: recommend up to 4 | SPEC §13.2's three destinations kept, with the argument in `ia.md` §1 |
| `docs/ux/proposals/`, 360 dp frames, S26+ at 384 dp | `docs/ux/directions/<n>-<slug>/index.html` at 411 dp (SPEC §13.1/§13.4); both phones are ~411 dp wide, so there is no separate S26+ layout |
| Swedish in one direction, English in the others | Swedish everywhere (§13.4), plus one English Home frame per direction to show English fits |
| `copy.md` table | `strings.csv` in the §13.4 format |
| Category suggested from the description | AC-8.6: last category used in that account on this phone, else Övrigt (a description-based suggestion would be a new rule; open question) |
| `tokens.md` "for the chosen scheme family" | Values for all three directions until the owner picks (§13.4 makes the pick precede the final spec) |

Additions the spec did not state, flagged for U2:

* **S-1 has a "Ditt namn" field:** AC-2.4 sends a display name with the accept call, but §13.3's S-1 lists no name field. A partner therefore types the name on S-1 and confirms it on S-2 (AC-2.10).
* **Category colour hex values** changed for contrast (`tokens.md` §4); adopting them needs a §9.7 spec change after the pick.
* **Avatar colours** for initials (AC-4.5) are defined per direction (`avatar-1`, `avatar-2`).
* **Expense save shows no "Ångra"** (an undo would be an audited create + delete that also notifies the partner).
* **Archived account detail hides the FAB** (an archived account is not offered for new expenses, AC-6.4).