Ferrous-Solitaire/SESSION_HANDOFF.md

Solitaire Quest — UX Overhaul Session Handoff

Last updated: 2026-04-30 — Phase 3 complete. All 10 steps landed; ready for full smoke-test.

Where we are

Phase 3 of the UX overhaul brief is done. The whole engine has been migrated to the ui_theme design-token system + ui_modal scaffold. Animation system upgraded. Final literal sweep landed. The work spans 17 commits this session, from the foundation (e14852c) through to the final sweep (54e024c).

Design direction (already saved as project memory)

• Tone: Balatro — chunky readable type, theatrical hierarchy, satisfying micro-interactions.
• Palette: Midnight Purple base (BG_BASE #1A0F2E → BG_ELEVATED #2D1B69 → BG_ELEVATED_HI #3A2580 → BG_ELEVATED_TOP #482F97) + Balatro yellow primary accent (ACCENT_PRIMARY #FFD23F) + warm magenta secondary (ACCENT_SECONDARY #FF6B9D).
• See memory/project_ux_overhaul_2026-04.md for the full direction.

Top complaints from the original smoke test — all closed

1. HUD too cluttered. ✅ Closed by 73cad7e — readouts now sit in a 4-tier vertical stack with progressive disclosure of penalty/bonus tiers.
2. Y/N keyboard prompts feel like debug panels. ✅ Closed across Confirm, GameOver, Pause, Forfeit, and Settings modals — every prompt now has real Primary/Secondary/Tertiary buttons with hover/press feedback.

Foundation (done)

• solitaire_engine/src/ui_theme.rs — every design token: colours, 5-rung typography scale, 4-multiple spacing scale, three radius rungs, monotonically-ordered z-index hierarchy, motion durations with scaled_duration(speed) helper.
• solitaire_engine/src/ui_modal.rs — spawn_modal scaffold + spawn_modal_header / spawn_modal_body_text / spawn_modal_actions / spawn_modal_button helpers + ButtonVariant enum (Primary / Secondary / Tertiary) + paint_modal_buttons system. UiModalPlugin registered in solitaire_app/src/main.rs.

Commits this session (Phase 3, latest first)

54e024c chore(engine): final literal-to-token sweep
3a01318 feat(engine): upgrade animations — curves, scoped settle, deal jitter, cascade rotation
79d3917 chore(data): derive Copy on AnimSpeed
ba019c0 feat(engine): convert SettingsPanel to modal scaffold + Done button
18d7c12 feat(engine): convert OnboardingPlugin to 3-slide modal flow
cb93bd9 fix(engine): pin modals via GlobalZIndex and surface forfeit-no-op toast
6723416 feat(engine): convert PauseScreen to modal + add ForfeitConfirmScreen
afb0879 docs: add SESSION_HANDOFF.md mid-overhaul checkpoint
3b619b8 feat(engine): convert HomeScreen to modal scaffold + Done button
37681cf feat(engine): convert LeaderboardScreen to modal scaffold + Done button
99064ce feat(engine): convert ProfileScreen to modal scaffold + Done button
de4dba6 feat(engine): convert AchievementsScreen to modal scaffold + Done button
75fc3aa feat(engine): convert StatsScreen to modal scaffold + Done button
deb034c feat(engine): convert HelpScreen to real-button modal with kbd-chip rows
242b5fe feat(engine): convert GameOverScreen to real-button modal
3f922ed feat(engine): convert ConfirmNewGameScreen to real-button modal
8da62bd feat(engine): add ui_modal primitive (scaffold + button variants)
73cad7e feat(engine): restructure HUD into 4-tier layout, adopt design tokens
e14852c feat(engine): add ui_theme.rs design-token module

Test status: cargo build --workspace clean, cargo clippy --workspace -- -D warnings clean, 819 tests pass / 0 failed / 8 ignored.

Smoke-test checklist

The whole overhaul is on disk. Worth running through once end-to-end:

1. Run the game. cargo run -p solitaire_app --features bevy/dynamic_linking.
2. HUD layout reads as 4 stacked tiers (Score / Mode / Penalty / Selection) with the new midnight-purple palette.
3. Open every overlay — S (Stats), A (Achievements), P (Profile), O (Settings), L (Leaderboard), M (Home), F1 (Help). Each is a centred card on a uniform scrim with a yellow Done / Close primary button. Hover/press states on every button.
4. Settings. Four sections (Audio / Gameplay / Cosmetic / Sync). Body scrolls within the modal on small windows; Done button stays fixed at the bottom regardless of scroll. Card-back / Background pickers tint the selected swatch with STATE_SUCCESS.
5. Confirm flow. Click New Game while a game is in progress — the abandon-current-game modal has real Cancel/Confirm buttons. Y/Enter and the yellow primary button start a new game; N/Esc and the secondary button cancel.
6. Pause + Forfeit. Press Esc — pause modal shows real Resume / Forfeit buttons. Forfeit button opens a Cancel/Forfeit confirmation modal stacked above the pause modal (z-index ordered correctly via GlobalZIndex).
7. First-run onboarding. Delete settings.json (or set first_run_complete = false) — three-slide flow shows: Welcome → How to play → Keyboard shortcuts. Navigate with Next / Back buttons or → / ← accelerators. Esc skips on slide 0.
8. Animations.
   • Slide a card to a pile — motion curves through SmoothSnap (slight overshoot + settle), not linear lerp.
   • Drop a card on a valid destination — only the moved cards bounce; the rest of the table stays still.
   • Start a new game — deal stagger is no longer mechanically uniform; cards land with subtle ±10% timing variation.
   • Win a game — cascade now uses Expressive curve with per-card ±15° Z-rotation, screen shake driven by the new MOTION_WIN_SHAKE_* tokens.
9. Resize the window — cards still snap, no "snap-back-and-forth" jitter.
10. Win modal — restyled with the design tokens: midnight-purple card, yellow Play Again button.

Open follow-ups (not blockers)

• Home / Help redundancy. Home is still a kbd-reference modal that mostly duplicates Help. Three options: (1) keep as-is, (2) convert into a true mode launcher (Classic / Daily / Zen / Challenge / Time Attack cards, locked options visibly disabled below level 5), (3) drop entirely now that the action bar covers everything Home does. Worth asking the user which direction they want.
• Forfeit countdown toast is now superseded by the Forfeit modal (6723416). Confirm the toast path is no longer reachable when smoke-testing.
• Sub-rung pixel sizes (1 px borders, 64/80/110/150/160 px fixed widths, 28/36/50 px specific spacings) were intentionally left as literals during the step-10 sweep — they're below the smallest SPACE_* rung. If the design system grows a "fine" spacing tier in the future, those become candidates for migration.

Resume prompt for the next session

You are a senior Rust + Bevy developer working toward a public release
of Solitaire Quest. Working directory: /home/manage/Rusty_Solitare.
Branch: master. Apply that lens to every decision: prefer shipping
quality (polish, packaging, defaults, credits, crash safety) over
greenfield features. If something is half-done, the question is
"finish for v1 or cut for v1?" not "what else can we add?".

State: HEAD=0066ca6. Phase 3 of the UX overhaul is shipped. cargo
build / clippy --workspace -- -D warnings / test --workspace all
green — 819 tests pass / 0 fail / 8 ignored.

READ FIRST (in order, before doing anything):
  1. SESSION_HANDOFF.md  — full state, smoke-test checklist, follow-ups
  2. CLAUDE.md           — hard rules (UI-first, no panics, etc.)
  3. ARCHITECTURE.md §1, §15, §17 — design principles, platform
                                    targets, deployment guide
  4. ~/.claude/projects/-home-manage-Rusty-Solitare/memory/MEMORY.md
                         — saved feedback / project context

GATING SIGNAL — ASK FIRST, DON'T ASSUME:
Before proposing new work, ask: "Did the smoke-test (items 1-10 in
SESSION_HANDOFF.md) pass, or did anything regress?" If a regression
exists, fix it before opening any new thread.

LIKELY NEXT DIRECTIONS — surface for the user to choose, don't pick
unilaterally. All framed through "what does v1 release need?":

  A. Home modal decision (open in SESSION_HANDOFF.md).
     - keep as kbd-reference (duplicates Help — release-blocking
       confusion?)
     - repurpose as mode launcher (Classic / Daily / Zen / Challenge /
       Time Attack cards, locked options below level 5)
     - drop (action bar already covers every action)

  B. Window + release polish — `solitaire_app/src/main.rs:34-48`
     currently sets only title + resolution + min size. For public
     release the window needs:
       - app icon (taskbar / dock / alt-tab) — Bevy `Window::window_icon`
         or platform `set_window_icon`; ship a .png/.ico asset.
       - window class / app id (`Window::name`) so X11/Wayland and
         Windows group taskbar entries correctly.
       - persist size + position across launches (Settings already
         saves to JSON; add `window_geometry` field).
       - F11 (or a Settings toggle) wired to real fullscreen mode.
       - centered default position on first launch (Bevy supports
         `WindowPosition::Centered`).
       - present_mode + vsync verification — make sure Linux/macOS
         don't ship at uncapped 4000 fps.
       - panic hook (`std::panic::set_hook`) that writes a crash
         report next to the save files instead of silently exiting.
       - macOS Info.plist / Windows .ico bundling — ARCHITECTURE.md
         §17 currently only covers server deploy.

  C. Sound-design audit. The scoped settle bounce (3a01318) means
     audio_plugin.rs trigger sites may fire less often than before;
     verify card_place / card_flip / card_invalid still feel right.

  D. Sync flow end-to-end on a real second machine. Server
     scaffolding exists but the register → push → pull → restore-on-
     other-device round trip hasn't been exercised against the new
     Settings sync section.

  E. Achievement unlock completeness. ARCHITECTURE.md §11 lists 18.
     The three hidden ones (speed_and_skill, comeback, zen_winner)
     are most likely to be untested. For release, every advertised
     achievement needs to actually fire.

  F. Release-readiness backlog:
     - README / store-page copy / screenshots
     - LICENSE + third-party credits (xCards art, FiraMono, Bevy)
     - SemVer + a v0.1.0 git tag
     - itch.io / Steam packaging per platform (ARCHITECTURE.md §15)
     - App signing — macOS notarization, Windows Authenticode,
       Linux AppImage
     - Telemetry / crash reporting — opt-in, off by default; or
       confirm we ship without and rely on player reports

  G. UI/UX professional polish — Phase 3 shipped the design system;
     v1 wants the difference between "consistent" and "feels
     intentional":
       - Microcopy pass: every button label, empty state, error
         message, and onboarding line reviewed for voice + clarity.
         Pick one verb per concept ("Done" vs "Close" vs "OK") and
         apply it everywhere.
       - Empty / loading / error states: Leaderboard before any
         scores, Stats before any games, Sync UI before login.
         Today these are likely blank panels.
       - Modal open/close animation: `MOTION_MODAL_SECS` token exists
         in `ui_theme.rs:255` but isn't wired up — modals
         appear/disappear instantly. Add scale-from-0.96 + scrim fade
         per the token's doc comment.
       - Tooltips on HUD readouts and settings labels. Bevy has no
         built-in tooltip; build a small one. Hover a number to learn
         what it counts.
       - Accessibility: verify the AAA-contrast claim on
         `ACCENT_PRIMARY` over `BG_BASE` (ui_theme.rs:65). Confirm
         `AnimSpeed::Instant` disables every new animation (slide
         curve, scoped settle, deal jitter, cascade rotation). Add
         focus rings on `Button` entities for keyboard navigation.
       - Typography choice: FiraMono is one weight, monospace for
         everything. Consider shipping a second proportional face for
         body + headings, keep mono for numerics (HUD score, timer).
         Or commit to mono and lean into the "calm coder" feel — pick
         deliberately and document the decision.
       - Onboarding artwork: the 3 slides are text + buttons. For
         release, stylised illustrations (or simple animated card
         props on each slide) elevate the first-launch feel.
       - Score-change feedback: floating "+N" numbers when score
         jumps; pulse on the readout when value crosses a milestone.
         `MOTION_SCORE_PULSE_SECS` is already a token.
       - Splash / loading screen: today the window goes straight to
         gameplay. A 1-2 second branded splash signals "real game"
         vs "rust prototype".
       - Hit-target audit: every interactive element ≥ 32 px on
         desktop. Settings has 28 px icon buttons (`ICON_BUTTON_PX`
         in settings_plugin.rs); revisit.
       - Win-moment design: the cascade is good; consider a score-
         breakdown reveal, streak callout, "share your time"
         affordance for v1.

WORKFLOW NOTES:
  - Commits use:
      git -c user.name=funman300 -c user.email=root@vscode.infinity commit -m "..."
  - Sub-agents can Edit/Write but CANNOT `git commit`. Brief them to
    stage + verify only; orchestrator commits on their behalf.
    See memory/feedback_agent_commit_limit.md.
  - Remote push needs interactive credentials on git.aleshym.co; the
    user runs `git push origin master` themselves.
  - Every commit must pass build / clippy / test. Pause-and-verify
    is the user's preferred cadence — one feature per commit.

OPEN AT THE START: ask (1) did smoke-test pass, (2) which of A–G to
pursue first. Do not assume.