Storybook ベストプラクティス

Storybook でコンポーネントライブラリを構築・ドキュメント化する専門家です。ストーリーの作成、コンポーネントの整理、デザインシステムの保守時にこれらのガイドラインを適用してください。

プロジェクト構造

ディレクトリ構成

• ストーリーをコンポーネントファイルの隣に配置 (Component.stories.tsx)
• ストーリーファイルに一貫した命名規則を使用
• 機能またはコンポーネントタイプ別にストーリーを整理
• コンポーネントライブラリと一致した明確な階層を維持

ファイル命名

• コンポーネントストーリーファイルに PascalCase を使用
• パターン: ComponentName.stories.tsx に従う
• 関連するストーリーを同じファイルにグループ化
• バリアントを説明するわかりやすいストーリー名を使用

ストーリーの作成

ストーリー構造

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

const meta: Meta<typeof Component> = {
  title: 'Category/Component',
  component: Component,
  parameters: {
    layout: 'centered',
  },
  tags: ['autodocs'],
  argTypes: {
    // Define arg types here
  },
};

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

export const Default: Story = {
  args: {
    // Default props
  },
};

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

ストーリーのベストプラクティス

• 主要な使用方法を示す Default ストーリーを作成
• 重要なバリアントごとにストーリーを追加
• エッジケースとエラー状態を含める
• インタラクティブ状態 (ホバー、フォーカス、無効化) をドキュメント化
• 関連する場合はレスポンシブ動作を表示

コンポーネントドキュメント

Autodocs

• 自動ドキュメント生成のために autodocs を有効化
• コンポーネントと props に対して明確な JSDoc コメントを記述
• prop タイプ、デフォルト値、必須項目をドキュメント化
• コンポーネントコメントに使用例を含める

カスタムドキュメント

• 複雑なドキュメント作成に MDX ファイルを追加
• デザイン根拠と使用ガイドラインを含める
• アクセシビリティに関する考慮事項をドキュメント化
• 一般的なユースケースのコード例を提供

Args とコントロール

ArgTypes 設定

argTypes: {
  variant: {
    control: 'select',
    options: ['primary', 'secondary', 'tertiary'],
    description: 'Visual style variant',
    table: {
      defaultValue: { summary: 'primary' },
    },
  },
  size: {
    control: 'radio',
    options: ['sm', 'md', 'lg'],
  },
  disabled: {
    control: 'boolean',
  },
  onClick: {
    action: 'clicked',
  },
}

Args のベストプラクティス

• 意味のあるデフォルト値を使用
• 関連する args を論理的にグループ化
• 複雑な props に説明を提供
• コールバック props のアクションを設定

デコレータとパラメータ

デコレータ

decorators: [
  (Story) => (
    <ThemeProvider theme={defaultTheme}>
      <Story />
    </ThemeProvider>
  ),
],

• 一貫したストーリーラッパーにデコレータを使用
• テーマプロバイダーを適切なレベルに適用
• 必要な場合はレイアウトコンテナを追加
• デコレータをシンプルで再利用可能に保つ

パラメータ

parameters: {
  layout: 'centered', // or 'fullscreen', 'padded'
  backgrounds: {
    default: 'light',
    values: [
      { name: 'light', value: '#ffffff' },
      { name: 'dark', value: '#1a1a1a' },
    ],
  },
  viewport: {
    defaultViewport: 'responsive',
  },
},

Storybook でのテスト

インタラクションテスト

import { within, userEvent } from '@storybook/testing-library';
import { expect } from '@storybook/jest';

export const Clickable: Story = {
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement);
    const button = canvas.getByRole('button');

    await userEvent.click(button);
    await expect(button).toHaveFocus();
  },
};

ビジュアルテスト

• ビジュアルリグレッションテストを設定
• 複数のビューポートでストーリーをキャプチャ
• テーマバリエーション (ライト/ダークモード) をテスト
• ビジュアルテストカバレッジをドキュメント化

アクセシビリティテスト

• アクセシビリティチェック用に a11y アドオンを有効化
• すべてのアクセシビリティ違反に対処
• ストーリー内でキーボードナビゲーションをテスト
• ARIA 要件をドキュメント化

アドオンと設定

主要なアドオン

• @storybook/addon-essentials (docs, controls, actions, viewport)
• @storybook/addon-a11y (アクセシビリティテスト)
• @storybook/addon-interactions (インタラクションテスト)
• @storybook/addon-designs (デザイン仕様統合)

設定

// .storybook/main.ts
const config: StorybookConfig = {
  stories: ['../src/**/*.stories.@(js|jsx|ts|tsx)'],
  addons: [
    '@storybook/addon-essentials',
    '@storybook/addon-a11y',
    '@storybook/addon-interactions',
  ],
  framework: {
    name: '@storybook/react-vite',
    options: {},
  },
};

export default config;

デザインシステム統合

デザイントークン

• デザインシステムからデザイントークンをインポート
• ストーリーでトークンを一貫性を持って適用
• コンポーネントドキュメント内でトークン使用方法をドキュメント化
• トークンバリエーション専用のストーリーを作成

テーマサポート

• preview.js でテーマプロバイダーを設定
• 各テーマバリアント用のストーリーを作成
• サポートされているすべてのテーマでコンポーネントをテスト
• テーマ固有の動作をドキュメント化

パフォーマンス

ビルド最適化

• 大規模なストーリー集合にはレイジーローディングを使用
• 静的アセットを最適化
• 適切なキャッシング設定を実装
• ビルド時間を監視および改善

ストーリーパフォーマンス

• ストーリーで重い計算を避ける
• モックデータを効率的に使用
• 複雑な依存関係を遅延ロード
• 遅いストーリーをプロファイルして最適化

ベストプラクティスの要約

• 生きたドキュメントとして機能するストーリーを記述
• 統合前にコンポーネントを単体でテスト
• ストーリーをシンプルで焦点を絞った状態に保つ
• すべてのストーリーで一貫性を維持
• コンポーネント変更時にストーリーを更新
• デザインレビューと QA にストーリーを使用
• アクセシビリティテストをワークフローの一部にする
• CI/CD パイプラインと統合