Automated pixel-perfect comparison between Figma designs and implementation screenshots. Uses ImageMagick for pixel diffing and Claude Code's multimodal vision for intelligent discrepancy analysis.
Works as both a Skill (auto-detected by Claude) and a Slash Command (
/pixel-check) for guided workflows.
- Exports your Figma design (via Figma MCP or REST API)
- Normalizes resolutions between design and screenshot
- Generates a pixel diff with ImageMagick
- Claude visually analyzes all 3 images (reference, implementation, diff)
- Produces a structured report with severity-classified discrepancies
# Clone into Claude Code skills directory
git clone https://github.com/ketcx/pixel-check.git ~/.claude/skills/pixel-check-skill
# Install the slash command
cp ~/.claude/skills/pixel-check-skill/pixel-check-skill/commands/pixel-check.md ~/.claude/commands/pixel-check.md# Clone into your project's .claude directory
git clone https://github.com/ketcx/pixel-check.git .claude/skills/pixel-check-skill
# Install the slash command
cp .claude/skills/pixel-check-skill/pixel-check-skill/commands/pixel-check.md .claude/commands/pixel-check.mdRestart Claude Code after installation. The skill loads automatically.
git clone https://github.com/ketcx/pixel-check.git ~/.claude/skills/pixel-check-skill && cp ~/.claude/skills/pixel-check-skill/pixel-check-skill/commands/pixel-check.md ~/.claude/commands/pixel-check.mdThe skill auto-detects missing dependencies and asks permission to install them.
| Dependency | Required | Install |
|---|---|---|
| ImageMagick | Yes | brew install imagemagick |
| curl | Yes | brew install curl |
| Python 3 | Yes | brew install python3 |
| Knox | No | go install github.com/pinterest/knox/cmd/knox-client@latest |
| Node.js (npx) | No | brew install node |
| Figma MCP | No | See Figma Setup |
If Figma MCP is not configured, you can provide a local reference image instead.
/pixel-check
Claude will guide you through:
- Dependency check (installs missing with your permission)
- Provide your implementation screenshot
- Provide a Figma URL or local reference image
- Automated comparison and analysis
- Structured report with actionable recommendations
"Compare this screenshot against the Figma design"
"Check if my implementation matches the mockup"
"Run a pixel-perfect validation on homepage.png vs the Figma link"
# Check dependencies
bash pixel-check-skill/scripts/check_deps.sh
# Compare two images directly
bash pixel-check-skill/scripts/compare.sh design.png screenshot.png ./output
# Fetch a Figma frame as PNG (token resolved via Knox or env var)
bash pixel-check-skill/scripts/fetch_figma.sh "https://www.figma.com/design/ABC/Name?node-id=42-1337" reference.png 2
# Generate report
python3 pixel-check-skill/scripts/report.py \
--reference reference.png \
--implementation screenshot.png \
--diff diff.png \
--rmse "1842.17 (0.0281)" \
--output report.md# Pixel-Perfect Validation Report
**Date:** 2026-03-05 14:30
**Figma:** https://www.figma.com/design/ABC123/MyProject?node-id=42-1337
**Screenshot:** ./screenshots/homepage-chrome.png
**RMSE:** 1842.17 (0.0281)
**Result:** FAIL (1 BLOCKER)
## Summary
Implementation is 97% faithful to design. 1 blocker in hero section
spacing, 3 minor warnings in shadows and font weights.
## Discrepancies
| # | Element | Severity | Design | Implementation | Recommendation |
|---|--------------|------------|--------|----------------|-------------------------|
| 1 | Hero padding | BLOCKER | 64px | 48px | Change py-12 to py-16 |
| 2 | Card shadow | WARNING | 0 4 6 | 0 2 4 | Use shadow-md |
| 3 | Font weight | WARNING | 600 | 500 | Use font-semibold |
| 4 | Border radius| ACCEPTABLE | 12px | 12px | Subpixel rendering diff |
- Log in to Figma
- Click your profile icon (top-left) and select Settings
- Scroll down to Personal access tokens
- Click Generate new token
- Give it a descriptive name (e.g.
pixel-check) - Set the expiration as needed (or no expiration for personal use)
- For scopes, grant File content → Read only (minimum required)
- Click Generate token
- Copy the token immediately — it starts with
figd_and is only shown once
Once you have the token, store it using one of the options below.
Store the token securely with Knox:
echo -n "figd_xxxxx" | knox create pixelcheck:figmatokenThe scripts automatically retrieve it at runtime. No env vars needed.
To rotate the token:
echo -n "figd_new_token" | knox add pixelcheck:figmatoken
knox promote pixelcheck:figmatokenexport FIGMA_ACCESS_TOKEN="figd_xxxxx"The fetch_figma.sh script resolves the token in this order:
- Knox —
knox get pixelcheck:figmatoken - Env var —
FIGMA_ACCESS_TOKEN
If neither is available, the script exits with instructions.
For automatic Figma design export within Claude Code, configure the Figma MCP.
Add to .claude/settings.json or .mcp.json:
{
"mcpServers": {
"figma": {
"command": "npx",
"args": ["-y", "@anthropic/figma-mcp-server"],
"env": {
"FIGMA_ACCESS_TOKEN": "figd_xxxxx"
}
}
}
}Without Figma MCP, you can still use the skill via fetch_figma.sh with Knox/env token, or provide a local reference image.
| Metric | PASS | WARNING | FAIL |
|---|---|---|---|
| RMSE (normalized) | < 0.03 | 0.03 - 0.05 | > 0.05 |
| BLOCKERs | 0 | 0 | >= 1 |
| WARNINGs | 0-2 | 3-5 | > 5 |
pixel-check-skill/
SKILL.md # Skill definition (auto-detected by Claude)
scripts/
check_deps.sh # Dependency checker & installer
compare.sh # ImageMagick normalize + compare
fetch_figma.sh # Figma API image export (fallback)
report.py # Markdown report generator
commands/
pixel-check.md # Slash command definition
- Font rendering: Browsers render text differently than Figma. Antialiasing diffs are classified as ACCEPTABLE if font and weight are correct.
- Responsive: Screenshot viewport must match the Figma frame. Mismatched viewports produce misleading diffs.
- Dynamic content: User photos, avatars, or API-driven content won't match. Use identical mock data.
- Figma export fidelity: API exports may differ slightly from the Figma editor (especially blur/shadow effects).
MIT