Visual Regression Guard

Visual Regression Guard Skill

Most visual regressions ship because nobody captured the "before." This skill turns "did this break anything else?" into a tractable two-phase workflow with a recovery procedure.

1. When to fire

Fire — pre-change baseline phase when the upcoming edit has blast radius > 1 screen. If you're about to touch one of these, baseline first.

Skip when:

• Change is scoped to a single component CSS module and not imported elsewhere
• Change is JS-only with no visual surface
• A reference image is supplied and visual-reference-compare is already running (still recommended in addition, but lower priority)

2. Phase 1 — capture baseline (before the change)

Do this before the first edit, not after. If you start editing first you've already lost the baseline.

2.1 List the affected screens

The affected-screen list is derived mechanically from the trigger:

• Token edit → grep the token across the repo. Every importing file owns at least one screen.
• Shared CSS module edit → import graph. Every importer + every page importing those.
• Common component edit → call-site grep.
• Breakpoint change → every page that has a layout at that viewport.
• Font CDN / theme swap → every page (treat as the whole surface).

When the answer is "every page," pick the 3-5 highest-blast-radius pages as sentinels: the home/landing, a primary list, a primary detail, settings, and one mobile-heavy page. These act as the regression alarm.

2.2 Capture each screen

Default tool order:

1. Inside cmux → cmux browser surface:N screenshot --out <path>
2. Otherwise → agent-browser, Playwright, or the screenshot skill

For each screen, capture:

• Each breakpoint the change might touch (desktop, tablet, mobile — pick three concrete pixel widths and stick to them)
• The default state at minimum; key interactive states (hover/focus, empty, populated) if the change touches them
• A pinned scroll position (record it — see §2.3)

2.3 Pin the comparison conditions

Without these, the after-diff will be full of false positives from random noise.

2.4 Store baselines

The shape is universal; the storage choice is project-by-project:

<repo>/screenshots/baseline/<branch-or-sha>/<screen-slug>__<breakpoint>__<state>.png

Always record the base commit sha alongside the baseline. Without sha, "what was the before" is recoverable only by memory.

3. Phase 2 — re-capture and diff (after the change)

3.1 Re-capture

Same screens, same conditions as §2.3. Verify the pinned conditions matched (especially viewport + scroll + font-load) before reading the diff.

3.2 Diff

Three modes, in order of effort:

Mode A — side-by-side visual (manual, no tooling) Open before / after PNGs in a viewer that supports A/B toggle. Look for movement. Fast for ≤ 5 screens. Sufficient for solo workflows.

Mode B — pixel diff with tolerance (lightweight) pixelmatch (Node), Resemble.js, or compare (ImageMagick) with a 0.1–1% threshold (anti-aliasing tolerance). Outputs a third "diff" PNG with red pixels where they differ.

pnpm dlx pixelmatch --threshold 0.1 baseline.png after.png diff.png
# exit code != 0 → diff exceeded threshold

Mode C — semantic diff with DOM measurement Compare getBoundingClientRect() of identified components instead of pixels. More robust to font-rendering noise; less robust to background / decorative changes. Best when paired with Mode B.

const items = document.querySelectorAll('[data-snapshot-key]');
JSON.stringify(Array.from(items).map(el => ({
  key: el.dataset.snapshotKey,
  ...el.getBoundingClientRect().toJSON()
})));

Compare the JSON; deltas beyond threshold (e.g., width Δ ≥ 4px) are regressions.

3.3 Classify each diff

For each red region or rect delta:

4. Recovery (when you find a regression)

A 4-step procedure. Don't skip steps even if step 1 looks obvious.

4.1 Locate — where exactly

• Which component? (point at the red region; cross-reference with data-snapshot-key if you instrumented it)
• Which CSS rule? (DevTools inspect → computed styles → find the source)
• Which token / class is responsible?

4.2 Hypothesize — root cause family

Most visual regressions fit one of these families. Name the family before opening the diff PNG; it sharpens the search:

4.3 Bisect — narrow to the change

If the cause isn't obvious from step 4.2:

# Find the first commit where the screenshot differs
git bisect start
git bisect bad HEAD                # current = bad
git bisect good <known-good-sha>   # phase-1 baseline sha
# For each step, the test command is: re-capture the screen and pixelmatch
git bisect run <script-that-captures-and-pixelmatches>

Even without bisect run automation, manual bisect over 5-10 commits beats reading 200 lines of CSS by eye.

4.4 Route — to the responsible skill

This skill detects and locates. The fix lives in the responsible skill.

Do not patch in this skill.

5. Anti-patterns

• ❌ Editing first, then asking "what broke?" — you've lost the baseline. Re-baseline-then-revert is far more expensive than baseline-then-edit.
• ❌ Capturing baseline at a different viewport / DPR / scroll than the after-shot — every difference will look like a regression.
• ❌ Capturing only the screen you're editing. Token / shared-CSS / common-component edits ripple to screens you aren't looking at — those are the regressions you'll ship.
• ❌ Calling a diff "noise" without checking. Sub-pixel shifts are noise; a card that moved 8px is not.
• ❌ Accepting a regression because "the new look is fine too" — that's a different decision. Decide explicitly: keep + update baseline + record the intent, or revert.
• ❌ Patching the regression at the call site when the cause is the token — you'll repeat the patch at every other call site.
• ❌ Skipping the bisect for "I know what it is" — being wrong once costs more than running bisect always.

6. Tooling fallback chain

The skill does not require a specific tool. The discipline of phase-1 capture and phase-2 comparison is the value, not any one tool.

7. Storage discipline

The fastest setup that scales:

screenshots/
  baseline/
    <ISO-date>-<short-sha>/
      <screen-slug>__<viewport>__<state>.png
  diff/                       # ephemeral, gitignored
    <ISO-date>-<short-sha>/
      <screen-slug>__<viewport>__<state>__diff.png

Update baseline only when:

• An intended visual change shipped — refresh that screen's baseline + record the commit sha + one-line reason
• A new screen entered the sentinel list

Do not auto-refresh on every PR — that defeats the purpose. Baselines lag intentionally.

8. Reporting

# Visual Regression Guard — <change description>

## Baseline
- Captured: <date>, base sha <abc1234>
- Screens (N=…): <list with viewport / state>

## After
- Re-captured: <date>, head sha <def5678>
- Conditions matched: ✓ (viewport / scroll / DPR / font-load)

## Diff results
- Mode used: <A side-by-side | B pixelmatch | C DOM measurement>
- Screens with diff > threshold:
  - <screen> @ <viewport>: <% pixel diff> — classified as <intended | noise | regression>

## Regressions
### <screen> @ <viewport>
- Family: <token ripple | cascade leak | layout shift | wrap shift | asset miss | breakpoint cliff | state mismatch | theme mismatch>
- Located: <component / CSS rule / token>
- Routed to: <skill name>
- Status: <fixed in commit … | open punch list item>

## Outstanding
- Baseline refreshes pending: <list>
- Skipped screens: <list with reason>

9. Relation to sibling skills

10. The one-line rule

If your change can be felt by a screen you're not currently looking at, capture before you start editing.

That single discipline removes most visual regressions before they happen. The rest of this skill is just procedure for when the discipline pays off.