Visual Diff

Skill: Visual Diff

Compare two URLs visually — a baseline (e.g. production site) and a current (e.g. local dev server or Storybook story) — to find pixel-level differences and guide corrections.

When to Use

• Replicating an existing page or section in Storybook or the Astro site
• Verifying visual accuracy of a component against a reference design
• Checking responsive fidelity across breakpoints after style changes
• Iterating on CSS/HTML until a component matches its reference

When NOT to Use

• Content-only changes (text updates, copy edits) where layout is unchanged
• Comparing designs from Figma — use the Figma MCP skill instead
• Performance or accessibility audits — use Lighthouse or the a11y addon

Prerequisites

Before starting, confirm:

1. Playwright MCP is configured in .vscode/mcp.json with --caps=vision
2. pixelmatch and pngjs are installed: check package.json devDependencies
3. The baseline URL is accessible (external site, or a running server)
4. The current URL is accessible (dev server on :4321, Storybook on :6006, etc.)
5. The temp/ directory exists in the workspace root (it's gitignored)

If the dev server or Storybook isn't running, start them using the VS Code tasks:

• Dev server: use the Dev Server task
• Storybook: use the Storybook task

Workflow

Step 1: Receive inputs

The agent needs:

Step 2: Screenshot the baseline

Component-scoped comparison (preferred when comparing a single component)

When comparing a specific component — especially when the Storybook story renders only that component but the baseline page has a full page around it — crop to the component's bounding box so the diff isn't polluted by unrelated page sections (nav bars, sticky overlays, other modules above/below).

How to crop on the baseline page:

1. Navigate to the baseline URL
2. Resize viewport to { width: 1280, height: 720 }
3. Scroll the target element into view:

   () => document.querySelector('<selector>').scrollIntoView({ behavior: 'instant', block: 'start' })

4. Measure the component's rendered height:

   () => document.querySelector('<selector>').getBoundingClientRect().height

5. Resize the viewport height to match that exact height (keeps width constant):

   mcp_playwright_browser_resize → { width: 1280, height: <measured height> }

6. Take the screenshot — it now captures only the component area.

Background bleed warning: What's visible behind the component will differ between Storybook (blank) and the baseline page (other modules). Common cases: sticky/local nav bars overlapping the top, modals/overlays with other page content visible behind them, and partially transparent components. These residual diffs cluster outside the component's own content and are not actionable — ignore them.

How to crop on the Storybook story:

Storybook iframe.html renders only the component with no surrounding chrome — no resizing needed. Just navigate and screenshot:

mcp_playwright_browser_navigate → { url: "http://localhost:6006/iframe.html?id=<story-id>&viewMode=story" }
mcp_playwright_browser_resize → { width: 1280, height: <same height as baseline crop> }
mcp_playwright_browser_take_screenshot → { filename: "temp/vdiff-current-desktop.png" }

Full-page viewport screenshot (when comparing full pages)

1. mcp_playwright_browser_navigate → { url: "<baseline-url>" }
2. mcp_playwright_browser_resize → { width: 1280, height: 720 }
3. mcp_playwright_browser_wait_for → { time: 2 }       # let page fully render
4. mcp_playwright_browser_take_screenshot → {
     type: "png",
     filename: "temp/vdiff-baseline-desktop.png"
   }

Repeat for each breakpoint:

Step 3: Screenshot the current

Repeat the exact same process for the current URL, using temp/vdiff-current-{breakpoint}.png filenames.

Important: Use the same viewport dimensions and the same cropping strategy (component-scoped or full-page) on both sides so the comparison is apples-to-apples.

Step 4: Run the diff script

For each breakpoint, run the visual-diff script in the terminal:

node scripts/visual-diff.mjs \
  --baseline temp/vdiff-baseline-desktop.png \
  --current temp/vdiff-current-desktop.png \
  --output temp/vdiff-diff-desktop.png

The script outputs JSON to stdout:

{
  "totalPixels": 921600,
  "diffPixels": 4521,
  "diffPercent": 0.49,
  "width": 1280,
  "height": 720,
  "baselineDimensions": { "width": 1280, "height": 720 },
  "currentDimensions": { "width": 1280, "height": 720 },
  "dimensionsMismatch": false,
  "diffImagePath": "/absolute/path/to/temp/vdiff-diff-desktop.png"
}

If dimensionsMismatch is true, the images had different sizes. The script pads the smaller image with transparent pixels before comparing. This often indicates a layout issue worth investigating.