jacobh2
d39eb2c79b
Records the owner's UX-sprint decisions UX-1 to UX-8 of docs/ux/proposed-decisions.md: D-047 direction Kalas muted, D-048 three tabs, D-049 category suggestion (§9.11, suggestCategory, contracts/category-keywords.csv, suggest_category.json), D-050 S-1 display-name field, D-051 colour token values from Kalas (slate, amber TODO(U2)), D-052 smaller UX rules, D-053 finer Splitwise mapping, D-054 fourteen default categories with server schema 2 (migration 0002, §14.1.1). Adds milestone group M12 (PLAN-M12a/b/c, prompts), the CLAUDE.md UX-sprint note, and rewrites HANDOFF. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TQd3pEP9UeN2uifbHknQ7B
80 lines
8.3 KiB
Markdown
80 lines
8.3 KiB
Markdown
# 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.
|