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.