Image Compare

Compare two images pixel-by-pixel. Returns a diff count, mismatch percentage, and generates a diff image highlighting the differences in red.

When to Use

• Comparing an implementation screenshot against the original design
• Spotting visual regressions between two versions of a page
• Verifying that a UI matches a Figma export

How It Works

1. Both images are loaded and resized to match dimensions (uses the smaller of the two)
2. pixelmatch compares every pixel and flags differences above a configurable threshold
3. Returns mismatch stats and writes a diff image showing changes in red

Usage

bash <skill-path>/scripts/image-compare.sh <image1> <image2> [diff-output.png] [threshold]

Arguments:

• image1 — First image path (required)
• image2 — Second image path (required)
• diff-output.png — Path to write the diff image (optional, defaults to ./diff.png)
• threshold — Pixel matching threshold 0-1, lower is stricter (optional, defaults to 0.1)

Examples:

# Compare a design against implementation
bash <skill-path>/scripts/image-compare.sh design.png screenshot.png

# Compare with custom threshold and output path
bash <skill-path>/scripts/image-compare.sh before.png after.png ./changes.png 0.05

Output

{
  "totalPixels": 921600,
  "differentPixels": 4523,
  "mismatchPercentage": 0.49,
  "dimensions": { "width": 1280, "height": 720 },
  "diffImage": "./diff.png",
  "threshold": 0.1
}

Present Results to User

After comparing, present a summary:

Comparison: design.png vs screenshot.png

Mismatch: 0.49% (4,523 pixels out of 921,600)
Diff image saved to: ./diff.png

The images are nearly identical. Differences are highlighted in red in the diff image.

Interpret the percentage:

• < 0.1% — Essentially identical
• 0.1% - 1% — Minor differences, likely anti-aliasing or sub-pixel rendering
• 1% - 5% — Noticeable differences, worth reviewing
• > 5% — Significant visual changes

Troubleshooting

Different sized images — The script automatically resizes both images to the smaller dimensions. For best results, use images of the same size.

Too many false positives — Increase the threshold (e.g., 0.2). Anti-aliasing differences are common between browsers.