Use case · Visual regression
Protect the UI
you already reviewed.
A spacing fix can change another component. Capture the affected stories and compare them with approved baselines before accepting the update.
Represent the states that matter
Use stories for meaningful component states: an empty field, a long heading, a disabled action, or an error. Add the viewports and themes you support. Tests can only check the states you capture.
Start with the Storybook or Ladle guide, approve an intentional starting state, and commit its manifest.
Compare after a change
Rebuild your workbench before running the CLI. For a Storybook project:
npx storybook build --quiet --disable-telemetry --loglevel error
npx -p @juxtapose/cli jux run --html
Affected-story selection limits the run when the dependency graph can establish scope. Use
--all to check everything. Inspect screenshot differences alongside DOM evidence
before deciding whether the change is intended.
Do not turn every failure into a new baseline
A deliberate heading-size change may be correct; an unrelated button shifting is still a regression. Fix unexpected changes, rebuild, and capture again. Approve a reviewed story by its exact ID:
npx -p @juxtapose/cli jux approve --story 'card--default'
npx -p @juxtapose/cli jux checkApproval confirms the capture again on a fresh renderer. The manifest changes belong in the same code review as the component change.
Treat noise as evidence too
Rendering can vary with data, timing, fonts, or platform. Inspect instability reports; use readiness selectors, deterministic fixtures, and appropriate freeze settings before introducing tolerances. Exact SHA-256 comparison is the default. Optional visual equivalence is explicit, and does not update a baseline automatically.
Next: run the check on pull requests and read rendering-noise controls. Approve on the same OS used by CI.