storybook

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 と Controls

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 パイプラインと連携します