figma-deep-component

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

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

スキルの範囲

• use_figma のルール — まず公式の figma-use スキルを読み込んでください。Figma Plugin API の完全なリファレンスです。これらのスクリプトで必要となる基本事項は、トップレベルの await と return を使ったプレーンな JS（IIFE や figma.closePlugin() は使用しないこと。console.log は返されません）、各スクリプトの先頭で const として入力をインライン化すること、色の値は 0～1 の範囲で指定すること、テキスト操作の前にフォントを読み込むこと、await figma.getNodeByIdAsync(...) を使うこと、そして アトミックエラー（スクリプトが失敗すると何も適用されません。エラーを読み取り、修正して再試行してください）です。
• ファイル全体の一覧（すべてのトークン／コンポーネント／スタイルを一度に取得）→ figma-design-system-inventory を使用します。
• バリアントセットを CSS の状態マシンとして分析（状態ごとの差分、擬似クラスへのマッピング）→ figma-analyze-component-set を使用します。
• この深さのツリー、解決済みトークン、リアクションの組み合わせは、ネイティブ MCP の get_design_context（選択範囲 1 件をレンダリングした概要）や get_metadata（フラットな構造）では取得できません。デザインシステムのコード生成機能をその上に追加するものです。

ワークフロー

1. ノード ID を取得します。 選択範囲（figma_get_selection）、検索、または貼り付けた ID から取得します。
2. 深度を選びます。 const DEPTH を設定します（デフォルトは 10）。深いデザインコンポーネントでも通常は約 6 階層を超えません。ペイロードを管理しやすくするため、まず小さめの数値を指定し、必要に応じて深くします。
3. scripts/deep-component.js を use_figma で実行します （skillNames: "figma-deep-component"）。先頭で 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（トリガー＋アクション：ナビゲーション／トランジション／遷移先）。
• 開発：annotations（ラベルの Markdown＋分類されたプロパティ）。

メモ

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