Next.js Storybook CSF3 ストーリー生成 (nextjs-storybook-story)
同じディレクトリに配置されたStorybookストーリー（[ComponentName].stories.tsx）を Component Story Format 3 (CSF3) で生成・更新するための専門ワークフローです。
[!TIP] モジュラーアセット:
- ストーリー実装の参考例:
examples/- 検証スクリプト:
scripts/verify-storybook.ps1(Windows) /scripts/verify-storybook.sh(Linux)
アーキテクチャルールと標準
1. メインコンポーネントのみ対象（マイクロリーフクライアントは除外）
- インタラクティブなクライアントロジックは、小さなリーフクライアントコンポーネント（例：トグルボタン、クリックリスナー）に押し下げます。
- 内部のマイクロリーフクライアントヘルパー用のストーリーは 作成しないでください。
- メインコンポーネント（主要機能セクションまたは複合UIブロック）にのみ Storybook ストーリーが必要です。
2. CSF3 構造とインタラクティブコントロール
- Component Story Format 3 (CSF3) を
Meta<typeof ComponentName>とStoryObj<typeof ComponentName>で使用します。 - タグを含める:
tags: ["autodocs", "ai-generated"]。 - TypeScript のプロパティを
meta.argTypes内のインタラクティブコントロール（text、select、boolean、number）にマッピングします。 argsに現実的なデフォルト値を提供します。
3. アクションスパイ（'storybook/test' の fn()）
- すべてのコールバックおよびミューテーションプロパティ（例：
onClick、onToggle、onSubmit）に対して、'storybook/test'からfn()をデフォルトのargsにバインドし、ユーザー操作が Storybook の Actions パネルにクリーンにログされるようにします。
4. 構造化ドキュメント（parameters.docs）
meta.parameters.docs.description.componentに包括的なマークダウンを記述します：- 概要と目的: コンポーネントの説明と存在理由。
- アーキテクチャと境界: RSC とリーフクライアントコンポーネント（
"use client"）、フック、キャッシュ。 - 主要なインタラクション: クリックハンドラー、状態トグル、アニメーション。
- アクセシビリティとモーション: ARIA ロール/ラベル および
prefers-reduced-motion。
- 個々のストーリーには
parameters.docs.description.storyで注釈を付けます。
5. 4つの標準ストーリーバリアントとプロダクショントークン（必須）
- ハードコードされた色は禁止: いかなる状況でも、任意の16進数値（
#FAFAFA、#050505）やトークン以外のパレットカラー（border-zinc-200、text-zinc-500）を使用しないでください。 - セマンティックプロダクショントークン:
app/globals.cssのセマンティックテーマトークン（bg-background、text-foreground、border-border、text-muted-foreground）のみを排他的に使用します。 - 厳密に4つのストーリーバリアントを、スコープ指定された
.lightおよび.darkクラスを持つセマンティックコンテナーカードにラップしてエクスポートします：Light:{ themes: { themeOverride: "light" }, backgrounds: { default: "light" } }を設定し、.light bg-background text-foreground border-borderカード内に配置、ラベルは"Light Mode"。Dark:{ themes: { themeOverride: "dark" }, backgrounds: { default: "dark" } }を設定し、.dark bg-background text-foreground border-borderカード内に配置、ラベルは"Dark Mode"。SkeletonLight:render: () => <[ComponentName]Skeleton />を.light bg-background text-foreground border-borderカード内に配置、ラベルは"Skeleton (Light)"。SkeletonDark:render: () => <[ComponentName]Skeleton />を.dark bg-background text-foreground border-borderカード内に配置、ラベルは"Skeleton (Dark)"。
ワークフローステップ
-
ステップ 1: コンポーネントコントラクトとプロパティの検査
[ComponentName].tsxを読み取り、すべてのエクスポートされたプロパティ、コールバックハンドラー、および表示状態を解決します。
-
ステップ 2: 同じディレクトリにストーリーを生成 (
[ComponentName].stories.tsx)[ComponentName].stories.tsxを[ComponentName].tsxと同じディレクトリに配置します。- CSF3 メタデータ、
argTypes、fn()アクションスパイ、マークダウンドキュメント、および4つの標準ストーリーバリアントを実装します。
-
ステップ 3: 検証とスモークテストの実行
- 検証スクリプトを実行してストーリーの存在を確認し、Storybook スモークテストを実行します：
- Windows (PowerShell):
pwsh .agents/skills/nextjs-storybook-story/scripts/verify-storybook.ps1 -ComponentPath <target_component_dir> - Linux / macOS (Bash):
bash .agents/skills/nextjs-storybook-story/scripts/verify-storybook.sh <target_component_dir>
- Windows (PowerShell):
- 構文の競合やエクスポート漏れのエラーを修正します。
- 検証スクリプトを実行してストーリーの存在を確認し、Storybook スモークテストを実行します：