visual-regression

Visual Regression Skill

When to Use

Use this skill to detect unintended visual changes:

• After CSS/style refactors
• After dependency or framework upgrades
• Before releases ("did anything shift?")
• Verifying a fix did not break unrelated screens
• Auditing a route matrix across viewports

Instructions

Baseline Capture

1. Define the matrix: routes x viewports (desktop 1280x720, tablet 768x1024, mobile 375x667)
2. For each cell: navigate(route), wait for stability (network idle + fonts loaded), capture_screenshot
3. Name deterministically: {route}-{viewport}-baseline; record the action sequence that produced the state (e.g., ["navigate /cart", "click .promo-accordion"])
4. Store baselines with route, viewport, timestamp, and action-sequence metadata

Re-run After Changes

1. Repeat the exact matrix with identical viewports, wait conditions, and action sequences
2. Name candidates with a run ID: {route}-{viewport}-{runId}
3. Any drift between runs (viewport size, wait timing, animations mid-flight) invalidates the comparison

Comparing

Two complementary concepts:

• Pixel diff: strict per-pixel inequality; catches everything but is noisy around text antialiasing and subpixel rendering
• Perceptual diff: similarity metrics tolerant of imperceptible rendering variance; fewer false positives on real changes

Pick one strategy per project, set explicit thresholds, and document them next to the baselines.

Reporting Failures

Every reported failure must include:

• Viewport + route
• Full action sequence reproducing the state at capture time
• Side-by-side evidence: baseline, candidate, highlighted diff overlay
• Confidence score plus a judgment on whether the changed region is meaningful (content/layout) or incidental (decoration)

Baseline Management

• Version-control baselines alongside intentional design changes
• Update baselines deliberately, one change at a time - never wholesale re-baselining to make diffs green
• Quarantine flaky regions (ads, timestamps, avatars) with masks or an exclusion list
• Re-baseline after browser or display-scale upgrades, noting it as a run-environment event