Visual Review

Pixel-diff the storyboards you track on every pull request, and keep the PR red until a person approves each change.

Visual Review

Visual review turns your canvases into a regression test. Mark a storyboard as tracked, and every pull request captures it, compares it with the version on your default branch, and posts a visual-review check on the PR. The check stays red until someone approves each changed, new, or removed storyboard in Tempo’s review portal — approving flips it green instantly, no CI re-run.

Nothing lands in your repo except one workflow file: baselines are captured by CI and stored by Tempo.

How it works

1. Tracked is opt-in. Only component storyboards carrying the vrt prop are captured.
2. Every push captures. A GitHub Actions workflow runs the published @tempo-ai/visual-review CLI: the check goes pending within about a minute, the capture and comparison finish roughly ten minutes later, and the PR gets a sticky comment linking the report.
3. A person approves. In the portal, each diff is approved or rejected (rejecting requires a comment). Approvals are keyed to the pixel change, so a re-push with identical pixels stays approved.
4. Main is the baseline. Pushes to your default branch publish the baselines the next PRs compare against.

Before you start

• The repo is on GitHub and its CI is GitHub Actions (the only supported CI today).
• Canvases already work in Tempo (tempo/tempo.config.json exists).
• The repo is connected as a project in your Tempo organization (Home → Connect your codebase). That connection is the opt-in; there is no token to create.
• The Tempo Labs AI GitHub App is installed on the repo — the same app you install to connect repos. Approvals post the check through it, so without it the check never turns green. A GitHub admin of the repo’s owner installs it.

Set it up

The fastest path is to let the agent do the plumbing.

1. Ask the agent

   In a chat on the repo, say “Set up visual review for this repo.” The agent runs a read-only check of every layer (canvas host, tracked storyboards, CI, workflow, connection, GitHub App, required check, first capture) and tells you what is missing before changing anything.

2. Review what it writes

   After you say yes, it adds .github/workflows/visual-review.yml from the template the CLI ships (an existing workflow is never overwritten), tracks a small first set of storyboards, and verifies each one renders identically three times so your baseline will not flake.

3. Open the PR

   The PR that adds the workflow is also its first run: everything reports as new, and the check goes pending within a minute of the push.

4. Approve the first set

   Open the report from the check (or the sticky PR comment), approve the new storyboards, and watch the check turn green.

5. Make it required

   Once the first capture has landed, a repo admin adds visual-review as a required status check (Settings → Branches → your default branch). Choose Any source (or the Tempo Labs AI app) as the status source — never GitHub Actions, or the approval can’t satisfy it.

Prefer to do it by hand? The workflow template is templates/visual-review.yml inside the @tempo-ai/visual-review npm package. Keep every npx --yes @tempo-ai/visual-review@latest … line as it is — Tempo’s own repository runs those exact commands.

Tracking storyboards

Add the vrt prop to a component storyboard in its canvas file, or use Track visual regression in the storyboard’s menu on the Design tab.

<Storyboard id="Button" component={Button} layout={{ x: 0, y: 0, width: 320, height: 180 }} vrt />

{/* Per-storyboard tuning: threshold 0–0.5, masked regions in storyboard px */}
<Storyboard id="Chart" component={Chart} layout={{ x: 400, y: 0, width: 640, height: 360 }}
  vrt={{ threshold: 0.2, ignore: [{ x: 0, y: 0, w: 640, h: 40 }] }} />

{/* Paused: stays in the manifest, neither captured nor gated */}
<Storyboard id="Feed" component={Feed} layout={{ x: 0, y: 400, width: 640, height: 360 }} vrt={{ skip: true }} />

• Component storyboards only; route and HTML storyboards are not tracked.
• Tracked storyboards must render deterministically. Live clocks, random data, network content, and in-flight animation produce diffs on every push. Ask the agent to verify a storyboard before you push, or fix the input and retry.
• Start small — design-system boards are the best first candidates — and grow the set as it proves stable.

Reviewing a pull request

Check state	Meaning
Pending	Capturing and comparing (about ten minutes after the push)
Failing — N of M need approval	Open the report and approve or reject each change
Failing — blocking error	A tracked storyboard failed to render; fix it, the error can’t be approved
Passing	Every change is approved, or nothing changed

Two escape hatches, both deliberate:

• The visual-review:bypass label posts success without capturing. Use it for incidents only.
• Put <!-- tempo-no-visual-change --> in the PR body only when you are certain the PR changes no UI and no tracked storyboard. Any doubt means leave it out and let capture prove it.

Never add the no-visual-change marker to a PR template. GitHub keeps HTML comments in the PR body, so every PR would silently skip capture.

Troubleshooting

Symptom	Where to look
The check never appears	The workflow must exist on the PR branch with id-token: write. Pull requests from forks can’t upload captures.
Pending forever	Ask the agent to run the visual review check-up; its first run row shows whether the capture reached Tempo and whether it failed. Capture failures are almost always the install step — the same fix as for the canvas host.
Approvals don’t flip the check	The Tempo Labs AI app isn’t installed on the repo, or the required check is bound to GitHub Actions instead of Any source.
Everything is “new” on a later PR	The workflow’s push trigger must name your real default branch; that run publishes the baselines.
One storyboard flakes	Fix the nondeterministic input, or pause it with vrt={{ skip: true }} until you can. Don’t untrack it to make a PR green.