kvitt/PLAN-U2.md

PLAN-U2: UX design spec

1. Goal

Turn the owner's chosen direction into the binding design spec: final tokens, component inventory, every screen S-1 to S-22 in all its states, and every user-visible string in English and Swedish. M6 and M7a to M7f build from these files and nothing else for visuals and copy.

2. Read first

Read these, in this order, and nothing else before starting. Everything needed is in SPEC §13 and the sections it cites.

1. The owner's pick and comments, given in the start prompt.
2. docs/ux/directions/README.md and the chosen direction's docs/ux/directions/<n>-<slug>/index.html (U1 output).
3. SPEC §13 UX sprint: §13.1, §13.2, §13.3 (screens and system notifications), §13.4 Deliverables (Phase 2), §13.5.
4. SPEC §9.2 Effect line, §9.3 Balances, §9.7 Icon and colour tokens, §9.8 Formatting, §9.9 Online-only actions.
5. SPEC §4 Functional requirements FR-2 to FR-16 and FR-19: every quoted user-facing phrase and every UI rule in the ACs.
6. SPEC §14.4.6 Rejection reasons (S-16 copy) and §14.6 Push payload v1, "Phone handling" item 2 (notification channel name).
7. SPEC §14.2.4 UI contract (which values each screen receives; the design must not need data that is not there).
8. SPEC §14.7, the "Strings" paragraph under the ownership table.
9. CLAUDE.md sections ORCHESTRATION (worktrees), ANTI-PATTERNS (no placeholder text, no hard-coded strings).

3. Already established

• Everything listed in PLAN-U1 §3 (context, navigation, accessibility, tokens, formatting) still holds (§13.1, §13.2, §9.7, §9.8).
• States per screen, where they apply: loaded, empty, offline (with pending changes), loading (first sync only; afterwards data is local), error (a failed online action), and for lists long content (long Swedish names, 7-digit amounts) (§13.3).
• The "Must show" and "Actions" columns of §13.3 for S-1 to S-22 are the content of each screen; the system notification copy table of §13.3 is fixed in English and the UX agent writes the Swedish (§13.3).
• "Needs connection" disables online-only actions; a failed REST call shows "Could not reach the server" (§9.9).
• Rejection explanations on S-16 are the English texts of §14.4.6.
• Notification channel id activity, name "Activity" / "Aktivitet" (§14.6).
• Initials: first letter of the first two words of the display name, uppercase, on a colour derived from the user id; the UX sprint defines the two colours (AC-4.5).
• strings.csv columns key,en,sv,notes; keys snake_case prefixed by the feature module that holds them (home_balance_owes_you, expense_save; shared :core:design strings, the notification copy included, never start with a feature name; the app name is the only :app string) (§6.2, §13.4, D-017); placeholders as Android format arguments (%1$s); plurals marked in notes with their quantities (§13.4). Feature agents add no strings outside this file unless the orchestrator records a decision for them (§13.4).
• Category default names (en, sv) are fixed in AC-7.2; every enum shown to users needs strings in both languages (AC-19.3).
• Colour token names fixed; new hex values for §9.7 are proposed, and the orchestrator turns them into a spec change (§13.4).
• The UX agent writes no Kotlin (§13).

4. Owned paths

From SPEC §14.7, verbatim: docs/ux/** (owner: U1, U2).

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

5. Deliverables

• docs/ux/design-spec.md: final tokens (colour roles light and dark, category colour hex values, typography scale, shapes, spacing scale in dp, elevation, motion durations and easing); component inventory (anatomy, states, sizes per component); for every screen S-1 to S-22: layout description, all states of §13.3 that apply (and an explicit "not applicable" for the ones that do not), interaction details, TalkBack labels.
• docs/ux/strings.csv: every user-visible string of the app, key,en,sv,notes, including notifications, rejection reasons, error codes the app shows, enum labels, category default names, relative-time phrases.
• docs/ux/screens/<S-id>-<slug>.png (one file per screen and state, light and dark, Swedish; name the state in the file name, for example S-4-home-empty-dark.png).
• docs/ux/colour-tokens-proposal.md: the proposed light and dark hex values for the 14 tokens of §9.7 (the muted Kalas values, slate and amber included, D-051) with contrast ratios against both surfaces, for the orchestrator's spec change.

6. Steps

1. Worktree. The owner runs the UX sprint in a separate session in ~/orca/workspaces/kvitt/UX-sprint on branch UX-sprint; work there and git rebase main. No git-ignored files are needed; copy none.
2. Read §2 in order. List the owner's comments and how each is addressed (goes into the report).
3. Write the token section of design-spec.md first, then the component inventory, deriving components from what S-1 to S-22 need (balance header, account row, ledger rows for expenses and settlements, money text, avatar with initials, category chip and grid, split control, allocation row, timeline line, sync line, update banner, charts, empty and error blocks, "Needs connection" hint).
4. For each screen S-1 to S-22, in id order: layout, each applicable state of §13.3 plus the screen-specific states its "Must show" column implies (for example S-1 errors invite_invalid, network, rate_limited; S-8 deleted; S-9 over-settle warning), interactions, TalkBack labels. Mark non-applicable states explicitly.
5. Write strings.csv as you go: every string on every screen and state, both languages, Android placeholders, plurals noted. Then add notification copy (§13.3), rejection reasons (§14.4.6), "Needs connection", "Could not reach the server", relative times (§9.8), enum labels (split modes, range presets, granularity, measure, group by, roles, invite kinds), category default names (AC-7.2).
6. Render every screen and state, light and dark, Swedish, to docs/ux/screens/ with a headless browser already installed (check with command -v; stop and ask if none).
7. Write colour-tokens-proposal.md.
8. Self-check the gate (§7) with a script you do not commit: every row of strings.csv has non-empty en and sv; every key is unique; every screen S-1 to S-22 has a section in design-spec.md covering all six state names (present or "not applicable"); grep for lorem|TODO|XXX is empty.
9. Commit on UX-sprint (only files under docs/ux/), git rebase main. Never merge, push or remove the worktree.

7. Gate

From SPEC §11.2 (v0.3), verbatim: "Every string key has en and sv; every screen has every state that design-spec.md lists for it (§13.3)". The per-screen state list in design-spec.md is the binding one (§13.3). Green means: the self-check of step 8 passes with zero missing translations, zero duplicate keys, all 22 screens present with each of the six §13.3 states either specified or marked not applicable, and a PNG for every specified state in light and dark.

8. HUMAN steps

From SPEC §11.2, verbatim: "Approve the design spec". Where in the flow: after this plan's report; M6 starts only after the owner's approval and after the orchestrator's spec change for the §9.7 hex values.

9. Out of scope

• New features, flow changes against §4, enum or limit changes, app icon production, animations beyond descriptions, Kotlin code (§13.5).
• Editing SPEC.md (the §9.7 hex change is the orchestrator's, from the proposal file).
• Android resources (values/strings.xml): M6 and M7a to M7f convert strings.csv.
• Revisiting the unchosen directions beyond what the owner's comments ask.
• Any file outside docs/ux/.

10. Report

• Branch UX-sprint and head commit hash after rebasing on main.
• Gate self-check output lines (string count, missing translations 0, screens 22, PNG count).
• How each owner comment was addressed, one line each.
• The proposed §9.7 hex values (summary line; detail in the proposal file).
• Typography in the Material 3 default typeface; no font is bundled (D-020).
• Open questions and spec gaps with section numbers; any screen that needs data not in §14.2.4.
• Numbering used (none expected; say none).
• HUMAN step to relay: "Approve the design spec", with the paths to review.

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.