Chromatic for Designers: Visual Testing for Storybook Components

Chromatic is visual testing infrastructure built specifically for Storybook. It captures pixel-perfect screenshots of every component state, compares them to your last approved version, and flags visual differences before they reach production. Made by the team behind Storybook, it’s designed to catch the UI bugs that slip through code reviews: layout shifts, broken styles, and unintended visual side effects.

Key Specs

How Designers Use Chromatic

Chromatic shifts visual QA from manual screenshots to automated reviews. Here’s how designers integrate it into their workflow.

For Approving Component Changes

When developers modify a component, Chromatic captures new screenshots and shows you a side-by-side diff of what changed. You review each diff in the web dashboard: approve if it matches the design intent, reject if it’s a regression. Approved changes become the new baseline. This replaces the old workflow of manually checking staging servers or test environments.

For Catching Unintended Side Effects

Change one component and accidentally break another? Chromatic catches this. Since it tests every component in Storybook on every build, you see all visual changes across your entire system, not just the one component a developer thought they were touching. This is critical for design systems where components share styles and tokens.

For Design System Maintenance

As your design system evolves, Chromatic creates a visual history of every change. Need to know when that button’s padding changed? Check the Chromatic timeline. This audit trail is valuable for understanding how components evolved and for debugging why something looks different than expected.

For Collaborating with Developers

Chromatic bridges designer-developer communication. Instead of describing a visual bug in Slack (“the spacing looks off”), you comment directly on the Chromatic diff. Developers see exactly what needs fixing with pixel measurements and browser details. No more “works on my machine” debates.

Chromatic vs. Alternatives

How does Chromatic compare to other visual testing tools? Here’s a quick breakdown.

Choose Chromatic if: You already use Storybook and want the tightest integration with the least setup. It’s built by the Storybook team, so updates stay in sync.

Choose Percy if: You need visual testing for full pages, not just components, or want AI to ignore unimportant changes like dynamic content.

Choose Applitools if: You need advanced features like cross-browser testing, accessibility checks, and AI-powered maintenance of test baselines.

Choose manual QA if: You have a small project, don’t use Storybook, or need full context of user flows that component-level testing can’t provide.

Getting Started with Chromatic

A 10-minute quick start to get visual testing running:

Step 1: Connect your Storybook

Sign up at chromatic.com using your GitHub account. Run npx chromatic --project-token=<your-token> in your project directory. This publishes your Storybook to Chromatic’s servers and captures initial baseline screenshots. Your developers typically handle this step, but it’s a one-line command.

Step 2: Accept baseline snapshots

In the Chromatic dashboard, you’ll see snapshots for every story in your Storybook. Click “Accept all” to set these as your baseline. Future builds compare against these approved snapshots. Review them carefully: this baseline becomes your source of truth.

Step 3: Review your first changes

Make a change to a component (or have a developer make one), then run another Chromatic build. You’ll see visual diffs for any component that looks different. Approve changes that match design intent, reject bugs. Chromatic integrates with GitHub status checks, so rejected builds block merging until fixed.

Chromatic in Your Design Workflow

Chromatic works alongside tools designers already use. Here’s how it connects to the broader design process.

• Before Chromatic: Designing in Figma, documenting specs in Notion, building components in Storybook
• During review: Chromatic for visual diffs, GitHub for code review, Slack for team discussion
• After approval: Deployed to staging, tested in full context, released to production

Common tool pairings:

• Chromatic + Storybook for component development and visual testing (required pairing)
• Chromatic + Figma to compare live components against design specs
• Chromatic + GitHub for automated checks that block merges if visual tests fail
• Chromatic + Slack for notifications when new builds need designer review

Common Problems (and How to Fix Them)

These issues come up regularly when teams adopt visual testing. Here’s how to solve them.

“Too many false positives”

Anti-aliasing, dynamic content, and animation timing cause snapshots to differ even when nothing meaningful changed. Fix this by adding data-chromatic=”ignore” attributes to elements with dynamic content, using consistent test data, and disabling animations in Storybook. Chromatic also offers delay settings to wait for content to load before capturing.

“My snapshot limit is too low”

Each component state in each viewport counts as one snapshot. A button with default, hover, and disabled states at mobile and desktop breakpoints is 6 snapshots. Multiply by every component and builds add up fast. Prioritize testing core components over every edge case. Use Storybook’s play functions to test interactions without creating separate stories.

“Designers aren’t reviewing builds”

If Chromatic sits unreviewed, it becomes useless. Make it part of your pull request checklist: “Has the Chromatic build been reviewed?” Set up Slack notifications for new builds. Some teams assign a rotating “visual QA reviewer” each sprint. Treat it like code review: required, not optional.

“Changes look fine in Chromatic but broken in production”

Chromatic tests isolated components, not full pages with real data and user interactions. It catches styling bugs but misses layout issues that only appear in context. Use Chromatic for component-level testing, but still do end-to-end QA on staging before releasing. Think of Chromatic as catching 80% of visual bugs early, not replacing all testing.

“Chromatic builds are too slow”

Large Storybooks with hundreds of stories take 10+ minutes to build. Speed it up by using TurboSnap, which only tests components that changed instead of everything. Split your Storybook into multiple smaller Storybooks if you have distinct product areas. Reduce viewports and states you’re testing to only what matters.