kvitt/PLAN-M6.md

PLAN-M6: Design system

1. Goal

Implement :core:design from the approved docs/ux/design-spec.md: theme, colour and category tokens, typography, shapes, spacing, shared components, the three analytics charts, and MoneyFormatter/DateFormatter per §9.8. Every component has screenshot tests in light and dark, Swedish and English, so the feature agents compose screens without inventing visuals.

2. Read first

1. docs/ux/design-spec.md (tokens, component inventory; the screen sections only to know which components are needed).
2. docs/ux/strings.csv (shared strings) and docs/ux/screens/ (reference renders).
3. SPEC §6.2 Android app (rows UI, Charts, Tests; :core:design row of the module table).
4. SPEC §9.7 Icon and colour tokens (with the hex values as updated by the orchestrator's spec change from U2's proposal), §9.8 Formatting, §9.2 and §9.3 (wording the components render).
5. SPEC §13.1 Context (accessibility, font scale, tabular figures), §13.2 Navigation model.
6. SPEC §4 AC-4.5 (initials avatar), FR-14 AC-14.6, AC-14.10 (charts), FR-19 Localisation and formatting.
7. SPEC §11.2 (row M6), §11.3, §14.7 (including the Strings paragraph).
8. Files: android/core/model/**, android/build-logic/**, android/gradle/libs.versions.toml, docs/decisions.md, CLAUDE.md (BUILD AND VERIFY: Screenshots; ARCHITECTURE RULES; ANTI-PATTERNS).

3. Already established

• Compose, Material 3, Material 3 Expressive components where stable; follows system light/dark (§6.2, §13.1).
• Charts: Vico; if Vico's current release cannot draw a stacked bar chart with Material 3 theming, hand-roll the three charts with Compose Canvas in :core:design (§6.2).
• Shared components named in §6.2: money text, avatar, category chip, balance header, charts; plus MoneyFormatter, DateFormatter (§6.2). The full inventory is the design spec's.
• Money: sv 1 234,50 kr (U+00A0 thousands and before kr, comma decimal, two decimals); other locales SEK 1,234.50 (U+00A0 after SEK); never a minus sign; dates in lists 3 okt. / 3 Oct, with year when not the current year; detail lördag 3 oktober 2026 / Saturday, 3 October 2026; times 14:02; relative "last synced" per §9.8 (§9.8). Formatting lives in :core:design, never in :domain (§9.8).
• Colour token names are the 12 of §9.7 (ColorToken); icon tokens the 30 of §9.7 (CategoryIcons.ALL) (§9.7, §14.2.4).
• Initials: first letter of the first two words, uppercase, on a colour derived from the user id (AC-4.5).
• Accessibility: 48 dp targets, 4.5:1 contrast, TalkBack labels, reflow at 200 % (§13.1).
• No hard-coded colours, sizes or strings in features: tokens come from one design file; shared strings live in :core:design with keys from docs/ux/strings.csv (CLAUDE.md, §14.7 Strings).
• Screenshot goldens are committed; open every changed PNG before committing (CLAUDE.md).
• :core:design depends only on :core:model (§6.2).

4. Owned paths

From SPEC §14.7, verbatim: android/core/design/** (owner M6; after landing: "M7x may not edit; requests go through the orchestrator"). Also from §14.7: "later plans may add catalog entries and module includes (rebase resolves)" for android/gradle/** and android/settings.gradle.kts.

Edit nothing outside these paths; a needed change elsewhere is a contract request to the orchestrator.

Open points the orchestrator must settle in the start prompt's notes: (a) shared UI that several features need but §6.2 does not list: the ledger rows used by S-5, S-12 and S-16 (M7b, M7e), and the expense form fields used by S-7 and S-19 (M7c, M7f), which cannot be shared between feature modules; whether M6 provides them; (b) whether the font of the chosen direction is cleared by the owner for bundling (CLAUDE.md "Licences first"); (c) that the §9.7 hex spec change has landed.

5. Deliverables

• android/core/design/build.gradle.kts: dependencies (:core:model, Compose, Material 3, Vico if used, Coil for avatars).
• .../design/theme/**: KvittTheme, colour schemes light and dark, category colour tokens mapped from ColorToken, typography (with tabular figures for amounts), shapes, spacing scale, elevation, motion tokens from the design spec.
• .../design/component/**: every component of the design spec's inventory (at least money text, avatar with initials, category chip and icon, balance header in three states, sync line, update banner, empty and error blocks, "Needs connection" hint, and what open point (a) assigns).
• .../design/chart/**: stacked bars over time, category breakdown bars, account breakdown bars.
• .../design/format/MoneyFormatter.kt, DateFormatter.kt: §9.8, with unit tests for every example in §9.8.
• android/core/design/src/main/res/values/strings.xml, values-sv/strings.xml: shared strings from docs/ux/strings.csv.
• android/core/design/src/main/res/font/**: only if the chosen font is cleared (open point b).
• Screenshot tests for every component in light and dark, Swedish and English, plus 200 % font scale for the balance header and money text; committed goldens.
• docs/decisions.md entry text for the chart choice (Vico or Canvas) in the report (the file is not owned by M6).

6. Steps

1. Worktree. From the main checkout /Users/jhag/projects/kvitt: git worktree add .claude/worktrees/agent-m6 -b agent-m6 main, then in .claude/worktrees/agent-m6: git reset --hard main. Copy android/local.properties from the main checkout (add sdk.dir if missing; never overwrite or commit). Run tools/install-git-hooks.sh.
2. Read §2 in order. Confirm U2's design spec is on main and approved (start prompt), M2b has landed, and the §9.7 hex change is in SPEC; otherwise stop and report.
3. Run python3 tools/dependency-report/latest.py; record the lines. Versions: Vico latest stable (official Vico documentation and releases); check whether it draws a stacked bar chart with Material 3 theming; record the finding and the decision (Vico or Canvas). Confirm Material 3 Expressive component stability from developer.android.com. Record versions.
4. Formatters test-first from the §9.8 examples (both languages, current-year and other-year dates, relative times).
5. Theme and tokens from the design spec; contrast check of every text/surface pair the spec lists (unit test computing ratios).
6. Components one by one, each with previews (real Swedish and English data from the design spec, no placeholder text) and screenshot tests in light/dark × sv/en.
7. Charts with screenshot tests (empty, one group, many groups, week granularity).
8. Record goldens; open every PNG; post the paths for the owner's look (§8).
9. Run the gate (§7). Commit on agent-m6, git rebase main, rerun the gate. Never merge, push or remove the worktree.

7. Gate

From SPEC §11.2, verbatim: "Android gate". Command, from android/: PATH=/opt/homebrew/opt/openjdk@25/bin:$PATH ../tools/gradle-serial.sh check. Green means: BUILD SUCCESSFUL in this session with the screenshot verification task for :core:design run and passing; formatter tests in fresh XML, 0 failures; the report lists one screenshot per component × light/dark × sv/en.

8. HUMAN steps

From SPEC §11.2, verbatim: "Look at the component screenshots the agent opens and posts (yes/no)". Where in the flow: after step 8, before committing the final goldens; the orchestrator shows the owner the PNG paths the agent lists and relays yes/no. A "no" with a comment goes back to the agent before the gate run.

9. Out of scope

• Feature screens and their ViewModels (M7a to M7f); feature strings.
• Navigation, :app (M8); :data (M5).
• Changing token names, enums or :core:model (contract change).
• Changing the design spec (U2's file); disagreements go in the report.

10. Report

• Branch agent-m6, head commit hash after rebasing on main.
• Gate output: BUILD line, actionable tasks line, screenshot task result, test counts from fresh XML.
• Versions chosen with sources; dependency-report lines; chart decision (Vico or Canvas) with the reason, as decisions text.
• Component list with screenshot paths (for the owner's look) and the owner's yes/no.
• How open points (a) to (c) were resolved.
• Numbering used or TODO(spec) occurrences.
• Contract requests, open questions, spec gaps (with section numbers).

11. Numbering

Decision ids, spec version and schema version are assigned by the orchestrator in the start prompt; use TODO(spec) if none was given.