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

bash

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

Review Page

Review a page against design specs:

bash

# 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:

bash

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

What happens:

•Browser opens with the page
•Automatic pre-scan runs immediately—scans buttons, links, inputs, images, forms, and more
•Visual badges appear on elements with issues (numbered, color-coded by severity)
•Press N to navigate through detected issues one by one
•Hover any element to see its compliance status
•Click elements for detailed compliance reports
•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:

bash

# 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:

bash

# 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)

bash

# 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

bash

# 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

json

{
  "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

json

{
  "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:

markdown

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

Pillar	Focus
Frictionless Insight to Action	Task efficiency, clear navigation, single primary actions
Progressive Clarity	Smart defaults, progressive disclosure, contextual help
Quality Craft	Accessibility, contrast, keyboard navigation, touch targets
Trustworthy Building	AI disclaimers, error handling, secure defaults

Session Artifacts

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

code

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:

markdown

# 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:

code

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

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

Typical Workflow

•

Run review to find issues:

bash

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

•
Review DESIGN-REVIEW-TASKS.md for fix priorities
•
Fix issues in code
•
Re-run review to verify fixes

Integration with Other Skills

Skill	Integration
`agent-eyes`	Screenshots, accessibility scans, DOM analysis
`agent-canvas`	Interactive element picker (review mode)
`canvas-verify`	Visual comparison logic (shared patterns)

Comparison Methods

The compare command supports three comparison methods:

Method	Description	Use Case
`pixel`	Fast pixel-by-pixel diff	Quick checks, exact matches
`ssim`	Structural Similarity Index	Perceptual comparison, minor shifts OK
`hybrid` (default)	Both methods combined	Comprehensive analysis

Diff Styles

Style	Description
`overlay`	Highlights diff regions on current screenshot
`sidebyside`	Shows reference, diff, and current side by side
`heatmap`	Color-coded intensity of changes