canvas-design-decomposition

Canvas のデザイン分解

必須トリガー（最初にこのスキルを読み込む）

コンポーネントライブラリのコンポーネント構成を提案する前、実装計画を作成する前、またはコンポーネントを実装する前に、このスキルを読み込み、従ってください。ユーザーが計画や分解だけを求めている場合も含みます。Canvas コンポーネントへの UI の分割方法をモデル化する場合（コンポーネントライブラリ、セクション、ページ全体）は、必ず適用してください。以下で説明するように、コンポーネントを作成、追加、またはスキャフォールドしようとする場合も同様です。次のいずれかに該当する場合は、トリガーとして扱ってください。

• Canvas コンポーネントの作成または追加： src/components/ に新しいフォルダーを作成する、component.yml とエントリーファイルを記述する（React プロジェクトでは index.jsx／.tsx、ヘッドレスプロジェクトではフレームワークに適したファイル）、チケットや仕様書からコンポーネントをスキャフォールドする、デザインからセクションをコーディングする、または名前の付いたブロック（ヒーロー、フッター、カードなど）を実装する場合。名前、スロット、バリアント、再利用性の整合性を保つため、スキーマや実装コードを書く前に分解してください。ただし、既存の安定した API 内の些細な 1 行の変更は除きます。
• ファイル、サイト、会話のいずれがきっかけであっても、Canvas のコンポーネントライブラリを設計または進化させる場合（領域の命名、再利用の判断、props／スロット、粒度の決定など）。
• メッセージに Figma URL（figma.com/design、figma.com/make、またはブランチ URL）か、Figma に関連付けられた明示的な node-id／フレームに関する記述が含まれている場合。
• レイアウトやコンポーネントの参考にする情報源が、既存のウェブサイト、スクリーンショット、スクレイピングしたページ、または参照 URLである場合（ライブ URL のキャプチャが必要な場合は、nebula-scrape-url と組み合わせてください）。
• 情報源がテキストのみ、または生成されたものである場合：文章のブリーフ、Markdown の仕様書、またはAI／プロンプトによって生成されたデザイン（レイアウトの説明、文章によるワイヤーフレーム、チャットから作成されたコンポーネント一覧など）。ピクセル情報がなくても、フェーズ A は適用されます。入力を分類し、不明点を列挙してください。
• あらゆる成果物や説明をもとに、デザイン、フレーム、画面、ページの実装、構築、再現、作り直し、または実装計画をユーザーが求める場合。

省略しないこと（よくある失敗例）

• 新規開発は対象外ではありません。 新しいページや Figma フレームをゼロから実装する場合も、このスキルが必要です。実装の詳細を確定する前に、デザインを一貫性のあるツリー、props、スロットに対応付けてください。
• リポジトリ内のドラフトファイルは近道にはなりません。 既存の pages/*.json、src/components/ 内の未完成コンポーネント、スクレイピングしたアセットは、出発点として役立つことがありますが、このスキルを読み、現在の成果物についてフェーズ A～G を完了する代わりにはなりません。ドラフトコードを分解結果と照合し、以前に分解が完了していると決めつけないでください。
• 計画も対象です。 ユーザーが実装計画だけを求めている場合も、このスキルを読み込み、ピクセル作業やツールによる近道に進む前に、領域 → コンポーネント → 配置を要約してください。

自動化ツールの出力（たとえば Figma MCP の参照 JSX、HTML エクスポート、生成コード）は、このワークフローへの入力であり、フェーズ A～G の完了に代わるものではありません。

デザイン成果物を、領域、ツリー、props とスロットの選択、粒度の確認を含む安定したコンポーネントモデルに変換してください。各ノードのprops とスロットをスケッチしていなければ、分解は未完成です。Canvas の作成者はこの API を介してツリーを操作するため、実装後ではなく、構造とともに計画してください。

計画時には、単一のフレームやチケットだけにとらわれず、各要素がほかにどこで使われるか、何が異なるか（コピー、子要素、variant）を考えてください。使い捨ての名前や、特定のキャンペーンのコンテンツをハードコードする props よりも、再利用可能な machineName、可変領域用のスロット、variant によるプリセットを優先してください。

禁止事項： このワークフロー内でピクセルを実装したり、component.yml を記述したりしないでください。まず構造と props／スロットのスケッチを完成させてから、引き継いでください。

スキルの順序

1. このスキル — ワークフロー、ツリー、引き継ぎ。
2. canvas-component-composability — 共通の props／slots のルール、繰り返し可能なコンテンツ、粒度の確認。
3. canvas-component-metadata — 厳密な component.yml スキーマ。
4. canvas-component-definition — フォルダーの契約、モック、命名の基準。
5. implement-design — ピクセルレベルの忠実度 ソースが Figma の場合、かつツリーを確定した後に使用します（使用時は Figma MCP が必要です）。Figma 以外のソースでは、ユーザーが Figma ファイルを参照するよう指示しない限り、このステップを省略し、確定したツリーとトークンに基づいて実装します。

Canvas の繰り返し可能なリスト／グリッドについては、 canvas-component-composability/references/repeatable-content.mdを参照してください。

入力

フェーズ A でソースを分類します。一般的なカテゴリは次のとおりです。

種類	例
デザインツール	Figma ファイル、フレームのエクスポート、FigJam
ライブリファレンス	既存の本番サイトまたはステージングサイト、競合サイトの URL
キャプチャ済みメディア	スクリーンショット、PDF、ブランド資料
構造化されたスクレイプ	ツールを介して取得した HTML／CSS スナップショット
プロンプト／文章	ユーザーのブリーフ、AI 生成のレイアウト説明、Markdown ワイヤーフレーム

任意の補助ツール：

• URL のキャプチャ：nebula-scrape-url（Figma またはドキュメントには使用しません）。
• Figma の忠実度確認（分解後）： implement-design。

ワークフロー（必須）

フェーズ A → G を順番に完了します。各フェーズには終了条件があります。 フェーズ F が失敗した場合は、ツリーを修正し、該当ノードのみフェーズ E を再実行します。

フェーズ A — インテークと要件整理

• 入力の種類を特定します：デザインファイル（例：Figma）、ライブサイト／スクレイプ、スクリーンショット、またはテキストのみ／プロンプト生成の仕様。
• 不明点を列挙します：ブレークポイント、空の状態、コピーの最大長、メディアのアスペクト比、ホバー／フォーカス／アクティブ状態、アクセシビリティの期待値。
• 各不明点にリスクを付けます：低／中／高（構造が大きく変更される可能性）。

終了条件： 入力の種類を明記し、リスク付きの不明点を列挙します（回答が不足しているものがあってもワークフローは続行します）。

フェーズ B — 領域マップ

• デザインを領域に分けます（例：ヘッダー、ヒーロー、コンテンツ帯、サイドバー、フッター、モーダルの枠）。
• 各領域について、ラベル、目的（1 行）、分類 — chrome（シェル）、navigation、または content — を記載します。

終了条件： 各領域の目的と分類を含む、順序付きの領域リストが完成していること。

フェーズ C — コンポーネント候補の一覧

• 領域を候補の machineName に対応付けます（canvas-component-definitionに従った kebab-case のフォルダー名）。
• 再利用可能な基本名を優先し、実際に一度きりの用途でない限り、コンポーネント名を増やさず、props／コンポジションでバリエーションを表現します。
• 同じパターンが 2 回以上登場する場合は、再利用回数を記載します。
• 汎用化： 各候補について、ほかに想定されるコンテキスト（別のページ、より短いコピー、異なる子要素）を記載します。この画面でしか意味をなさない場合は、再利用可能な範囲になるまで名前を変更するか、分解します。

終了条件： 候補の machineName、責務、再利用回数、親領域を含む表が完成していること。

Phase D — コンポーネントツリー

• 親子関係を構築します。レイアウトシェルとコンテンツリーフを区別します。
• **レイアウトの所有権：**複数列のグリッド、ページ単位のスタック、セクションのラッパーは、レイアウト指向のコンポーネントに配置します。すべてのインスタンスでレイアウトが変わらない場合を除き、無関係なグリッドをコンテンツコンポーネントに組み込まないでください。
• ツリーは、ネストされたアウトラインまたは Mermaid 図で表現します（Mermaid のノード ID にスペースは使わず、camelCase またはアンダースコアを使用します）。

**完了条件：**ツリーにインベントリのすべての行が含まれ、レイアウトとコンテンツの役割が明確になっています。

Phase E — Props とスロット（ノードごと）

必須：すべての分解でこのフェーズを実施します。Props とスロットは後付けではなく、編集者がツリーをどのように使用するかを定義します。ツリーの各ノードについて、次の項目をまとめます。

• **Props：**編集者が直接設定する構成と単純な値（バリアント、ブール値、短い文字列、URL、列挙型）。用途と大まかな型分類（string、boolean、enum、画像／参照など）を記載します。最終的な YAML は不要です。実際の Props とスロットの判断基準、バリアントと細分化の指針、Props の順序については、canvas-component-composability に従ってください。このフェーズでは判断を記録しますが、その基準を再定義するものではありません。
• **スロット：**作成者が子コンポーネントや任意のブロックを組み合わせる領域です。スロット名、許可されるコンテンツ、空の場合の動作（折りたたむ、プレースホルダーを表示する、最小の高さを設ける）を記載します。
• **実装スタイル：**引き継ぎ資料に、variants（デフォルト）または granular props のいずれかを記載し、理由を1行で説明します。Phase E の記述形式については、references/props-vs-slots-rubric.md を参照してください。

**完了条件：**すべてのノードで Props とスロットの概要が示され、実装スタイルが明記され、繰り返し可能なリッチコンテンツの子要素が Props のオブジェクト配列としてモデル化されていません。

Phase F — 粒度の監査

共有の粒度チェックリストを canvas-component-composability で実施します。 このフェーズでは、その共有ルールに照らして候補ツリーを監査し、結果を記録します。ここで別の分割／統合基準を作成しないでください。Phase F の監査メモについては、references/granularity.md を参照してください。

• 各ノードに合格／不合格を付け、簡潔な理由を記載します。
• 不合格のノードがある場合は、統合、分割、または抽出を行い、変更したノードのみを対象に Phase E を再実施します。
• 意図的な例外は明示的に記録します。

**完了条件：**すべてのノードが合格するか、不合格の理由が明示されています。

Phase G — 引き継ぎ

以下のテンプレートを使用して、Markdown の成果物を1つ作成します。次のステップには、以下を示します。

• スキーマ：canvas-component-metadata
• 構成上の例外： canvas-component-composability
• 契約とモック： canvas-component-definition
• Figma との視覚的な一致： implement-design （該当する場合）

**完了条件：**テンプレートが記入され、イシューまたは MR に貼り付けられる状態です。

**ここでは対象外：**ページ JSON (canvas-page-definition)、検証の実行 (nebula-component-validation)。

出力テンプレート

コピーして記入します。

## Summary

- **Design source:** (e.g. Figma URL | live URL | screenshots | prompt/spec
  text)
- **Scope:** (single component | section | full page)
- **Version / date:**

## Assumptions and open questions

- ...

## Region map

| Region | Purpose | Class |
| ------ | ------- | ----- |
| ...    | ...     | ...   |

## Component inventory

| machineName (candidate) | Responsibility | Reuse | Parent region | Notes |
| ----------------------- | -------------- | ----- | ------------- | ----- |
| ...                     | ...            | ...   | ...           | ...   |

## Component tree

(Nested list or Mermaid)

## API sketch (per component)

### `machine-name`

**Implementation style:** variants (default) | granular props — one-line
rationale

**Props** (table rows in editor order: **variant first** when there is a single
primary variation enum; **content first** otherwise—then configuration)

| Name (camelCase intent) | Purpose | Required? | Kind (string / bool / enum / …) |
| ----------------------- | ------- | --------- | ------------------------------- |
| ...                     | ...     | ...       | ...                             |

**Slots**

| Slot key | Purpose | Empty behavior |
| -------- | ------- | -------------- |
| ...      | ...     | ...            |

## Granularity audit

| Component / node | Pass/Fail | Notes / fix |
| ---------------- | --------- | ----------- |
| ...              | ...       | ...         |

## Next steps

- [ ] `canvas-component-composability` — edge cases for props/slots,
      repeatability, or granularity
- [ ] `canvas-component-metadata` — draft `component.yml`
- [ ] `canvas-component-definition` — folder, entry file, mocks
- [ ] `implement-design` — Figma fidelity pass (only when matching a Figma file)

参考情報

• canvas-component-composability
• references/granularity.md
• references/props-vs-slots-rubric.md
• references/worked-example.md

重複の防止

• component.yml の文法全体を再掲しないでください。canvas-component-metadata を参照してください。
• 再利用可能な Props／スロットや粒度のルールブックをここで再掲しないでください。canvas-component-composability にリンクしてください。