Sanity Visual Coverage

Visual regression coverage

The question this skill answers is "if this file's rendering changes, does a Chromatic snapshot catch it?". The answer is a static fact about the repo, so a script computes it. Do not answer it by reading the Chromatic check, and do not answer it from memory.

Run the check

pnpm visual-coverage --changed                # files changed vs origin/main, including uncommitted
pnpm visual-coverage --changed --prs          # also mark files that an open PR is about to cover
pnpm visual-coverage <path> [<path>...]       # specific files
pnpm visual-coverage                          # whole tree, one row per area
pnpm visual-coverage --uncovered              # whole tree plus every uncovered file
pnpm visual-coverage --format json ...        # machine-readable, same modes
pnpm visual-coverage --help

For a PR you are not on: gh pr checkout <number> && pnpm visual-coverage --changed --prs. Every same-repo PR that touches packages/**/src/**/*.tsx or *.css.ts also gets a sticky "Visual regression coverage" comment from .github/workflows/visual-coverage.yml, produced by the same script with --format markdown --prs. Read that comment first when reviewing; its counts are in plain sight and the per-file table sits behind the collapsed Per-file coverage toggle.

The script is scripts/visualCoverage.ts. It has no dependencies and runs under tsx or plain Node 22.18+ (node scripts/visualCoverage.ts).

What counts as covered

Chromatic snapshots stories, not components. A component is covered when a story renders it. The script models that as direct imports:

Both projects snapshot on every PR: a story is captured by the Storybook build, a browser test's end state by the CHROMATIC=1 capture run (plus any takeSnapshot() it calls). The Playwright project ("sanity studio playwright") is curated opt-in and is not modelled as coverage.

A file is covered when a story or browser test imports it directly, or imports a *Story.tsx harness that imports it. A .css.ts file inherits the coverage of the .tsx files that import it. Nothing deeper than that counts. TestWrapper imports the whole sanity package, so a transitive graph would mark everything covered, and Chromatic's TurboSnap has the same blind spot. That is why the green Chromatic check on a PR says only "the affected stories still match", never "your component is rendered by a story".

How stories map to Studio UI

• dev/storybook is the host. Its stories glob in dev/storybook/.storybook/main.ts finds *.stories.tsx under every workspace package's src. Stories live next to the component in its __tests__ directory. Nothing lives under dev/storybook/stories.
• Two story shapes. Plain variant grids for packages/sanity/src/ui-components wrappers (Button.stories.tsx imports ../Button). Harness stories for anything that needs a workspace, i18n, or layers. The harness is <Name>Story.tsx, wraps TestWrapper, and <Name>.stories.tsx is a thin CSF file whose component is the harness.
• Browser tests define their harness component inline (function <Name>Harness() inside the <Name>.browser.test.tsx), so every *Story.tsx belongs to a story. The Vitest Chromatic integration snapshots the test's end state in place; do not extract a test's harness into a *Story.tsx to put a story on it. Their coverage shows up as browser-test evidence.
• "ui5 sentinel" and "box sentinel" are the same thing. A story added so the @sanity/ui to ui5 Box/Flex/Card migration gets a snapshot before the swap lands. The harness renders the states most likely to drift (tones, spacing, truncation, empty states) with fixture copy only. Naming follows the harness pattern above. title is Area/Component. Sentinels are ordinary stories — browsable, with a JSDoc description saying what they pin down; there is no tag to hide them. Read FieldDiffChromeStory.tsx and FieldDiffChrome.stories.tsx under packages/sanity/src/core/field/diff/components/__tests__ as the reference pair.
• A story covers exactly the components its harness imports. A DocumentLayout story also paints buttons and cards, but only the Button story is the sentinel for Button.