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 spec change from U2's proposal; that change lands before M6 starts (§11.1). §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), §6.2 "Feature convention (D-017)"; docs/decisions.md D-017, D-019, D-020.
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; the ledger rows (expense row per AC-8.10 and settlement row per AC-11.7, used by S-5, S-12 and the pending list of S-16) and the expense editor fields (amount entry, description, account picker, category grid, date, payer toggle, split section with live preview, notes, used by S-7 and S-19) (D-019); plus MoneyFormatter, DateFormatter (§6.2). The full inventory is the design spec's.
• Typography uses the Material 3 default typeface; no font file is bundled and no licence step is needed (D-020).
• Shared strings in :core:design include the notification copy of §13.3 and the channel name "Activity"/"Aktivitet" of §14.6, which :app uses; their keys never start with a feature name (D-017).
• 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 14 of §9.7 (ColorToken, slate and amber added by D-054, hex values from U2 per D-051); icon tokens the 33 of §9.7 (CategoryIcons.ALL); fourteen default categories (AC-7.2), whose localised default names :core:design holds as shared strings (§9.7, §14.2.4, D-054). Direction "Kalas", muted (D-047). M12c must have landed (§11.2).
• 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; lint MissingTranslation is an error in this module (CLAUDE.md, §14.7 Strings, D-017).
• M2b created the module shell (build file, manifest, empty string files); M6 owns it and fills it in (D-004).
• Screenshot goldens are committed; open every changed PNG before committing (CLAUDE.md).
• :core:design depends only on :core:model (§6.2).
• Design-spec open points (docs/ux/design-spec.md §6, SPEC v0.9): (1) System font on One UI: FontFamily.Default may resolve to a One UI font instead of Roboto; check on the owner's S26 that amounts stay tabular (tabular figures) and weights 500, 600 and 700 are distinct, and report it (D-020 stands either way). (2) Material 3 Expressive API status: check every Expressive API of design-spec §3.1 against the Material 3 release pinned in android/gradle/libs.versions.toml; any that is not usable (not in the pinned release, or experimental without a stable path) takes its listed stable fallback without a design change; list each with its outcome in the report. (3) S-19 has no category suggestion (CS-1); CategoryQuickRow must work without one.
• The §9.7 hex values are in SPEC v0.9 (from design-spec §2.3; D-051 fulfilled); design-spec.md §2 and §3 and strings.csv are the sources (§13.4). M6 started 2026-10-18. CategoryQuickRow takes its list from the caller: ExpenseEditorOptions.frequentCategoryIds (D-059) is added by M12d in parallel; the component must not depend on it existing.
• Avatars (v0.5, §14.2.4 readings): :data always loads pictures at size 512 (E-11); the 128 variant is unused. If the avatar component needs the small size, ask the orchestrator for a size parameter (a contract request on :core:model and :data).

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.

Never edit SPEC.md or docs/decisions.md: put proposed decision entries (for example the chart choice) in the report.

Resolved open points (SPEC v0.3):

• (a) M6 builds the ledger rows and the expense editor fields in :core:design (D-019).
• (b) No font is bundled; the app uses the Material 3 default typeface (D-020).
• (c) The §9.7 colour change lands in the spec before M6 starts (§11.1); confirm it in step 2.

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, the ledger rows and the expense editor fields of D-019).
• .../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, including the notification copy and channel name.
• 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.
• The proposed decision text for the chart choice (Vico or Canvas), in the report.

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 resolved points (a) to (c) were applied; the public API of the ledger rows and editor fields (for M7b, M7c, M7e, M7f).
• Proposed decision entries (never written to SPEC.md or docs/decisions.md by this agent) 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.