pixel-diff

Pixel Diff

Pixel-level comparison of two screenshots, producing a difference visualization image.

When to use

• Comparing a Figma design mockup with a webpage screenshot
• Detecting visual regressions caused by CSS changes
• Tracking UI changes between versions

Prerequisites

• Install Pillow and numpy：pip install Pillow numpy

Usage

python "${CLAUDE_PLUGIN_ROOT}/scripts/pixel-diff.py" <image_a> <image_b> --output diff.png \
  [--threshold 10] [--pass-below 5] [--block-above 15] [--ignore-region x,y,w,h]

The script is in the plugin directory, not in the user's project—the path must use ${CLAUDE_PLUGIN_ROOT}; a relative path will fail to find the file.

Parameters

Parameter	Required	Description
image_a	Yes	Reference image (design mockup)
image_b	Yes	Comparison image (webpage screenshot)
--output	No	Diff image output path (default diff.png）
--threshold	No	Per-pixel color difference sensitivity 0-100 (default 10; lower is stricter). This is "how much color difference counts as different", not an overall tolerance ratio
--pass-below	No	Overall difference below this percentage is judged PASS (default 5)
--block-above	No	Overall difference above this percentage is judged BLOCK (default 15); in between is WARNING
--ignore-region	No	Ignore region x,y,w,h, repeatable—mask out dynamic content such as clocks and carousels
--background	No	Background color for compositing transparent layers (default white）
--highlight-color	No	Diff marker color (default red）

Output

1. diff.png — Diff visualization image (diff regions marked with semi-transparent red)
2. stdout JSON — Diff statistics:

   {
     "total_pixels": 2073600,
     "diff_pixels": 12450,
     "diff_percentage": 0.60,
     "diff_regions": [
       {"x": 100, "y": 200, "width": 300, "height": 50, "label": "region_1"}
     ]
   }
   

Notes

• When sizes differ, it willproportionallyscale to a common width and then crop the height (it will not stretch each axis independently); if the aspect ratios differ too much it will warn—that usually means the two images are not the same screen area at all
• It is best to align sizes at the source: the Figma-exported --scale and the webpage screenshot's device pixel ratio must match
• --threshold is the per-pixel color difference sensitivity: the default 10 filters out subtle color differences such as font anti-aliasing and browser rendering; lowering it to 5 catches finer differences, but false differences will also increase
• Figma exports with transparent backgrounds are automatically composited onto a white background before comparison (can be changed with --background )