Chromatic

Overview

Chromatic is a hosted visual testing and review platform made by the maintainers of Storybook. The chromatic CLI builds and publishes your Storybook, Chromatic captures a snapshot of every story in cloud browsers, compares it with the accepted baseline, and lists the differences in a web UI where designers and developers accept or deny them. The same service also snapshots Playwright, Cypress and Vitest tests through the @chromatic-com/playwright, @chromatic-com/cypress and @chromatic-com/vitest packages. This skill covers the Storybook workflow.

Instructions

Initial assessment

1. Which Storybook version, and which framework package (@storybook/react-vite, @storybook/nextjs, ...)?
2. Does it build locally (npm run build-storybook)? Chromatic needs a working static build.
3. Which CI provider, and who reviews visual changes?

Setup

npm install --save-dev chromatic
export CHROMATIC_PROJECT_TOKEN=chpt_...   # from the project's Manage page on chromatic.com
npx chromatic

The CLI reads CHROMATIC_PROJECT_TOKEN from the environment (preferred over the --project-token flag, which leaks into shell history and CI logs). The first build becomes the baseline; later builds are compared with it and marked "unreviewed" until someone accepts or denies the changes. The CLI needs Node 22 or newer.

Story parameters

Set parameters.chromatic at the project (.storybook/preview.ts), component (meta) or story level:

• delay: 300 waits that many milliseconds before the snapshot.
• diffThreshold: 0.063 is the default sensitivity (0 most sensitive, 1 least); raise it to ignore anti-aliasing noise.
• disableSnapshot: true skips a story, for example one that is purely animated.
• ignoreSelectors: ['.product-price'] ignores pixels in matching elements. Equivalent markup: data-chromatic="ignore" or the chromatic-ignore class. A size change of the ignored element still counts as a change.
• modes captures a story under several viewport/theme combinations (see Modes below). The older viewports parameter is legacy; use modes.

Interaction tests

Chromatic runs each story's play function and takes the snapshot after it finishes. In Storybook 9 and 10, import the test utilities from storybook/test; the old @storybook/testing-library and @storybook/jest packages are deprecated.

Configuration file

chromatic.config.json in the project root (JSON, not a JS module) holds a subset of CLI options. Keys: buildScriptName, storybookBuildDir, onlyChanged, externals, skip, autoAcceptChanges, exitZeroOnChanges, exitOnceUploaded. Boolean-or-glob options accept branch globs, for example "autoAcceptChanges": "main". Keep the token out of this file.

TurboSnap

onlyChanged: true snapshots only stories affected by the changed files, using the bundler's dependency graph (Webpack or Vite) and full git history, so CI must fetch with fetch-depth: 0. Changes to .storybook/preview, static files, a mismatched lockfile, or paths listed in externals (fonts, global CSS, images) force a full rebuild.

CI (GitHub Actions)

Chromatic recommends triggering on push; pull_request builds a synthetic merge commit that can produce wrong baselines. The official workflow uses chromaui/action@latest with a CHROMATIC_PROJECT_TOKEN repository secret and fetch-depth: 0 on checkout (see Example 2).

Modes

Define modes once in .storybook/modes.ts and reuse them across stories. Modes set at project (.storybook/preview.ts), component and story level are stacked, not overridden: a story is snapshotted under every mode from all three levels, each with its own baseline and approval. Name the mode keys clearly, because the name becomes the badge in the review UI.

Examples

Example 1: Snapshot a Button across themes and sizes

User request: "Make Chromatic capture our Button in light and dark, on mobile and desktop."

// .storybook/modes.ts
export const allModes = {
  "light mobile": { theme: "light", viewport: 375 },
  "dark mobile": { theme: "dark", viewport: 375 },
  "light desktop": { theme: "light", viewport: 1200 },
  "dark desktop": { theme: "dark", viewport: 1200 },
} as const;

// src/components/Button.stories.jsx
import { allModes } from "../../.storybook/modes";
import { Button } from "./Button";

export default {
  component: Button,
  parameters: { chromatic: { modes: allModes, diffThreshold: 0.063 } },
};

export const Primary = {
  args: { variant: "primary", children: "Checkout" },
};

The theme key only changes anything if your preview defines a global of that name (for example through a theme decorator); viewport accepts a pixel width or a named viewport.

Result: the next build shows four snapshots per story, named after the mode; accept them to set the baselines.

Example 2: Open dropdown and run Chromatic in CI

User request: "Snapshot the Dropdown while it is open, and add Chromatic to GitHub Actions."

import { expect, userEvent, within } from "storybook/test";
// inside Dropdown.stories.jsx
export const Opened = {
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement);
    await userEvent.click(canvas.getByRole("button", { name: "Options" }));
    await expect(canvas.getByRole("menu")).toBeVisible();
  },
};

# .github/workflows/chromatic.yml
name: Chromatic
on: push
jobs:
  chromatic:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v7
        with:
          node-version: 24
      - run: npm ci
      - uses: chromaui/action@latest
        with:
          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
          autoAcceptChanges: main
          onlyChanged: true
          skip: "dependabot/**"

Result: pushes to feature branches get a Chromatic status check that reports the diffs for review; pushes to main are auto-accepted so the baseline follows the merged code. A failing expect in play is reported as an interaction test failure.

Guidelines

• Treat the project token as a secret: keep it in CI secrets or an environment variable, never in chromatic.config.json or committed scripts.
• Make stories deterministic before blaming Chromatic: fixed dates, seeded random data, mocked network, no looping animations. Use delay, disableSnapshot or ignoreSelectors for the rest.
• Each snapshot counts against your plan, so every extra mode multiplies usage; use onlyChanged and apply wide mode sets only to components that need them.
• With the CLI, a build with visual changes exits non-zero by default, which blocks merging; the GitHub Action defaults exitZeroOnChanges to true, so there the gate is the Chromatic status check. exitOnceUploaded makes the CLI exit 0 as soon as the upload finishes, without waiting for results.
• Auto-accept only on the main branch; accepting on feature branches defeats review.
• For one-off screenshot comparison outside Storybook, use a general tool such as Percy or Playwright's built-in snapshot assertions.