storybook

name	storybook
description	Use when documenting, developing, or testing UI components with Storybook. Covers CSF3, CSF Factories, play functions, Args, interaction testing, and addon configuration. USE FOR: Storybook stories (CSF3 and CSF Factories), play functions, Args and ArgTypes, interaction testing, Storybook addons, visual regression testing, component documentation DO NOT USE FOR: design token authoring (use design-tokens), token transformation (use style-dictionary), Figma design handoff (use figma), cross-framework component compilation (use mitosis)
license	MIT
metadata	{"displayName":"Storybook","author":"Tyler-R-Kendrick"}
compatibility	claude, copilot, cursor
references	[{"title":"Storybook Official Documentation","url":"https://storybook.js.org/docs"},{"title":"Storybook — GitHub Repository","url":"https://github.com/storybookjs/storybook"}]

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"), "[e-mail]");

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

    // Assert the callback was called
    await expect(args.onSubmit).toHaveBeenCalledWith("[e-mail]");
  },
};

Play Function API

Import	Description
within(element)	Scoped Testing Library queries
userEvent.click(el)	Simulate click
userEvent.type(el, text)	Simulate typing
userEvent.selectOptions(el, value)	Select dropdown option
userEvent.keyboard(keys)	Simulate keyboard input
expect(value)	Jest-compatible assertions
fn()	Create a spied function (like jest.fn())
waitFor(callback)	Wait for async conditions

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

Control	Type	Description
text	string	Text input
boolean	boolean	Checkbox toggle
number	number	Number input
range	number	Slider with min/max
select	enum	Dropdown
radio	enum	Radio buttons
color	string	Color picker
date	Date	Date picker
object	object	JSON editor

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

Addon	Purpose
@storybook/addon-a11y	Accessibility audits (axe-core)
@storybook/addon-viewport	Responsive viewport simulation
@storybook/addon-backgrounds	Background color switching
@storybook/addon-actions	Log callback invocations
@storybook/addon-docs	Auto-generated documentation
@storybook/addon-interactions	Step-through play function debugger
@storybook/addon-designs	Embed Figma frames alongside stories

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.