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'.
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 30
- Forks
- 7
01 前言 Front Matter
- metadata
- { "summary": "Baseline screenshots before a change, pixel counts against them after", "workflow-stage": "test" }
- description
- 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'.
- argument-hint
- <baseline|compare> [states]
- user-invocable
- true
- disable-model-invocation
- false
02 资源文件 5
- 脚本scripts/package-lock.json1.0 KB
- 脚本scripts/package.json313 B
- 脚本scripts/visual-compare.mjs7.1 KB
- 脚本scripts/visual-compare.sh18.5 KB
- 脚本scripts/visual-compare.test.sh19.2 KB
03 SKILL.md 正文
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 exampleinvoice 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
toHaveScreenshotspec, 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:driveis 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 inbaseline-routes.txt. When drive reportsscreenshotas 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-e2estarts it. For the other routes, start and restart the app through/testing:run-e2e's launch path (its orchestrator rule, the bundledrunskill, 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 asinvoice-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,playwrightorharness), outside the baseline directory so the manifest does not hash it.comparereads 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 runmanifeston that directory with the same--browser,--viewportand--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
--reasononly when the tolerance is above 0. The first run installs pixelmatch and pngjs from the committed lockfile; whennpmis 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_tolerancewith 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.
04 同仓库更多 Skills
track
Backlog reads through the bound tracker: search open and closed items, view one item with its comments and state history. Use when another skill searches or reads tracker items.
reviewer-media
Reviewer media for one pull request: decides whether it needs a narrated walkthrough, builds the storyboard from /review:explain-change's digest, has /explainer-video:produce render it and hands the manifest to /source-control:pull-request media. Use when asked for 'reviewer media', 'a walkthrough video for this PR', 'a produced video of this change', or when pull-request ready or monitor hands a PR over.
route
Model and effort per agent role (orchestrator, worker, verifier, retrieval) for a multi-agent run, resolved through the bundled defaults and the user, team and personal override config layers into fenced JSON with single-agent and fan-out variants and the layer behind each value. Use when asked 'which model for the subagents', 'route the roles' or 'model routing', or before a skill passes a role's model on a spawn.
route
Model and effort per agent role (orchestrator, worker, verifier, retrieval) for a multi-agent run, resolved through the bundled defaults and the user, team and personal override config layers into fenced JSON with single-agent and fan-out variants and the layer behind each value. Use when asked 'which model for the subagents', 'route the roles' or 'model routing', or before a skill passes a role's model on a spawn.
principles
Module-design vocabulary for architecture findings, and the checks built on it. Use when: 'what is a deep module', 'what is a seam', 'deep vs shallow module', 'what is the deletion test', 'leverage and locality', 'module design vocabulary', 'which word do we use for X in architecture findings'. Scanning a codebase for friction is /architecture:improve.
write
Structured five-field bug report (title, steps to reproduce, expected vs actual, justified severity, suggested fix location) from an informal description, read-only. Use when the user names a defect they observed, or asks for one written up ('report a bug', 'file a bug', 'write this up as a bug').