Design Review

Design Review

Spec-driven design quality assurance for web applications. Reviews UI implementations against customizable design specs, generates annotated screenshots with issues marked, and creates actionable task lists.

Prerequisites

• Python 3.10+
• uv package manager
• Playwright browsers: playwright install chromium

Commands

SKILL_DIR=".claude/skills/design-review/scripts"

Review Page

Review a page against design specs:

# Full page review with default spec
uv run $SKILL_DIR/design_review.py review http://localhost:3000

# Review with custom spec
uv run $SKILL_DIR/design_review.py review http://localhost:3000 --spec my-project.md

# Review specific element
uv run $SKILL_DIR/design_review.py review http://localhost:3000 --selector ".hero-section"

# Generate annotated screenshot
uv run $SKILL_DIR/design_review.py review http://localhost:3000 --annotate

# Generate task file for fixes
uv run $SKILL_DIR/design_review.py review http://localhost:3000 --generate-tasks

# Generate markdown export with CSS selectors
uv run $SKILL_DIR/design_review.py review http://localhost:3000 --markdown

# Combine annotations and markdown export
uv run $SKILL_DIR/design_review.py review http://localhost:3000 --annotate --markdown

Interactive Mode (Default)

Explore pages with automatic issue detection and visual badges:

uv run $SKILL_DIR/design_review.py interactive http://localhost:3000

What happens:

1. Browser opens with the page
2. Automatic pre-scan runs immediately—scans buttons, links, inputs, images, forms, and more
3. Visual badges appear on elements with issues (numbered, color-coded by severity)
4. Press N to navigate through detected issues one by one
5. Hover any element to see its compliance status
6. Click elements for detailed compliance reports
7. Close browser → report.json generated with all findings

Badge colors:

• 🔴 Red = blocking/critical issues
• 🟠 Orange = major issues
• 🟡 Yellow = minor issues

This is the default mode. Any query without explicit "review", "audit", or "compare" keywords will open interactive mode.

Compare Against Reference

Compare the current page against a reference image:

# Compare against reference image (from imgs/ directory)
uv run $SKILL_DIR/design_review.py compare http://localhost:3000 --reference homepage.png

# Compare with full path
uv run $SKILL_DIR/design_review.py compare http://localhost:3000 --reference imgs/homepage.png

# Customize thresholds
uv run $SKILL_DIR/design_review.py compare http://localhost:3000 \
  --reference homepage.png \
  --threshold 3.0 \
  --ssim-threshold 0.98

# Different diff visualization styles
uv run $SKILL_DIR/design_review.py compare http://localhost:3000 \
  --reference homepage.png \
  --diff-style sidebyside  # or overlay, heatmap

# Generate task file for differences
uv run $SKILL_DIR/design_review.py compare http://localhost:3000 \
  --reference homepage.png \
  --generate-tasks

# Generate markdown export with CSS selectors
uv run $SKILL_DIR/design_review.py compare http://localhost:3000 \
  --reference homepage.png \
  --markdown

Options:

• --reference, -r: Reference image path (checks imgs/, cwd, or absolute)
• --threshold, -t: Pixel diff threshold % (default: 5.0)
• --ssim-threshold: SSIM similarity threshold (default: 0.95)
• --diff-style: Visualization style (overlay, sidebyside, heatmap)
• --viewport-only: Capture only viewport (not full page)
• --generate-tasks: Generate DESIGN-REVIEW-TASKS.md
• --markdown: Generate issues.md with CSS selectors for easy fixes

Standalone Image Comparator

For direct image-to-image comparison:

# Compare two images directly
uv run $SKILL_DIR/image_comparator.py reference.png current.png --output diff.png

# Use SSIM only
uv run $SKILL_DIR/image_comparator.py reference.png current.png --method ssim

# JSON output
uv run $SKILL_DIR/image_comparator.py reference.png current.png --json

Figma Integration (Planned)

# Compare with Figma (requires Figma MCP - not yet implemented)
uv run $SKILL_DIR/design_review.py compare http://localhost:3000 \
  --figma "https://figma.com/file/xxx" \
  --frame "Homepage"

Until Figma MCP is available, export frames as PNG and place them in imgs/.

Manage Specs

# List available specs
uv run $SKILL_DIR/design_review.py specs --list

# Validate a spec file
uv run $SKILL_DIR/design_review.py specs --validate my-project.md

# Show spec details
uv run $SKILL_DIR/design_review.py specs --show default.md

Output Format

All commands return JSON:

Review Output

{
  "ok": true,
  "summary": {
    "blocking": 1,
    "major": 3,
    "minor": 2
  },
  "issues": [
    {
      "id": 1,
      "checkId": "color-contrast",
      "pillar": "Quality Craft",
      "severity": "major",
      "element": ".subtitle-text",
      "cssSelector": "main > section.hero > p.subtitle-text",
      "description": "Contrast ratio 3.2:1 (minimum 4.5:1 required)",
      "recommendation": "Darken text to #595959 or darker"
    }
  ],
  "sessionId": "review_20260122...",
  "artifacts": {
    "screenshot": ".canvas/reviews/review_.../screenshot.png",
    "annotated": ".canvas/reviews/review_.../annotated.png",
    "markdown": ".canvas/reviews/review_.../issues.md",
    "tasks": "DESIGN-REVIEW-TASKS.md"
  }
}

Compare Output

{
  "ok": true,
  "match": false,
  "url": "http://localhost:3000",
  "reference": "imgs/homepage.png",
  "comparison": {
    "method": "hybrid",
    "pixelDiffPercent": 12.5,
    "ssimScore": 0.92,
    "pixelThreshold": 5.0,
    "ssimThreshold": 0.95,
    "sizeMismatch": false
  },
  "diffRegions": [
    {
      "x": 100,
      "y": 200,
      "width": 300,
      "height": 50,
      "pixelCount": 2500,
      "severity": "moderate"
    }
  ],
  "artifacts": {
    "screenshot": ".canvas/reviews/review_.../screenshot.png",
    "reference": "imgs/homepage.png",
    "diff": ".canvas/reviews/review_.../diff.png",
    "annotated": ".canvas/reviews/review_.../annotated.png",
    "markdown": ".canvas/reviews/review_.../issues.md"
  }
}

Specs

Design specs are Markdown files with YAML frontmatter:

---
name: My Project Spec
version: "1.0"
extends: default.md
---

# My Project Spec

## Brand Guidelines

### Checks

#### brand-colors
- **Severity**: major
- **Description**: Uses approved brand colors
- **How to check**: Compare against approved color list

See specs/README.md for full format documentation.

Default Spec Pillars

The default spec (specs/default.md) includes:

Session Artifacts

Reviews are saved to .canvas/reviews/<sessionId>/:

session.json       # Full event log + metadata
report.json        # Structured issue data
screenshot.png     # Original screenshot
annotated.png      # Screenshot with redlines (for issues)
diff.png           # Visual diff (for compare mode)
issues.md          # Markdown export with CSS selectors (--markdown)

Markdown Export

The --markdown flag generates an issues.md file with:

• Summary header with URL, timestamp, spec name, and issue counts
• Detailed issue tables with severity, pillar, check ID, and CSS selectors
• A "Quick Fix Reference" section with all CSS selectors for easy copying

Example output:

# Design Review Issues

**URL**: http://localhost:3000  
**Reviewed**: 2026-01-23T17:20:00  
**Spec**: default.md  
**Total Issues**: 3 (1 major, 2 minor)

---

## Issue #1: Contrast ratio 3.2:1 (minimum 4.5:1...

| Property | Value |
|----------|-------|
| **Severity** | major |
| **Pillar** | Quality Craft |
| **Check** | color-contrast |
| **CSS Selector** | `main > section.hero > p.subtitle-text` |

**Description**: Contrast ratio 3.2:1 (minimum 4.5:1 required)

**Recommendation**: Darken text to #595959 or darker

---

## Quick Fix Reference

Copy these selectors for your AI assistant:

\`\`\`
main > section.hero > p.subtitle-text
header > nav > a.nav-link
footer > div.copyright
\`\`\`

The annotated screenshot legend also displays CSS selectors for each issue when --annotate is used.

Reference Images

Place reference images in imgs/ for comparison:

.claude/skills/design-review/imgs/
├── README.md
├── homepage.png
├── settings.png
└── mobile-nav.png

Supported formats: PNG (recommended), JPG, WebP.

Typical Workflow

1. Run review to find issues:

   uv run $SKILL_DIR/design_review.py review http://localhost:3000 --generate-tasks
   

2. Review DESIGN-REVIEW-TASKS.md for fix priorities

3. Fix issues in code

4. Re-run review to verify fixes

Integration with Other Skills

Comparison Methods

The compare command supports three comparison methods:

Diff Styles