design-review-skill

Design Review — a Claude Code skill

Turns Claude Code into a design reviewer that sees your page instead of guessing from the code.

A skill for Claude Code that opens an HTML file or URL in a real browser through Playwright MCP, captures desktop / tablet / mobile screenshots, audits typography, contrast, rhythm, spacing, hierarchy, color, and alignment by a structured checklist, and proposes (or applies) concrete fixes.

Why this exists

Most AI design feedback is generic — "improve typography hierarchy", "add more whitespace" — because the model never actually sees the page. It reads the code and guesses. This skill enforces a visual step:

1. Open the page in a real headless browser
2. Screenshot at three breakpoints
3. Look at the pixels through Claude's multimodal vision
4. Audit by a structured checklist
5. Produce specific findings with ready-to-apply CSS fixes

The result reads like feedback from a senior designer, not an autocomplete.

Prerequisites

You need Playwright MCP installed and connected to Claude Code:

claude mcp add playwright -- npx -y @playwright/mcp@latest

Verify by running /mcp inside Claude Code — you should see playwright listed.

Installation

Option 1 — one-liner (recommended)

English version:

mkdir -p ~/.claude/skills/design-review
curl -fsSL https://raw.githubusercontent.com/AslanMazhidov/design-review-skill/main/SKILL.md \
  -o ~/.claude/skills/design-review/SKILL.md

Russian version:

mkdir -p ~/.claude/skills/design-review
curl -fsSL https://raw.githubusercontent.com/AslanMazhidov/design-review-skill/main/SKILL.ru.md \
  -o ~/.claude/skills/design-review/SKILL.md

Option 2 — manual

1. Clone the repo:

   git clone https://github.com/AslanMazhidov/design-review-skill.git
   

2. Copy SKILL.md (or SKILL.ru.md) to ~/.claude/skills/design-review/SKILL.md

Verify

Start a new Claude Code session. The skill should appear in your active skills list under the name design-review.

Usage

Inside Claude Code, just say:

Review the design of ./index.html

or invoke explicitly:

/design-review

Claude will:

1. Open the page in a headless browser
2. Take screenshots at 1440 × 900, 768 × 1024, and 375 × 812
3. Look at the screenshots
4. Walk through a structured audit — typography → color → rhythm → composition → responsive → polish
5. Hand you a report with specific findings and ready-to-apply CSS fixes
6. Offer to apply them in place, then re-run the review to confirm the improvements

What you get back

## Design Review: index.html

### What's working
- Strong hierarchy in the hero section: h1 72 px, lead 22 px, body 18 px.
- Consistent 8-pt spacing scale across all sections.

### Critical issues (must fix)
1. **Pricing cards — touch targets too small on mobile**
   Why: CTA buttons are 36 × 36 px; below the 44 × 44 px accessibility minimum.
   Fix:
   ```css
   .pricing-card__cta { min-height: 48px; padding: 12px 24px; }

2. Footer contrast fails WCAG AA Why: #888 on #fff measures 3.1:1; required ≥ 4.5:1 for body. Fix: bump the gray to #595959 (4.6:1) or darker.

Recommended improvements

1. Tighten the hero line-height from 1.3 to 1.1 for a punchier read.
2. ...

Screenshots

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

## Languages

- 🇬🇧 [SKILL.md](SKILL.md) — English
- 🇷🇺 [SKILL.ru.md](SKILL.ru.md) — Russian (original)

## License

[MIT](LICENSE) — free to use, modify, and redistribute.

## Author

Aslan Mazhidov · [github.com/AslanMazhidov](https://github.com/AslanMazhidov)

If this skill makes your day easier, a ⭐ on the repo is appreciated.