motif/docs/home-ux-audit.md

Home UX audit + improvements (arcade-first)

This doc is a saved copy of the current home UX audit plan (no code changes).

Current UX issues (what’s making it feel uninspiring/confusing)

• Unclear hierarchy: “Search”, “Preview”, and “Synthesis Engine” compete; users don’t instantly see the main thing to do.
• Weak step-by-step guidance: The app is a 3-step flow (Search → Select → Run engine), but the UI doesn’t feel like a guided sequence.
• Controls feel detached from state: Buttons don’t always read as “locked until selection”; the reason for disabled state isn’t visible.
• Results table is dense on mobile: long titles wrap unpredictably, selection highlight is subtle.
• Copy and concept drift: “emulator/engine” and “MIDI scrape/analyse” copy varies; the story should be consistent and confident.
• iOS audio state: The “Enable Audio” banner is reactive but not integrated into the flow (and can appear “random”).

Target outcome

Arcade cabinet vibe with a clear, dramatic main CTA:

• Primary action: “Run the engine” (Generate & Play)
• Secondary: preview the MIDI
• Stronger “insert coin” style guidance: show step chips and a big engine panel.

Proposed UX changes (high impact, low risk)

1) Make the flow explicit

Update index.html:

• Add a compact “Steps” row near the top:
  • Step 1: Search
  • Step 2: Pick a MIDI
  • Step 3: Run the engine
• Tie each step’s visual state to app state:
  • Step 2/3 show “locked” styling until available.

2) Promote “Synthesis Engine” as the hero module

• Move the engine card visually above Preview (or keep order but make engine card visually dominant).
• Make engine CTA bigger and more arcade:
  • Primary button: Run the engine
  • Secondary: Stop
  • Volume + progress remain but visually subordinate.
• Add a small one-line “what this does” under the button, not as a paragraph.

3) Preview becomes clearly “optional”

• Rename to “Listen to the source MIDI (optional)”
• Collapse preview by default on mobile (or add a “Show preview” toggle) to reduce overwhelm.

4) Results list readability + selection confidence

• Increase row tap targets and selection contrast.
• Add a right-side “Selected” chip on the selected row.
• On mobile:
  • clamp long titles to 2 lines
  • reduce columns (hide Source or Duration) based on width.

5) iOS audio UX integrated into the engine (subtle)

• Only on iOS-like browsers and only when audio is locked.
• Show a small under-section link: “Having trouble on iOS? Enable audio”
• Clicking expands a compact CTA row (Enable Audio button + tiny state line).
• Avoid a big persistent banner that could confuse non-iOS users.

6) Copy pass

Deferred for now: keep copy changes out of this pass.

Implementation plan (concrete)

Files

• Primary: index.html
• Minor TS adjustments (state-driven CSS classes): src/main.ts

Approach

• Add a small set of state CSS classes on body (or on .container):
  • state-has-results
  • state-has-selection
  • state-audio-locked
• In src/main.ts, toggle these classes when:
  • results are loaded
  • a selection is made
  • audio unlock state changes
• Use CSS to:
  • style locked sections
  • highlight the engine CTA
  • improve mobile responsiveness

Test plan

• Desktop Chrome/Safari:
  • search → select → engine run
  • preview optional still works
• iOS Safari:
  • first run shows “arm audio” only when needed
  • no random banner when audio is already running
• Visual:
  • mobile widths (320–430px)
  • long titles wrapping

Non-goals

• No changes to the core synthesis engine behavior or backend.
• No copywriting/wording changes in this pass.