Steph Huynh

● Design systems

June 2026 · CI tooling

Visual regression for Superbloom.

Superbloom stories are the visual contract for this site. I added Argos so every pull request gets screenshot comparisons in light and dark mode before changes land. This post is the workflow record. Setup details live in the visual testing guideline.

Design systemsStorybookVisual testingCI

Scope

Superbloom Storybook stories

Stack

Storybook, Vitest, Playwright, Argos

Coverage

Light and dark mode per story

Trigger

GitHub Actions on pull requests and main

Why add it

Superbloom already had Storybook stories and a Vercel deploy. Visual regression closes the loop so token and pattern changes do not slip through unnoticed.

Light and dark both matter here. A spacing tweak can look fine in one theme and wrong in the other.

The same stories power docs, the pattern library, and CI. One source of truth for how components should look.

What it is not

Argos does not replace Storybook for exploration or the Vercel deploy for browsing. It runs in CI, compares screenshots to approved baselines, and blocks merges when pixels change unexpectedly.

How it works

Each story renders in a real browser during CI. Argos does not pull from the public Storybook URL. It renders stories directly, which keeps results consistent.

  1. 01

    Render in CI

    Vitest runs each Storybook story in headless Chromium. Argos captures a screenshot after the story renders.

  2. 02

    Compare to baselines

    Uploads land in Argos with separate baselines per mode. Pixel changes surface on the pull request before merge.

  3. 03

    Review and approve

    Intentional visual updates get approved in the review UI. The GitHub check passes once diffs are resolved.

Screenshots

Exports from Argos and GitHub. Click to enlarge.

Light mode: primitives-button default story in the first build
Dark mode: same story captured with the dark global applied

What shipped

  • Argos Vitest plugin wired into the existing Storybook test project
  • Light and dark modes via Storybook globals in .storybook/modes.ts
  • GitHub Actions workflow: visual tests, Storybook build, deploy
  • Guideline doc under Superbloom for pipeline and local commands

Repo entry points

  • vite.config.ts argosVitestPlugin
  • .storybook/modes.ts light + dark
  • .github/workflows/argos.yml CI workflow