Deterministic Storybook stories

Mental model — Storybook already removed most of the flake

UI Verify renders each story as a baseline. Because a story is an isolated component in a controlled
harness, you get for free the things that make real-page capture hard: no page scroll, no A/B / analytics
/ chat / consent scripts, no lazy-load-on-scroll races. That isolation is the point — the determinism
work here is narrow. If you reach for scroll-settling or third-party stubbing, you're fighting a
problem Storybook already removed; that's a real-page concern (see playwright-visual-testing).

UI Verify's capturer also neutralizes these automatically — do NOT hand-fix them:

• CSS animations & transitions (killed at render), and the Web Animations API (disabled).
• prefers-reduced-motion: reduce — emulated, so any component that honors it renders its calm state.
• Math.random — seeded before your app code runs (a shuffle/jitter driven by Math.random is

already stable).

• Web fonts and <img> loading — waited for before capture (the fonts your story actually loads; see

the preview.ts setup below).

• Finite JS animations (a Recharts entry draw, react-smooth) — captured at their settled final frame.

You don't need to disable these.

So the checklist below is only the remainder — what lives inside your app and can't be fixed from
outside it. And like Vitest browser mode (vitest-visual-testing) and unlike a real page, a story has
no SSR — no server-rendered random pick to reconcile.

The headline: freeze the data. Once the list above is off the table, the one thing left that floods a
story suite with false "changes" is live/dynamic data — star counts, follower counts, contributor
lists, tiles, timestamps. Give every story static args / fixtures and that entire class disappears at
the source: static data can't churn run-to-run, so there is nothing to diff. This is the single
highest-value determinism step here — do it first (step 1), and most stories need nothing else.

Load your app's global CSS + fonts in .storybook/preview.ts. A story renders an isolated component,
so anything your real app loads in its entry/layout — the global stylesheet, an icon-font CSS
(bootstrap-icons) — has to be imported in preview.ts (which loads once for every story) or the story
captures with fallback fonts / tofu glyphs:

// .storybook/preview.ts
import 'bootstrap-icons/font/bootstrap-icons.css';
import '../src/styles/globals.css';

Import fonts from a package or a same-origin asset (not a CDN <link> in preview-head.html), so the
archive captures the bytes. The capturer waits for these like any other font — but only ones the story
actually loads; it can't declare a font you never imported. Rule of thumb: if a story renders right in
your local Storybook, its fonts are already in the build.

Point UI Verify at your built stories:

npm run build-storybook && uiverify upload --static-dir storybook-static

The checklist (only what the tool can't do for you)

1. Freeze the data — the one that actually matters

A story fed live/dynamic data is flaky by construction: the stars, followers, contributor list, tile
order, and timestamps move between runs, so the diff lights up with no code change. Give every story
static args/fixtures and the whole class is gone. Never let a story hit a real backend.

Concrete — fixed, ordered, complete data:

• fixed counts (stars, followers, downloads) — literal args, not a live fetch;


• a fixed contributor/author list: fixed names and avatar URLs (or inlined avatars), in a fixed

order;

• a fixed set of tiles/rows in a fixed order (a live "trending" sort reorders every run);


• fixed timestamps (pair with the clock, step 2).

Two ways to inject them, both fine:

• args — the Storybook-native path: pass the component's data as fixed args on the story;


• mock the fetch — when a story fetches internally, [MSW via msw-storybook-addon](https://storybook.js.org/addons/msw-storybook-addon)

returns the same response every time.

One component per story file, every variant × state in one story where you can — cheaper and easier
to eyeball than N near-identical stories. Keep each in its own file so unchanged ones are skipped,
and add a path filter so the visual job only runs on UI PRs.

2. Freeze the clock

The one thing the capturer deliberately does not do (freezing time breaks entry animations). Any
component that reads the clock — a relative timestamp, a date picker defaulting to "today", a chart's day
axis — drifts every run. Pin it with
[storybook-addon-mock-date](https://www.npmjs.com/package/storybook-addon-mock-date) (Storybook 10+),
which mocks Date per story:

// .storybook/main.ts
addons: ['storybook-addon-mock-date'],

// .storybook/preview.ts — a fixed date for every story (meta- or story-level overrides it)
export default { parameters: { mockingDate: new Date('2020-01-01T00:00:00Z') } };

Pass a Date, a millisecond timestamp, or an ISO string as mockingDate; the most specific value
(story > meta > preview) wins, so a single story can pin its own "today". On older Storybook, install
[@sinonjs/fake-timers](https://github.com/sinonjs/fake-timers) in a decorator instead
(install({ now: FROZEN_NOW })) — it covers Date, Date.now, and timers in one call.

3. Infinite JS animations

A CSS/WAAPI/finite animation is handled for you (above). What's left is an infinite JS loop that
never has a final frame — framer-motion pulsing dots, a Lottie loop, an autoplay spinner, or a
<canvas> / requestAnimationFrame loop (which no media query can reach). Two fixes:

• Preferred — honor reduced motion. The capturer emulates prefers-reduced-motion: reduce, so make

the component respect it. framer-motion ignores it by default (reducedMotion: "never"); opt in:

  // .storybook/preview.tsx decorator
  <MotionConfig reducedMotion="user"><Story /></MotionConfig>

or gate the loop yourself with useReducedMotion(). One line, and it's good app behavior anyway.

• Escape hatch — detect the capture and render the end state. UI Verify flags every capture with a

UIVerify marker on the user-agent and a window.__UI_VERIFY__ global, so a component can branch:

  export const isUIVerify = () =>
    (typeof navigator !== 'undefined' && navigator.userAgent.includes('UIVerify')) ||
    (typeof window !== 'undefined' && '__UI_VERIFY__' in window);

  <RadarChart isAnimationActive={!isUIVerify()} />

Prefer pausing at the end frame, not the start. For a hand-rolled <canvas> rAF loop the same branch applies: if (isUIVerify()) drawOneStaticFrame(); else startRaf(); in the component's effect.

4. Non-Math.random randomness

Math.random is seeded for you, but crypto.randomUUID(), a uuid library, or faker are not. Use
fixed fixtures for anything that ends up on screen (an id in the DOM, a faker name), or set a fixed faker
seed.

5. Dynamic layout

A JS-measured layout that reflows or reorders on its own (packing driven by measured size, a shuffled
list) can vary run-to-run even with identical content. Force a deterministic variant in the story (a
fixed order/size), or mask the region (step 6).

6. Mask what you can't pin

Last resort for content that is supposed to differ and can't be pinned at the source (a third-party
embed, a map, an ad slot, a live feed): add data-uiverify-ignore to the element. UI Verify paints
its box solid black on every capture, so its content never reaches the diff. The box's size and position
still diff (give it a fixed size), and nothing inside it is checked, so mask only what you can't pin and
fix what you own. [Docs](https://uiverify.ai/docs/ignore-regions).

<aside data-uiverify-ignore style={{ width: 320, height: 256 }}><AdSlot /></aside>

Anti-patterns

• A story that fetches live data → mock it (MSW).
• Disabling CSS animations / seeding Math.random / waiting on fonts by hand → wasted effort; the

capturer already does all three. Spend the effort on the clock and infinite loops.

• Unseeded crypto/uuid/faker or a bare Date.now() → fixtures + freeze the clock.
• Reaching for scroll-settle / A-B stubbing → wrong path; that's a real-page concern.