Skill: Modern Storybook Mastery (CSF 3.0)

Professional Storybook authoring using Component Story Format 3 (CSF 3), TypeScript, and best-in-class architectural patterns.

When to use

Use this skill when:

• Creating or updating Storybook stories for React components
• Setting up Storybook 7/8+ projects
• Implementing Component Story Format 3.0 (CSF 3)
• Configuring argTypes, decorators, or parameters
• Working with TypeScript in Storybook
• Ensuring type safety with satisfies operator
• Setting up interactive controls and documentation

Instructions

1. Core Structure & Type Safety

Always use CSF 3.0 with the satisfies operator for maximum type safety and auto-completion.

import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';

const meta = {
  title: 'Components/Common/Button', // Path-based hierarchy
  component: Button,
  tags: ['autodocs'],
  parameters: {
    layout: 'centered',
  },
  // Global args for all stories in this file
  args: {
    label: 'Click Me',
  },
} satisfies Meta<typeof Button>;

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

// Basic Story
export const Primary: Story = {
  args: {
    variant: 'primary',
  },
};

// Derived Story (Reusing args)
export const PrimaryDisabled: Story = {
  args: {
    ...Primary.args,
    disabled: true,
  },
};

2. Exhaustive ArgTypes (The UI Control Panel)

Configure argTypes to provide a rich, interactive playground for designers.

3. Decorators (Providing Context)

Use decorators to wrap components in Providers (Theme, Router, State) or Layout wrappers.

// Local Decorator (specific to this component)
const meta = {
  component: UserProfile,
  decorators: [
    (Story) => (
      <div style={{ padding: '3rem', background: '#eee' }}>
        <Story />
      </div>
    ),
  ],
} satisfies Meta<typeof UserProfile>;

// Context Provider Decorator
export const WithDarkTheme: Story = {
  decorators: [
    (Story) => (
      <ThemeProvider theme="dark">
        <Story />
      </ThemeProvider>
    ),
  ],
};

4. Advanced Patterns

A. Form Components

Showcase various states: Empty, Filled, Validation Error.

export const ValidationError: Story = {
  args: {
    label: 'Email',
    error: 'Please enter a valid email address',
    value: 'invalid-email',
  },
};

B. Mocking Data-Driven Components

const MOCK_ITEMS = [{ id: 1, name: 'Item 1' }, { id: 2, name: 'Item 2' }];

export const Loaded: Story = {
  args: { items: MOCK_ITEMS },
};

export const Empty: Story = {
  args: { items: [] },
};

C. Responsive Viewports

export const MobileView: Story = {
  parameters: {
    viewport: { defaultViewport: 'mobile1' },
  },
};

5. Project Configuration

.storybook/preview.ts (Global Config)

import type { Preview } from '@storybook/react';

const preview: Preview = {
  parameters: {
    actions: { argTypesRegex: '^on[A-Z].*' }, // Auto-log onEvent props
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/,
      },
    },
  },
};
export default preview;

6. Anti-Patterns (What to Avoid)

• ❌ No CSF 2.0: Don’t use Template.bind({}). It is verbose and lacks type-inference.
• ❌ No Hardcoded Props: Avoid render: () => <Button label="Fix" />. Use args so the Controls panel works.
• ❌ No Logic in Stories: Don’t put useState or useEffect inside a story. Use play functions for interactions or mock the state via props.
• ❌ No Flat Hierarchies: Don’t name every story Primary. Use groups like Components/Inputs/Checkbox.
• ❌ No Missing Types: Never export a story without the Story (StoryObj) type annotation.

7. File Naming & Organization

• Component.tsx (Logic)
• Component.stories.tsx (Stories – same folder)
• Component.test.tsx (Unit tests)
• Component.module.css (Styles)

Why this approach is better

1. Satisfies Keyword: Ensures that your meta object is strictly typed while still allowing TypeScript to “remember” the specific literal types of your args.
2. Explicit ArgTypes: Provides a checklist of UI controls, ensuring the generated Storybook isn’t just a static image but a functional tool.
3. Hierarchy Focus: Emphasizes title paths (e.g., Components/Common/Button) for better sidebar organization in large projects.
4. Action Automation: Uses argTypesRegex so you don’t have to manually mock every single onClick or onChange.
5. Anti-Pattern Guardrails: Prevents falling back on outdated 2020-era Storybook syntax.