Ferrous-Solitaire/docs/ui-redesign-2026-07.md

# Menu UX Redesign — July 2026

Status: IN PROGRESS. A / E / C / G shipped in v0.43.0; B implemented on
`feat/home-hierarchy` (2026-07-13); F / H and the I–M backlog remain open.
Visual identity (Terminal / base16-eighties) is settled and out of
scope — this is about **structure and interaction**, not colors or type.

## Diagnosis (from code survey, 2026-07-07)

| Surface | Today | Pain |
| --- | --- | --- |
| Settings | One scrolling modal, 5 section labels, ~37 control rows, single Done | Scroll-hunting for any toggle; endless on the folded (cover) screen; every new feature (theme store, import) stretches it further |
| Home | Modal launcher: stats strip, draw-mode row, difficulty rows, 6 equal mode cards, Cancel | No "Continue" primacy; deal options (draw/difficulty/winnable) crowd the mode choice; six cards weighted identically though Classic dominates play |
| HUD menu | Popover with 7 destinations (Help, Modes, Stats, Achievements, Profile, Settings, Leaderboard) | "Modes" duplicates Home's job; flat list, no grouping; each item opens another modal — modal-on-modal navigation |
| Global | Everything is a modal over the felt | No hierarchy; near-square unfolded Fold renders one narrow wasted column |

## Phase A — Settings tabs (highest pain, lowest risk)

- Replace the single scroll with **tabs**: `Audio · Gameplay · Appearance ·
  Accessibility · Account`.
  - *Appearance* = today's Cosmetic (card back, background, card theme,
    theme store, import).
  - *Accessibility* = extracted from Gameplay/Cosmetic: color-blind,
    high-contrast, reduce-motion, touch input mode, tooltip delay.
  - *Account* = Sync + Privacy merged.
- Narrow screens: tab chips in a row under the header. Wide (aspect > ~1.2 —
  unfolded Fold, desktop): left rail, rows in two columns.
- Only the active tab's rows are spawned → each tab is ≤ 8 rows and fits the
  cover screen without scrolling.
- **Implementation constraint:** pure `ui.rs` re-layout + one `SettingsTab`
  resource. The `SettingsButton` enum, input handlers, and persistence are
  untouched, so the 25 settings tests and the ambiguity gate stay green.

## Phase B — Home becomes a real home

- **Hierarchy, top to bottom:**
  1. `Continue` card (only when a game is in progress) — mode, elapsed, score.
  2. Hero `New Game` — one tap, reuses last mode + deal options.
  3. Compact 2×3 mode grid (Classic, Daily, Zen, Challenge, Time Attack,
     Seed) — smaller cards, glyph + name + one-line description on wide only.
  4. Stats strip moves to the bottom (or right pane when unfolded).
- **Deal options** (draw 1/3, difficulty, winnable-only) move off the top
  level into a disclosure on the Classic card / New Game hero — they are
  Classic-mode concerns, not global ones.
- Cancel becomes `Back to table` and only renders when a game exists.
- Unfolded Fold / desktop: two panes — modes left, Continue + stats +
  daily/weekly right.

## Phase C — HUD menu consolidation

- Drop `Modes` from the popover (Home owns mode selection; HUD's New-Game
  path opens Home).
- Group the remaining six: **Play** (Home) · **You** (Profile, Stats,
  Achievements) · **Community** (Leaderboard) · **System** (Settings, Help) —
  section dividers in the existing popover, not a new widget.
- Dismissal audit: Esc / scrim-tap / Done must behave identically on every
  modal (most already do via `ScrimDismissible`; sweep the stragglers).

## Phase D — Validation gates

- Optional Stitch mockups (Terminal design-system asset
  `assets/0f1652274fea460585d0b331a9ddbb06`, project 593811793268308763) for
  Home + Settings before implementing Phase B. Phase A is safe to build
  straight in-engine.
- Per-phase gates: full test suite, clippy `-D warnings`, ambiguity gate at 0,
  Android checklist (§15.3), on-device pass on the Fold 7 in BOTH postures.

## Sequencing & risk

| Phase | Size | Risk | Depends on |
| --- | --- | --- | --- |
| A — Settings tabs | ~1 session | Low (layout-only) | — |
| B — Home hierarchy | 1–2 sessions | Medium (touches launch flow) | D mockups if wanted |
| C — Menu grouping | small | Low | B (Modes removal) |

## Phase E — "You" hub (reuses the Phase A tab component)

Profile, Stats, Achievements, and the replay browser are four separate
modals today, reached through the HUD popover one at a time. Fold them
into ONE tabbed hub — `Profile · Stats · Achievements · Replays` — using
the same tab widget Phase A builds for Settings. Cuts the HUD popover to
four destinations and makes the tab component pay for itself twice.
Existing per-screen systems keep their markers/handlers; only the outer
shell changes (same trick as Phase A).

## Phase F — Mobile ergonomics (Fold-first)

- **Bottom action bar** on touch: Undo, Hint, Draw within thumb reach at
  the bottom safe-area edge (via the existing `SafeAreaAnchoredBottom`),
  score-only band stays on top. Desktop keeps the current top band.
  Biggest one-handed-play win available; folded posture is tall and
  top-heavy today.
- **Hold-to-repeat Undo** — press-and-hold steps back repeatedly
  (respecting the existing undo scoring penalty), instead of tap-tap-tap.
- Both are additive; game stays fully playable with the top band alone
  (UI-first rule §3.3 satisfied).

## Phase G — Post-win flow

Win summary today is a stats dump with a close. Give it an action
hierarchy: **Play again** (same mode/options, primary) · **Share replay**
(the upload already returns a share URL; surface it here with copy
feedback) · **Watch replay** · quiet stats below. Rematch loop drops from
4 taps to 1.

## Phase H — Feedback polish (small, bundling candidates)

- Unify queued vs. immediate toast styling (two subtly different styles
  exist today) and anchor both to one position; consider a 5-item toast
  history on the stats screen.
- Theme-store modal: render the preview PNGs the server already serves
  (v1 is text-only rows).
- Hint: optional ghost-motion preview of the suggested move instead of a
  static highlight (auto-disabled under reduce-motion).

## Phase I — Onboarding & discoverability

The first-run onboarding exists, but everything learned after it is
invisible: the radial menu (long-press/right-click), hint cycling,
tap-to-toggle HUD chrome, hotkeys. Add **contextual one-time tips** —
fired by the situation, not a tour (first stall → hint tip; first
long-press-able stack → radial tip; each shows once, stored in
Settings like `shown_achievement_onboarding` already is). Plus a
one-shot **"What's new"** card on first launch after a version bump —
ObtainX updates are silent today, so shipped features go unnoticed
(nobody will find the theme store on their own).

## Phase J — Keyboard & focus completeness (desktop + web)

`ui_focus` already gives deterministic Esc order and tab-walk
(`FocusRow`/`Focusable`), and `KeyboardDragState` exists — but full
keyboard-only play has never been audited end to end. Deliverables: every
modal reachable/dismissable without a mouse, a visible focus ring styled
to the Terminal system (current focus state is subtle), and a hotkey
cheat-sheet overlay (hold `?`) generated from the actual bindings instead
of the static Help text. Web build (Rhys) benefits most.

## Phase K — UI scale & touch-target accessibility

All type sizes flow through `TYPE_*` tokens and layout through
`compute_layout` — which makes a **UI scale setting** (90/100/115/130 %)
cheap to wire and genuinely useful on the Fold's dense cover screen.
Pair with: respect Android system font scale on first run (seed the
setting from it), and a one-time audit that every interactive element
meets the 44 px logical minimum in BOTH Fold postures (the pill buttons
and picker swatches are the suspects). Lands in the Accessibility tab
that Phase A creates.

## Phase L — Empty & loading states, standardized

Async/empty surfaces each improvise today: leaderboard with no entries,
stats with no games, replay browser with no replays, theme store
loading/error (just added), sync status text. Define ONE pattern —
glyph + one-line explanation + a single next-step action — as a
`spawn_empty_state` helper in `ui_modal`, and sweep all five surfaces
onto it. Small, mechanical, big perceived-quality win.

## Phase M — Sync transparency & data stewardship

The sync layer returns `ConflictReport`s ("data is never silently
discarded") — but no UI ever shows them; players can't tell what a merge
did. Add: a post-sync summary line ("merged, 2 conflicts kept newer
values" → tap for detail in the Account tab), a visible last-synced
timestamp (exists as `SyncStatus::LastSynced`, barely surfaced), and
local **data export/import** (zip of the JSON saves) for device
migrations without a server. Closes the trust loop the server work
opened.

## Roadmap tie-ins (already in flight elsewhere)

- **Spider mode** (feat/spider-core, PR #157): Home's mode grid gains a
  7th card once engine work lands — the 2×3 grid in Phase B should be
  designed as N-card flow from day one. Spider UI also needs positional
  card→entity keys (documented in spider.rs module docs).
- **Show solution** (feat/solution-line, in flight): lands in the pause
  menu; Phase C's grouping should leave room for it under a "Game"
  cluster if the pause menu grows.

## Sequencing (updated)

| Phase | Size | Risk | Depends on |
| --- | --- | --- | --- |
| A — Settings tabs | ~1 session | Low | — (DECIDED: tabs) |
| E — "You" hub | ~1 session | Low | A's tab component |
| C — Menu grouping | small | Low | E (popover shrinks) |
| B — Home hierarchy | 1–2 sessions | Medium | D mockups if wanted |
| F — Bottom action bar | ~1 session | Medium (input paths) | — |
| G — Post-win flow | small | Low | — |
| H — Feedback polish | small each | Low | — |
| I — Onboarding & discoverability | ~1 session | Low | ships best after B/F land |
| J — Keyboard & focus completeness | ~1 session | Low | A/E (fewer modals to audit) |
| K — UI scale & touch targets | ~1 session | Medium (layout-wide) | A (Accessibility tab) |
| L — Empty-state standardization | small | Low | — |
| M — Sync transparency & export | ~1 session | Low–Medium | A (Account tab) |

Suggested order: **A → E → C** (one arc: the tab component and the menu
slimming), then **B**, then **F/G/H** as independent follow-ups.

## Open decisions

1. ~~Settings: tabs vs. sub-pages~~ — **DECIDED 2026-07-07: tabs.**
2. ~~Deal options: disclosure on Classic card vs. keep global row~~ —
   **DECIDED 2026-07-09: disclosure on the Classic card / New Game hero.**
3. ~~Time Attack + Seed: top-level cards vs. "More" card~~ —
   **DECIDED 2026-07-09: top-level cards, symmetric 2×3 grid.**
4. ~~Stitch mockups for Phase B, or iterate directly in-engine~~ —
   **DECIDED 2026-07-09: directly in-engine.**
5. ~~Phase F bottom bar: touch-only vs. also desktop~~ —
   **DECIDED 2026-07-13: touch-only.** Desktop keeps the current top
   band; the bar is additive per §3.3 so a later desktop rollout stays
   a settings flag away.