/design-review

name: design-review
description: "Review a web app or page for visual design quality — layout, typography, spacing, colour, hierarchy, consistency, interaction patterns, and responsive behaviour. Not a UX audit (that checks usability) — this checks whether it looks professional and polished. Produces a design findings report with screenshots. Triggers: 'design review', 'does this look good', 'review the design', 'check the layout', 'is this polished', 'visual review', 'design audit', 'make it look better', 'it looks off'."
compatibility: claude-code-only

Design Review

Review a web app or page for visual design quality. This is not a UX audit (usability, workflow, friction) — this checks whether the design is **professional, consistent, and polished**.

The goal: would a design-conscious person look at this and think "this is well made" or "this looks like a developer designed it"?

When to Use

• Before showing something to a client or team
• When something "looks off" but you can't pinpoint why
• After building a feature, before calling it done
• Periodic quality check on a shipped product
• After a UX audit — this is the visual companion

Browser Tool Detection

Same as ux-audit — Chrome MCP, Playwright MCP, or playwright-cli.

URL Resolution

Same as ux-audit — prefer deployed/live over localhost.

What to Check

1. Layout and Spacing

| Check | Good | Bad | |-------|------|-----| | **Consistent spacing** | Same gap between all cards in a grid, same padding in all sections | Some cards have 16px gap, others 24px. Header padding differs from body | | **Alignment** | Left edges of content align vertically across sections | Heading starts at one indent, body text at another, cards at a third | | **Breathing room** | Generous whitespace around content, elements don't feel cramped | Text touching container edges, buttons crowded against inputs | | **Grid discipline** | Content follows a clear column grid | Elements placed freely, no underlying structure | | **Responsive proportions** | Sidebar/content ratio looks intentional at every width | Sidebar takes 50% on tablet, content is squeezed | | **Vertical rhythm** | Consistent vertical spacing pattern (e.g. 8px/16px/24px/32px scale) | Random spacing: 13px here, 27px there, 8px somewhere else |

2. Typography

| Check | Good | Bad | |-------|------|-----| | **Hierarchy** | Clear visual difference between h1 → h2 → h3 → body | Headings and body text look the same size/weight | | **Line length** | Body text 50-75 characters per line | Full-width text running 150+ characters — hard to read | | **Line height** | Body text 1.5-1.7, headings 1.1-1.3 | Cramped text or excessive line height | | **Font sizes** | Consistent scale (e.g. 14/16/20/24/32) | Random sizes: 15px, 17px, 22px with no relationship | | **Weight usage** | Regular for body, medium for labels, semibold for headings, bold sparingly | Everything bold, or everything regular with no hierarchy | | **Truncation** | Long text truncates with ellipsis, title attribute shows full text | Text overflows container, wraps awkwardly, or is cut off without ellipsis |

3. Colour and Contrast

| Check | Good | Bad | |-------|------|-----| | **Semantic colour** | Using design tokens (bg-primary, text-muted-foreground) | Raw Tailwind colours (bg-blue-500, text-gray-300) | | **Contrast ratio** | Text meets WCAG AA (4.5:1 for body, 3:1 for large text) | Light grey text on white, or dark text on dark backgrounds | | **Colour consistency** | Same blue means the same thing everywhere (primary = action) | Blue means "clickable" in one place and "informational" in another | | **Dark mode** | All elements visible, borders defined, no invisible text | Elements disappear, text becomes unreadable, images look wrong | | **Status colours** | Green=success, yellow=warning, red=error consistently | Green used for both success and "active" with different meanings | | **Colour overuse** | 2-3 colours + neutrals | Rainbow of colours with no clear hierarchy |

4. Visual Hierarchy

| Check | Good | Bad | |-------|------|-----| | **Primary action** | One clear CTA per page, visually dominant | Three equally styled buttons competing for attention | | **Squint test** | Squinting at the page, the most important element stands out | Everything is the same visual weight — nothing draws the eye | | **Progressive disclosure** | Most important info visible, details available on interaction | Everything shown at once — overwhelming | | **Grouping** | Related items are visually grouped (proximity, borders, backgrounds) | Related items scattered, unrelated items touching | | **Negative space** | Intentional empty space that frames content | Empty space that looks accidental (uneven, trapped white space) |

5. Component Consistency

| Check | Good | Bad | |-------|------|-----| | **Button styles** | One primary style, one secondary, one destructive — used consistently | 5 different button styles across the app | | **Card styles** | All cards have the same border-radius, shadow, padding | Some cards rounded, some sharp, some with shadows, some without | | **Form inputs** | All inputs same height, same border style, same focus ring | Mix of heights, border styles, focus behaviours | | **Icon style** | One icon family (Lucide, Heroicons), consistent size and stroke | Mixed icon families, different sizes, some filled some outlined | | **Border radius** | Consistent radius scale (e.g. 4px inputs, 8px cards, 12px modals) | Random radius values: 3px, 7px, 10px, 16px | | **Shadow** | One or two shadow levels used consistently | Every component has a different shadow depth |

6. Interaction Design

| Check | Good | Bad | |-------|------|-----| | **Hover states** | Buttons, links, and clickable cards change on hover | No hover feedback — user unsure what's clickable | | **Focus states** | Keyboard focus visible on all interactive elements | Focus ring missing or invisible against background | | *