A site comparison run has two responsibilities. First it captures evidence: browser screenshots, cropped regions, pixel diffs, computed CSS, bounds, attributes, and a root summary.json. Then it serves that evidence in the interactive review site so a human can compare screenshots, inspect CSS differences, leave notes, drop pins, and export a handoff document.

The important design choice is that comparison and review are separate steps. The JavaScript verb in examples/verbs/review-sweep.js opens pages and writes files. The built-in css-visual-diff serve command reads those files and displays them. This keeps browser automation, artifact generation, and human review independent. You can regenerate evidence without changing the review site, and you can reopen a completed run without re-running Chromium.

What the Workflow Produces

A complete run is a directory with one manifest and one artifact directory per page section. The review site does not infer this structure; it expects it. The review-sweep example verb writes the structure for you.

/tmp/cssvd-review-site-smoke/
├── summary.json
└── smoke/
    └── artifacts/
        ├── app/
        │   ├── compare.json
        │   ├── compare.md
        │   ├── left_region.png
        │   ├── right_region.png
        │   ├── diff_only.png
        │   ├── diff_comparison.png
        │   ├── url1_full.png
        │   └── url2_full.png
        ├── hero/
        ├── card/
        └── cta/

The summary.json file drives the card list. Each row says which page and section it represents, how many pixels changed, how the result was classified, and where the screenshots live. Each compare.json file contains the detailed evidence for one section: source URLs, selectors, bounds, pixel statistics, computed CSS differences, and attribute differences. The PNG files are the visual evidence used by the view modes.

The key files are:

The Site Spec

The site spec is a YAML file consumed by the example JavaScript verb. It describes what to compare, not how the review site should render. The spec names pages, declares left and right URLs, defines section selectors, chooses viewport dimensions, and lists CSS properties and attributes to collect.

A minimal spec looks like this:

name: cssvd-review-site-smoke
variant: desktop

viewport:
  width: 1000
  height: 760

defaults:
  waitMs: 250
  threshold: 30

policy:
  bands:
    - name: accepted
      maxChangedPercent: 0.5
    - name: review
      maxChangedPercent: 10
    - name: tune-required
      maxChangedPercent: 30
    - name: major-mismatch
      maxChangedPercent: 100

computed:
  - font-size
  - font-weight
  - line-height
  - color
  - background-color
  - border-radius
  - padding-top
  - padding-right
  - padding-bottom
  - padding-left

attributes:
  - id
  - class
  - aria-label

pages:
  smoke:
    leftUrl: http://127.0.0.1:18767/examples/pages/review-site-smoke-left.html
    rightUrl: http://127.0.0.1:18767/examples/pages/review-site-smoke-right.html
    sections:
      app:
        selector: "#app"
      hero:
        selector: ".hero"
      cta:
        selector: ".cta"

Each section normally uses the same selector on both sides. If your prototype and implementation use different DOM shapes, use leftSelector and rightSelector:

pages:
  pricing:
    leftUrl: http://localhost:7070/pricing.html
    rightUrl: http://localhost:6006/iframe.html?id=pricing--desktop
    sections:
      cards:
        leftSelector: "#pricing-cards"
        rightSelector: "[data-component='PricingCards']"

The spec fields have these responsibilities:

Selectors should target stable visual regions. A section that is too broad produces noisy screenshots and large pixel percentages. A section that is too narrow can miss the visual problem. For a first run, choose a small set of regions such as header, main, .hero, .card, and the primary CTA. Add more sections after the review site confirms the pipeline is working.

How the Example JavaScript Verb Works

The example generator lives at examples/verbs/review-sweep.js. It is a repository-scanned JavaScript verb, not a built-in Go command. You make it available by passing --repository examples/verbs to css-visual-diff verbs.

The verb exposes two commands:

css-visual-diff verbs --repository examples/verbs examples review-sweep from-spec \
  --specFile examples/specs/review-site-smoke.yaml \
  --outDir /tmp/cssvd-review-site-smoke

css-visual-diff verbs --repository examples/verbs examples review-sweep summary \
  --specFile examples/specs/review-site-smoke.yaml \
  --outDir /tmp/cssvd-review-site-smoke

from-spec reads the YAML spec, runs comparisons, writes all artifacts, and creates summary.json. summary walks an existing output directory and rebuilds summary.json from compare.json files. The second command is useful when you changed policy bands, copied artifacts, or lost the root manifest.

At the center of from-spec is a loop over pages and sections. For each section it calls the native diff module:

const diff = require("diff")

const result = diff.compareRegion({
  left: {
    url: pageSpec.leftUrl,
    selector: leftSelector,
    waitMs: leftWait,
  },
  right: {
    url: pageSpec.rightUrl,
    selector: rightSelector,
    waitMs: rightWait,
  },
  viewport: {
    width: vpWidth,
    height: vpHeight,
  },
  output: {
    outDir: artifactDir,
    threshold: threshold,
    writeJson: true,
    writeMarkdown: writeMd,
    writePngs: true,
  },
  computed: computedProps,
  attributes: attrProps,
})

The native comparison writes section artifacts into <outDir>/<page>/artifacts/<section>/. The JS verb then converts the raw result into a row for summary.json: it copies pixel counts, computes the policy classification, records screenshot paths, extracts style changes, extracts attribute changes, and computes bounds deltas.

This split is useful when you adapt the workflow for a project. Keep the low-level comparison call stable, and customize the spec reader, policy bands, naming rules, or output rows in JavaScript. Project-specific concepts belong in the JS verb; the Go core stays focused on browser automation and artifact primitives.

Running the Smoke Setup

The repository includes a deterministic setup for testing the review website with visible differences. Start the fixture server from the repository root:

python3 -m http.server 18767

In a second terminal, build a local binary and generate the review data:

GOWORK=off go build -o /tmp/css-visual-diff-review-smoke ./cmd/css-visual-diff

rm -rf /tmp/cssvd-review-site-smoke
/tmp/css-visual-diff-review-smoke verbs \
  --repository examples/verbs \
  examples review-sweep from-spec \
  --specFile examples/specs/review-site-smoke.yaml \
  --outDir /tmp/cssvd-review-site-smoke \
  --output json

Serve the review site:

/tmp/css-visual-diff-review-smoke serve \
  --data-dir /tmp/cssvd-review-site-smoke \
  --port 18098 \
  --open

Open http://127.0.0.1:18098. The page should show four cards: smoke/app, smoke/hero, smoke/card, and smoke/cta. The fixture intentionally changes spacing, color, typography, border radius, card layout, and button text, so the classifications should include tune-required and major-mismatch.

Reading Screenshots in the Review Site

Screenshots are the main evidence. The review site provides four view modes because each mode answers a different question.

Start with Diff only to locate the area of change. Move to Side-by-side to understand the visual meaning of that change. Use Overlay or Slider when the difference is spatial: shifted text, different padding, altered height, or different alignment.

The screenshot links at the bottom of each expanded card open the raw artifacts. Use these links when you need to inspect the exact PNG file outside the review UI or attach it to an issue.

Reading CSS Differences

The CSS diff panel depends on the computed list in the spec. If a property is not listed, the example verb cannot show it as a style difference. Choose properties that explain the visual questions you expect to ask: font size, line height, margins, padding, color, background, radius, shadow, display, position, width, and height are good first choices.

CSS differences and pixel differences do not always have a one-to-one relationship. A changed font-size may produce many pixel differences. A changed box-shadow may produce a small pixel percentage but still matter visually. Use the CSS panel to explain likely causes; use the screenshots to decide visual importance.

Serving Existing Runs

Once a data directory exists, serving it is independent of the original pages. The original URLs do not need to be live for review unless you want to re-run the comparison. The server only needs summary.json, compare.json, and artifact files on disk.

css-visual-diff serve \
  --data-dir /tmp/cssvd-review-site-smoke \
  --port 18098

The server provides:

The React app converts absolute artifact paths from summary.json into /artifacts/... URLs before loading images. The Go server validates path segments so a browser request cannot escape the selected data directory.

Adapting the Example to a Real Site

For a real site, copy the smoke spec or examples/specs/review-sweep.example.yaml and replace URLs and selectors:

pages:
  homepage:
    leftUrl: https://production.example.com/
    rightUrl: http://localhost:5173/
    sections:
      header:
        selector: "header"
      hero:
        selector: ".hero"
      primary-action:
        selector: "[data-testid='primary-action']"

Run a small comparison first. One page and two or three sections are enough to validate URLs, selectors, waits, and artifact loading. Add more pages after the first data directory serves correctly.

If a selector fails, run a narrow inspection command or open the page in the browser and verify the DOM. A missing selector is usually caused by one of these conditions: the page has not finished rendering, the selector differs between prototype and implementation, the content is inside an iframe, or the target requires authentication.

Troubleshooting

See Also

• css-visual-diff help review-site explains the interactive review UI, keyboard shortcuts, local storage, and export modal.
• css-visual-diff help review-site-data-spec defines the summary.json, compare.json, and artifact directory contracts in detail.
• css-visual-diff help js-verb-review-sweep explains the example verb that generates review-site data.
• css-visual-diff help javascript-verbs explains repository-scanned JavaScript verbs.
• css-visual-diff help pixel-accuracy-scripting-guide explains lower-level browser, locator, screenshot, and CSS inspection primitives.