TUI UX review & design partnership
The design-data TUI (sdk/tui) is a ratatui/Elm-architecture terminal app for authoring
and inspecting Spectrum design tokens. This skill helps you evaluate and improve the user
experience — conventions, ergonomics, discoverability, workflow smoothness — using the
tuiwright MCP tools to drive and observe the app.
NOT correctness testing. For regression tests and render assertions use
tui-verify. This skill hands off to it whenever a finding needs a deterministic guard.
Orientation — TUI surfaces
| Surface | Entry key | Source files | What it does |
|---|---|---|---|
| Command palette | : |
src/command.rs, src/update_command.rs |
All commands: query / resolve / describe / validate / new / find / name |
| Fuzzy find | / |
src/fuzzy.rs, src/update.rs |
Live-ranked token search; Esc restores prior view |
| Authoring wizard | :new |
src/wizard.rs, src/wizard_draft.rs, src/wizard_common/ |
4-screen token creation: Intent → Classification → Values → Confirm |
| Find wizard | :find |
src/find.rs, src/view_find.rs |
Filter by property/component/variant/state/intent |
| Naming wizard | :name |
src/naming.rs |
3-screen name assembly; copies to clipboard |
| Help overlay | ? |
src/help.rs |
Scrollable keybinding reference |
| Home screen | (default) | src/logo.rs, src/view.rs |
Logo + command table |
| List views | (result) | src/app_views.rs, src/view.rs |
query / resolve / validate result tables |
| Describe view | :describe |
src/app_views.rs, src/view.rs |
Component token breakdown, scrollable |
| Theme | (config) | src/theme.rs |
terminal() (16-color) and spectrum() (truecolor) |
Source of truth for keybindings and commands: always read src/help.rs (HELP_TEXT)
and the Command enum in src/command.rs before asserting what the app does — the
documentation drifts; the code does not.
Drive-tier decision guide
Choose the tier that answers your question with the least friction.
tui_headless (NDJSON replay) ← fast, deterministic, no PTY — default for layout & flow
tui_open + send_keys + snapshot ← real terminal interaction, mouse, truecolor
tui_record_start → tui_record_stop → tui_to_gif ← visual evidence for findings
When to use each tier
| Question | Use |
|---|---|
| "How does the palette render after submitting a query?" | tui_headless with NDJSON seed |
| "What does the home screen look like at 80×24?" | tui_headless (set cols/rows params) |
| "Does Tab autocomplete feel natural while typing?" | tui_open + tui_send_keys + tui_snapshot |
| "Does mouse click-to-select work on the token list?" | tui_open + live interaction |
| "Show the full wizard workflow as evidence in a report" | Record with tui_record_* + tui_to_gif |
| "Is the truecolor Spectrum theme rendering correctly?" | tui_open + tui_snapshot (image mode) |
NDJSON message format
Each line of an NDJSON replay file is one serialized Message. The only format confirmed
to work reliably in headless mode is PaletteSubmit — it drives the TUI as if the user
typed the command and pressed Enter:
{"PaletteSubmit":"query property=background-color"}
{"PaletteSubmit":"describe button"}
{"PaletteSubmit":"validate"}
{"PaletteSubmit":"new accent background"}
Key events in NDJSON are unreliable. The
{"Key":...}format exists but does not reliably produce the expected state changes in headless replay — usetui_open+tui_send_keysfor anything requiring keyboard navigation (j/k, Esc, Tab, etc.).
Ready-made seeds for this repo live in the tuiwright examples directory:
/Users/garthdb/Projects/tuiwright/examples/spectrum-design-data/
(browse.ndjson, query-background-color.ndjson, describe-button.ndjson). Use them as starting
points, then extend or truncate as needed.
Tool quick-reference
tui_headless(ndjson, cols, rows, format) → rendered text grid (+ PNG if freeze on PATH)
tui_open(cols, rows) → open live pane
tui_send_keys(keys) → send input (\r=Enter, \x1b=Esc, \x1b[A=Up, \x1b[B=Down)
tui_snapshot(format) → capture live pane (text | image | both)
tui_wait_for(text, timeout_ms) → block until text appears (server-side 5s cap — use Bash sleep for longer waits)
tui_resize(cols, rows) → resize live pane
tui_assert(contains, not_contains, ndjson, ...) → pass/fail assertion on text presence
tui_diff(baseline, ndjson, create_if_missing) → compare against a named .snap.json baseline
tui_record_start(path) → begin asciinema .cast recording
tui_record_stop() → finalize recording
tui_to_gif(cast, gif) → convert .cast to GIF via agg
tui_close() → kill live pane
tui_snapshotmay hang on live panes. If it hangs >10s, kill the session and use the rmux CLI fallback instead:rmux new-session -d -s tui-qa -x 120 -y 36 "sdk/target/release/design-data packages/design-data/tokens --components packages/design-data/components" sleep 2 rmux send-keys -t tui-qa "query property=background-color" Enter sleep 1 rmux capture-pane -t tui-qa -p
tuiwright.toml (repo root) configures launch (sdk/target/release/design-data), default
size (120×36), and the headless_snapshot command template.
Workflow 1 — QA / UX review pass
Use when asked to review a surface or the full TUI for UX quality.
Step 0 — Build and verify the binary
Always do this before any QA session. A stale binary silently produces wrong behavior and wrong help content.
# Check whether the binary is older than key source files:
ls -la sdk/target/release/design-data
find sdk/tui/src -newer sdk/target/release/design-data -name "*.rs"
# If any source files are newer, rebuild:
cargo build -p design-data-cli --release
# or: moon run :build
Also verify the ? help overlay matches src/help.rs — run a headless probe with
{"PaletteSubmit":""} (home screen), then check if the binary's live help overlay content
matches what help.rs says. If they differ, rebuild before proceeding.
Step 1 — Define scope
Pick one surface (e.g. "the command palette") or state "full end-to-end pass." Write it down before driving.
Step 2 — Read the source of truth
# Check the actual keybindings:
# Read sdk/tui/src/help.rs (HELP_TEXT constant)
# Read sdk/tui/src/command.rs (Command enum + define_commands! macro)
Do this even for surfaces you think you know — implementations drift.
Step 3 — Drive and observe
For each surface in scope, use the tier decision guide above. Drive a representative user journey through the surface (happy path, then edge cases: empty input, Esc mid-flow, invalid input, very long content, narrow terminal).
Take a tui_snapshot or tui_headless result at each key state. Note: what rendered, what
was expected from convention, any gap.
Use tui_resize to check graceful degradation at 120×36 (target), 80×24 (standard), and
narrow/short sizes. The logo drops below 33 content rows — verify that still works.
Step 4 — Evaluate against conventions
Open references/tui-conventions.md and step through the
checklist for each surface you drove. Mark each convention: ✓ match / ~ partial / ✗ gap.
Step 5 — Evaluate against heuristics
Open references/qa-playbook.md and run the heuristic checklist.
For each failing heuristic, note the surface, the exact gap, and a severity:
- Blocker — prevents a user goal or causes confusion about state
- Friction — works, but harder than it should be; user has to figure it out
- Polish — works fine, small improvement opportunity
Step 6 — Capture evidence
For each finding that benefits from visual evidence:
# GIF of a workflow
tui_record_start("/tmp/finding-N.cast")
# … drive the flow with tui_open / tui_send_keys / tui_snapshot …
tui_record_stop()
tui_to_gif("/tmp/finding-N.cast", "/tmp/finding-N.gif")
# Read /tmp/finding-N.gif ← include in report
Step 7 — Emit deliverables (all four)
See Deliverables spec below.
Workflow 2 — Workflow / journey planning
Use when asked "how would a user do X?" or to identify whether a task is discoverable.
Step 1 — State the user goal
Write it out: "User wants to author a new color token." The goal should be what the user wants to accomplish, not which command to run.
Step 2 — Map what conventions would predict
Given the goal, describe what an experienced terminal-app user would try first — based on
the conventions in references/tui-conventions.md. This is
the baseline expectation before touching the actual app.
Step 3 — Drive the actual happy path
Drive the canonical successful path using tui_headless or tui_open + tui_send_keys.
Record a GIF of this path.
Step 4 — Drive the predicted-but-wrong paths
Try the paths a user would try based on convention that the app does NOT support (if any). Document what happens (error? silence? wrong result? accidental navigation?).
Step 5 — Identify discoverability gaps
- Are the entry points for this goal visible on the home screen or reachable from
?? - Does the command autocomplete surface it?
- Does partial input give helpful feedback?
- Would a user arriving at the wrong screen understand how to correct?
Step 6 — Deliver
Write a journey map (goal → steps → what the user sees at each step → where they could get stuck) plus findings for each gap, using the Deliverables spec below.
Workflow 3 — QoL recommendation
Use when asked "how can we improve X?" or after a review pass surfaces specific friction.
Step 1 — Categorize the improvement
- Quick win: a text change (empty-state copy, footer hint, error message), a single keybinding alias, or a minor layout tweak. Can be a direct inline edit.
- Larger change: new mode, new command, new wizard screen, significant interaction redesign. File a beads issue instead of inline-editing.
Step 2 — For quick wins — verify the guardrails apply
Before proposing an edit, check the architectural guardrails:
tests/budget.rsenforces 800-LOC cap persrc/file — checkwc -lon the target.- No
asyncinview*.rs(the no-async-in-render rule). Messagevariants must be ≤128 bytes (box large payloads if needed).- Adding or renaming a command requires updating both
command.rsand theCOMMANDSconstant insrc/logo.rs(a bidirectional sync test guards this; it will fail if out of sync). - Adding a hit region requires keeping
compute_hit_regionsin sync withview::draw(runtime.rs and tests guard this too).
After any inline fix, note: "run cargo test -p design-data-tui to verify guardrails pass."
Step 3 — Deliver
Inline edit + explanation for quick wins. Beads issue with design rationale for larger changes. Use the Deliverables spec below.
Deliverables spec
Every review or recommendation produces some or all of these four artifacts.
1. Structured critique report
## TUI UX Review — [scope] — [date]
**Method:** [headless / live / mixed] — [why that tier]
### Summary
[2–4 sentence overall verdict]
### Findings
#### [Surface name]
| # | Severity | Finding | Convention | Recommendation |
|---|---|---|---|---|
| 1 | Friction | Esc in the naming wizard cancels all three screens at once | Esc should undo one step at a time (lazygit, helix) | Add per-screen cancel that pops to prior screen |
**Evidence:** [inline snapshot text or GIF path]
### Triage table
| Finding | Beads ID | Inline fix | Status |
|---|---|---|---|
2. Beads issues
For each Blocker or Friction finding:
bd create \
--type=bug \ # or feature for improvements
--title="[Surface]: [one-line description]" \
--description="## Problem
[What happens and why it's wrong/suboptimal]
## Convention / expected behavior
[What users expect based on analogous TUIs — cite references/tui-conventions.md]
## Repro
[NDJSON seed or tui_send_keys sequence that demonstrates the issue]
## Suggested fix
[Concrete recommendation, with file:line reference if known]" \
--priority=2 # 1 for Blocker, 2 for Friction, 3 for Polish
3. Inline fix proposals
For quick wins, propose the edit using the Edit tool with:
- File path + old_string / new_string
- One-sentence rationale
- Note: "verify with
cargo test -p design-data-tui"
4. Annotated GIFs / screenshots
Capture evidence using the record workflow in Step 6 of Workflow 1. Read the resulting GIF into the conversation to annotate it (describe what to look for, circle attention areas in the report text).
Handoff to tui-verify
When a finding needs a correctness assertion or a regression guard — "does this cell render
the right symbol?", "does this layout hold at 80×24?" — stop and use tui-verify instead.
Do not invent a buffer assertion inline; let tui-verify's Tier 1 handle it.
For correctness tests → tui-verify (Tier 1 buffer assertions, tui_assert, tui_diff)
For UX/product judgment → tui-ux (this skill)
Gotchas
- Build the binary first — and check for staleness.
tuiwright.tomlpoints atsdk/target/release/design-data. A stale binary silently shows old behavior and old help text. Runfind sdk/tui/src -newer sdk/target/release/design-data -name "*.rs"— if anything is newer, rebuild withcargo build -p design-data-cli --release. - TOML scoping in tuiwright.toml. Top-level keys (like
headless_snapshot) must appear before the first[section]header in the file. A key after[size]becomessize.headless_snapshot(silently ignored) rather than the rootheadless_snapshot. tui_snapshotmay hang. The tuiwright SDK's rmux connection can fail to capture live panes even whentui_openreports success. Iftui_snapshothangs >10s, use the rmux CLI fallback (see Tool quick-reference above).tui_wait_forhas a server-side 5s cap. Thetimeout_msparameter is capped at 5000ms by the server regardless of the value you pass. For operations that take longer, useBash: sleep Nafter sending the command.- 800-LOC cap.
tests/budget.rsrejectssrc/files over 800 lines. Checkwc -lon any file you're about to touch. - No async in view.
tests/budget.rsscansview*.rsforasync fnand fails the build. All render code must be synchronous. - Message size budget. Every
Messagevariant must be ≤128 bytes. Box large payloads (seeDescribeDone,ValidateDoneas examples). - Command ↔ home-screen sync. The
COMMANDSconstant insrc/logo.rsmust stay in sync with theCommandenum. A bidirectional sync test enforces this. - Hit-region ↔ layout sync.
compute_hit_regionsinruntime.rsmust matchview::draw. A test inruntime.rsguards this; it will catch any drift. --no-resume-wizardfor clean state. When driving the wizard from a fresh state, pass--no-resume-wizardvia args intuiwright.tomlor thetui_openargsparam to avoid picking up a persisted draft from a prior session.