Design Review Skill

Turns Claude into a design reviewer that sees the result instead of guessing from the code.

When to invoke

The user asks to review an HTML page, landing, or artifact
After generating new HTML — proactively offer a review
The user complains that something looks "off", "ugly", or "broken"

Dependencies

Playwright MCP (@playwright/mcp) must be installed and connected. Verify by checking for tools prefixed with mcp__playwright__*.
If Playwright MCP is unavailable — tell the user and offer to install it:
```
claude mcp add playwright -- npx -y @playwright/mcp@latest
```

Arguments

The skill accepts:

A local file path (for example ./index.html or ~/site/index.html) — open via a file:// URL
A URL (http://... or https://...) — open as-is
If nothing is passed — ask the user for a path or URL before continuing

Workflow

1. Open the page

Use mcp__playwright__browser_navigate to load the page.

2. Capture screenshots at three widths

Use mcp__playwright__browser_resize followed by mcp__playwright__browser_take_screenshot:

Desktop: 1440 × 900
Tablet: 768 × 1024
Mobile: 375 × 812

Save the screenshots into a .design-review/ folder next to the file under review, with clear names (desktop.png, tablet.png, mobile.png).

After capturing them — read them back through the Read tool to actually look at the result. This step is critical: without reading the screenshots, you are not seeing the design.

3. Snapshot the DOM

Use mcp__playwright__browser_snapshot to grab the accessibility tree — it exposes hierarchy and semantics without the noise of raw HTML.

4. Audit by checklist

Walk through these axes; for each, log concrete findings (with section and coordinates, not vague observations):

Typography

Size hierarchy (h1 → h2 → h3 → body) — is the contrast clear?
Line-height for long-form text (target 1.4–1.7)
Line length (50–75 characters is optimal)
Font pairing — any conflicts?

Color & contrast

Text-to-background contrast (WCAG AA: 4.5:1 for body, 3:1 for large text)
Palette — no more than 3–4 accents
States (hover, active, disabled) — are they visible?

Rhythm & space

Vertical rhythm between sections
Section padding — anything cramped?
Spacing scale — multiples of 8 / 16 / 24 / 32 / 48 / 64?
Breathing room around CTAs?

Composition & hierarchy

What hits the eye first? Is that the primary message?
F-pattern / Z-pattern legible?
Grouping by proximity working?
Alignment — is the grid respected?

Responsive

On mobile, does anything overflow the viewport?
Mobile font sizes readable (≥ 14–16 px for body)?
Touch targets ≥ 44 × 44 px?
Hero not cropped on mobile?

Polish

Border-radius consistent?
Shadows — soft and natural, not flat?
Icons consistent in style and weight?
Images sharp, not stretched?

5. Deliver the report

## Design Review: <file>

### What's working
- ...

### Critical issues (must fix)
1. **<section> — <issue>**
   Why: ...
   Fix: <concrete CSS or HTML>

### Recommended improvements
1. ...

### Screenshots
- Desktop: .design-review/desktop.png
- Tablet: .design-review/tablet.png
- Mobile: .design-review/mobile.png

6. Offer to apply fixes

At the end, ask: "Apply the critical fixes now?"

If yes — walk through the list, edit the source via the Edit tool, then re-run /design-review on the same file to verify the result.

Rules

Never guess from code. Always open the page in the browser and look at the screenshots. The skill is useless without the visual step.
Be specific, not vague. Not "bad typography" — but "h1 in the hero is 32 px while body is 18 px; the hierarchy is weak, bump h1 to at least 56 px".
Respect the user's design system. Before editing, check for design tokens or variables already in the project (CSS custom properties, theme files, etc.) and reuse them instead of inventing new values.
Don't break the existing theme. If the page uses a specific palette or aesthetic, fixes should land inside it.
After any fix — always re-run the review on the same file. One pass rarely gets to perfect.

Example invocation

/design-review ./index.html

or just:

/design-review

(then ask the user for the path)

🇷🇺 Russian version: SKILL.ru.md

design-review