You spend all this time building a component library, documenting it in Storybook, and giving AI the rules. Then someone decides the orange button would look better in blue, asks an agent to change it, and opens a pull request. The code can work perfectly while the product starts looking like somebody else designed it.
I wanted to see what happens at that exact moment, so I deliberately changed a button in a product we’re building at The Design Project. I used Paper to explore the change, asked an agent to implement it, and took it through GitHub. Chromatic visual testing made the difference visible, and a required UI Review check gave me a place to stop it before merging.
That’s the part I’m excited about for teams designing and building with AI. Once your components are documented, you need a way to notice when the implementation moves away from them, with someone responsible for deciding whether that change belongs in the product.
Try this with your own repository: get our free Chromatic setup skill. It guides your coding agent through connecting Chromatic, configuring visual coverage, and verifying the setup.
Table of contents
- What is Chromatic visual testing?
- Why Storybook needs a review checkpoint
- Our test: changing an orange button to blue
- How to add Chromatic to your design workflow
- What visual regression testing can and cannot catch
- Get the Chromatic setup skill
- Watch the Chromatic walkthrough
What is Chromatic visual testing?
Chromatic visual testing compares screenshots of rendered UI with baseline snapshots to find appearance changes. With Storybook, those snapshots capture the component states your team has documented. Reviewers can inspect differences in color, spacing, typography, and layout, then decide whether to accept the change or ask for a correction.
Think about a shared button that appears throughout your product. A small style change can affect multiple places at once. Comparing the rendered states gives the team a way to see what changed before those differences reach users.
Storybook’s visual testing documentation explains how stories become tests and how the initial build establishes baseline snapshots. Your stories determine which component states are represented, so the quality of that coverage matters.
Why Storybook needs a review checkpoint
Storybook gives a team a shared reference for implemented components. A review checkpoint connects that reference to the changes people are proposing in code. Without that connection, someone can read the documentation, make a different styling decision, and carry on.
This is the next question I’ve been exploring after building and documenting components: how do we keep the work aligned when designers, engineers, PMs, and agents can all contribute? Asking AI to follow the component library helps, but I still want to inspect what it actually produces.
In our Paper and Storybook workflow, I used existing components to explore a voice-comment feature. Chromatic adds a checkpoint when that kind of exploration becomes a proposed implementation. It gives the person reviewing the work a concrete comparison to discuss.
The distinction that matters here is between detecting a difference and deciding whether it is appropriate. A new color might be an accidental override, or the team might have agreed to update the component. The screenshot comparison brings that decision into view.
Our test: changing an orange button to blue
I used the commenting flow in our feedback product for this test. The existing design had an orange button, and I changed it to blue in Paper. It was deliberately extreme (I wanted the difference to be obvious), but the situation behind it was familiar: someone working on a feature decides a component would look better another way.
Then I asked the agent to take the blue I had applied to the record button and use it in the flow’s code. The agent made the change, ran its checks, and we opened a pull request. That took the styling decision out of the design canvas and into the same review process we use for implementation.
Passing code checks still left a design decision
In this run, the automated workflow checks passed, while a separate, required UI Review remained waiting for approval. That was exactly the situation I wanted to explore: the implementation could get through its technical checks while someone still needed to consider how it looked.
From GitHub, I opened the review in Chromatic and inspected the before-and-after view. The original button was orange; the proposed version was blue. I could also toggle the highlighted diff to locate the changed area. The green overlay was a comparison aid, rather than the button’s actual color.
Giving the change a clear review outcome
As the designer reviewing it, I left feedback asking for the orange styling to be restored and withheld approval. Blue did not follow the component styling we had established. With the UI Review check required, that outstanding review kept the pull request from being ready to merge.
I also looked at a subtler button-style change, where the difference was easier to miss at a glance. That’s the more everyday value for me. The obvious blue button makes the process easy to understand; small changes to spacing or treatment are where a comparison becomes especially useful.
The result of this exercise was a visible change and a review decision before merge. I’d use it as a small test of your own setup: deliberately alter one covered component and confirm that the expected person has to review it.
How to add Chromatic to your design workflow
Start with a component your team already understands, establish its approved appearance, and test a deliberate change through a pull request. Work with engineering on the repository integration and required checks. These are the pieces I’d check before relying on the process for ongoing work.
- Choose the components and states you want to cover.
- Connect Chromatic and establish baseline snapshots.
- Run Chromatic on proposed changes through CI.
- Require the relevant review check before merging.
- Test the review process with one intentional visual change.
1. Choose the components and states you want to cover
Begin with shared UI that already has a clear design direction. Buttons, inputs, and the comment container were useful starting points for our example because we knew what they should look like. Include relevant states so you can inspect more than the default appearance.
If your library still needs that foundation, our Storybook guide for designers covers reviewing real components and making the library easier for the team and AI to use.
2. Connect Chromatic and establish baseline snapshots
Use Chromatic’s setup guide with your engineering team to connect the Storybook project and publish its first build. Inspect the initial snapshots. They should reflect the component styling your team intends to preserve.
Our setup skill can guide an agent through the repository work, but someone still needs to confirm the starting UI. An existing inconsistency can otherwise become part of the reference you keep comparing against.
3. Run Chromatic on proposed changes through CI
Connect the build to your continuous integration workflow so a proposed code change produces snapshots for review. The useful sequence is the one we tested: make the change, open a pull request, then inspect the rendered difference alongside the implementation.
Give reviewers enough context to understand the intent. “This updates the record button’s styling” is much easier to assess than opening a comparison and trying to guess why the component changed.
4. Require the relevant review check before merging
Installing Chromatic alone does not prevent a merge. Configure your Git provider’s branch protection or ruleset to require the relevant Chromatic check, and confirm that the corresponding check is enabled in Chromatic. Its mandatory PR checks guide covers that connection.
For the human sign-off shown in our example, enable Chromatic UI Review and decide who reviews the changes. The review tracks approval and outstanding discussions, while the Git provider enforces the merge requirement. Confirm both parts with engineering.
5. Test the review process with one intentional visual change
Change one covered component on a test branch, open a pull request, and follow the result through the review. Can the assigned reviewer see the difference? Does the required check remain unresolved while approval is outstanding? Can the contributor correct the styling and produce an updated comparison?
That small exercise tells you more than seeing a successful build. You’re checking whether the whole team can use the process, from the person proposing a change to the person responsible for approving it.
What visual regression testing can and cannot catch
Visual regression testing helps surface appearance changes in the UI you have covered. A screenshot difference still needs context: the reviewer has to understand whether the change is intentional, whether it follows the design system, and whether it makes sense for the product.
For the Storybook workflow described here, a screen or state that has no story is outside that story coverage. If you want to check application screens as well, define that coverage separately. Our setup skill supports choosing Storybook components, app screens, or both.
A visual comparison also leaves other questions open. Does recording actually work? What happens when microphone access is denied? Can someone operate the controls with a keyboard? Those need their own implementation and testing work alongside the appearance review.
What I like about this checkpoint is that it makes an established design decision visible again when someone changes it. We can keep experimenting with AI and new features while giving the team a clear moment to question a change before it becomes part of the product.
Get the Chromatic setup skill
We’ve packaged the setup into a free skill for Claude Code, Codex, Cursor, and other coding agents that can work in your repository. It guides the agent through inspecting the project, choosing coverage, connecting Chromatic, configuring CI, and verifying real cloud builds.
Open the resource page and enter your name and email to access the skill on GitHub. Start with one component or flow, review the first snapshots with your team, and try the deliberate-change test before expanding coverage.
Get the free Chromatic setup skill and add a visual review checkpoint to your product workflow.
Related reading
- Paper and Storybook: Design new features from your codebase
- Storybook for designers: Review real UI and help AI reuse it
- Figma to Storybook: Build a component library AI can use
- Agent skills: stop re-teaching AI your design system
