# Design Review

> 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…

- **Type:** Skill
- **Install:** `agentstack add skill-jezweb-claude-skills-design-review`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [jezweb](https://agentstack.voostack.com/s/jezweb)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [jezweb](https://github.com/jezweb)
- **Source:** https://github.com/jezweb/claude-skills/tree/main/plugins/frontend/skills/design-review
- **Website:** https://jezweb.com.au

## Install

```sh
agentstack add skill-jezweb-claude-skills-design-review
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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 |
| **Active states** | Nav items, tabs, sidebar links show current selection | Active item looks the same as inactive |
| **Transitions** | Subtle transitions on hover/focus (150-200ms ease) | No transitions (jarring) or slow transitions (laggy) |
| **Loading indicators** | Skeleton screens or spinners during async operations | Content pops in without warning, layout shifts |
| **Disabled states** | Disabled elements are visually muted, cursor changes | Disabled buttons look clickable, no cursor change |

### 7. Responsive Quality

| Check | Good | Bad |
|-------|------|-----|
| **Mobile nav** | Clean hamburger/sheet menu, easy to tap | Desktop nav squished into mobile, tiny tap targets |
| **Image scaling** | Images fill containers proportionally | Images stretched, cropped badly, or overflowing |
| **Table responsiveness** | Horizontal scroll on mobile, or stack to cards | Table wider than screen with no way to see columns |
| **Touch targets** | At least 44x44px on mobile | Tiny links, close buttons, checkboxes |
| **Tablet** | Layout works at 768px (not just desktop and phone) | Layout breaks at tablet widths, awkward gaps |

## Severity Guide

| Level | Meaning | Example |
|-------|---------|---------|
| **High** | Looks broken or unprofessional | Invisible text in dark mode, buttons different heights inline |
| **Medium** | Looks unpolished | Inconsistent spacing, mixed icon styles, truncation without ellipsis |
| **Low** | Nitpick | 1-2px alignment, slightly different border-radius, shadow too strong |

## Output

Write findings to `.jez/artifacts/design-review.md`:

```markdown
# Design Review: [App Name]
**Date**: YYYY-MM-DD
**URL**: [url]

## Overall Impression
[1-2 sentences — professional / unpolished / inconsistent / clean]

## Findings

### High
- **[issue]** at [page/component] — [what's wrong] → [fix]

### Medium
- **[issue]** at [page/component] — [what's wrong] → [fix]

### Low
- **[issue]** — [description]

## What Looks Good
[Patterns that are well-executed and should be preserved]

## Top 3 Fixes
1. [highest visual impact change]
2. [second]
3. [third]
```

Take screenshots of findings where the issue is visual (most of them).

## Tips

- Check dark mode AND light mode — most issues appear in one but not the other
- The squint test is the fastest way to find hierarchy problems
- Component inconsistency is the most common issue in dev-built UIs
- "Looks off" usually means spacing — check margins and padding first
- If you can't identify the issue, compare to a well-designed app in the same category

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [jezweb](https://github.com/jezweb)
- **Source:** [jezweb/claude-skills](https://github.com/jezweb/claude-skills)
- **License:** MIT
- **Homepage:** https://jezweb.com.au

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-jezweb-claude-skills-design-review
- Seller: https://agentstack.voostack.com/s/jezweb
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.