| name | ui-review |
| description | Structured fresh-eyes design review of any UI — screenshot-driven critique that produces ranked, concrete findings in a shared feel-word vocabulary (clean, sharp, cluttered, calm…). Use when the user asks to review/critique/improve a UI, says something "looks off / feels bolted on / isn't working", before shipping any user-facing surface, or after substantive UI changes. Works on live URLs (playwright-cli), local dev servers, and screenshots they paste. Run any deterministic UI-lint oracle you have FIRST, then the judgment passes. Companion: your visual-design system if you keep one, tufte (if charts are present). |
ui-review — the fresh-eyes critique loop
A review is measurements first, judgment second, and every finding lands as a concrete fix
("padding 12→16 on .card, kill the inner border"), never as "improve the visual hierarchy."
Findings cite the feel-word they serve (clean, sharp, calm, dense…) — that's how a shared vocabulary compounds.
Protocol
0. Oracle first
<your-ui-lint-command> <url>
Machine findings (contrast, tap targets, off-scale spacing, palette sprawl…) come free —
never spend judgment on what the oracle already caught. Attach its summary to the review.
1. Capture — three widths, key states
npx playwright-cli open <url>
npx playwright-cli resize 390 844 && npx playwright-cli screenshot
npx playwright-cli resize 834 1112 && npx playwright-cli screenshot
npx playwright-cli resize 1440 900 && npx playwright-cli screenshot
Then capture the states that hide problems: an empty state, a loading moment if reachable, an
error (bad input), dark mode if the app has it, and one "full" state (long text, many items —
where truncation and overflow live). snapshot gives the accessibility tree — check names/roles
while there.
2. The squint pass (hierarchy)
Blur your reading of the desktop screenshot (literally squint / shrink it): what survives?
- Exactly one primary thing should survive per view. None = flat; several = shouting.
- Do groups read as groups (proximity), or does it blur into an even field?
3. The lines pass (alignment)
Trace the left edges, top edges, gutters. Every edge should share a line with another element.
Flag every almost-aligned edge (2–6px off) — those are defects, not style.
4. The scale pass (spacing + type)
- Count distinct gap sizes doing the same job (card padding, row gaps) — more than one = drift.
- Count font sizes and weights in view — >4 sizes or half-step jumps (16→17, 400→500) = drift.
5. The color pass
- Count colors doing emphasis work — more than one accent = sprawl.
- Any gray-on-gray that matters? Any status carried by color alone?
- Layers: do bg/surface/raised actually separate, or is it one muddy field?
6. The states + interaction pass (the ux agent's ground)
Loading/empty/error/success present and designed? Focus-visible on everything interactive?
Primary action obvious and consistent across views? (Deep interaction critique → the ux agent's
checklist; this pass just catches the visible gaps.)
7. The copy pass
Labels ≤3 words; messages say what to DO, not what went wrong; no jargon leaking from the
backend (ERR_CONN_REFUSED → "Can't reach the server — retrying").
Output format
## UI review — <surface> (<date>)
**Oracle:** your-lint X hard / Y advisory (attached — omit if you have no deterministic lint)
**Verdict in one line:** <e.g. "solid bones, spacing drift + accent sprawl are 80% of the 'off' feeling">
### Findings (ranked by visual payoff per effort)
1. **[uncluttered] Card borders → whitespace.** 6 bordered boxes organize what spacing can.
Fix: kill `.card` border, gap 16→24, keep --shadow-1. (biggest single win)
2. **[sharp] Body text is mid-gray on off-white (3.8:1).** Fix: use the ink/body color token for body text, the softer tone only for meta.
3. …
### Knobs I'd turn (summary for steering)
- borders −6 · accents 3→1 · paddings reconciled to one spacing step · …
### Vocabulary note (one per review)
"Optical alignment": the play icon is mathematically centered but LOOKS right-shifted —
triangles need a 1–2px optical nudge. Where it applies here: …
Rules
- Rank by payoff-per-effort — the top 3 findings should carry most of the "off" feeling.
A review with 25 equal-weight findings is a review nobody acts on.
- Every finding names its feel-word — the review teaches the vocabulary as it goes.
- Fixes are diffs-in-prose (selector + token + value), so the dev pass is mechanical.
- One vocabulary note per review — exactly one, so it lands.
- Fresh eyes are real: review the screenshots, not the code first — the code biases you
toward what was intended over what is seen. Code comes second, to locate fixes.
- If the surface has charts/data viz, run the
tufte skill's checklist on those specifically.
- Pre-ship or forms/inputs/motion-heavy surfaces: add a
web-interface-guidelines rules pass
(vendored Vercel rules — interaction-correctness details feel-words don't cover) and, for
public-facing pages, a web-quality-audit perf/a11y pass. Both report file:line findings
that merge into this review's ranked list.
- Re-review after fixes with the same protocol (inverse hypothesis: the finding should be gone
in the new screenshot, and your deterministic lint should stay/turn green).
