kvitt/docs/ux/proposed-decisions.md

# UX sprint: owner answers, findings and proposed spec changes

The UX sprint runs in the owner's own session, which has no orchestrator. This file is how its results reach the main line. **No numbers are assigned here:** the decision ids and the spec version are handed out when a docs agent records these (CLAUDE.md › Numbering; next free at the time of writing: D-044, spec v0.6). Ids `UX-1` … are local labels only.

Every entry has: the owner's answer or the finding, the proposed decision text for `docs/decisions.md`, and the spec text to change.

## Owner answers (2026-10-18)

| Question (U1 report) | Owner's answer |
|---|---|
| Which direction? | **3 Kalas**, with less bright colours ("I'm nervous that I will get tired of too bright colors over time"). |
| Bottom navigation | **Three tabs** for now (Översikt, Statistik, Inställningar), as SPEC §13.2. No change. |
| Category from the description | **Yes:** the category is auto-selected from the description and the user can still change it. Rule: history first, then a built-in keyword list, then the AC-8.6 default. The keyword list is learned from the household's Splitwise export. |
| S-1 "Ditt namn" field (partner types the name on S-1 and confirms it on S-2) | **OK** |
| Swedish wording "Ni är kvitt", "Gör upp", "Du lånade ut / Du lånade", "Inte inblandad" | **Yes** |

## UX-1 Direction: Kalas, muted

* **Decision:** the app's visual direction is U1's direction 3 "Kalas" (cards, very round shapes, a solid category-colour tile on every expense, the seesaw balance), with a muted palette (status: being revised; see `directions/3-kalas/`). Typeface per D-020 (Material 3 default, Roboto); Kalas's preview font Nunito is dropped.
* **Why:** owner's pick; muted because bright colours tire over years of daily use.
* **Spec:** none beyond UX-5 (category colours). U2's `design-spec.md` carries the tokens.

## UX-2 Navigation stays at three destinations

* **Decision:** no change to SPEC §13.2. An "Aktivitet" feed (the other person's changes across accounts) was considered as a fourth tab and not taken for v1.
* **Spec:** none.

## UX-3 Category suggested from the description

* **Decision (owner, 2026-10-18):** for a new expense, the editor selects a category from the description as the user types, while the user has not picked a category by hand in this editor session: (1) history match, (2) built-in keyword list, (3) the AC-8.6 default. The user can always change it. Editing an existing expense never changes its category automatically.
* **Why:** most expenses repeat the same shops; fewer taps in the ten-second flow (§13.1).
* **Evidence** (chronological replay of the household's 1 775 Splitwise expenses, aggregates only, `category-suggestion.md`): history step right 92.3 % of the time and used for 71.5 % of rows; keyword step 94.2 % on 7.8 %; overall 79.5 % correct versus 31.9 % for today's AC-8.6 default alone. At cold start (no history) keywords fire on 78 % of rows and are right 96 % of the time.
* **Spec changes:**
  * AC-8.6: the category default becomes "the suggestion of §9.11, which falls back to the current rule".
  * New §9.11 "Category suggestion": the text CS-1 to CS-7 of `category-suggestion.md`.
  * New contract file `contracts/category-keywords.csv` (columns `keyword,match,default_key,source`; draft `docs/ux/category-keywords.csv`, 149 entries), listed in §14.8.
  * §14.2.4: `ExpenseRepository` gains `suspend fun suggestCategory(accountId: AccountId?, description: String): CategoryId?` (computed in `:data` from Room and the keyword table; the editor calls it on description and account changes while the category was not picked by hand).
  * §14.5: a pure Kotlin function `suggestCategory(description, history, keywords, activeCategories, fallback)` in `:domain` with test vectors (Kotlin only, like analytics).
  * `strings.csv`: `expense_editor_category_suggested` "Vald utifrån beskrivningen" / "Chosen from the description".
* **Open points** (owner, low stakes; defaults in brackets): keep the five keywords that pick Övrigt, e.g. insurance words [keep]; "most recent" vs "most frequent" history match, the latter about one point better [most recent, as chosen].

## UX-7 §10.8 misses nine Swedish Splitwise category names

* **Finding** (from the export analysis): 21 rows use Swedish Splitwise category names that the §10.8 mapping table lacks: Utbildning (4), Tjänster (3), Livet - Övrigt (3), Kläder (3), Städning (2), Flyg (2), Spel (2), Verktyg - Övrigt (1), Cykel (1). They would import as `other` with a warning.
* **Proposed decision:** add them to the §10.8 table and `server/crates/kvitt-import/data/splitwise_categories.csv` by their English equivalents: Utbildning → other, Tjänster → home, Livet - Övrigt → other, Kläder → shopping, Städning → utilities, Flyg → travel, Spel → entertainment, Verktyg - Övrigt → utilities, Cykel → transport. (Needed by M9.)

## UX-4 S-1 asks for the display name

* **Finding:** AC-2.4 sends a display name with the accept call, but §13.3's S-1 lists no name field.
* **Decision (owner OK, 2026-10-18):** S-1 has a required "Ditt namn" field on a first pairing (hidden in the "Para ihop telefonen igen" variant); the partner confirms it again on S-2 (AC-2.10).
* **Spec:** §13.3 S-1 "Must show": add "display name field (1–40, §9.6), required on a first pairing".

## UX-5 Category colour values (§9.7)

* **Finding:** several provisional §9.7 values fail contrast as icon colours on tinted containers (light orange, yellow, lime).
* **Decision:** replace the §9.7 hex values with the muted Kalas values (pending; filled in when the revision is approved). Token names unchanged.
* **Spec:** §9.7 table values.

## UX-6 Smaller UX rules found during U1 (no owner question needed)

| Rule | Spec place |
|---|---|
| Saving an expense shows "Utgiften sparades" without "Ångra" (an undo would be an audited create + delete that also notifies the partner). | §13.3 S-7 |
| Account detail of an archived account hides the FAB (archived accounts are not offered for new expenses, AC-6.4); settling stays available. | §13.3 S-5 |
| The per-account settle-up keeps the direction swap (§9.4: per-account settle-ups go either way) and lets the amount be edited (AC-11.4 "defaults to"); its one account row is fixed. | §13.3 S-9 |
| Avatar initials colours are two tokens `avatar-1`, `avatar-2`; the slot is a stable function of the user id (AC-4.5). | AC-4.5 |
| `strings.csv` keys are renamed in U2 to the feature-module prefixes of D-017 (`onboarding_`, `home_`, `account_`, `expense_`, `settle_`, `analytics_`, `settings_`; shared keys without a feature prefix). | none (U2 work) |

## Status

* U1: delivered (`d27f92e` rebased on `main`), direction picked.
* Done: muted Kalas revision (`directions/3-kalas/`, awaiting the owner's look); keyword list and suggestion analysis (`category-keywords.csv`, `category-suggestion.md`).
* Next: owner approves the muted palette → U2 `design-spec.md`, renamed `strings.csv`, per-screen PNGs, and the final values for UX-3 and UX-5.