visual-regression

Visual Regression

WHEN: A prototype is iterated more than once, or before declaring a prototype review-ready. This skill snapshots the key screens at the canonical breakpoints, diffs new builds against an approved baseline, and fails the audit if drift is unintended. Default engine is Playwright; managed services (Chromatic, Percy, Applitools) are listed for teams that prefer hosted review queues.

When to Use This Skill

• Iterating a prototype where each change can shift unrelated screens
• Hardening a working SPA prototype that will inform a production build
• Catching CSS regressions from token or theme changes
• Reviewing a PR that touches global styles or shared components

Visual regression complements axe (a11y) and Lighthouse (performance). It does not replace either.

Authoritative Sources

Default Engine: Playwright

Reasoning:

• Already required by development/browser-automation for the axe pass.
• Free and runs locally and in CI.
• Deterministic with explicit threshold and animation handling.

Install (per prototype)

npm install --save-dev @playwright/test
npx playwright install --with-deps chromium

Project layout

docs/ux/prototypes/<feature>/
  __screenshots__/
    chromium-darwin/         # baseline images, committed to git
  tests/
    visual.spec.ts
  playwright.config.ts

Baselines live next to the prototype, not in tests/ at the repo root, because they are tied to the prototype version.

Minimal config

playwright.config.ts:

import { defineConfig } from "@playwright/test";

export default defineConfig({
  testDir: "./tests",
  use: {
    baseURL: "http://localhost:4173",
    screenshot: "only-on-failure",
    trace: "retain-on-failure",
  },
  expect: {
    toHaveScreenshot: {
      maxDiffPixelRatio: 0.01,
      animations: "disabled",
      caret: "hide",
      scale: "css",
    },
  },
  projects: [
    { name: "mobile",  use: { viewport: { width: 360,  height: 800  } } },
    { name: "tablet",  use: { viewport: { width: 768,  height: 1024 } } },
    { name: "desktop", use: { viewport: { width: 1440, height: 900  } } },
  ],
});