/visual-diff

name: visual-diff
description: "Visual Regression Testing — screenshot comparison before and after changes. Use when user wants to check for visual regressions, compare UI changes, or verify CSS/layout changes didn't break anything."

Visual Regression Testing

Automated screenshot comparison using Playwright. Catch visual bugs before they ship.

Process

Phase 1: Determine Test Scope

Ask the user: 1. **What URL(s) to test?** (localhost, staging, or production) 2. **What changed?** (CSS update, component refactor, dependency upgrade, etc.)

If the user already described what changed, skip asking.

Phase 2: Take "Before" Screenshots

If comparing against the current state (before making changes):

Use the Playwright MCP to capture screenshots:

1. Navigate to the URL:

• Use `browser_navigate` to go to the target URL

2. Take full-page screenshot:

• Use `browser_take_screenshot` to capture the current state

3. Capture key viewports:

• Desktop (1920x1080): `browser_resize` then `browser_take_screenshot`
• Tablet (768x1024): `browser_resize` then `browser_take_screenshot`
• Mobile (375x812): `browser_resize` then `browser_take_screenshot`

4. Save screenshots with descriptive names noting they are "before" state.

Phase 3: Make Changes

Let the user make their changes, or make them yourself if that's the task.

Phase 4: Take "After" Screenshots

Repeat the same screenshot process for the same URLs and viewports.

Phase 5: Visual Comparison

Compare before and after screenshots:

1. **Layout shifts** — did any elements move unexpectedly? 2. **Color changes** — did colors, gradients, or shadows change? 3. **Typography** — did font sizes, weights, or spacing change? 4. **Responsive issues** — does it look correct on all viewports? 5. **Missing elements** — did anything disappear? 6. **Overflow issues** — is content clipping or overflowing?

Use `browser_snapshot` to get the accessibility tree and compare DOM structure between before/after.

Phase 6: Report

Present findings in a clear format:

**No Visual Regressions Found:**

• "All pages look identical across desktop, tablet, and mobile viewports."

**Regressions Detected:** For each regression:

• **Page:** URL where the issue appears
• **Viewport:** Which screen size is affected
• **What changed:** Description of the visual difference
• **Severity:** Critical (broken layout), High (noticeable shift), Medium (minor difference), Low (pixel-level)
• **Suggested fix:** How to resolve the regression

Phase 7: Targeted Testing

For specific component changes, also test:

• Hover states (use `browser_hover`)
• Click interactions (use `browser_click`)
• Form states (use `browser_fill_form`)
• Dark mode (if applicable)
• Loading states
• Error states
• Empty states

Key Pages to Always Test

When the user doesn't specify pages, test these by default: 1. Homepage / Landing page (/) 2. Login/signup page (if exists) 3. Main app page (dashboard, etc.) 4. Any page the user recently modified

Key Principle

**Trust screenshots, not assumptions.** CSS changes cascade unpredictably. A "small tweak" in one component can break layouts across the entire app. Always verify visually.