figma-analyze-component-set

figma-analyze-component-set — バリアント状態マシン → 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(...) を使うこと、そしてアトミックエラー（スクリプトが失敗すると何も適用されません。エラーを読み、修正して再試行してください）です。
• 完全な再帰ツリー（深さ無制限、リアクション、インスタンス参照）→ figma-deep-component を使用してください。
• バリアントをラベル付きグリッドに再編成する→ figma-arrange-component-set を使用してください。
• プロパティ自体を追加／削除する→ figma-component-properties を使用してください。
• これはデザインシステムのコード生成機能であり、ネイティブ MCP の get_design_context／ get_metadata では提供されません。これらは生の構造を返すだけで、バリアントから CSS 状態マシンへの変換は行いません。

ワークフロー

1. COMPONENT_SET の ID を取得します。 ユーザーの選択（figma_get_selection）、検索、またはユーザーが貼り付けたノード ID から取得します。個別のバリアントではなく、セットである必要があります。スクリプトが型を検証します。
2. use_figma を使って scripts/analyze-component-set.js を実行します （skillNames: "figma-analyze-component-set"）。最初に const COMPONENT_SET_ID を設定してください。
3. 結果を読みます。 variantAxes（各軸とその選択肢）、componentProps （バリアント以外の 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 を読み、状態を手動で対応付けてください。