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
Muted Kalas (2026-10-18, second round)	Approved ("let's go with that for now").
Mark the suggested category ("Vald utifrån beskrivningen")?	No: the category is simply selected; a wrong guess is changed with one tap; simpler UI.
History match: most recent or most often?	Most often.
Import granularity	Splitwise's categories are finer than Kvitt's ten defaults (several "Övrigt" under different groups); map them better. "Hemförsäkring" must not end up in Övrigt.
Which new default categories?	All four proposed: Boende, Försäkringar, Barn, Avgifter & skatter.

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 the muted palette of directions/3-kalas/ (owner approved 2026-10-18). 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, the category used most often among matching expenses, (2) built-in keyword list, (3) the AC-8.6 default. The selected category is not marked as a suggestion (no caption); the user changes it with one tap. 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 with the 14 categories of UX-8 and the mapping of UX-7, aggregates only, category-suggestion.md): history step ("most often") used for 71.5 % of rows and right 92.8 % of the time; keyword step 92.4 % on 8.2 %; overall 79.7 % correct versus 30.5 % for today's AC-8.6 default alone ("most recent" would give 79.0 %). Cold start (no history): keywords fire on 77 % 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, 148 entries, none mapping to other), 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).

UX-7 Finer Splitwise import mapping (§10.8)

• Finding (export analysis): 21 rows use Swedish Splitwise category names that the §10.8 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); and §10.8 collapses Splitwise's finer categories, so e.g. Försäkringar (26 rows), Barnomsorg (73) and Skatter (19) land in other and Hyra (106) and Avbetalning/Amortering (48) in home.
• Decision (owner, 2026-10-18): map Splitwise categories as finely as Kvitt's categories allow, with the four new defaults of UX-8.
• Spec: the §10.8 table and server/crates/kvitt-import/data/splitwise_categories.csv become:

Splitwise category (English)	Splitwise category (Swedish)	Kvitt default_key
Groceries, Food and drink - Other, Liquor	Livsmedel, Mat och dryck - Övrigt, Alkohol	groceries
Dining out	Restaurangbesök	restaurants
Rent, Mortgage	Hyra, Avbetalning/Amortering	housing
Electronics, Furniture, Household supplies, Maintenance, Services, Pets, Home - Other	Elektronik, Möbler, Förbrukningsvaror, Skötsel/underhåll, Tjänster, Husdjur, Hem - Övrigt	home
Electricity, Heat/gas, Water, Trash, TV/Phone/Internet, Cleaning, Utilities - Other	El, Värme/gas, Vatten, Sophämtning, TV/telefon/internet, Städning, Verktyg - Övrigt	utilities
Insurance	Försäkringar	insurance
Bicycle, Bus/train, Car, Gas/fuel, Parking, Taxi, Transportation - Other	Cykel, Buss/tåg, Bil, Bensin/bränsle, Parkering, Taxi, Transport - Övrigt	transport
Hotel, Plane	Hotell, Flyg	travel
Games, Movies, Music, Sports, Entertainment - Other	Spel, Filmer, Musik, Sport, Underhållning - Övrigt	entertainment
Medical expenses	Sjukvård/medicin	health
Childcare	Barnomsorg	children
Clothing, Gifts	Kläder, Presenter	shopping
Taxes	Skatter	fees
General, Education, Life - Other, Other	Allmänt, Utbildning, Livet - Övrigt	other
any other value	any other value	other, counted as unmapped

Swedish names not seen in the export (El, Värme/gas, Vatten, Sophämtning, Husdjur) are Splitwise's Swedish labels by analogy and must be checked against Splitwise before M9 relies on them; an unseen name simply stays unmapped.

UX-8 Four new default categories

• Decision (owner, 2026-10-18): Kvitt seeds 14 default categories instead of 10. New: Boende, Försäkringar, Barn, Avgifter & skatter. Hem keeps furniture, supplies, maintenance, electronics and services; rent and mortgage move to Boende.
• Why: the household's history shows these as separate, large groups (Hyra + Amortering 154 rows, Barnomsorg 73, Försäkringar 26, Skatter 19) that were collapsed into Hem and Övrigt; separate categories make analytics and the category suggestion meaningful.
• Spec (AC-7.2 table, full new list in sort order; new rows in bold):

default_key	English name	Swedish name	icon	color	sort_order
groceries	Groceries	Mat & hushåll	shopping_cart	green	10
restaurants	Restaurants	Restaurang & café	restaurant	orange	20
housing	Housing	Boende	key	indigo	25
home	Home	Hem	home	brown	30
utilities	Utilities	Räkningar	bolt	yellow	40
insurance	Insurance	Försäkringar	shield	new token (UX-5)	45
transport	Transport	Transport	directions_car	blue	50
travel	Travel	Resor	flight	teal	60
entertainment	Entertainment	Nöje	movie	purple	70
health	Health	Hälsa	medical_services	red	80
children	Children	Barn	child_care	lime	85
shopping	Shopping	Shopping	shopping_bag	pink	90
fees	Fees & taxes	Avgifter & skatter	account_balance	new token (UX-5)	95
other	Other	Övrigt	category	grey	100

• Contract consequences (one landing, numbered by the docs agent): AC-7.2 table; §9.7 icon set gains key, shield, account_balance (33 tokens) and the colour set gains two tokens (UX-5); §14.1 seed rows with four new fixed ids and a server schema migration to version 2 inserting them (existing databases, including the development stack, get them on upgrade); DefaultCategoryKey and ColorToken in §14.2.4 gain the new values and CategoryIcons.ALL the new icons; the OpenAPI enums; default-name strings in both languages (strings.csv); test vectors that enumerate categories, if any. The Room schema is unchanged (category rows arrive through sync).
• Order matters for existing milestones: M3 (server) and M5 (:data) already landed with ten defaults, so this is a contract change against code on main, not only the spec.

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, and add two colour tokens for the new categories of UX-8 (values and names from the Kalas revision in progress; filled in when it reports). Existing 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 (approved); keyword list and replay for 14 categories and "most often".
• In progress: Kalas mocks with the 14 categories and two new colour tokens;
• Next: owner approves the muted palette → U2 design-spec.md, renamed strings.csv, per-screen PNGs, and the final values for UX-3, UX-5 and UX-8.