Getting started

What you need

A Storybook is a collection of isolated component examples, called stories. Framecheck tests this built collection, rather than crawling a public website.

• A GitHub repository with a Storybook that builds to static files (for example with a build-storybook script)
• Storybook 8.6 or newer (tested with 8.6, 9 and 10). Storybook 7 is not supported.
• GitHub Actions, or another CI system that can run a Node.js command
• Permission to install a GitHub App on the repository, or an organisation owner who can approve it
• For Smart Snapshots, build Storybook with --stats-json (Storybook 8 or later, Vite builder), so pull requests capture only the stories they could change. Without it, every story is captured.

Don’t use Storybook yet? Set up Storybook first, or ask us whether your setup fits before creating an account.

What you connect and upload

Choose which repositories the GitHub App can access. Your CI builds Storybook and uploads the static files needed to render your stories, which can include compiled code, assets and fixture data. Use mock data and keep secrets and personal customer data out of stories.

Company members can access their project’s results. Links created by Open Storybook can be used by anyone holding the link until they expire, so share them carefully. Read the privacy notice for permissions, access and retention, or ask support before connecting.

Your first review

Open a run and select a changed story. Compare the previously approved image with the new image. Accept an intentional change; if the layout is broken, fix it in your code and run again. Accepting a change approves the new appearance—it does not repair the component.

Before uploading, make sure stories work without your local development server. Bundle fonts and images, mock external services and use predictable fixture data. Capture workers cannot use your local credentials or reach a service running only on your laptop.

Runs allow up to 5,000 visual snapshots across all screen sizes and browsers, with a 45-minute deadline. Accessibility adds billed checks without increasing that visual limit. Runs share capacity and can queue; paid runs take priority over trials. Estimate your run and monthly usage.

Open the story behind a screenshot

Use Live on a supported run to open the component example and inspect its behaviour, or Open Storybook to explore that uploaded build. These links use the saved Storybook, so external services still need to be available. This is separate from hosting Storybook on your own custom domain.

After setup

• Turn on accessibility checks in the project’s settings if you want them. Each check counts as a snapshot.
• Invite teammates by email, as viewers, members or admins.
• Top up your credit and set a spend limit from the company’s billing settings.

Already set up? Sign in

Unstable stories

When a changed story is captured a second time in the same run and that capture is different from the first and matches your accepted baseline, the change did not reproduce, so Framecheck puts the story in the Unstable group on the run page, labelled “not blocking”. It does not fail the pull request check, and the baseline keeps its previous image unless someone accepts it. You can still open, accept or reject it; a rejection fails the check as usual, and every decision on an unstable story is recorded in the audit log.

The second capture runs on the same worker seconds later: it shows the difference did not reproduce that time, not that the change can never be real. A story whose captures differ from each other but never match the baseline keeps blocking, and so does one that was not checked (for example because the run’s re-capture limit was used up: “Not checked for consistency”). A capture that was not made as requested (such as an unknown viewport) blocks whatever its stability. Automatic acceptance, “Accept all” and carried approvals never accept an unstable story.

Unstable stories and quarantine

The Unstable group is about one capture in one run and needs no setup. Quarantine is a standing project decision about a story that keeps being unstable: it applies to every run until an admin (or the automatic rule) releases it. A quarantined story is shown as quarantined, not in the Unstable group.

Making a story stable

The usual causes are the real clock, random values, JavaScript-driven animation, animated GIFs and data that arrives late. Mock the date and random values, pause animations in the story, and serve fixed data (for example with MSW) so every capture renders the same pixels.

Accessibility checks

Off until a company admin turns them on under Project settings → Accessibility. Every captured story is checked with axe-core for WCAG A and AA issues. Automated checks find some problems, not all, and are not a WCAG compliance certification.

Report only, unless you choose to block

New projects start in Report only: issues are listed on the run and the GitHub check, and the check never fails because of them. Choose Block pull requests to make new issues at or above the level you pick follow your PR check policy.

Your starting point is set automatically

The first complete run on your default branch becomes the accessibility baseline, including any issues it found (they are listed as known issues). This happens only when every story was checked and the run came from your default branch: uploaded from GitHub Actions without a token (OIDC), or, with an upload token, only when “Accept main automatically” is on and GitHub confirms the commit. An existing baseline is never replaced this way. The run says “Accessibility baseline set automatically from run #N”, and the audit log records it.

Before the baseline exists

Pull requests still list what they find, but nothing is compared and the accessibility part of the check is neutral under every policy: “accessibility baseline not set yet”. A branch that started before the baseline was set is treated the same way; merge or rebase your default branch into it to compare. Checks that could not finish still show as incomplete.