chromatic-diff

Diagnoses Chromatic visual test diffs by comparing rendered Storybook DOM, styles, and tokens.

1.1k|89|Updated Mar 11, 2021
One-click install
npx skills add https://github.com/daangn/seed-design --skill chromatic-diff
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: chromatic-diff
Source: https://github.com/daangn/seed-design/tree/main/skills/chromatic-diff
Command: npx skills add https://github.com/daangn/seed-design --skill chromatic-diff

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve?

Chromatic tells you that a snapshot changed but not why. This Skill turns a chromatic.com build or test URL into a concrete answer by resolving the build behind it, listing the stories that changed, and rendering both sides' published Storybooks so the difference can be read as DOM structure, computed styles, and design token values instead of pixels.

Core Features & Use Cases

  • URL Resolution: Accepts Chromatic /build or /test URLs and reports the build number, branch, commit, status, and every story with unreviewed changes via the Chromatic GraphQL API.
  • Side-by-Side Render Comparison: Proxies both published Storybooks to localhost with authentication, then compares the same story's DOM, computed styles, layout boxes, and CSS custom properties through a chrome-devtools driver.
  • Flakiness Verdicts: Distinguishes real regressions from flaky snapshots by reproducing capture conditions (viewport, globals) and screenshotting one page twice to test render determinism.
  • Use Case: A teammate pastes a Chromatic link asking "why did this visual test fail?" — the Skill identifies that a dark-theme surface token changed in a specific commit, or proves both builds render identically so the snapshot is flaky.

Quick Start

Paste a Chromatic build or test URL and ask why the visual diff appeared, making sure CHROMATIC_TOKEN is exported in the environment first.

Frequently Asked Questions about chromatic-diff

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I find out why a Chromatic visual test failed?

Pass the Chromatic build or test URL to the resolve script, which reports the build, branch, commit, and every story with unreviewed changes. The Skill then renders both sides' published Storybooks and compares DOM, computed styles, and design tokens to name the actual cause.

How do I compare a Chromatic build against a specific branch instead of the baseline?

Use the --against flag with a branch name, build number, build id, or another Chromatic URL. This answers questions like what changed versus the dev branch rather than versus the automatic per-branch baseline Chromatic selected.

What credentials does the Chromatic GraphQL API require?

It requires a CHROMATIC_TOKEN OAuth access token obtained by signing in through the Storybook Visual Tests addon, not the CHROMATIC_PROJECT_TOKEN used by the CLI. The token lasts 30 days and is read from the environment by the scripts.

Can I use Playwright or Puppeteer instead of chrome-devtools for the comparison?

No. The Skill's render checks are written against the chrome-devtools MCP tools or CLI, and substituting another browser driver is explicitly refused because it silently drops those checks. Without a driver, the run stops after reporting build and story metadata.

How can I tell if a Chromatic diff is flaky rather than a real regression?

If both builds render identically at the captured viewport and globals, the snapshot is likely flaky. The strongest evidence is screenshotting one unchanged page twice and comparing the shots — if the page disagrees with itself, it cannot render deterministically.

Why is an old Chromatic build unreachable through the API?

The Chromatic API only exposes Project.lastBuild, which returns the newest build matching branch and status filters, so superseded builds cannot be looked up directly. Filtering by status often rescues them; otherwise compare against a reachable build.