/design-review

A Claude Code skill that reviews your frontend UI like a design director — not a linter.

Screenshots your page at multiple viewports, extracts your project's design system from code, applies opinionated taste rules, and produces a severity-ranked report with file:line references and specific fix suggestions.

What it does

Your page → Screenshot (3 viewports) → Design system extraction → Taste review → Scored report

Phase 1: EXTRACT — Reads your CSS variables, Tailwind config, DESIGN.md, and existing component patterns to understand what "correct" looks like for your project.

Phase 2: CAPTURE — Screenshots at desktop (1440px), tablet (768px), and mobile (375px). Extracts actual computed styles via JavaScript to see what's rendering, not just what's in source.

Phase 3: REVIEW — Evaluates hierarchy, typography, color, spacing, component consistency, responsive behavior, and overall polish against your design system and a set of hard-coded taste rules.

Phase 4: REPORT — Outputs severity-ranked findings (Critical / High / Medium / Low / Good) with CSS selectors, file paths, and fix suggestions. Scores the page out of 10. Lists quick wins.

Install

Option A: Claude Code plugin

cd your-project
claude plugins add /path/to/design-review

Option B: Copy the skill

Copy skills/design-review/SKILL.md into your project's .claude/skills/ directory or your global ~/.claude/skills/ directory.

Option C: npx (if published)

npx skills add Bbasche/design-review

Usage

/design-review https://localhost:3000/payroll

Focused reviews

/design-review typography          # Type scale, font pairing, readability
/design-review color               # Palette, contrast, semantic color usage
/design-review spacing             # Grid alignment, rhythm, density
/design-review responsive          # All 3 viewports, stacking, touch targets
/design-review consistency         # Component uniformity across the page
/design-review quick               # Top 5 findings, no extraction phase

Figma comparison

/design-review vs https://figma.com/design/abc123/MyDesign?node-id=1:2

Compares your live implementation against the Figma spec, reporting color, typography, spacing, and layout discrepancies.

What it catches

AI slop (flags these)

• Generic font stacks (Inter/Roboto/Arial as the only design choice)
• Purple gradients on white backgrounds
• Uniform card grids with no hierarchy
• Evenly-distributed rainbow palettes
• Meaningless motion and shadow overload
• Every button looking the same

Good design (rewards these)

• Clear visual hierarchy at a glance
• Intentional typography pairing
• Controlled color — 1-2 accents used surgically
• Consistent spacing rhythm on a base unit
• Context-appropriate density
• Subtle depth (shadows at 4-8% opacity)
• Empty states that help
• Responsive layouts that re-compose, not just squish

Requirements

Works best with:

• Chrome DevTools MCP — for screenshots and computed style extraction
• Figma MCP (optional) — for design spec comparison mode

Falls back gracefully:

• Without Chrome DevTools MCP, uses computer-use screenshot or asks for manual screenshots
• Without Figma MCP, skips comparison mode
• Design system extraction always works via file reading (Grep/Glob/Read)

Example output

# Design Review: /payroll

## Design System Summary
- Colors: PopPay Green #007A4D, Gold #FFB81C, Emerald #059669, SA Red #DE3831, SA Blue #002395
- Typography: Inter, 14px base, 8px spacing grid
- Radius: 10px cards, 6px inputs, 999px badges
- Shadows: sm (barely visible), md (hover), lg (modals)

## Overall Impression
The page has strong bones — clear section hierarchy and consistent card patterns.
Typography scale could be tighter and the button hierarchy needs work in the pay run detail area.

## Score: 7/10

## Findings

### HIGH
- **Too many secondary buttons in pay run actions** — `.card:nth-child(4) .btn-secondary`
  6 secondary buttons in a row with no visual grouping creates decision paralysis.
  → Group into primary lifecycle (Confirm/Pay) and secondary ops (Payslips/Export) with a visual divider.

### MEDIUM
- **Metric cards lack top-border accent** — `Payroll.tsx:298`
  Dashboard page uses colored top borders on KPI cards. Payroll metrics are flat.
  → Add `borderTop: 3px solid {accent}` to match Dashboard pattern.

### GOOD
- **Section headers with eyebrow labels** — consistent pattern across all sections.
  Preserves clear information architecture. Keep this.

Taste rules

The skill applies 50+ specific rules across typography, color, spacing, shadows, button hierarchy, and responsive behavior. Rules are hard-coded opinions, not configurable — the point is to have taste, not to be flexible.

Some examples:

• "If you can immediately see the shadow without looking for it, it's too heavy"
• "The most refined black isn't #000000 — it's #1A1A1A"
• "If there are more than 2 primary buttons visible at once, the hierarchy is broken"
• "Card padding: 16-24px. Never 10px or 30px."
• "Uppercase text MUST have positive letter-spacing"

Full rules are in the SKILL.md.

Prior art and credits

Built on research from:

• Anthropic's frontend-design skill — anti-slop rules baseline
• bitjaru/styleseed — 69 opinionated visual design rules
• VoltAgent/awesome-design-md — DESIGN.md format and schema
• twostraws/SwiftUI-Agent-Skill — mistake-targeting pattern, partial review modes
• Shpigford/skills/feature-image — brand extraction methodology
• dembrandt/dembrandt — computed style extraction approach
• Agentation — selector-to-code mapping pattern

License

MIT