Understanding Storybook stories
One story per component state.
Why a Storybook entry is a development workflow, the CSF3 file shape, and the interaction-testing trick that replaces a third of unit tests.
Stories are components in isolation.
A Storybook story renders one component in one specific state, isolated from the rest of the app. The point: develop and review components without the mess of routing, auth, data fetching. A Button has stories for primary, secondary, disabled, loading, with-icon. Designers see them; QA reviews them; developers iterate against them. The same stories double as visual regression tests and component documentation.
CSF3 — Component Story Format.
The modern story file: import type { Meta, StoryObj } from "@storybook/react";
import { Button } from "./Button";
const meta = { component: Button } satisfies Meta<typeof Button>;
export default meta;
type Story = StoryObj<typeof meta>;
export const Primary: Story = { args: { children: "Click me", variant: "primary" } };
export const Disabled: Story = { args: { children: "Click me", disabled: true } }; The default export is the component's meta; named exports are individual stories. Args are the props for each story. TypeScript types flow through — arg typos become compile errors.
Decorators and parameters.
Decorators wrap every story in additional context — a theme provider, a router mock, an i18n provider. Parameters configure Storybook's chrome — the viewport sizes, the default background colour, the actions panel. Set them per-story, per-component (in meta), or globally (in preview.ts). The right granularity is "global for things every component needs, per-component for component-specific quirks".
A worked set of stories.
For a Button: Primary, Secondary, Destructive (the variant ladder); Disabled, Loading (the state ladder); WithIcon, IconOnly (the composition ladder). Six to eight stories cover the visual surface. Add an Interaction Test story (next section) for the hover/focus/click states. The combination is what designers and PMs see in code reviews — visible proof the component handles every state correctly.
Story ladders
variant + state + composition
Three orthogonal dimensions; one story per significant point.
3 variants × 2 states × 2 compositions ≠ 12 stories
= Pick the representative subset
Interaction tests.
Storybook 7+ lets stories include a play function — a Testing Library script that runs against the rendered story. Primary.play = async ({ canvasElement }) => {
const button = within(canvasElement).getByRole("button");
await userEvent.click(button);
expect(button).toHaveAttribute("aria-pressed", "true");
}; The story doubles as a behaviour test. Run via storybook test; results show in the Storybook UI and in CI. Replaces a meaningful chunk of unit-test surface area.
What Storybook isn't.
A replacement for end-to-end tests (Storybook can't drive the whole app). A replacement for visual design tools (Storybook renders code, not Figma). A documentation system on its own (use it as one but document the design system somewhere humans read). A project that runs Storybook well treats it as one of three or four collaboration surfaces, not the only one.