Auditing a Component Library or Storybook for Visual Drift with the Compare API

A shared button, input, or card component changing shape usually gets noticed first at the page level — a pricing page looks slightly off, a form feels misaligned — long after the actual change happened in the component itself. By the time it's caught, tracing it back to "which component, which commit" takes real digging.

Catching drift at the component level, instead of the page level, means diffing components directly against a stored baseline, and Storybook — which already isolates each component on its own URL — makes this straightforward with the Visual Diff API.

Why Component-Level Diffing Is Different From Page-Level Diffing

A full-page diff (covered in Visual Diff API for QA, Release Reviews, and Web Change Monitoring) tells you a page changed, but a page is made of dozens of components — the diff doesn't tell you which one moved, or whether the same regression is quietly present on twenty other pages that use the same component. Diffing each component's isolated Storybook story directly points at the actual source.

Capturing a Component's Storybook Story

Storybook gives each story its own URL, typically something like ?path=/story/button--primary. Capture it the same way as any other page:

curl --request POST \
  --url https://api.prod.ss.snapshot-site.com/api/v1/screenshot \
  --header 'Content-Type: application/json' \
  --header 'x-snapshotsiteapi-key: YOUR_API_KEY' \
  --data '{
    "url": "https://storybook.example.com/iframe.html?id=button--primary",
    "format": "png",
    "width": 400,
    "height": 200,
    "fullSize": false
  }'

Using Storybook's iframe.html URL (rather than the full Storybook UI shell) captures just the rendered component, without the sidebar and toolbar around it. A small, fixed width/height matching the component's expected size is usually more useful here than fullSize — components don't need scrolling.

Diffing Against a Stored Baseline

The same pattern from Comparing a Live Page Against a Design Mockup applies directly, just at component scale:

curl --request POST \
  --url https://api.prod.ss.snapshot-site.com/api/v3/compare \
  --header 'Content-Type: application/json' \
  --header 'x-snapshotsiteapi-key: YOUR_API_KEY' \
  --data '{
    "before": {"imageUrl": "https://cdn.example.com/baselines/button-primary.png"},
    "after": {"url": "https://storybook.example.com/iframe.html?id=button--primary", "width": 400, "height": 200},
    "threshold": 0.05
  }'

A tighter threshold makes sense at this scale than for a full page — a component is small and mostly static, so there's less legitimate pixel noise (no rotating testimonials or live timestamps) to account for. See Tuning the threshold Parameter if a tighter setting starts producing false positives on a specific component.

Running This Across an Entire Component Library

Most Storybook setups expose a stories.json or an equivalent index listing every story's ID. Loop over that list, capturing and comparing each one against its stored baseline, and you get a full component-library health check in one run rather than a spot check on whichever components someone happened to notice.

Wiring It Into CI

This pairs naturally with a pull request check, the same pattern covered in Automating Visual Regression Checks in GitHub Actions — run the component sweep on every PR that touches the design system package, and a shared-component regression gets caught before it ships to every page that uses it, not after.

For the page-level version of this same discipline, see Visual Regression Testing for Marketing Sites Without Browser Engineering.

Design system drift is easier to catch — and much easier to trace back to its source — when the diff happens at the same scale the component actually lives at, and Snapshot Site runs that check the same way whether it's one component or the whole library.