How to Test Visual Designs in Storybook and Figma

Test visual designs by turning important interface states into Storybook stories, comparing their rendered pixels with approved baselines, and reviewing each change before accepting it. Use Figma integrations to keep the design reference beside the implementation. Run checks during development and in CI before merging. A visual diff finds changes in appearance; it does not prove that behavior or accessibility is correct.

Storybook describes the basic check this way: “Visual tests compare the rendered pixels of every story against known baselines.” The baseline is an agreed appearance to compare against, not a guarantee that the design itself is correct. [Storybook visual testing documentation]

1. Decide what you need to compare

There are two related but different jobs:

Visual regression testing: compare a rendered story with an accepted earlier screenshot to detect unintended appearance changes.
Design comparison: view the Figma design alongside the rendered implementation to judge whether it matches the intended design.

A markup snapshot compares rendered HTML. A visual test compares pixels. Neither replaces interaction tests, which exercise behavior, or accessibility checks, which evaluate accessibility concerns. Use each method for the question it can answer.

2. Prepare Storybook stories as visual test cases

A story is a repeatable UI state. Build stories for the components and states whose appearance matters, rather than relying on one default view. Include meaningful variants and states that have caused regressions or are important to the design.

Identify the components and screens that need visual review.
Create stories for their relevant variants and states. Keep data and setup stable so reruns render the same intended state.
Decide which browsers, viewports, and themes represent your supported experience. Include combinations that matter to users and your design system.
Check your Storybook version and project setup against the current integration requirements.

Storybook’s visual testing guide recommends a development feedback loop paired with CI checks. The @chromatic-com/storybook addon listing states that it requires Storybook 7.6 or later and access to a Chromatic project; verify the current requirements before installing because setup details can change. [Storybook visual testing] [Addon listing]

3. Set up baseline comparison with Storybook

For the documented Storybook and Chromatic workflow, install and configure the official addon, connect the project to Chromatic, and create an initial baseline build. Follow the current installation steps in Storybook’s documentation: package setup and project linking can vary by project and version, so copy the commands for your specific setup rather than relying on a version-independent snippet.

Confirm that the project meets the addon’s current Storybook version and access prerequisites.
Install and configure @chromatic-com/storybook using the official guide.
Link the Storybook project to Chromatic and publish an initial build to establish the starting baseline.
Run visual tests as stories change. Inspect the flagged visual diffs rather than treating every detected pixel change as a defect.
If a change is intended and approved, accept it as the new baseline. If it is unintended, fix the implementation or story and rerun the comparison.
Run the checks in CI before merging. Review the UI Tests check for errors or changes needing review; teams can make the provider check required for merge according to their repository policy.

Acceptance records approval of a new appearance. It does not independently establish that the result matches Figma or that it is usable. Have the appropriate reviewer assess intentional changes.

4. Connect Figma designs and Storybook stories

Storybook documents two integration directions. Choose based on where the team wants to see the reference.

Show a Figma design in Storybook

Add a design parameter to the story and provide the Figma URL, following Storybook’s integration guide. This lets a reviewer see the design reference alongside the implementation. Use the Figma URL for the intended frame or design reference and confirm that reviewers have access.

Show a published Storybook story in Figma

Use the Storybook Connect Figma plugin to link stories to Figma components, variants, and instances. The documented workflow requires a Storybook published to Chromatic:

Publish the Storybook to Chromatic.
Choose the branch to link and copy the story URL.
Paste the URL into the Storybook Connect plugin in Figma and associate it with the appropriate component or variant.

Storybook says linked stories reflect later publishes on that branch. Connect does not support linking stories to Figma layers. Check the official guide for current plugin setup and access requirements. [Storybook design integrations]

5. Review changes consistently

For each detected difference, decide whether it is intended, whether it matches the design reference, and who approves the updated appearance. Keep the review focused on the changed area and its context.

Intended change: compare it with the relevant design, obtain the team’s approval, then accept the new baseline.
Unexpected change: inspect the story and implementation, correct the regression, and rerun the comparison.
Unclear change: do not accept it just to clear the check; ask the design or component owner to review the Figma reference and rendered state.

Set team rules for baseline approval and CI merge requirements. Explicit ownership makes it clear who can approve a design change and prevents an unexplained diff from becoming the new expected appearance.

6. Choose a comparison approach

Approach	Best for	Key requirement or limit
Storybook visual tests	Finding regressions against accepted rendered baselines and reviewing changes in development or CI.	Requires representative stories, a baseline workflow, and human review of detected changes.
Figma design embedded in Storybook	Keeping the design reference close to the implementation during review.	Reviewers need access to the linked design; it does not by itself perform baseline regression testing.
Storybook Connect in Figma	Opening published implementation stories from linked Figma components, variants, or instances.	Documented workflow requires a Storybook published to Chromatic; Figma layers are not supported.
Third-party Storybook Addon Figma Sync	An in-browser overlay or side-by-side design comparison, if its current capabilities fit the project.	The addon directory listing describes overlay, side-by-side, and pixel-diff features. Verify maintenance, compatibility, and Figma access requirements before adopting it; these are the addon’s claims, not independent validation. [Addon listing]

Before choosing, compare the purpose, workflow location, required story and viewport coverage, review governance, Storybook version, Chromatic access or publishing requirements, and compatibility of any third-party addon.

7. Troubleshooting visual tests and design links

Symptom	Likely cause	What to do
A visual test flags a difference after a change.	The rendered appearance changed; this may be an intended update or an unintended regression.	Inspect the diff against the story and relevant Figma design. Accept only an intentional, reviewed change; otherwise fix the implementation or story and rerun.
A story’s screenshots vary between runs.	The story or its rendering setup may not be repeatable, or the chosen browser, viewport, or theme may not match the intended coverage.	Review story state and project configuration, then confirm the browser, viewport, theme, and current addon setup in the project documentation.
The addon cannot be installed or configured.	Storybook version, project access, or setup may not meet the current prerequisite.	Check the current official addon listing and setup guide. The listing states Storybook 7.6 or later and a Chromatic project as prerequisites; verify that these remain current.
The Connect plugin cannot find or update a story.	The Storybook may not be published to Chromatic, the wrong branch or story URL may be selected, or access may be missing.	Confirm the published Storybook, select the branch to link, copy the correct story URL, and check Figma access. The documented workflow does not link Figma layers.
A visual diff passes but the component behaves incorrectly.	Visual comparison checks appearance, not interaction behavior.	Add or run interaction tests for behavior and accessibility checks for accessibility; a pixel comparison does not establish either.
A Figma overlay addon is incompatible or stale.	Third-party addon maintenance, compatibility, or Figma access requirements may have changed.	Check its current listing and project compatibility before relying on it; use documented Storybook integrations when they meet the review need.

8. Performance, reliability, and cost considerations

Visual testing coverage grows with the stories and environment combinations you choose. Start with the important states and supported browser, viewport, and theme combinations, then expand when a user experience or regression risk justifies it. The sources reviewed for this guide provide no current, verified benchmark or pricing figures, so estimate runtime and cost for your own project from the provider’s current documentation.

Reliability depends on repeatable story states, an agreed baseline, and a review path for changes. Pair local checks with CI checks before merge, and decide whether the provider’s check is required. Recheck version requirements and integration behavior when updating Storybook, Chromatic setup, or third-party addons.

9. Capture a rendered design reference

When a review needs a standalone capture of a rendered Storybook page or other URL, ScreenshotNeo provides a screenshot API and MCP server. It complements Storybook visual testing: a captured image can document a rendered reference, while the Storybook baseline workflow handles repeatable story comparisons and review.

Or skip the browser setup

Make a GET request with the page URL to receive a screenshot. The API supports PNG, JPEG, WebP, or PDF output; see the ScreenshotNeo API documentation for output and capture options.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://storybook.js.org -o shot.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://storybook.js.org"},
    timeout=90,
)
r.raise_for_status()
with open("shot.webp", "wb") as f:
    f.write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://storybook.js.org' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
const image = Buffer.from(await res.arrayBuffer());
await import('node:fs/promises').then(fs => fs.writeFile('shot.webp', image));

Cookie banners, newsletter popups, and chat widgets are removed before the shot. Bot checks, blank pages, and failed loads are never billed; response headers identify the page verdict and billing status. An MCP server gives AI agents tools to take screenshots, inspect page information, and capture PDFs. The free plan includes 1,000 screenshots per month with no card, and paid plans start at $5 for 3,000. See ScreenshotNeo for the product details.

FAQ

Does a passing visual test mean the design is correct?

No. It means the rendered pixels match the accepted baseline within the configured workflow. Review against the design reference and use separate checks for behavior and accessibility.

Can Storybook Connect link a Figma layer?

No. Storybook’s documented Connect plugin workflow supports linking stories to components, variants, and instances, but not Figma layers.

Do I need Chromatic to view a Figma design in Storybook?

The documented Figma-in-Storybook integration uses a design parameter and Figma URL. The separately documented Connect workflow, which links published stories from Figma, requires a Storybook published to Chromatic.

How often should baselines be updated?

Update a baseline when a visual change is intentional and reviewed. Do not update it merely to clear an unexplained difference.