visual-diff

Compare replica screenshots against references to compute pixel diffs and fidelity scores.

Updated Apr 10, 2026
One-click install
npx skills add https://github.com/imehr/design-extractor --skill visual-diff
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: visual-diff
Source: https://github.com/imehr/design-extractor/tree/main/skills/visual-diff
Command: npx skills add https://github.com/imehr/design-extractor --skill visual-diff

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill measures how closely a rendered replica matches its reference capture and pinpoints where visual fidelity breaks down so refinement agents can prioritize fixes.

Core Features & Use Cases

  • Pixel-level comparison: Generate pixelmatch diffs and red/yellow visualizations that expose exact pixel divergences and compute an aggregate fidelity score.
  • Structural critique: Use LLM-guided vision prompts to interpret layout and token-level mismatches that pixel diffs alone cannot explain.
  • Token traceability & gating: Map drift regions back to design tokens, flag blocking failures (for example wrong font family or hero colour), and apply plateau detection to stop endless iteration.
  • Use Case: Validate replicas during the design-extraction pipeline, drive the refinement loop by locating problem regions, or run ad-hoc replica-vs-reference comparisons to produce gate verdicts.

Quick Start

Run visual-diff to compare replica.png with reference.png and produce a pixel diff image, a visual drift map, and a fidelity score.

Frequently Asked Questions about visual-diff

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I compare a website replica screenshot against a reference capture to find visual differences?

To compare a website replica screenshot against a reference capture, you generate pixel-level diffs to expose exact divergences. This process produces a visual drift map, a pixelmatch diff image, and an aggregate fidelity score to pinpoint mismatched regions.

What is visual regression testing with LLM critique and how does it map design drift?

Visual regression testing with LLM critique uses vision prompts to interpret layout and token-level mismatches that pixel diffs miss. It maps visual drift regions back to design tokens, providing structural feedback and a composite fidelity score for replicas.

How can I automate stopping an iterative design refinement loop when visual fidelity plateaus?

You can automate stopping an iterative design refinement loop by applying plateau detection rules alongside blocking-failure thresholds. This enforces automated iteration control by halting the process when visual fidelity scores stop improving or when critical design tokens mismatch.

Can I trace pixel mismatch regions back to specific design tokens during replica validation?

Yes, you can trace pixel mismatch regions back to specific design tokens during replica validation. The structural critique mechanism maps drift regions to design tokens, flagging blocking failures like incorrect font families or hero colors for prioritized fixes.

Does pixelmatch work for generating red and yellow visualizations of UI screenshot differences?

Yes, pixelmatch works for generating red and yellow visualizations of UI screenshot differences. It computes exact pixel divergences between replica and reference captures, outputting diff images that expose specific areas of visual drift for refinement.

What are the limitations of using pixel diffs alone for design validation without LLM critique?

Pixel diffs alone cannot explain structural layout or token-level mismatches during design validation. Without LLM critique, you miss semantic context, lacking the ability to interpret why visual drift occurred or enforce blocking-failure thresholds tied to specific design tokens.