# Check Visual Parity

> Hold a UI pixel-for-pixel steady through a change: PNG screenshots of the listed states before the first edit (baseline), then again at each green checkpoint, with differing pixels counted against pixel_tolerance (compare). Never edits a baseline. Use when: a plan phase has a Parity contract line, a refactor must leave the UI unchanged, 'check visual parity', 'did this change the UI'.

- Skill: `melodic-software/check-visual-parity` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx get-skill add melodic-software/check-visual-parity`
- Raw SKILL.md: https://api.skillmd.com/api/skills/melodic-software/check-visual-parity/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: melodic-software (https://skillmd.com/u/melodic-software)
- Updated: 2026-11-12
- Page: https://skillmd.com/skills/melodic-software/check-visual-parity

---


## Purpose

A change that promises "the UI looks the same" is checked here by counting pixels, not by looking
at screenshots. `baseline` records PNG images of the screens and states to hold, before any code
changes. `compare` records the same screens and states again and reports, per image, how many
pixels differ. The count is held to the repository's `pixel_tolerance`, which is 0 unless the team
records a reason for more.

The baseline is the reference the change answers to. This skill never edits, replaces or
re-captures it, and never edits a capture harness or the app's styles to make a compare pass.

## Arguments

`$ARGUMENTS`: `<baseline|compare> [states]`.

- `baseline`: capture the reference images. Run it before the first edit of the change.
- `compare`: capture again and count. Run it at each green checkpoint.
- `[states]`: the screens and states to hold, for example `invoice list (empty), invoice list (40
  rows), invoice editor (validation errors)`. Without it, read the plan phase's `**Parity
  contract:**` line; with neither, ask once which screens and states to hold, and stop when there
  is no answer.

## Step 1: Pick the capture route

1. **The repository's own visual suite first.** When the repository already runs a
   visual-regression suite (a Playwright `toHaveScreenshot` spec, a Storybook visual test, a
   screenshot test in its unit runner), run it at each checkpoint and report its verdict as the
   result for the states it covers. Run it through the repository's own entry point when it has
   one (its documented test command or runner script), not the test tool directly, and name that
   command in the report. Capture here only the states it does not cover. A state the run did not
   compare (the run stopped on a build, install or browser-launch error, or the state has no
   baseline image) has no verdict: report the environment failure with the last lines of its
   output, and give that state the gap report (the state, the command, and that it needs that
   command to run to a verdict). Never move it to another route: the suite holds its baseline,
   and another renderer's capture would measure the renderer change.
2. **A driver that writes PNG files.** When `/app-control:drive` is among the available skills,
   capture each state with `/app-control:drive capture --kind screenshot --out <the baseline or
   after directory>`, and use the result only when drive reports a non-empty PNG file at that
   path. Drive names its files for the feature and a step number
   (`checkout-cart-02-screenshot.png`), and compare pairs images by filename, so rename or copy
   each drive PNG to its state name (`invoice-list-empty.png`) in the baseline or after directory,
   and record that state name in `baseline-routes.txt`. When drive reports `screenshot` as a
   capability gap, or writes no PNG, fall through to the next choice. Otherwise capture only
   through the Playwright CLI (`/playwright:playwright`, when it is among the available skills) or
   through the repository's own harness when that harness writes PNG files. Any other driver,
   including one that returns screenshots only into the conversation, cannot feed a pixel count:
   stop with the gap report (what to hold, which driver resolved, and that a PNG-writing driver is
   needed).
3. **One launch path.** When drive captures, drive's own launch is the one launch path: do not
   also start the app the way `/testing:run-e2e` starts it. For the other routes, start and
   restart the app through `/testing:run-e2e`'s launch path (its orchestrator rule, the bundled
   `run` skill, or the already-running app). Never start a second instance beside the one that
   path starts.

This step is done when each listed state has a route: the repository's suite, a PNG-writing
driver, or the gap report.

Fix the capture settings before the baseline and keep them for every compare, on the drive route
too: the browser and its version, the viewport, the device scale factor, and the same seed data,
clock and fonts the app renders with. Freeze or hide anything that changes on its own (a clock, a
spinner, a caret).

## Step 2: Resolve the tolerance

Run, with the repository root as `--repo`:

```bash
bash "${CLAUDE_PLUGIN_ROOT}/skills/check-visual-parity/scripts/visual-compare.sh" config --repo "<repository root>" --user 'pixel_tolerance=${user_config.pixel_tolerance}'
```

It prints one line, `pixel_tolerance=<n> source=<layer> reason=<text>`. The team value lives in
`docs/conventions/testing.yaml` as a `pixel_tolerance` map with `pixels` and `reason`, read from
origin's default branch:

```yaml
pixel_tolerance:
  pixels: 2
  reason: "subpixel text: the CI image renders without hinting"
```

The user-global `~/.claude/testing.yaml`, the personal override `.claude/testing.local.yaml`
(`source=personal-override`) and the plugin option can only lower the team value. The script reports a raise as ignored, and names an invalid
layer and drops it. Quote a `reason` that holds a colon followed by a space.

A tolerance above 0 is used only with its recorded reason; never pass a higher `--tolerance` than
this line gives. To keep a known baseline mismatch under tolerance, the team records a
`pixel_tolerance` map with the pixel count and a reason in `docs/conventions/testing.yaml`; this
skill never raises it. Whenever a reply proposes or declines a higher tolerance, it names that
file and the `pixel_tolerance` map.

## Step 3: baseline

Before the first edit of the change:

1. Launch the app through the route in Step 1 and capture each listed state as one PNG in
   `<memory_dir>/<branch-slug>/visual-parity/baseline/` (`<memory_dir>` is `.work/` unless the
   project's instructions name another root). Name each file for its state, such as
   `invoice-list-empty.png`. Write the route that captured each state to
   `<memory_dir>/<branch-slug>/visual-parity/baseline-routes.txt`, one `<image name>: <route>`
   line per state (`drive`, `playwright` or `harness`), outside the baseline directory so the
   manifest does not hash it. `compare` reads it there and reuses each route.
2. Record the manifest:

   ```bash
   bash "${CLAUDE_PLUGIN_ROOT}/skills/check-visual-parity/scripts/visual-compare.sh" manifest --dir "<baseline dir>" --browser "<name and version>" --viewport <W>x<H> --scale <n>
   ```

   It stores each image's sha256 with the OS, browser, viewport, scale and commit. It refuses a
   directory that already has a manifest; a new baseline goes in a new directory, and only when
   the person asks for one.

## Step 4: compare

At each green checkpoint:

1. Capture each state through the route that captured its baseline (read it from
   `baseline-routes.txt`). When that route is unavailable now, for example drive reports a
   capability gap or writes an empty PNG, do not fall through to another route: two renderers
   differ in browser build, font rasterisation and scale factor, so the count would measure the
   renderer change. Stop that state with the gap report and name the route it needs. Capture the
   same states, on the same host with the same settings, into
   `<memory_dir>/<branch-slug>/visual-parity/after/<checkpoint>/`, and run `manifest` on that
   directory with the same `--browser`, `--viewport` and `--scale`.
2. Compare:

   ```bash
   bash "${CLAUDE_PLUGIN_ROOT}/skills/check-visual-parity/scripts/visual-compare.sh" compare --baseline "<baseline dir>" --after "<after dir>" --tolerance <n> --reason "<reason>" --diff-dir "<memory_dir>/<branch-slug>/visual-parity/diff/<checkpoint>" --deps-dir "${CLAUDE_PLUGIN_DATA}"
   ```

   Pass `--reason` only when the tolerance is above 0. The first run installs pixelmatch and pngjs
   from the committed lockfile; when `npm` is missing or the install fails, the script prints one
   repair line, which goes in the report as is.
3. Read the exit code: 0 every image passed, 1 at least one failed, 2 the run could not compare (a
   baseline image changed after its manifest, the after capture's browser, viewport, scale or OS
   differs from the baseline's, or the install is broken).

A failing image is a finding, not something to fix here. Report it with its diff image and stop
the checkpoint. A change the person accepts as intended is recorded by them as a new baseline in a
new directory, never by overwriting this one.

## Report

Per checkpoint: the `pixel_tolerance` line from Step 2; each image's
`differing=<n> tolerance=<t> verdict=<pass|fail> name=<image>` line; the diff image path for each
failure; when route 1 ran the repository's visual suite, the command that ran it and its verdict,
or its environment failure with its last lines; each gap report; the route that captured each state
(drive, the Playwright CLI or the repository's harness); and the capture cost, as the number of
images captured and the seconds the capture and compare took.

## Upstream facts this rests on

| Claim | Pointer | As of | Recheck trigger |
|---|---|---|---|
| pixelmatch counts a pixel as differing by a perceptual color threshold, `0.1` by default, which the script passes and prints | [pixelmatch README, API](https://github.com/mapbox/pixelmatch#api) | 2026-10-10, pixelmatch 8.0.0 | A pixelmatch release that changes the default or the option's meaning (a Dependabot bump of this skill's lockfile) |
| Packages a plugin loads at run time install on first use from a committed lockfile with `npm ci` into the plugin data directory | [On-demand dependencies, Rule 2](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/on-demand-dependencies/README.md#rule-2-install-on-first-use-with-npm-ci-into-the-plugin-data-directory-spec) | 2026-10-10, version 2.2.0 | A new version of that convention |

## Next

- Continue the change one structural step at a time: /implementation:implement refactor
- Verify the changed flows end to end beyond the pixels: /testing:run-e2e

## Gotchas

- A compare on a different host, browser version or scale factor counts rendering noise as
  regressions; the manifest check stops it with exit 2 rather than reporting a misleading count.
- Anti-aliased text and gradients shift by a few pixels between GPU and software rendering; that
  is what a team `pixel_tolerance` with a reason is for, never a per-run `--tolerance`.
- A screenshot taken before the page settles (web fonts, lazy images, an animation) differs on
  every run; wait for the state before capturing.

