Conduct a design review of UI code and return a prioritised critique. The reviewer's lens is Emil Kowalski's design-engineering philosophy — taste is the differentiator; the unseen details compound; show the eye where to look — made concrete with the heuristics from Refactoring UI, WCAG, and MDN.
This is a read-only review skill: it diagnoses and proposes fixes; it does not rewrite the codebase. Each finding names the wrong default the code fell into, the exact fix, and why it matters.
When to Apply
- The user asks to "review this UI", run a "design review", or "critique" a component, screen, or page.
- The user says the output "looks off", "looks AI-generated", "looks like a wireframe", or "feels generic", and wants to know why.
- A PR touches CSS/JSX/Tailwind and the user wants design feedback before merge.
- The user wants to raise the visual polish or accessibility of an existing interface.
Not for building UI from scratch (use web-taste) or for the exhaustive animation rule set (use emilkowal-animations).
How to Run the Review
Two modes. A static review reads the code and is the default. A runtime review additionally drives a real browser to measure what the code can't show — animation timing and dropped frames, layout shift, the live focus order and accessibility tree, and the multi-page flow clicked through end to end. Switch to runtime whenever the verdict turns on rendered behaviour (the motion-, interact-, and flow- categories), per runtime-capture.md.
- Orient — the 0.5-second test. Before reading line by line, picture the rendered screen. Where does the eye land first? Is there a single focal point, or does everything carry equal weight? This frames which categories matter most for this UI.
- Pass the categories in priority order (table below). For each decision the code makes, read the matching reference file and check the code against it. Visual hierarchy and spacing are where the largest, most frequent problems live — start there.
- For multi-page or interaction-driven UX, walk it in a browser. When the brief is a flow ("review this onboarding") or the issue is felt in motion (jank, blank route flashes, lost focus), capture runtime evidence per runtime-capture.md so the Before column is a measured value, not a guess.
- Record each problem as a finding with a Before (the exact code or measurement), an After (the concrete fix), a Why (the principle), and a context-assigned Severity.
- Close with a verdict: the top 3 fixes, ranked by impact, so the author knows what to change first.
Output Format (Required)
Report findings as a single markdown table, one row per issue. Do not write findings as prose or as Before: / After: on separate lines.
| Severity | Before | After | Why |
|---|---|---|---|
| High | transition: all 300ms ease-in |
transition: opacity 180ms cubic-bezier(0.23, 1, 0.32, 1) |
ease-in feels sluggish on entry; name the property and use a strong ease-out curve |
| High | every button bg-indigo-600 |
one filled primary; others ghost/outline | Equal-weight buttons compete; one primary makes the next step obvious |
| Medium | color: #000 on #fff |
color: hsl(222 47% 11%) |
Pure black is harsher than ink and reads as stark |
| Critical | <div onClick={remove}> |
<button type="button" onClick={remove}> |
A div is unreachable by keyboard and invisible to screen readers |
Wrong format — never do this:
Before: transition: all 300ms
After: transition: opacity 180ms ease-out
────────────────────────────
Before: color #000
After: color slate-900
Severity guide (assigned per finding, by impact in this UI):
| Severity | Meaning |
|---|---|
| Critical | Breaks usability or accessibility — fails contrast, no keyboard access, unreadable text |
| High | Clearly damages the design — no hierarchy, cramped spacing, competing primary actions |
| Medium | Noticeable polish gap — default easing, uniform line-height, missing press feedback |
| Low | Minor refinement — a value slightly off the scale |
Finish with: Top 3 fixes — the highest-impact rows, in the order the author should tackle them.
Rule Categories
| # | Category | Prefix | Covers |
|---|---|---|---|
| 1 | Visual Hierarchy | hier- |
Focal point, emphasis technique, one primary action, value-over-label, space over borders |
| 2 | Spacing & Layout | space- |
Spacing scale, generous whitespace, proximity grouping, constrained width |
| 3 | Typography | type- |
Type scale, line length, line-height, alignment, readable body text |
| 4 | Colour & Contrast | color- |
Near-black text, WCAG contrast, HSL ramps, restrained accents, colour-plus-cue |
| 5 | Component States & Feedback | state- |
Press feedback, focus-visible, the full state matrix, empty states |
| 6 | Motion & Animation | motion- |
Purpose/frequency, ease-out curves, sub-300ms, enter origin/scale, transform-only |
| 7 | Responsiveness & Touch | resp- |
Fluid mobile-first, 44px targets, gating hover |
| 8 | Accessibility & Semantics | access- |
Semantic elements, accessible names, reduced-motion |
| 9 | Flow & Navigation | flow- |
App-shell consistency, view-state persistence, entry-point integrity, wayfinding |
| 10 | Interaction Continuity | interact- |
Bridging route transitions, async feedback, focus on navigation |
Quick Reference
1. Visual Hierarchy (hier-)
hier-one-focal-point— Establish one clear focal point per screenhier-emphasis-color-weight— Use colour and weight to set emphasis, not size alonehier-one-primary-action— Limit each view to one primary actionhier-values-over-labels— Make values louder than their labelshier-replace-borders-with-space— Replace borders with spacing and background
2. Spacing & Layout (space-)
space-use-a-scale— Size spacing from a consistent scalespace-start-generous— Give layouts more whitespace than feels necessaryspace-proximity-groups— Vary spacing to show what is groupedspace-constrain-measure— Cap and centre the page container width
3. Typography (type-)
type-modular-scale— Choose font sizes from a small type scaletype-limit-line-length— Limit body line length for readabilitytype-line-height-by-size— Set line-height relative to font sizetype-left-align-prose— Align multi-line text to the lefttype-readable-body-size— Keep body text large and solid enough to read
4. Colour & Contrast (color-)
color-avoid-pure-black— Use a near-black instead of pure blackcolor-meet-contrast— Meet WCAG contrast for body textcolor-hsl-scales— Define colour as HSL shade rampscolor-limit-accents— Limit the palette to one accent plus neutralscolor-not-only-signal— Pair colour with a second cue for state
5. Component States & Feedback (state-)
state-press-feedback— Give pressable elements active feedbackstate-focus-visible— Keep an accessible focus indicatorstate-design-all-states— Design every interactive state, not just the defaultstate-empty-state— Design the empty state with guidance
6. Motion & Animation (motion-)
motion-needs-purpose— Animate only with a purposemotion-ease-out-custom— Use ease-out with a custom curve for UI transitionsmotion-under-300ms— Keep UI transitions under 300msmotion-enter-origin-scale— Enter from a near scale and the trigger's originmotion-transform-opacity-only— Animate only transform and opacity
For drag, gestures, springs, stagger, clip-path, and the full timing/easing tables, defer to the emilkowal-animations skill.
7. Responsiveness & Touch (resp-)
resp-fluid-not-fixed— Build mobile-first with fluid widthsresp-touch-target-size— Size touch targets to at least 44pxresp-gate-hover— Gate hover-only affordances behind a pointer query
8. Accessibility & Semantics (access-)
access-semantic-elements— Use semantic elements for interactive controlsaccess-name-icon-controls— Give icon-only controls an accessible nameaccess-respect-reduced-motion— Honor the reduced-motion preference
9. Flow & Navigation (flow-)
Reviews the experience across pages, which single-screen review can't see. Walk the flow in a browser (runtime-capture.md).
flow-consistent-shell— Keep the app shell consistent across pagesflow-preserve-state-on-nav— Preserve scroll and view state across navigationflow-entry-point-integrity— Make every page work as a first entry pointflow-wayfinding— Show where the user is and the way back
10. Interaction Continuity (interact-)
Reviews whether the experience stays continuous over time and across transitions — the dimension a screenshot can't show. Best judged against a captured trace (runtime-capture.md).
interact-bridge-route-transitions— Bridge route changes so the screen never flashes blankinteract-feedback-spans-async— Fill the gap while an interaction is in flightinteract-move-focus-on-navigation— Move focus to new content after client-side navigation
How to Use
Read a reference file when its decision comes up in the code under review. Each rule names the wrong default it corrects, then shows the canonical fix (with an Incorrect/Correct contrast only where the wrong way is a real trap). Cite the rule slug in the "Why" column so the author can follow up.
- Runtime capture — drive a real browser (chrome-devtools-mcp) to measure motion, jank, focus order, and multi-page flow when a static read isn't enough
- Section definitions — category structure and order
- Rule template — for adding new rules
- AGENTS.md — auto-built table of contents across all rules
Related Skills
emilkowal-animations— the exhaustive animation rule set (easing, gestures, springs, stagger); this skill defers motion depth to it.web-taste— building React/Next/Tailwind UI with taste from the ground up (the build counterpart to this review).tailwind-ui-refactor— applying these fixes as Tailwind refactors.ui-design— broader build-time frontend reference (Core Web Vitals, forms, dark mode). Where the two overlap (semantics, contrast, focus, single primary action), reach forui-designwhile authoring anddesign-reviewwhile reviewing.
Reference Files
| File | Description |
|---|---|
| references/_runtime-capture.md | Browser-driven capture playbook (chrome-devtools-mcp via mcporter) |
| references/_sections.md | Category definitions and ordering |
| assets/templates/_template.md | Template for new rules |
| metadata.json | Version and source references |