OperantAI Workflow Design System
ComfortableCompact

/storybook embeds a separately-running Storybook instance in an iframe — it is not part of the Next.js app's own build. The page itself (apps/web/app/(tool)/storybook/page.tsx) is a thin wrapper: it points an <iframe> at whatever URL NEXT_PUBLIC_STORYBOOK_URL resolves to, defaulting to http://localhost:6006 when that env var isn't set.

Running it locally

From the repo root:

npm run dev:storybook

This starts apps/storybook — a @storybook/react-vite catalog built straight from packages/ui/src (no prebuilt dist/ required; Vite compiles the TypeScript source live) — on http://localhost:6006. With that running alongside npm run dev, /storybook in the docs app will show the real catalog instead of a blank iframe.

In production

Storybook is deployed as its own small Vercel project (npm run build inside apps/storybook → storybook-static/), and NEXT_PUBLIC_STORYBOOK_URL in the main app's environment points at that deployed URL. See Architecture for the full deployment layout.

What it's for

Storybook is the isolated counterpart to the live app: instead of seeing a component inside a real page, you see it alone, with controls for every variant/state and, critically, a11y checks via @storybook/addon-a11y run against each story automatically. That makes it the fastest place to check a single component's states and accessibility in isolation, before it's composed into anything.

Coverage is one story file per @operant/ui component, colocated with its source, e.g. packages/ui/src/components/Button/Button.stories.tsx, packages/ui/src/components/Card/Card.stories.tsx, packages/ui/src/components/ApprovalBar/ApprovalBar.stories.tsx. Every component currently shipped in @operant/ui has a matching *.stories.tsx next to its implementation — see Architecture's "Component coverage" section for which components exist as React wrappers today versus CSS-only (backlog).

Storybook vs. Playground vs. Generator

  • Storybook — one real component at a time, every variant/state, a11y-checked. Best for verifying a component in isolation.
  • Playground — a full page/snippet you write yourself, live preview, both HTML and React modes. Best for composing several components together.
  • Generator — an AI writes the starting snippet for you from a prompt, which you can then open in the Playground to keep iterating.