/design-review

name: design-review
description: "Evaluate and refine UI the way a senior product designer would, visual hierarchy, spacing and rhythm, typographic scale, legibility, information density, alignment, and restraint, then apply the highest-leverage fixes. Use this skill WHENEVER the user says a UI / page / screen / component feels 'clunky', 'packed', 'cramped', 'busy', 'off', 'amateur', 'cluttered', or 'needs polish'; when they ask to 'improve the design / layout / hierarchy / spacing / legibility', 'make this look designed / professional', 'apply design principles', 'clean this up', 'review the design', or want a 'senior designer' / 'senior product designer' pass; and proactively after building any non-trivial UI, to critique and tighten it before moving on. Grounded in the design canon (Dieter Rams, Edward Tufte, the Gestalt principles, the Vignelli Canon, Nielsen's heuristics) and the Refactoring UI playbook. It respects and extends the project's existing brand / design system first, runs a mandatory system coverage inventory (undesigned groups and unspent brand personality are automatic findings, not just visual excess), reviews the whole surface across all states rather than the recent diff, and documents any missing pattern before building it. When a screen 'lacks personality' it benchmarks named personality-forward references (e.g. PostHog, Duolingo) and designs from them rather than rearranging what exists. Works on existing UI code (improves it in place) or on a screenshot / description. Distinct from a usability/UX audit (this is visual / product-design craft) and from code review (this is design, not correctness)."

Design Review: the senior product designer's eye

Evaluate a screen the way a senior product designer does, then apply the highest-leverage fixes. The goal is never decoration. It is to make the screen's **one job** unmistakable, through hierarchy, whitespace, legibility, and restraint. A good pass usually *removes and quiets* more than it adds.

> "Less, but better." (Dieter Rams) · "Above all else show the data." (Edward Tufte)

The one move: emphasize by de-emphasizing

The single most valuable senior instinct: when the important thing doesn't stand out, **don't pile on more emphasis; quiet the things competing with it, or remove them.** A UI that feels "clunky", "packed", or "busy" is almost always *too many equal-weight signals*. The fix is **remove → demote → quiet**, and only rarely *add*. Emphasis is a fixed budget you allocate, not a property you sprinkle: if everything is bold, nothing is.

First, respect the design system

Before touching a single style, find the project's design language and work *inside* it:

• A brand / design-system doc (`brand.md`, `design-system.md`, a Figma/tokens export).
• Design tokens (a Tailwind theme, CSS variables, a spacing/type/color scale).
• Existing components (a `ui/` folder, shared primitives).

Pull type sizes, spacing, color, radii, and shadows from those **defined scales**, never invent a one-off spacing value, a bespoke grey, or a novel button for a single screen. Per-screen invention is how design systems rot (Vignelli's *discipline*; Nielsen's *consistency & standards*). **If a needed pattern genuinely isn't defined, derive it from the system's north-star, write it into the system first, then build it.** If no system exists, establish the minimal one (a spacing scale, a type scale, ~2-3 text weights, one accent) before styling screens.

The system coverage inventory (mandatory, before any lens)

Reading the system for *tokens* is not the same as reading it as a *checklist*. Before diagnosing, **enumerate every visual group on the screen(s)** — header, each form cluster, each card, each list, each footer strip — and for each one, **name the system recipe it instantiates**. Two outcomes are findings, automatically ranked top-3:

• **A group with no recipe** is undesigned UI: either design it into the system first, or it's the

reason the screen "feels thrown together" (a bare form floating outside the card language is the classic case).

• **A declared pattern with zero instances** is unused budget: if the system defines personality

devices (a mascot, hand-scrawl asides, rotation, illustrations) and the screen has none, the brand is silently off. Ask where the personality *should* live on this screen.

This inventory exists because the squint test below only catches **excess** (what stands out that shouldn't); it is structurally blind to **omission** (what was never designed, dead space, missing personality). You need both instruments.

Called by `/flagrare:ui-review`

When the arguments start with `called by /flagrare:ui-review, diagnose only`, the caller owns the browser session, the report and the fixes. Run step 1 (Diagnose) in full, inventory included, with three changes:

• **Work from the screenshots and source the arguments name.** Do not open a new tab or walk the screen again; the walk already captured every state. If a state is missing, say which one, so the caller captures it in its own tab.
• **Skip step 2 (Apply).** Edit nothing. The caller applies fixes after its merged report is on disk.
• **Return the diagnosis, not a hand-off:** the one job and priority order, the inventory (unmapped groups, unspent personality), the squint test result, the subtraction pass, and the ranked top 3 plus polish, each with its location and the principle behind it.

Workflow: diagnose, then apply

1. Diagnose, a *prioritized* critique, not nitpicks

**Review the whole surface, never the diff.** Walk the screen the way a visitor does — every state (empty, partial, full, error), top to bottom — not the way its author does (only the elements recent work touched). Scoping the critique to what you just built is confirmation bias wearing a design hat; the stale header nobody has looked at in weeks is exactly where the findings hide.

Start from the job, not the pixels: 1. **Name the ONE job**