analyze-component-set-figma

analyze-component-set-figma — バリアントの状態機械 → CSS

Figma の COMPONENT_SET（1 つのコンポーネントのすべてのバリアントをまとめた紫色の破線コンテナー）を、コード生成用の設計図に変換します。どのプロパティ軸が状態で、どの軸がサイズなのか、各状態がどの CSS 疑似クラスまたは ARIA 属性に対応するのか、そして各状態がデフォルトのバリアントに適用する最小限の視覚的な差分を明らかにします。これにより、「Figma にはボタンのバリアントが 12 個ある」を、「.btn ルールを 1 つ出力し、:hover／:disabled のオーバーライドを追加する」に結び付けられます。

スキルの範囲

• use_figma のルール — まず公式の figma-use スキルを読み込んでください。これは Figma Plugin API の完全なリファレンスです。これらのスクリプトが前提とする重要事項：トップレベルの await と return を使うプレーンな JS（IIFE や figma.closePlugin() は使わない。console.log の内容は返されない）、各スクリプトの先頭で入力を const としてインライン化する、色の値は 0～1 の範囲にする、テキスト操作の前にフォントを読み込む、await figma.getNodeByIdAsync(...) を使う、そしてエラーはアトミックに処理される（スクリプトが失敗すると何も適用されません。エラーを読み、修正して再試行してください）。
• 完全な再帰ツリー（深さの制限なし、リアクション、インスタンス参照）には → deep-component-figma を使用してください。
• バリアントをラベル付きグリッドに並べ替えるには → arrange-component-set-figma を使用してください。
• プロパティ自体を追加／削除するには → component-properties-figma を使用してください。
• これはデザインシステム向けのコード生成機能です。ネイティブ MCP の get_design_context／ get_metadata では提供されません。これらは生の構造を返すだけで、バリアントから CSS への状態機械は返しません。

ワークフロー

1. COMPONENT_SET の ID を取得します。 ユーザーの選択（figma_get_selection）、検索、またはユーザーが貼り付けたノード ID から取得します。個別のバリアントではなく、セットである必要があります。スクリプトが型を検証します。
2. scripts/analyze-component-set.js を use_figma 経由で実行します（skillNames: "analyze-component-set-figma"）。最初に const COMPONENT_SET_ID を設定してください。
3. 結果を確認します。 variantAxes（各軸とそのオプション）、componentProps（VARIANT 以外の TEXT／BOOLEAN／INSTANCE_SWAP プロパティ → コードのプロパティ）、cssMapping（状態名 → CSS セレクター）と defaultSignature を含む stateMachine、およびバリアントごとの diffFromDefault が返されます。
4. コードを生成します。 defaultSignature をもとにデフォルトのバリアントを実装し、次に cssMapping の各エントリーに対して、そのバリアントの diffFromDefault だけを適用するルールを 1 つずつ追加します。componentProps はフレームワークのプロパティにマッピングします：BOOLEAN→boolean、TEXT→string、INSTANCE_SWAP→ReactNode／スロット、VARIANT→union。
5. 検証します。 stateMachine.states のすべての状態に CSS ルールが設定されていること、また差分内のトークン名（例：Color/Brand/Primary）がエクスポート済みトークンとして解決できることを照合します。

状態から CSS へのマッピング

スクリプトは状態軸の値を大文字と小文字を区別せずに正規化し、セレクターに変換します：

バリアントの値	CSS／ARIA セレクター
default	（ベースルール。セレクターなし）
hover	:hover
focus / focused / focus-visible	:focus-visible
active / pressed	:active
disabled	:disabled, [aria-disabled="true"]
error / invalid	[aria-invalid="true"]
selected	[aria-selected="true"]
checked	:checked
loading	[aria-busy="true"]
open / closed	`[aria-expanded="true"
filled	.has-value

補足

• 差分はデフォルトのバリアントを基準に計算されます。そのため、ある状態の diffFromDefault には、変更されるプロパティ（塗りつぶしトークン、ストローク、テキストの色、不透明度、エフェクト、子要素の表示／非表示）だけが含まれます。オーバーライドにはその項目だけを正確に出力し、変更のないプロパティを再指定しないでください。
• スクリプトは boundVariables（塗りつぶし／ストローク）を解決し、利用可能な場合はトークン名を返します。利用できない場合は、生の 16 進数カラーコードにフォールバックします。生成コードではトークン名を優先してください。
• 軸の検出はヒューリスティックです。state／status／interaction という名前の軸は状態軸、size／scale という名前の軸はサイズ軸と判断されます。セット内の軸に別の名前が付いている場合、cssMapping が空になることがあります。その場合は variantAxes を確認し、自分で状態をマッピングしてください。