Storybook

ベストプラクティス

1. CSF 3.0 形式を使用

最新の Component Story Format 3.0 を使用。より簡潔で型安全。

// ❌ CSF 2.0 (旧形式)
export default {
  title: 'Components/Button',
  component: Button,
};

export const Primary = () => <Button variant="primary">Click me</Button>;

// ✅ CSF 3.0 (推奨)
import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';

const meta = {
  component: Button,
  tags: ['autodocs'], // 自動ドキュメント生成
  args: {
    variant: 'primary',
    children: 'Click me',
  },
} satisfies Meta<typeof Button>;

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

export const Primary: Story = {};

export const Secondary: Story = {
  args: {
    variant: 'secondary',
  },
};

2. Args ベースでストーリーを作成

コンポーネントの Props を Args として定義し、Controls パネルでインタラクティブに操作可能にします。

• デフォルト値は args で宣言 (❌ argTypes.defaultValue の使用禁止)。Meta の args にデフォルト値を配置すると、Controls パネルでその値が自動的に選択されます
• 複数のストーリーで共通に必要な args は Meta(コンポーネント) レベルで宣言し、個別のストーリーでは差分のみをオーバーライド

// ❌ Props のハードコーディング
export const Disabled: Story = {
  render: () => <Button disabled>Disabled</Button>,
};

// ❌ 複数ストーリーで同じ args を重複
export const Primary: Story = {
  args: { children: 'Click me', variant: 'primary' },
};
export const Secondary: Story = {
  args: { children: 'Click me', variant: 'secondary' },
};

// ✅ Meta で共通 args を宣言、ストーリーで差分のみをオーバーライド
const meta = {
  component: Button,
  args: {
    children: 'Click me',
    variant: 'primary',
  },
} satisfies Meta<typeof Button>;

export const Primary: Story = {};

export const Secondary: Story = {
  args: { variant: 'secondary' },
};

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

3. title を省略 — ファイルパスベースの自動推論

title を文字列で直接指定すると型安全ではなく、コンポーネント名やパスを変更するたびに同期が崩れやすい。Storybook はファイルパスからサイドバーの階層を自動推論するため、title を省略します。

// ❌ title を直接指定 — 型安全ではなく同期崩れのリスク
const meta = {
  title: 'Components/Button',
  component: Button,
} satisfies Meta<typeof Button>;

// ✅ title を省略 — ファイルパスから自動推論
const meta = {
  component: Button,
} satisfies Meta<typeof Button>;

4. 型安全な Meta 定義

satisfies キーワードで型チェックと型推論の両方を活用。

// ❌ 型推論なし
const meta: Meta<typeof Button> = {
  component: Button,
};

// ✅ 型チェックと推論の両方が可能
const meta = {
  component: Button,
  args: {
    size: 'md',
    variant: 'primary',
  },
} satisfies Meta<typeof Button>;

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

5. Decorators でコンテキストを提供

共通のラッパーまたは Provider を Decorator として適用。

// 個別ストーリーに Decorator を適用
export const WithTheme: Story = {
  decorators: [
    (Story) => (
      <ThemeProvider theme="dark">
        <Story />
      </ThemeProvider>
    ),
  ],
};

// すべてのストーリーに Decorator を適用
const meta = {
  component: Button,
  decorators: [
    (Story) => (
      <div style={{ padding: '3rem' }}>
        <Story />
      </div>
    ),
  ],
} satisfies Meta<typeof Button>;

6. Parameters で動作をカスタマイズ

const meta = {
  component: Button,
  parameters: {
    layout: 'centered', // ストーリーを中央配置
    backgrounds: {
      default: 'light',
      values: [
        { name: 'light', value: '#ffffff' },
        { name: 'dark', value: '#000000' },
      ],
    },
  },
} satisfies Meta<typeof Button>;

// 個別ストーリーでオーバーライド
export const OnDark: Story = {
  parameters: {
    backgrounds: { default: 'dark' },
  },
};

7. ArgTypes — 自動推論を優先、手動指定を最小化

Storybook はコンポーネント関数の TypeScript 型から最適な argType を自動適用します。手動で上書きするとコンポーネント型を変更するたびに argType の同期を合わせなければならないため、正当な理由がない限り argType を直接指定しない。

手動指定が正当である場合:

• ReactNode 型だが Controls でテキスト入力が必要な場合 → control: 'text'
• Compound pattern(複数コンポーネントをエクスポート) → argTypes で明示
• 特定のストーリーで常に固定される prop → control: false

// ❌ 不要な argType 手動指定 — 型変更時に同期崩れ
const meta = {
  component: Button,
  argTypes: {
    variant: {
      control: 'select',
      options: ['primary', 'secondary', 'tertiary'],
    },
    size: {
      control: 'radio',
      options: ['sm', 'md', 'lg'],
    },
    disabled: {
      control: 'boolean',
    },
  },
} satisfies Meta<typeof Button>;

// ✅ 自動推論に任せて、必要な場合のみ手動指定
const meta = {
  component: Button,
  argTypes: {
    // ReactNode 型だがテキスト入力が必要な場合
    children: { control: 'text' },
  },
} satisfies Meta<typeof Button>;

// ✅ 特定ストーリーで prop を固定する場合 — control: false
export const Horizontal: Story = {
  args: { orientation: 'horizontal' },
  argTypes: {
    orientation: { control: false }, // このストーリーでは常に horizontal
  },
};

推奨ストーリー構造

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

// 1. Meta 定義 — title 省略、共通 args を宣言、argTypes は自動推論に委譲
const meta = {
  component: Button,
  tags: ['autodocs'],
  parameters: {
    layout: 'centered',
  },
  args: {
    children: 'Button',
    size: 'md',
    variant: 'primary',
  },
} satisfies Meta<typeof Button>;

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

// 2. 基本ストーリー — Meta args をそのまま使用
export const Primary: Story = {};

// 3. バリエーションストーリー — 差分のみをオーバーライド
export const Secondary: Story = {
  args: {
    variant: 'secondary',
  },
};

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

// 4. prop 固定が必要なストーリー — control: false を使用
export const Horizontal: Story = {
  args: { orientation: 'horizontal' },
  argTypes: {
    orientation: { control: false },
  },
};

// 5. 複雑な状態やコンテキストが必要な場合
export const WithCustomTheme: Story = {
  decorators: [
    (Story) => (
      <ThemeProvider theme="custom">
        <Story />
      </ThemeProvider>
    ),
  ],
};

ArgTypes 手動指定が必要な場合のリファレンス

原則: ほとんどの argType は Storybook がコンポーネント型から自動推論。以下は自動推論が不適切な場合のみ使用。

デフォルト値は argTypes.defaultValue ではなく args で宣言。

argTypes: {
  // ReactNode 型だがテキスト入力が必要な場合
  children: { control: 'text' },

  // Range slider (自動推論が適切でない場合)
  opacity: {
    control: { type: 'range', min: 0, max: 1, step: 0.1 },
  },

  // Action logger (イベントハンドラ)
  onClick: { action: 'clicked' },

  // Control 無効化 (特定ストーリーで prop 固定)
  orientation: { control: false },
}

頻出 Parameters

parameters: {
  // レイアウト設定
  layout: 'centered' | 'fullscreen' | 'padded',

  // 背景設定
  backgrounds: {
    default: 'light',
    values: [
      { name: 'light', value: '#ffffff' },
      { name: 'dark', value: '#333333' },
    ],
  },

  // Actions パネル設定
  actions: {
    argTypesRegex: '^on[A-Z].*', // on で始まる Props を自動検出
  },

  // Docs 設定
  docs: {
    description: {
      component: 'ボタンコンポーネントの詳細説明',
    },
  },
}

Decorators パターン

// 1. スタイルラッパー
(Story) => (
  <div style={{ padding: '3rem' }}>
    <Story />
  </div>
)

// 2. Theme Provider
(Story) => (
  <ThemeProvider theme="dark">
    <Story />
  </ThemeProvider>
)

// 3. Router Provider (React Router 使用時)
(Story) => (
  <MemoryRouter initialEntries={['/']}>
    <Story />
  </MemoryRouter>
)

// 4. 多言語 Provider
(Story) => (
  <I18nProvider locale="ja">
    <Story />
  </I18nProvider>
)

// 5. グローバル状態 Provider
(Story) => (
  <Provider store={mockStore}>
    <Story />
  </Provider>
)

ファイル命名規則

Component.tsx           # コンポーネント実装
Component.stories.tsx   # ストーリーファイル (同じディレクトリ)
Component.test.tsx      # テストファイル

Storybook 設定ファイル

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

const config: StorybookConfig = {
  stories: ['../src/**/*.stories.@(ts|tsx)'],
  addons: [
    '@storybook/addon-essentials', // Controls、Actions、Docs など
    '@storybook/addon-interactions', // Play functions
  ],
  framework: {
    name: '@storybook/react-vite',
    options: {},
  },
};

export default config;

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

const preview: Preview = {
  parameters: {
    actions: { argTypesRegex: '^on[A-Z].*' },
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/,
      },
    },
  },
  // すべてのストーリーに適用されるグローバル Decorators
  decorators: [
    (Story) => (
      <div style={{ fontFamily: 'Arial, sans-serif' }}>
        <Story />
      </div>
    ),
  ],
};

export default preview;