Storybook Patterns

Quick Guide: Storybook is a component workshop for building and documenting UI in isolation. Use CSF 3.0 format with typed meta and story objects. Define component variants via args. Use play functions for interaction testing. Enable autodocs for automatic documentation. Configure addons in .storybook/main.ts.

<critical_requirements>

CRITICAL: Before Using This Skill

All code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering, import type, named constants)

(You MUST use CSF 3.0 format with satisfies Meta<typeof Component> for type-safe story metadata)

(You MUST define a default meta export with component property - stories without component won't render)

(You MUST use args for defining props - NOT rendering components with hardcoded props)

(You MUST use play functions with @storybook/test utilities for interaction testing - NOT custom event firing)

(You MUST use named exports for stories - default export is reserved for meta object)

</critical_requirements>

Auto-detection: Storybook, .stories.tsx, .stories.ts, CSF, Component Story Format, meta, Meta, StoryObj, args, argTypes, play function, autodocs, @storybook/test, @storybook/addon-essentials

When to use:

• Developing UI components in isolation without full application context
• Creating interactive documentation for component libraries
• Testing component interactions and visual states
• Building design systems with comprehensive examples
• Generating automatic API documentation from TypeScript props
• Visual regression testing

When NOT to use:

• E2E user flow testing spanning multiple pages (use your E2E tool)
• Unit testing pure functions without UI (use your test runner directly)
• Integration testing with real backend services
• Performance testing and load testing

Key patterns covered:

• CSF 3.0 story format with TypeScript
• Args and ArgTypes for props control
• Play functions for interaction testing
• Autodocs for automatic documentation
• MDX for custom documentation pages
• Decorators and parameters
• Addon configuration and customization
• Visual testing integration

Detailed Resources:

• For code examples, see examples/ folder:
  • examples/core.md - CSF 3.0 format, args, controls
  • examples/docs.md - Autodocs, MDX documentation
  • examples/testing.md - Play functions, interaction testing
  • examples/addons.md - Addon configuration
• For decision frameworks and anti-patterns, see reference.md

Philosophy

Storybook enables component-driven development - building UI from the bottom up, starting with basic components and progressively combining them into complex interfaces.

Core Principles:

1. Isolation - Develop components without needing the full application, database, or authentication
2. Documentation - Stories serve as living documentation that stays in sync with code
3. Testing - Use stories as test fixtures for interaction, visual, and accessibility testing
4. Collaboration - Designers, developers, and stakeholders can review components independently

The Story Paradigm:

A "story" captures a specific state of a component. Each story represents one meaningful variation - a button's primary state, disabled state, loading state, etc. Stories are not test cases; they are documented examples.

When to use Storybook:

• Building component libraries or design systems
• Developing UI in parallel with backend work
• Creating documentation for component APIs
• Visual testing and regression detection
• Reviewing UI changes in pull requests

When NOT to use:

• For user journey testing (use E2E tools)
• For testing business logic without UI
• For components that require full application context

Core Patterns

Pattern 1: CSF 3.0 Story Format

Component Story Format 3.0 is the standard for writing stories. It uses typed objects for maximum type safety.

Basic Story Structure

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

// Meta object describes the component
const meta = {
  title: "Components/Button",
  component: Button,
  tags: ["autodocs"],
  parameters: {
    layout: "centered",
  },
  argTypes: {
    onClick: { action: "clicked" },
  },
} satisfies Meta<typeof Button>;

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

// Each named export is a story
export const Primary: Story = {
  args: {
    variant: "primary",
    children: "Primary Button",
  },
};

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

export const Disabled: Story = {
  args: {
    variant: "primary",
    children: "Disabled Button",
    disabled: true,
  },
};

Why good: satisfies Meta<typeof Button> provides full type checking while allowing inference, stories are simple objects, tags: ["autodocs"] generates documentation automatically

Pattern 2: Args and ArgTypes Configuration

Args define prop values for stories. ArgTypes configure controls in the Storybook UI.

ArgTypes Configuration

const meta = {
  title: "Components/Card",
  component: Card,
  argTypes: {
    // Control type for enums
    variant: {
      control: { type: "select" },
      options: ["default", "outline", "filled"],
      description: "Visual variant of the card",
    },
    // Control type for booleans
    isLoading: {
      control: { type: "boolean" },
      description: "Shows loading skeleton",
    },
    // Control type for strings
    title: {
      control: { type: "text" },
      description: "Card title text",
    },
    // Range control for numbers
    padding: {
      control: { type: "range", min: 0, max: 64, step: 4 },
      description: "Padding in pixels",
    },
    // Color picker
    backgroundColor: {
      control: { type: "color" },
    },
    // Hide from controls
    internalId: {
      table: { disable: true },
    },
    // Action handler
    onClose: {
      action: "closed",
    },
  },
} satisfies Meta<typeof Card>;

Default Args

const meta = {
  title: "Components/Input",
  component: Input,
  // Default args applied to all stories
  args: {
    placeholder: "Enter text...",
    disabled: false,
  },
} satisfies Meta<typeof Input>;

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

// Story inherits default args, only overrides what changes
export const Default: Story = {};

export const WithLabel: Story = {
  args: {
    label: "Email address",
  },
};

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

Why good: centralized defaults reduce duplication, argTypes provide interactive documentation, control types match prop types for intuitive editing

Pattern 3: Decorators for Context

Decorators wrap stories with providers, layouts, or styling context.

Component-Level Decorators

const meta = {
  title: "Components/Modal",
  component: Modal,
  decorators: [
    // Add padding around the story
    (Story) => (
      <div style={{ padding: "3rem" }}>
        <Story />
      </div>
    ),
    // Wrap with theme provider
    (Story) => (
      <ThemeProvider theme="light">
        <Story />
      </ThemeProvider>
    ),
  ],
} satisfies Meta<typeof Modal>;

Global Decorators

// .storybook/preview.tsx
import type { Preview } from "@storybook/react";
import { ThemeProvider } from "../src/theme-provider";

const preview: Preview = {
  decorators: [
    (Story) => (
      <ThemeProvider>
        <Story />
      </ThemeProvider>
    ),
  ],
};

export default preview;

Story-Level Decorators

export const InDarkMode: Story = {