Storybook

Overview

Storybook is the standard tool for developing, documenting, and testing UI components in isolation. Components are rendered in "stories" — declarative examples that showcase every state. Storybook supports React, Vue, Angular, Svelte, Web Components, and more.

CSF3 — Component Story Format 3

CSF3 is the default story format since Storybook 7. Stories are plain objects with args, reducing boilerplate:

// Button.stories.tsx
import type { Meta, StoryObj } from "@storybook/react";
import { Button } from "./Button";

const meta = {
  component: Button,
  parameters: { layout: "centered" },
  argTypes: {
    variant: {
      control: "select",
      options: ["primary", "secondary", "ghost"],
    },
    size: {
      control: "radio",
      options: ["sm", "md", "lg"],
    },
  },
} satisfies Meta<typeof Button>;

export default meta;
type Story = StoryObj<typeof meta>;

export const Primary: Story = {
  args: {
    variant: "primary",
    children: "Click me",
  },
};

export const Secondary: Story = {
  args: {
    variant: "secondary",
    children: "Click me",
  },
};

export const Disabled: Story = {
  args: {
    ...Primary.args,
    disabled: true,
  },
};

CSF Factories (Experimental)

CSF Factories provide full type inference through a factory function chain — no manual type annotations needed:

// .storybook/preview.ts
import { definePreview } from "@storybook/react";
import addonA11y from "@storybook/addon-a11y";

export default definePreview({
  addons: [addonA11y()],
  parameters: {
    layout: "centered",
  },
});

// Button.stories.tsx
import preview from "#.storybook/preview";
import { Button } from "./Button";

const meta = preview.meta({
  component: Button,
  argTypes: {
    variant: { control: "select", options: ["primary", "secondary"] },
  },
});

export const Primary = meta.story({
  args: { variant: "primary", children: "Click me" },
});

export const Secondary = meta.story({
  args: { variant: "secondary", children: "Click me" },
});

Subpath Imports

CSF Factories use subpath imports for stable references. Add to package.json:

{
  "imports": {
    "#*": ["./*", "./*.ts", "./*.tsx"]
  }
}

Play Functions

Play functions add automated interactions to stories — simulating clicks, typing, and assertions:

import { expect, fn, userEvent, within } from "@storybook/test";

export const SubmitForm: Story = {
  args: {
    onSubmit: fn(),
  },
  play: async ({ canvasElement, args }) => {
    const canvas = within(canvasElement);

    // Type into the input
    await userEvent.type(canvas.getByLabelText("Email"), "user@example.com");

    // Click the submit button
    await userEvent.click(canvas.getByRole("button", { name: "Submit" }));

    // Assert the callback was called
    await expect(args.onSubmit).toHaveBeenCalledWith("user@example.com");
  },
};

Play Function API

Args and ArgTypes

Args are the dynamic inputs to a story. ArgTypes control how Storybook renders controls in the UI:

const meta = {
  component: Card,
  argTypes: {
    title: { control: "text" },
    elevation: { control: { type: "range", min: 0, max: 5 } },
    variant: { control: "select", options: ["outlined", "filled"] },
    showHeader: { control: "boolean" },
    padding: { control: "number" },
    onClick: { action: "clicked" },
  },
} satisfies Meta<typeof Card>;

Control Types

Interaction Testing

Play functions double as interaction tests when run via the Storybook test runner:

# Install test runner
npm install -D @storybook/test-runner

# Run all interaction tests
npx test-storybook

# Run in CI (requires a running Storybook)
npx test-storybook --url http://localhost:6006

Decorators

Decorators wrap stories with context — providers, layouts, themes:

const meta = {
  component: ProfileCard,
  decorators: [
    (Story) => (
      <ThemeProvider theme="light">
        <div style={{ padding: "1rem" }}>
          <Story />
        </div>
      </ThemeProvider>
    ),
  ],
} satisfies Meta<typeof ProfileCard>;

Parameters

Parameters configure addons and story behavior:

export const Mobile: Story = {
  args: { children: "Hello" },
  parameters: {
    viewport: { defaultViewport: "mobile1" },
    backgrounds: { default: "dark" },
    a11y: { config: { rules: [{ id: "color-contrast", enabled: true }] } },
  },
};

Key Addons

Storybook Configuration

// .storybook/main.ts
import type { StorybookConfig } from "@storybook/react-vite";

const config: StorybookConfig = {
  framework: "@storybook/react-vite",
  stories: ["../src/**/*.stories.@(ts|tsx)"],
  addons: [
    "@storybook/addon-a11y",
    "@storybook/addon-interactions",
  ],
};

export default config;

Commands

# Start dev server
npx storybook dev -p 6006

# Build static site
npx storybook build -o storybook-static

# Run interaction tests
npx test-storybook

# Initialize in an existing project
npx storybook@latest init

Best Practices

• Write a story for every meaningful component state — default, hover, disabled, loading, error, empty.
• Use play functions for interaction tests so tests live alongside the stories they verify.
• Use args inheritance (...Primary.args) to build story variants without duplication.
• Add argTypes with controls so designers and PMs can explore component variations without code.
• Use decorators for providers (theme, i18n, router) rather than wrapping every story manually.
• Add the @storybook/addon-a11y addon and leave it enabled by default for continuous accessibility checks.
• Run test-storybook in CI to catch interaction regressions on every PR.
• Use @storybook/addon-designs to embed Figma frames next to stories for easy comparison.