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
- 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.
- 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).
- 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 "${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:
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:
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.
Record the manifest:
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:
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.
Compare:
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.
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 |
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 |
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.
1---2name: check-visual-parity3description: "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'."4argument-hint: "<baseline|compare> [states]"5user-invocable: true6disable-model-invocation: false7metadata:8 source: https://skillmd.com/skills/melodic-software/check-visual-parity9 workflow-stage: test10 summary: Baseline screenshots before a change, pixel counts against them after11---1213## Purpose1415A change that promises "the UI looks the same" is checked here by counting pixels, not by looking16at screenshots. `baseline` records PNG images of the screens and states to hold, before any code17changes. `compare` records the same screens and states again and reports, per image, how many18pixels differ. The count is held to the repository's `pixel_tolerance`, which is 0 unless the team19records a reason for more.2021The baseline is the reference the change answers to. This skill never edits, replaces or22re-captures it, and never edits a capture harness or the app's styles to make a compare pass.2324## Arguments2526`$ARGUMENTS`: `<baseline|compare> [states]`.2728- `baseline`: capture the reference images. Run it before the first edit of the change.29- `compare`: capture again and count. Run it at each green checkpoint.30- `[states]`: the screens and states to hold, for example `invoice list (empty), invoice list (4031 rows), invoice editor (validation errors)`. Without it, read the plan phase's `**Parity32 contract:**` line; with neither, ask once which screens and states to hold, and stop when there33 is no answer.3435## Step 1: Pick the capture route36371. **The repository's own visual suite first.** When the repository already runs a38 visual-regression suite (a Playwright `toHaveScreenshot` spec, a Storybook visual test, a39 screenshot test in its unit runner), run it at each checkpoint and report its verdict as the40 result for the states it covers. Run it through the repository's own entry point when it has41 one (its documented test command or runner script), not the test tool directly, and name that42 command in the report. Capture here only the states it does not cover. A state the run did not43 compare (the run stopped on a build, install or browser-launch error, or the state has no44 baseline image) has no verdict: report the environment failure with the last lines of its45 output, and give that state the gap report (the state, the command, and that it needs that46 command to run to a verdict). Never move it to another route: the suite holds its baseline,47 and another renderer's capture would measure the renderer change.482. **A driver that writes PNG files.** When `/app-control:drive` is among the available skills,49 capture each state with `/app-control:drive capture --kind screenshot --out <the baseline or50 after directory>`, and use the result only when drive reports a non-empty PNG file at that51 path. Drive names its files for the feature and a step number52 (`checkout-cart-02-screenshot.png`), and compare pairs images by filename, so rename or copy53 each drive PNG to its state name (`invoice-list-empty.png`) in the baseline or after directory,54 and record that state name in `baseline-routes.txt`. When drive reports `screenshot` as a55 capability gap, or writes no PNG, fall through to the next choice. Otherwise capture only56 through the Playwright CLI (`/playwright:playwright`, when it is among the available skills) or57 through the repository's own harness when that harness writes PNG files. Any other driver,58 including one that returns screenshots only into the conversation, cannot feed a pixel count:59 stop with the gap report (what to hold, which driver resolved, and that a PNG-writing driver is60 needed).613. **One launch path.** When drive captures, drive's own launch is the one launch path: do not62 also start the app the way `/testing:run-e2e` starts it. For the other routes, start and63 restart the app through `/testing:run-e2e`'s launch path (its orchestrator rule, the bundled64 `run` skill, or the already-running app). Never start a second instance beside the one that65 path starts.6667This step is done when each listed state has a route: the repository's suite, a PNG-writing68driver, or the gap report.6970Fix the capture settings before the baseline and keep them for every compare, on the drive route71too: the browser and its version, the viewport, the device scale factor, and the same seed data,72clock and fonts the app renders with. Freeze or hide anything that changes on its own (a clock, a73spinner, a caret).7475## Step 2: Resolve the tolerance7677Run, with the repository root as `--repo`:7879```bash80bash "${CLAUDE_PLUGIN_ROOT}/skills/check-visual-parity/scripts/visual-compare.sh" config --repo "<repository root>" --user 'pixel_tolerance=${user_config.pixel_tolerance}'81```8283It prints one line, `pixel_tolerance=<n> source=<layer> reason=<text>`. The team value lives in84`docs/conventions/testing.yaml` as a `pixel_tolerance` map with `pixels` and `reason`, read from85origin's default branch:8687```yaml88pixel_tolerance:89 pixels: 290 reason: "subpixel text: the CI image renders without hinting"91```9293The user-global `~/.claude/testing.yaml`, the personal override `.claude/testing.local.yaml`94(`source=personal-override`) and the plugin option can only lower the team value. The script reports a raise as ignored, and names an invalid95layer and drops it. Quote a `reason` that holds a colon followed by a space.9697A tolerance above 0 is used only with its recorded reason; never pass a higher `--tolerance` than98this line gives. To keep a known baseline mismatch under tolerance, the team records a99`pixel_tolerance` map with the pixel count and a reason in `docs/conventions/testing.yaml`; this100skill never raises it. Whenever a reply proposes or declines a higher tolerance, it names that101file and the `pixel_tolerance` map.102103## Step 3: baseline104105Before the first edit of the change:1061071. Launch the app through the route in Step 1 and capture each listed state as one PNG in108 `<memory_dir>/<branch-slug>/visual-parity/baseline/` (`<memory_dir>` is `.work/` unless the109 project's instructions name another root). Name each file for its state, such as110 `invoice-list-empty.png`. Write the route that captured each state to111 `<memory_dir>/<branch-slug>/visual-parity/baseline-routes.txt`, one `<image name>: <route>`112 line per state (`drive`, `playwright` or `harness`), outside the baseline directory so the113 manifest does not hash it. `compare` reads it there and reuses each route.1142. Record the manifest:115116 ```bash117 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>118 ```119120 It stores each image's sha256 with the OS, browser, viewport, scale and commit. It refuses a121 directory that already has a manifest; a new baseline goes in a new directory, and only when122 the person asks for one.123124## Step 4: compare125126At each green checkpoint:1271281. Capture each state through the route that captured its baseline (read it from129 `baseline-routes.txt`). When that route is unavailable now, for example drive reports a130 capability gap or writes an empty PNG, do not fall through to another route: two renderers131 differ in browser build, font rasterisation and scale factor, so the count would measure the132 renderer change. Stop that state with the gap report and name the route it needs. Capture the133 same states, on the same host with the same settings, into134 `<memory_dir>/<branch-slug>/visual-parity/after/<checkpoint>/`, and run `manifest` on that135 directory with the same `--browser`, `--viewport` and `--scale`.1362. Compare:137138 ```bash139 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}"140 ```141142 Pass `--reason` only when the tolerance is above 0. The first run installs pixelmatch and pngjs143 from the committed lockfile; when `npm` is missing or the install fails, the script prints one144 repair line, which goes in the report as is.1453. Read the exit code: 0 every image passed, 1 at least one failed, 2 the run could not compare (a146 baseline image changed after its manifest, the after capture's browser, viewport, scale or OS147 differs from the baseline's, or the install is broken).148149A failing image is a finding, not something to fix here. Report it with its diff image and stop150the checkpoint. A change the person accepts as intended is recorded by them as a new baseline in a151new directory, never by overwriting this one.152153## Report154155Per checkpoint: the `pixel_tolerance` line from Step 2; each image's156`differing=<n> tolerance=<t> verdict=<pass|fail> name=<image>` line; the diff image path for each157failure; when route 1 ran the repository's visual suite, the command that ran it and its verdict,158or its environment failure with its last lines; each gap report; the route that captured each state159(drive, the Playwright CLI or the repository's harness); and the capture cost, as the number of160images captured and the seconds the capture and compare took.161162## Upstream facts this rests on163164| Claim | Pointer | As of | Recheck trigger |165|---|---|---|---|166| 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) |167| 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 |168169## Next170171- Continue the change one structural step at a time: /implementation:implement refactor172- Verify the changed flows end to end beyond the pixels: /testing:run-e2e173174## Gotchas175176- A compare on a different host, browser version or scale factor counts rendering noise as177 regressions; the manifest check stops it with exit 2 rather than reporting a misleading count.178- Anti-aliased text and gradients shift by a few pixels between GPU and software rendering; that179 is what a team `pixel_tolerance` with a reason is for, never a per-run `--tolerance`.180- A screenshot taken before the page settles (web fonts, lazy images, an animation) differs on181 every run; wait for the state before capturing.