Set up UI Verify, end to end

Goal: take a repo from no visual testing to a green UI Verify check on every PR, with the first
stories authored the cheap + deterministic way so the setup doesn't start flaky or expensive. This
skill is the conductor — it decides the capture path, wires CI, then hands the authoring and
determinism work to the focused skills.

Step 1 — pick the capture path (don't ask the user; detect it)

UI Verify captures UI four ways. Choose by what the repo already has:

• Storybook path — the repo has .storybook/ or @storybook/ in package.json, or is a

npm i -D uiverify

- import { test, expect } from '@playwright/test';
+ import { test, expect } from '@uiverify/playwright';

npm i -D @uiverify/playwright uiverify

import { playwright } from '@vitest/browser-playwright';
import { uiverifyPlugin } from '@uiverify/vitest/plugin';
export default defineConfig({
  plugins: [uiverifyPlugin()],
  test: { browser: { enabled: true, provider: playwright(), instances: [{ browser: 'chromium' }] } },
});

npm i -D @uiverify/vitest @vitest/browser-playwright uiverify

# .github/workflows/visual.yml
name: Visual
on:
  push:
    branches: [main]                           # your default branch, so the first build seeds the baseline
  pull_request:
jobs:
  uiverify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }             # full history so baseline ancestry works
      - uses: actions/setup-node@v4
        with: { node-version: 24, cache: npm }
      - run: npm ci
      - run: npm run build-storybook -- --stats-json    # ./storybook-static + the dependency graph
      - run: npx uiverify upload --static-dir storybook-static
        env:
          UIVERIFY_API_KEY: ${{ secrets.UIVERIFY_API_KEY }}
        # Playwright / Vitest instead (browsers aren't preinstalled on the runner): run
        #   "npx playwright install --with-deps && npx playwright test"  (or "npx vitest run"), then
        #   "npx uiverify upload --static-dir uiverify-archive".
        # Screenshot upload (native / mobile / React Native): produce your PNGs (Detox, Maestro, etc.),
        #   then "npx uiverify upload --screenshots ./screenshots" in place of the build+upload steps.

npm run build-storybook -- --stats-json && UIVERIFY_API_KEY=uv_proj_… npx uiverify upload --static-dir storybook-static
# Playwright:  npx playwright test && npx uiverify upload --static-dir uiverify-archive
# Vitest:      npx playwright install --with-deps && npx vitest run && npx uiverify upload --static-dir uiverify-archive

• Plain paths: filter — add paths: to the trigger. Simplest, but it skips the whole job, so it

# .github/workflows/visual.yml
on:
  push:
    branches: [main]          # advance the baseline as PRs merge
  pull_request:
jobs:
  changes:
    runs-on: ubuntu-latest
    outputs: { ui: '${{ steps.f.outputs.ui }}' }
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: dorny/paths-filter@v4
        id: f
        with:
          filters: |
            ui:
              - 'src/components/**'
              - 'src/app/**'
              - 'packages/ui/**'                 # shared UI packages
              - '**/*.css'
              - '.github/workflows/visual.yml'    # the workflow itself
  uiverify:
    needs: changes
    runs-on: ubuntu-latest
    steps:                     # every step below is also guarded:  if: ${{ needs.changes.outputs.ui == 'true' }}
      - if: ${{ needs.changes.outputs.ui == 'true' }}
        uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      # ...the setup-node / install / build / upload steps from Step 4, each guarded the same way.
      # On main, add --auto-accept-changes to the upload so the post-merge render becomes the baseline.

A missed render is silent — bias to include. An unnecessary run costs a few CI minutes; a missed
one renders nothing, the check passes green, and the unseen change becomes the next baseline every branch
inherits. So list every dir the UI is built from (components, pages, shared UI packages, global CSS) and
the workflow file itself — and don't exclude a mixed folder just because it's mostly backend: a
lib/ holding both a cn() helper the UI imports and unrelated db/AI code stays in the filter. If that
over-runs, split the UI-facing code onto its own path, then filter on that — separate for granularity;
never trade coverage for speed.

Render only what the PR could have changed — on by default for Storybook and Vitest. Whenever the
upload carries a dependency graph, UI Verify renders just the stories your commit's changed files could
affect and carries the rest of the baselines forward, so a PR's build time and bill track the size of the
diff, not the size of the suite. It is safe from the first run - when it
can't prove a story is unaffected it renders it, and a first build has nothing to carry, so it renders
everything anyway. Local uploads are safe on the default too: files you haven't committed count as
changed, so what they affect renders.

For Storybook the graph comes from the build, and an agent must not drop it: --stats-json writes
preview-stats.json, the dependency graph the server reads. Without it every story renders, and the
upload log says so on every run. If the repo already has a visual workflow, edit its build and upload
steps in place rather than appending new ones, or the job builds Storybook twice and registers two builds
per PR.

Vitest needs no build flag: @uiverify/vitest 1.6+ writes the Vite module graph into the archive
on its own, so the plain upload is enough:

      - run: npx uiverify upload --static-dir uiverify-archive
        env:
          UIVERIFY_API_KEY: ${{ secrets.UIVERIFY_API_KEY }}

For Vitest the skip is only as granular as your test files: the server traces a changed source file to
the tests that import it and carries the rest forward, so keep one page/component per
.visual.test.tsx file (each importing only what it renders). A file that colocates next to its
component (SecurityPage.visual.test.tsx beside SecurityPage.tsx) lets a one-component change skip every
other page; a single mega-test that imports half the app re-renders on every commit. A test whose imports
git can't follow (bundler output, as under Angular's unit-test builder, a workspace package's built
dist/, gitignored generated code) always renders; the test run prints [uiverify] The tests in N
file(s) always render: ... with the reason. It does nothing for the Playwright path out of the box - a Playwright
archive has no dependency graph, so every test renders unless you add a preview-stats.json to the
archive directory yourself ([module graph format](https://uiverify.ai/docs/skip-unchanged#module-graph-format)).

Check the Storybook major before you write the build step - the flag is --stats-json on Storybook 8+,
but --webpack-stats-json on 7.x, and passing the wrong one fails the build step before the upload ever
runs.

Step 5 — the check gates every PR

Once wired, every PR gets a UI Verify check. The first run on your default branch captures the
baseline; after that each PR is diffed against it, and a real visual regression (or an operational
failure like a broken build or network error) turns the job red. Strict-by-default is intentional: a
silently dropped upload must not leave CI green. If the first few diffs are noisy, don't disable the
check — loop back to the determinism skill (Step 3) to remove the flake at its source.

Step 6 — connect your agent so it can see the diffs (MCP)

The check gates the PR; the MCP is how your coding agent reviews it without leaving the terminal —
list builds, look at the actual before/after pixels, post them to the PR, accept baselines. Add it as a
real MCP server (Claude Code, Cursor, Codex, …) — don't hand-roll curl, or the image tools come back
as blocks a shell can't render. One command for Claude Code, run in the project root:

claude mcp add --scope project --transport http uiverify https://uiverify.ai/mcp

Then restart Claude Code, run /mcp, pick uiverify, and log in to UI Verify in the browser. That one
login reaches every project in every team the user belongs to, so it is done once, not per project, and
there is no API key in the config: the committed .mcp.json holds only the URL and each teammate logs in
with their own account.

Then hand the review loop to triage-visual-changes (it has the per-client setup and the recipes:
bucket real regressions vs noise, put the before/after in the PR, bulk-accept). On a passed build the
agent can still pull any story's current image by id to confirm it looks right.

Make it stick — install making-ui-changes and point your AGENTS.md / CLAUDE.md at it.* The setup
only pays off if new UI keeps getting captured, and it will only get captured if the agent reads the
discipline on every* UI change instead of when a human remembers to. So don't leave the customer to
hand-edit CLAUDE.md — do it as part of setup: install the making-ui-changes skill (the playbook
for changing UI safely — reuse before you create, add the story/capture in the same change, check the
blast radius, prove it with a visual test), then add a one-line rule to both AGENTS.md and
CLAUDE.md so every tool (Claude, Codex, Cursor, …) sees it:

## UI changes
- Before changing any component, page, or styles, read the `making-ui-changes` skill and follow it:
  reuse before you create, add/update the story or capture in the same change, check the blast radius on
  shared components, and prove the change with a visual test before calling it done.

That turns a one-time wiring into a habit the agent follows on every change.

Done when

• A PR shows a UI Verify check with a baseline captured.
• The first build's changed-stories list is empty or all-real (no clock/data/animation flake) — if not,

• Stories cover the variants without one-story-per-combo explosion (economical-visual-tests applied).