UI Design Review skill for Codex

A good review is evidence-based and actionable: every finding points to a specific element, explains what it breaks for the viewer, and proposes a fix precise enough to implement (a value, a token, a component swap). Taste without evidence is noise; twenty unranked nits is also noise.

Inputs to collect first

• What the screen is for: the primary task and the user. If unknown, infer from content and state the assumption.
• Live URL or dev-server command (check AGENTS.md and package.json scripts), or screenshots supplied by the user.
• The design system in use, if any: tokens, components/ui, Storybook. Findings should cite tokens (“use --space-6”), not raw values, when a system exists.
• Scope: one screen, a flow, or the whole app. Default to the screens the user named.

Workflow

- [ ] 1. Capture the screens at real viewports and states
- [ ] 2. First-impression pass (5 seconds per screen)
- [ ] 3. Inventory computed styles to find drift
- [ ] 4. Lens-by-lens review
- [ ] 5. Rate severity and cut to what matters
- [ ] 6. Write the report; optionally implement the top fixes

1. Capture

npx playwright screenshot --full-page --viewport-size "1440,900" http://localhost:3000/settings .shots/settings-1440.png
npx playwright screenshot --full-page --viewport-size "390,844" http://localhost:3000/settings .shots/settings-390.png

Browsers need npx playwright install chromium once (network). Also capture the states a static screenshot misses: empty, loading, error, long content (a 60-character name, a 4-digit count), hover and focus. If the app needs login, ask the user for a seeded test account or a dev bypass; never type real credentials.

2. First impression

Look at each screenshot for five seconds, then write down:

• Where the eye landed first, second and third. Is that the intended order?
• What the screen is for, in one sentence. If you cannot say, hierarchy is failing.
• The overall feel in three words. Compare with the product’s intent.

Then do a squint pass: ignore text, see only blocks of weight. The primary action should be one of the two heaviest shapes on screen.

3. Inventory computed styles

Drift is easier to prove with numbers than adjectives. Run this in the page (DevTools console, or page.evaluate in a Playwright script):

const tally = (prop) => {
  const m = new Map();
  for (const el of document.querySelectorAll('body *')) {
    if (!el.checkVisibility?.()) continue;
    const v = getComputedStyle(el)[prop];
    m.set(v, (m.get(v) ?? 0) + 1);
  }
  return [...m].sort((a, b) => b[1] - a[1]);
};
console.table({
  fontSize: tally('fontSize').length,
  fontWeight: tally('fontWeight').length,
  color: tally('color').length,
  borderRadius: tally('borderRadius').length,
  boxShadow: tally('boxShadow').length,
});
console.log(tally('fontSize'), tally('borderRadius'), tally('color'));

Rough thresholds for a single screen: more than 8 font sizes, 4 weights, 4 radii, 3 shadows or 12 text colors means the system is drifting. Values used once or twice are usually the bugs (a stray 13px, a #333 beside #334155).

4. Lens-by-lens review

Work through each lens and note findings with the element and evidence.

Hierarchy

• One primary action per view; secondary actions visibly quieter (outline or text style).
• Headings differ from body by at least two of: size, weight, color, spacing.
• Related information grouped by proximity; group gaps larger than item gaps (the gap between groups at least 1.5x to 2x the gap inside them).

Spacing and alignment

• All spacing from one scale; flag off-scale values (13px, 22px).
• Left edges align across sections; check text baselines in rows with icons.
• Padding inside containers consistent per component type; horizontal padding usually greater than or equal to vertical in buttons and inputs.
• Optical alignment: icons, play triangles and quote marks often need 1–2 px nudges.

Typography

• Body 16 px or larger on content screens (14 px acceptable in dense tools), line height 1.4–1.6, measure under ~75ch.
• No more than two families; numbers in tables use tabular-nums and right alignment.
• Truncation is deliberate (ellipsis with a tooltip or wrap), not clipped text.

Color

• Accent reserved for action and selection; flag decorative use that competes.
• Text contrast 4.5:1 (3:1 for 18.66 px bold or 24 px and up); component boundaries and focus rings 3:1 against adjacent colors.
• Status colors are not the only signal: pair with icon or label.

Consistency

• The same thing looks the same everywhere: buttons, inputs, cards, tags, dates.
• One icon family and stroke; icon sizes match adjacent text.
• Copy conventions: sentence case vs title case, date formats, verb choice on buttons.

States and edges

• Hover, :focus-visible, active, disabled and loading for every control.
• Empty, error and overflow states designed, not default.
• Mobile: tap targets at least 24x24 px (WCAG 2.2 minimum) and ideally 44x44; no horizontal scroll; sticky elements do not cover content.

Polish

• Image cropping and aspect ratios consistent; no stretched images.
• Borders and dividers not doubled where two components meet.
• Shadows share one light direction; radii nested correctly (inner radius = outer radius minus padding).

5. Severity and cut

Severity	Meaning	Example
P1	Blocks the task or misleads	Primary action invisible below fold on mobile; destructive button styled as primary
P2	Slows the user or erodes trust	Two competing primary buttons; inconsistent form field styles
P3	Polish	2 px misalignment; off-scale gap

Report all P1s, the P2s, and at most ten P3s grouped by theme. If findings overlap (eight spacing nits from one missing scale), report the root cause once.

6. Fixes

Each finding gets a fix specific enough to implement. Prefer system-level fixes:

Finding	Weak fix	Strong fix
Cramped cards	“Add more space”	Card padding --space-4 to --space-6; gap between cards --space-6
Weak heading	“Make it pop”	h2 from 18/500 to 24/650, margin-bottom --space-3, color --text-strong
Button chaos	“Make consistent”	Replace 5 local button styles with <Button variant>; list files

If the user asked for fixes too, implement P1s and P2s, re-capture, and show before and after screenshots side by side. Keep changes scoped; propose system refactors separately.

Hard rules

• Review what is on screen, not what the code intends; always look at a rendered capture.
• Do not mix an accessibility audit into a design review silently: flag contrast and focus issues found, and point to wcag-accessibility-audit for full coverage.
• Do not restyle the product to your taste; review against its own direction and system.
• Praise what works in one or two lines so the team knows what to keep.

Output contract

## UI review: <screen or flow> (<date>)

**Purpose as read:** <one sentence>  **First impression:** <three words>
**Eye path:** 1. <element> 2. <element> 3. <element> (intended: <...>)
**Style inventory:** 11 font sizes, 6 radii, 4 shadows, 15 text colors (drift: high)

### P1
1. **<title>** at <element/selector, viewport>. Evidence: <screenshot/measurement>.
   Impact: <what the user experiences>. Fix: <specific change>.

### P2
...

### P3 (grouped)
- Spacing: <root cause + list>
- Alignment: ...

### Keep
- <what works>

**Screenshots:** .shots/settings-1440.png, .shots/settings-390.png