Design Review

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:

``bash 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: 

### What's working
- ...

### Critical issues (must fix)
1. ** — **
   Why: ...
   Fix: 

### 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](SKILL.ru.md)

Source & license

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

• Author: AslanMazhidov
• Source: AslanMazhidov/design-review-skill
• License: MIT

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