storybook

dot-skills Storybook のベストプラクティス

TypeScript/React コンポーネントライブラリのワークショップ かつ テストベンチとして Storybook 9+ を使用するための包括的なガイドです。8 カテゴリにわたる 52 のルールを、デザインシステムにおけるコンポーネントのライフサイクル順に並べています。誤った .storybook/main.ts はすべてのストーリーに波及し、不正な CSF Meta はそのファイルの autodocs、コントロール、テスト、a11y パネルを利用できなくします。

このスキルの対象

1. セットアップ — main.ts、preview.ts、フレームワークの選択（Vite と Webpack、Next.js と React のみ）、CLI を使ったアドオンのインストール、staticDirs。
2. ストーリーの作成（CSF3） — satisfies Meta<typeof Component>、名前付きエクスポート＝ストーリー、tags: ['autodocs'] の配置、render が適切な場合、ストーリーの命名規則。
3. Args、argTypes、コントロール — 推論に頼る場合、control: 'select' を宣言する場合、コールバックに storybook/test の fn() を使う方法、args と parameters と globals の使い分け。
4. デコレーターと合成 — preview.ts のグローバルプロバイダー、ネットワークモック用の MSW、サブパスインポートのモジュールモック（Storybook 9+）、デコレーターのシグネチャに関する落とし穴。
5. インタラクションテスト — play 関数、storybook/test のインポートパス（@storybook/test ではありません）、canvas／userEvent の分割代入、waitFor より findBy*、CI 用の addon-vitest、ポータブルストーリー。
6. アクセシビリティ（@storybook/addon-a11y 経由の axe-core） — 実際のゲートとしての parameters.a11y.test = 'error'、ルール単位の無効化、対象とする WCAG に合わせた runOnly の範囲指定、ポータルの context、意図的な違反フィクスチャ用の globals.a11y.manual。
7. ドキュメントとデザインシステム — autodocs と MDX、<Canvas of={...} /> を使った MDX からのストーリー参照、ステータスタグ、ストーリーとしてのデザイントークン、parameters.design を使った Figma リンク。
8. ビルドとデプロイ — Webpack より Vite、大規模なライブラリ向けのオンデマンドバンドル、デザイナーによるレビュー用の Chromatic/Vercel へのデプロイ、CI キャッシュの設定。

適用するタイミング

次のような場合にこのスキルを使用します。

• storybookTest を読み込む *.stories.tsx、*.mdx、.storybook/main.ts、.storybook/preview.ts、vitest.config.ts を編集または作成するとき。
• 新しいプロジェクトに Storybook をセットアップするとき（フレームワークの選択、npx storybook init の後続作業）。
• アドオン（a11y、vitest、designs、msw）を追加またはアップグレードするとき。
• play 関数と Vitest アドオンを使ってコンポーネントテストを接続するとき。
• 「Storybook が遅い」「コントロールが select ではなくテキストを表示する」「ダイアログで a11y パネルに何も表示されない」「play 関数が CI で不安定」といった問題を調査するとき。

次の場合はこのスキルを使わず、以下を使用してください。

• 基盤となるコンポーネント設計には react-optimise / clean-code-ts-react。
• Storybook の外部での render/screen/userEvent の使い方には react-testing-library。
• 仕様そのものについては WCAG/ARIA のリファレンスドキュメント。このスキルでは aria-labelledby の役割を理解していることを前提とし、addon-a11y によるチェック方法を説明します。

優先度別ルールカテゴリ

順序はコンポーネントのライフサイクル（設定 → 作成 → 接続 → デコレート → テスト → 監査 → ドキュメント化 → リリース）を反映しています。先行する段階の影響は後続にも波及します。

優先度	カテゴリ	影響	プレフィックス	ルール数
1	セットアップと設定	CRITICAL	config-	8
2	ストーリーの作成（CSF3）	CRITICAL	csf-	8
3	Args、ArgTypes、コントロール	HIGH	args-	5
4	デコレーターと合成	HIGH	deco-	7
5	インタラクションテスト	HIGH	test-	7
6	アクセシビリティ（axe）	HIGH	axe-	5
7	ドキュメントとデザインシステム	MEDIUM-HIGH	docs-	5
8	ビルド、パフォーマンス、デプロイ	MEDIUM	build-	7

クイックリファレンス

1. セットアップと設定（重要）

• config-typed-main-config — satisfies StorybookConfig を使って main.ts に型を付けます
• config-pick-the-right-framework-package — ビルド環境に合ったフレームワークパッケージを使います（Next.js の場合は @storybook/nextjs-vite など）
• config-narrow-stories-glob — stories の glob をストーリーファイルだけに絞ります
• config-typed-preview — フレームワークの Preview 型を使って preview.ts に型を付けます
• config-add-addons-via-cli — アドオンは手動ではなく、npx storybook add でインストールします
• config-static-dirs-not-bundler-imports — バンドラーのインポートではなく、staticDirs でアセットを配信します
• config-tokens-css-vars-in-preview — Style Dictionary／Tokens Studio の出力を CSS 変数として preview.ts に接続します
• config-story-sort-for-large-libraries — デザインシステムのサイドバーでは parameters.options.storySort で順序を設定します（基礎 → コンポーネント → パターン）

2. ストーリーの作成 — CSF3（重要）

• csf-satisfies-meta-not-typed — : Meta<typeof Component> ではなく、satisfies Meta<typeof Component> を使います
• csf-prefer-args-over-render — 基本的に args を使い、render は複合ストーリー用にします
• csf-set-meta-component-explicitly — 常に meta.component を設定します（autodocs、controls、型はこれに依存します）
• csf-name-stories-by-state — prop の値ではなく、ユーザーに見える状態に基づいてストーリーに名前を付けます
• csf-tags-autodocs-on-meta — tags: ['autodocs'] はストーリーごとではなく、meta に設定します
• csf-co-locate-stories-with-component — Component.stories.tsx を Component.tsx の隣に配置します
• csf-default-export-is-the-meta — デフォルトエクスポートは meta、名前付きエクスポートはストーリーです
• csf-title-hierarchy-for-design-systems — Meta の title: 'Components/Inputs/Button' で分類します（基礎／コンポーネント／パターン／例）

3. Args、ArgTypes、Controls（高）

• args-derive-from-component-props — argTypes は推論に任せ、推論できない項目だけを宣言します
• args-use-fn-for-callbacks — コールバックの args には storybook/test の fn() を使います
• args-explicit-control-for-unions — 推論できないユニオン型には control と options を宣言します
• args-no-jsx-in-args — args に JSX を記述せず、render で JSX を組み立てます
• args-pick-args-vs-parameters-vs-globals — args はコンポーネントへの入力、parameters はアドオンの設定、globals はツールバーの状態です

4. デコレーターと合成（高）

• deco-global-providers-in-preview — Theme／QueryClient／Intl プロバイダーは preview.ts に配置します
• deco-msw-for-network-mocks — MSW でネットワーク層をモックし、SDK はスタブ化しません
• deco-mock-modules-with-subpath-imports — package.json#imports を使ってネットワーク以外のモジュールをモックします
• deco-decorator-component-not-call — デコレーターは {story()} ではなく <Story /> としてレンダリングします
• deco-context-aware-decorators — リアクティブなラッパーでは context から globals と parameters を読み取ります
• deco-themes-addon-for-multi-brand — マルチブランドの切り替えには @storybook/addon-themes の withThemeByClassName／withThemeByDataAttribute を使います
• deco-rtl-direction-toggle — 双方向テキストのリグレッションテスト用に、すべてのストーリーを dir="rtl" でラップするツールバーの dir 切り替えを用意します

5. インタラクションテスト（高）

• test-import-from-storybook-test — @storybook/test ではなく storybook/test からインポートします（Storybook 9 以降）
• test-await-every-userevent-call — userEvent の呼び出しはすべて await します
• test-use-canvas-from-play-arg — play 引数から canvas／userEvent を分割代入します
• test-fn-for-spied-callbacks — args: { onSubmit: fn() } を指定し、expect(args.onSubmit).toHaveBeenCalledWith(...) でアサートします
• test-findby-over-waitfor — waitFor ＋ getByRole より findByRole を優先します
• test-vitest-addon-for-ci — 従来の test-runner ではなく、@storybook/addon-vitest を使って CI で play を実行します
• test-portable-stories-for-rtl — composeStories を使って、RTL／Vitest テストでストーリーを再利用します

6. アクセシビリティ — axe（高）

• axe-set-test-error-globally — preview.ts で parameters.a11y.test = 'error' を設定し、実際のゲートとして機能させます
• axe-disable-rules-not-stories — 特定のルールを無効にし、ストーリー全体に test: 'off' を設定することは避けます
• axe-restrict-runonly-to-wcag-aa — runOnly の対象を WCAG の適合目標（通常は AA）に限定します
• axe-context-for-portals — ポータル内にレンダリングするコンポーネントには parameters.a11y.context を設定します
• axe-globals-manual-for-intentional-violations — 意図的に違反を含めるフィクスチャには globals.a11y.manual: true を設定します

7. ドキュメントとデザインシステム（中〜高）

• docs-autodocs-vs-mdx — コンポーネントのページには Autodocs、複数の領域にまたがるドキュメントには MDX を使います
• docs-mdx-references-stories — インラインレンダリングではなく <Canvas of={Story} /> を使います
• docs-component-status-tags — ステータスタグとサイドバーのバッジでライフサイクルを示します
• docs-design-tokens-as-stories — ビジュアルリグレッション用に、トークンをストーリーとしてドキュメント化します
• docs-figma-link-via-design-addon — parameters.design を使って、各ストーリーを対応する Figma フレームにリンクします

8. ビルド、パフォーマンス、デプロイ（MEDIUM）

• build-prefer-vite-over-webpack — レガシーな Webpack より Vite ベースのフレームワークパッケージを使用します
• build-trim-test-bundle — main.ts の build.test 設定で Vitest-addon のテストビルドを縮小します
• build-deploy-static-build-to-shareable-host — すべての PR について storybook build を Chromatic/Vercel にデプロイします
• build-cache-storybook-in-ci — CI で Vite/Webpack と Playwright のレイヤーをキャッシュします
• build-storybook-composition-refs — main.ts の refs で複数パッケージのデザインシステムを 1 つのホスト Storybook に統合します
• build-manager-brand — .storybook/manager.ts の create() でロゴ、ブランドリンク、サイドバーの配色を設定します
• build-chromatic-modes-multi-theme — Chromatic の modes で、すべてのストーリーをテーマ／ビューポート／方向ごとにスナップショットします

使い方

• カテゴリー構成と影響の根拠については、まず references/_sections.md を確認してください。
• 「Storybook をセットアップする」場合は、すべての config- ルールを読んでから csf- を読んでください。
• 「新しいストーリーを書く」場合は、csf- と args- を読んでください。
• 「ストーリーのテストをしたい」場合は、test- と deco-msw-for-network-mocks を読んでください。
• 「違反がある場合に a11y で CI を失敗させたい」場合は、すべての axe- ルールを読んでください。
• 「デザインシステムをゼロから構築する」場合は、次の順に読んでください：config-tokens-css-vars-in-preview、config-story-sort-for-large-libraries、csf-title-hierarchy-for-design-systems、deco-themes-addon-for-multi-brand、build-manager-brand、build-chromatic-modes-multi-theme。次に、ガバナンスとトークン表示のレイヤーについて、docs-component-status-tags と docs-design-tokens-as-stories を読んでください。
• 「複数パッケージのモノレポ型デザインシステムがある」場合は、まず build-storybook-composition-refs を読み、その後、上記のデザインシステム構築手順を読んでください。
• 「RTL／複数方向のカバレッジが必要」な場合は、deco-rtl-direction-toggle を読んでから build-chromatic-modes-multi-theme を読み、ビジュアルリグレッションに RTL を組み込んでください。
• gotchas.md には、時間とともに判明した失敗パターンが記載されています。原因のわかりにくい問題をデバッグする前に、必ず確認してください。
• assets/templates/_template.md を使って、新しいルールを追加してください。

リファレンスファイル

ファイル	説明
references/_sections.md	カテゴリーの定義と順序
assets/templates/_template.md	新しいルールを追加するためのテンプレート
gotchas.md	時間とともに蓄積された失敗パターン
metadata.json	バージョン、リファレンス、概要

関連スキル

• clean-code-ts-react — 基盤となるコンポーネント設計の品質（命名、関数の形、抽象化）。
• react-testing-library — Storybook 以外で使用する場合の RTL クエリとパターン。
• web-interface-guidelines — ドキュメント化するコンポーネントに関する Vercel Web Interface Guidelines。