storybook-to-product

Storybook からプロダクトへ

Storybook で、デザインシステムの実際のコンポーネントと実際のコンテンツを使い、バックエンドに手を煩わされることなく、その場でプロダクトの次期バージョンを設計しました。完成したように見えます。これはフロントエンドの中でも最前線のコードで、ほぼ本番環境に出せる状態です。

「ほぼ」の部分が問題です。ストーリーと稼働中のプロダクトの間には、Storybook では扱う必要のなかったものがすべてあります。プロダクト独自のテンプレート言語、データファイル、サムネイルをクリックすると開くモーダル、サーバーレス関数に送信するフォーム、デザインを補うために誰かが考え出した文言、そして新しいコンポーネントがまだリリースされていないデザインシステムのバージョンです。

このスキルは、その隔たりを埋めます。作業内容を評価し、マークアップとスタイルをプロダクト独自の言語に移し、背後にあるすべての仕組みと連携させ、プロダクトがデザインどおりになったことを確認します。最後にプルリクエストを作成し、各ストーリーのどのバージョンがリリースされたかを正確に記録します。これにより、次回 Storybook に変更を加える際は、最初からやり直すのではなく、差分を取り込んで追いつけます。

これは何ではないか

• product-to-storybook ではありません。 そちらは、プロダクトに既存の画面を Storybook へ取り込みます。こちらは、画面を Storybook から本番環境へ移します。両者は組み合わせて使えるように作られています。ストーリーが product-to-storybook から作られたものであれば、このスキルはその記録を読み取り、必要な情報の大半を手間なく取得します。
• ds-adoption-plan ではありません。 そちらは、プロダクト独自の UI をシステムに移行する計画を、プロダクト側から立てます。こちらは完成したデザインを起点に、それをリリースするために何が必要かを検討します。両者の見積もりを同じ基準で比較できるよう、導入計画の工数評価を活用します。
• vibe-killer ではありません。 そちらは、システムのコンポーネントを使って単一のページを再構築します。こちらではページはすでにシステムのコンポーネントで構築済みで、目的はそれを本番環境に反映することです。
• リリースツールではありません。 デザインシステムの公開、マージ、デプロイは行いません。

基本ルール

1. 仕様はストーリーであり、目指す先はプロダクトです。 何をレンダリングするかはストーリーが決めます。どのように記述するかはプロダクトが決めます。テンプレート言語、ファイル名、CSS アーキテクチャ、クラス名などがそれにあたります。プロダクトを Storybook のコードのように見せてしまう引き継ぎは、プロダクトのメンテナーによって元に戻されます。
2. 手を加える前に評価します。 プロダクトのファイルをひとつでも変更する前に、すべての領域の処遇を決め、すべての動作に名前を付け、すべてのシステム依存関係を確認します。評価結果をユーザーに提示し、確認を取ります。誤った廃止によって、ビジネスに今も必要なものが削除されるおそれがあるためです。
3. 作り上げたコンテンツを公開してはいけません。 フィクスチャには、実際のコピーと、形を整えるためだけに存在するプレースホルダーコンテンツが混在しています。すべてのフィールドに由来と判断を記録し、完了とする前に、ビルド内に作り上げた値が残っていないかを検索します。公開中のページに偽の人物が載ることを防ぐために、このスキルが存在します。
4. コンテンツとメディアはユーザーが決めます。 根拠に基づいてコピーのデフォルトを提案します。画像と動画はすべて確認します。
5. 未リリースのものは確認します。 ストーリーが、プロダクトにまだインストールできないデザインシステムの作業に依存している場合、スキルは停止して、どうするかを確認します。デザインシステムのローカルコピーを参照するプロダクトを公開することは決してありません。
6. Storybook の要素を本番環境に持ち込みません。 オリジンマーカー、@scope ラッパー、デコレーター、フィクスチャの残骸はすべて削除し、その後、ビルド出力を検索して削除されたことを確認します。
7. すべてのトリガーに遷移先を設定します。 Storybook ではインタラクションの見た目だけが示され、動作は示されません。すべてのモーダル、フォーム、トグル、リンクを接続し、実際のブラウザーですべてのトリガーを操作します。
8. プロダクト独自のルールを優先します。 プロダクトのリポジトリにある CLAUDE.md、AGENTS.md、またはプロセス設定は、作業のブランチ作成、コミット、リリース方法も含め、ここにあるすべてのルールより優先されます。スキルは確認せずにそれに従い、ユーザーが明示的に指示した場合に限り、そこから逸脱します。
9. プルリクエストで作業を終えます。 マージとデプロイは、チェックがすべて成功していても、常に人が行います。
10. 追従時に上書きしません。 Storybook と本番環境の両方でフィールドが変更されている場合は競合として扱い、人が判断します。本番環境での編集が正しい可能性もあります。

実行の流れ

モード 1：引き継ぎ

1. インテーク（intake/HANDOFF-INTAKE.md）。それぞれにデフォルトが設定された3つの質問に答えます。回答はプロダクトのリポジトリにある storybook-to-product/HANDOFF.md に記録します。
2. フェーズ 1：評価（phases/phase-1-assessment.md）。すべての領域をマッピングし、すべてのシステム依存関係を確認し、すべての動作を一覧にして、見積もりを行います。該当する場合はリリースゲートについて確認します。停止して、ユーザーに提示します。 返答を待ちます。
3. フェーズ 2：コンテンツ（phases/phase-2-content.md）。すべてのフィールドの由来を分類し、デフォルト案を提示して、まとめて一度に確認します。すべてのアセットについて確認します。
4. フェーズ 3：統合（phases/phase-3-integration.md）。デザインシステムを更新し、マークアップを変換し、スタイルを取り込み、確認済みのものを廃止します。
5. フェーズ 4：接続（phases/phase-4-wiring.md）。データ、動作、フォーム、リンク、ページを囲むドキュメント、およびリンク記録に対応します。
6. フェーズ 5：検証（phases/phase-5-proof.md）。ビルド、漏れの検索、ストーリーとの並列比較、すべての動作のテスト、axe、レポート、プルリクエストを行います。

モード 2：追従

phases/catch-up.md。リンク記録を読み、公開済みのバージョン以降にストーリーで変更された箇所をすべて特定し、引き継ぎ以降に本番環境で行われた編集を確認して、差分を独自のプルリクエストで反映します。

ファイルの配置場所

製品のコードは、製品リポジトリのブランチ上で、製品固有の規約に従って変更します。

作業記録は、製品リポジトリのルートに置きます。

storybook-to-product/
├── HANDOFF.md                ← intake answers, both versions, runs
├── ASSESSMENT.md             ← regions, dependencies, behaviors, estimate
├── CONTENT.md                ← every field and asset, with its decision
├── REPORT.md                 ← what was proven, side by sides
├── links.json                ← which story version is in production
└── catch-up/
    └── YYYY-MM-DD.md         ← one per catch-up

ds-adoption-plan/ または product-inspection/ フォルダーと同じ階層に置きます。ストーリーが product-to-storybook から来た場合は、まずデザインシステムリポジトリ内の作業記録（product-to-storybook/<product>/）を読み、作業がマージされたら 引き継ぎのメモを追加します。reference/LINKS.md では、両者のつながりを保つ方法を説明しています。

このキットのファイル

• intake/HANDOFF-INTAKE.md：3つの質問と、確認するタイミングを待つ質問
• phases/phase-1-assessment.md：領域、依存関係、動作、見積もり、そしてチェックポイント
• phases/phase-2-content.md：どのコンテンツをリリースするかを項目ごとに記載
• phases/phase-3-integration.md：製品の言語で記述するマークアップとスタイル
• phases/phase-4-wiring.md：データ、動作、フォーム、リンク
• phases/phase-5-proof.md：ビルド、レンダリング、検証、報告、プルリクエスト
• phases/catch-up.md：後から加わった Storybook の変更を反映
• reference/TRANSLATION.md：ストーリーの構成要素と製品テンプレートの対応関係
• reference/LINKS.md：Storybook と製品をつなぐ要素
• reference/CAPABILITIES.md：このスキルでできることとできないこと
• templates/：作業記録内の各ファイルの出力テンプレート

文体

平易で、勢いがあり、具体的にします。評価は、対応方針を示す領域の表と、末尾の数値で構成します。コンテンツ台帳には、両方の値を並べて示します。レポートには、構築した内容、検証できた内容、誰かの対応待ちの項目を記載します。読む人が、プルリクエストに含まれる内容、自分が判断すべきこと、そしてリリースの準備ができているかを正確に把握できるようにします。