deep-component-figma

deep-component-figma — トークンを解決した無制限深度のツリー

1 つのノード（通常は COMPONENT／COMPONENT_SET／INSTANCE ですが、どのノードでも使用できます）を選び、指定した深度まで再帰的にたどります。すべての階層で、レイアウト（オートレイアウト、パディング、間隔、サイズ設定）、ビジュアルプロパティ（塗り、線、線幅、角丸、エフェクト、不透明度）、テキストノードのタイポグラフィ、トークン名とコード構文に解決されたboundVariables、INSTANCE のメインコンポーネント参照（メインコンポーネントがバリアントかどうか、およびそのセットを含む）、プロトタイプのreactions、Dev Mode のannotationsを取得します。高精度なコード生成に最適な、単一コンポーネントの最も包括的な読み取り機能です。

スキルの適用範囲

• use_figma のルール — まず公式の figma-use スキルを読み込んでください。これは Figma Plugin API の完全なリファレンスです。これらのスクリプトで重要なのは、トップレベルのawaitとreturnを使う通常の JavaScript（IIFE やfigma.closePlugin()は使わないこと。console.logの内容は戻り値になりません）、各スクリプトの先頭でconstとしてインライン化する入力、0～1の範囲のカラー値、テキスト操作の前にフォントを読み込むこと、await figma.getNodeByIdAsync(...)、そしてアトミックエラー（スクリプトが失敗すると、変更は一切適用されません。エラーを読み、修正して再試行してください）です。
• ファイル全体のインベントリ（すべてのトークン／コンポーネント／スタイルを一度に取得） → design-system-inventory-figmaを使います。
• バリアントセットを CSS のステートマシンとして扱う場合（状態ごとの差分、擬似クラスへのマッピング） → analyze-component-set-figmaを使います。
• このようにツリーを深くたどり、トークンを解決してreactionsを取得する機能は、ネイティブ MCP のget_design_context（選択対象をレンダリングした単一選択の概要）やget_metadata（フラットな構造）が返すものではありません。デザインシステムのコード生成機能をさらに拡張するものです。

ワークフロー

1. ノード ID を取得します。 選択（figma_get_selection）、検索、または貼り付けた ID から取得できます。
2. 深度を選びます。 const DEPTHを設定します（デフォルトは 10）。深いデザインコンポーネントでも、通常は約 6 階層を超えません。ペイロードを扱いやすくするため、まず小さめの値を使い、必要に応じて深くしてください。
3. 実行します。 use_figma（skillNames: "deep-component-figma"）を介してscripts/deep-component.jsを実行します。先頭でconst NODE_IDとconst DEPTHを設定してください。
4. コードを生成します。 返されるツリーは、構築すべき DOM を反映しています。生の16進数カラー値よりもboundVariablesのトークン名（およびそのcodeSyntax）を優先し、インポート済みコンポーネントを再利用するにはmainComponent参照を、インタラクションやナビゲーションを設定するにはreactionsを使ってください。
5. ペイロードが大きすぎる場合は、DEPTHを小さくするか（上限を超えるノードはchildCountと_depthLimitReachedマーカーで要約されます）、より小さなサブノード ID を対象にしてください。

各ノードに含まれる情報

• 識別情報：id、name、type、visible。非表示のコンポーネント以外のノードには_hiddenマーカーが付き、再帰的な処理の対象外となります。
• レイアウト：layoutMode、軸方向のサイズ設定／配置、padding*、itemSpacing、counterAxisSpacing、layoutWrap、幅／高さの最小値・最大値、clipsContent。
• ビジュアル：fills、strokes、strokeWeight、cornerRadius、effects、opacity（デフォルト値以外の場合のみ。figma.mixedの値は安全にスキップされます）。
• タイポグラフィ（TEXT）：characters、fontSize、fontFamily／fontStyle、fontWeight、lineHeight、letterSpacing、配置、テキストの省略、大小文字、装飾。
• トークン：バインドされているプロパティごとに、boundVariablesを{ id, name, collection, resolvedType, codeSyntax }として解決します。
• インスタンス：mainComponent（id、name、key、isVariant、セットの名前／ID）とcomponentProperties。
• 定義（COMPONENT／COMPONENT_SET）：componentPropertyDefinitions、variantProperties。
• プロトタイプ：reactions（トリガーとアクション：ナビゲーション／トランジション／移動先）。
• Dev：annotations（ラベルのマークダウンと分類されたプロパティ）。

メモ

• 解決済みトークンはあらゆるプランで機能します — 変数の検索には Plugin API が使用されるため、Enterprise 以外のファイルでも、不透明な VariableID: エイリアスではなくトークン名が取得されます。
• ルートノードは、確認用に _variableMapSize と _maxDepthUsed をエコーします。
• 読み取り操作であっても affectedNodeIds: [NODE_ID] を返します — 規約を統一するためです。