product-to-storybook

製品を Storybook に取り込む

デザインシステムの Storybook では、すべてのコンポーネントを個別に確認できます。しかし、それらのコンポーネントが使われている製品については、ほとんど分かりません。そのため、カードやテーブルを変更すると、下流で何が起きるかは推測するしかなく、推測をやめるには、製品を一つずつすべて開いて確認するしかありません。

このスキルは、その問題を解決します。既存の製品を受け取り、主要なページテンプレートを特定して、製品ですでに使われている箇所では、ローカルのデザインシステムを使いながら、代表的なバージョンを Storybook 内に再構築します。すべての製品を取り込めば、あるコンポーネントへの変更が、それらすべてにどう波及するかを一度に確認できます。また、バックエンドに邪魔されることなく、Storybook 上で製品の次のバージョンをデザインできます。

これは後付けで取り込む作業です。生成される画面は、すべての URL をライブで再現するものではなく、実際のコンテンツをさまざまに組み合わせて固定したページテンプレートです。それが目的です。デザインの参考にするには十分な代表性を備え、背後にあるものが壊れても影響を受けないよう切り離されています。

これは何ではないか

• vibe-killer ではありません。 こちらは、特注のページをデザインシステムに移行します。このスキルは、製品の画面を Storybook に移し、デザインシステムに含まれていない部分を明示します。領域を変換することは決してありません。明示された領域を変換したい場合は、その後に vibe-killer を実行してください。
• ds-adoption-plan ではありません。 こちらは、移行のコストを見積もり、スケジュールを立てます。このスキルは、今日すぐに確認できる画面と、デザインシステムで対応を検討できる不足項目の一覧を作成します。
• プロトタイピングツールではありません。 作成する画面は、すべてすでに存在するものです。「この製品はまだ存在しない」というのはプロトタイピングであり、プロトタイピングは別のプレースホルダーを使う別の作業です。
• 本番向けの作業ではありません。 ストーリーとフィクスチャを作成します。ライブラリ内のレシピ、パターン、コンポーネントを自ら作成することはありません。製品にデザインシステム由来ではない UI が含まれている場合、その扱いについて確認し、何かを実行する前に回答を記録します。

基本ルール

1. ローカルのデザインシステムを優先します。 ストーリーは、プロダクトが固定しているバージョンではなく、ストーリーと同じ場所にチェックアウトされているシステムのバージョンでレンダリングされます。これによって、波及の様子がわかります。プロダクトが固定しているバージョンを記録し、ローカルに存在しなくなった各プロパティやスロットには、黙って修正するのではなく、ギャップ台帳でバージョンドリフトのフラグを付けます。
2. URLではなくテンプレートを対象にします。 3,000ページあるサイトでも、テンプレートはおそらく5つほどです。テンプレートと、そのバリエーション（妥当な範囲内で）を見つけて作成します。ここでの分類を間違えると実行全体を無駄にすることになるため、ストーリーを1つでも書く前に、インベントリをユーザーに提示して確認を得ます。
3. 実際のコンテンツを一度だけ固定します。 各ストーリーには、システムが対応すべきさまざまな形状を示す、プロダクトの実際のコンテンツを横断的に含めます。たとえば、YouTube の埋め込みがある投稿、タイトルが60文字のカード、タグが40個あるリストです。日付とソース URL を付けてフィクスチャに保存します。lorem は使わず、ライブで取得することもありません。
4. 実在する人物のデータは使いません。 ログインが必要な画面には、誰かのアカウントのデータではなく、データの形状をもとに作成したフィクスチャを使います。キャプチャに実際のユーザーデータが含まれていることに気付いたら、作業を止めて削除し、そのことを報告します。これは警告ではなく、作業停止の条件です。
5. すべてにマークを付けます。 ストーリー内の各領域には、出所を示す data-origin="system"、data-origin="product"、または data-placeholder="missing-component" のいずれかを付けます。規約は reference/MARKERS.md に記載されています。ギャップ台帳はこれらのマークから生成されるため、マークを付け忘れた領域は、気付かれないギャップになります。
6. プロダクトの CSS は所定の範囲内に留めます。 プロダクト独自のスタイルシートが適用するものはすべて @scope で囲み、そのプロダクトのストーリーでのみ読み込みます。その後、デザインシステムのストーリーを変更前と変更後にレンダリングして、変化がないことを確認します。波及はシステムから外側へ進みます。プロダクトからシステムへ逆向きに波及することはありません。
7. 多少の差異は想定内であり、そのことを明示します。 ローカルのシステムを使って作成したストーリーは、ライブページと少し異なって見えるはずです。ローカルのシステムのほうが、プロダクトが固定しているバージョンより新しいためです。並べて比較するレポートには両方を示し、どの差異がバージョンドリフトによるもので、どの差異がスキルの誤りによるものかを読者にはっきり伝えます。
8. 更新時に既存のものを上書きしません。 後続の実行では、何がドリフトしたかを報告して確認を求めます。その画面は意図的に再設計されたものかもしれません。

実行の流れ

モード1 — プロダクトのバックフィル

1. Storybook の初期設定（intake/STORYBOOK-INTAKE.md）。デザインシステムごとに1回実施します。この Storybook でのストーリーの記述方法、プロダクト画面の配置場所、システムの読み込み方法を確認します。product-to-storybook/STORYBOOK.md がすでに存在し、最新であれば省略します。
2. プロダクトの初期設定（intake/PRODUCT-INTAKE.md）。プロダクトごとに1回実施します。デフォルト値付きの質問を5つ行います。更新時に再度質問しなくて済むよう、回答をプロダクトの GARAGE.md に記録します。
3. フェーズ1 — インベントリ（phases/phase-1-inventory.md）。テンプレートとそのバリエーションを見つけます。作業を止めてユーザーに提示します。 確認を待ちます。
4. フェーズ2 — キャプチャ（phases/phase-2-capture.md）。コンテンツの横断的なサンプルを選び、フィクスチャとして固定します。
5. フェーズ3 — 移行（phases/phase-3-relocation.md）。ストーリーを記述します。プロダクトが使う場所にはシステムコンポーネントを配置し、それ以外の領域にはマークを付け、プロダクトの CSS はスコープを限定します。
6. フェーズ4 — 検証（phases/phase-4-proof.md）。レンダリングして並べて比較し、システム自体のストーリーに変更がないことを証明し、ギャップ台帳とレポートを作成します。

モード2 — 更新（ドリフトチェック）

phases/refresh.md。プロダクトを再読み込みして Storybook の内容と比較し、何が変わったかを報告します。追加または削除されたテンプレート、変更されたバリエーション、固定バージョンの更新、システム由来ではない新しい UI などを確認します。ドリフトレポートを作成し、それ以外は何も変更しません。

モード 3 — Storybook プロファイルを構築または更新する

intake/STORYBOOK-INTAKE.md を単独で実行します。 Storybook が新しいメジャーバージョンに移行したとき、ストーリーが 誤ったセクションに登録され始めたとき、またはシステムの読み込み順が 変わったときに適した方法です。

プロダクトの確認

ソースリポジトリ、稼働中の URL、またはその両方を使います。 intake/PRODUCT-INTAKE.md の質問 1 では、ユーザーに表示される言葉で それぞれの利点を説明します。どちらを使ったかを記録してください。 後続の成果物にはすべて、その内容が記載されます。

ファイルの配置先

ストーリーは、デザインシステムリポジトリ内の、ユーザーが選んだ Storybook セクション（デフォルト：Products/<product>/）に配置します。 テンプレートごとにストーリーファイルを 1 つ作成し、その中に バリエーションを名前付きストーリーとして記述します。各テンプレートの 先頭には代表的な Default を置きます。フィクスチャはストーリー ファイルの隣に配置します。

作業記録は、デザインシステムリポジトリのルートに置きます。

product-to-storybook/
├── STORYBOOK.md                     ← how this Storybook works, built once
├── markers.css                      ← the origin/placeholder stylesheet
└── <product>/
    ├── GARAGE.md                    ← intake answers, source, pinned version
    ├── INVENTORY.md                 ← templates and permutations, confirmed
    ├── GAPS.md                      ← the gap ledger
    ├── REPORT.md                    ← side-by-side proof, what was verified
    └── drift/
        └── YYYY-MM-DD.md            ← one per refresh

ds-inspection/、vibe-killer/、または ds-adoption-plan/ フォルダーと同じ階層です。プロダクトリポジトリに、関連スキルによる adoption-plan/MAPPING.md または product-inspection/GARAGE.md が ある場合は、まずそれらを読んでください。どの領域がシステム由来で、 どの領域がカスタムなのかはすでに記載されています。最初からやり直す のではなく、レンダリングしたページと照らし合わせて確認します。

このキットのファイル

• intake/STORYBOOK-INTAKE.md — ホスト Storybook を一度確認します
• intake/PRODUCT-INTAKE.md — 5 つの質問にプロダクトごとに一度回答します
• phases/phase-1-inventory.md — テンプレートとバリエーションを整理し、 その後チェックポイントを設けます
• phases/phase-2-capture.md — コンテンツの横断的な記録を固定します
• phases/phase-3-relocation.md — ストーリーを作成します
• phases/phase-4-proof.md — レンダリング、比較、検証、報告を行います
• phases/refresh.md — 差分を確認します
• reference/MARKERS.md — 出自とプレースホルダーの規約
• reference/CAPABILITIES.md — このスキルでできることとできないこと
• templates/ — 作業記録に含まれる各ファイルの出力テンプレート

文体

平易で、活気があり、具体的にします。インベントリは件数付きの テンプレート一覧です。ギャップ台帳はスクリーンショット付きの表です。 レポートには、何をレンダリングしたか、何が一致したか、何が変わったか、 その理由を記載します。読んだ人が、どの画面が Storybook に追加されたか、 どの領域がシステム由来ではないか、それらにどう対処すべきかを正確に 把握できる内容にしてください。