component-properties-figma

component-properties-figma — コンポーネントの API を定義してインスタンス化する

関連する 2 つの作業です。

1. コンポーネントのプロパティ API を作成する — TEXT、BOOLEAN、INSTANCE_SWAP、VARIANT プロパティを追加・編集・削除して、コンポーネントに適切な操作項目を公開します（React コンポーネントの props に相当する Figma の機能です）。
2. コンポーネントを使用する — インスタンスを作成して、そのプロパティ（ラベルのテキスト、ブール値の切り替え、バリアントの選択、サブインスタンスの差し替え）を設定します。

スキルの対象範囲

• use_figma のルール — 最初に公式の figma-use スキルを読み込んでください。Figma Plugin API の完全なリファレンスです。スクリプトで依存する基本事項は、トップレベルの await と return を使ったプレーンな JS（IIFE や figma.closePlugin() は使用しないこと。console.log の内容は返されません）、各スクリプトの先頭で const として入力値をインライン化すること、色を 0～1 の範囲で指定すること、テキスト操作の前にフォントを読み込むこと、await figma.getNodeByIdAsync(...) を使うこと、そしてアトミックエラー（スクリプトが失敗すると変更は何も適用されません。エラーを読み、修正して再試行してください）です。
• コンポーネントの既存のプロパティ定義／ステートマシンを読み取るには → analyze-component-set-figma または deep-component-figma を使用してください。
• これらはデザインシステムの作成・編集のための書き込み操作です。ネイティブ MCP の get_design_context ／ get_metadata（読み取り専用）では対応していません。

プロパティの種類

種類	制御する内容	defaultValue	備考
TEXT	テキストレイヤーの文字列のオーバーライド	"Label"	UI でテキストノードの文字列にバインドします
BOOLEAN	レイヤーの表示／非表示	true/false	レイヤーの表示状態にバインドします
INSTANCE_SWAP	スロットに入れるサブコンポーネント	コンポーネントの キー	ピッカーに選択肢を表示するには preferredValues を渡します
VARIANT	バリアントの軸（サイズ、状態など）	1 つのオプション文字列	COMPONENT_SET でのみ意味を持ちます

ワークフロー — プロパティの作成

1. COMPONENT_SET（または単独の COMPONENT）を対象にします。 個々のバリアントにはプロパティを追加できません。スクリプトはエラーを返し、親セットを使用するよう案内します。
2. scripts/add-property.js を使って 追加します（use_figma、skillNames: "component-properties-figma"）。NODE_ID、PROPERTY_NAME、PROPERTY_TYPE、DEFAULT_VALUE を設定します。addComponentProperty は #id サフィックス付きの名前を返すので、取得しておいてください。
3. 同じスクリプトの editComponentProperty(name, {...}) ／ deleteComponentProperty(name) を使って 編集／削除します（スクリプト内にコメントアウトされた例があります）。バリアント以外のプロパティを編集／削除する場合は、作成時に返されたサフィックス付きの名前を使用してください。
4. node.componentPropertyDefinitions を再読み込みして確認します（スクリプトがこれを返します）。

ワークフロー — インスタンス化してインスタンスのプロパティを設定

1. コンポーネントの識別情報を取得します。 公開済みライブラリの componentKey（推奨）および／またはローカルの nodeId を指定します。両方ある場合は両方渡してください。スクリプトはまずライブラリからのインポートを試し、次にローカルノードを試します。
2. scripts/instantiate-and-set.js を実行します。COMPONENT_KEY ／ COMPONENT_ID、任意の VARIANT（例：{ Size: "md", State: "default" }）、OVERRIDES、POSITION、PARENT_ID を設定します。
3. 同じスクリプトの setProperties パスを使って、既存のインスタンスのプロパティを設定します。このパスではメインコンポーネントを読み込み、サフィックスなしの名前と Name#id サフィックス付きの名前の両方を自動的に照合します。

補足

• インスタンスのプロパティキーには #nodeId サフィックスが付きます（TEXT／BOOLEAN／INSTANCE_SWAP の場合。例："Label#12:3"）。VARIANT プロパティは名前のみです。インスタンス化スクリプトはどちらの形式も解決するため、人が読める名前（Label）を渡せば、サフィックス付きのキーを見つけます。
• インスタンス内のテキストレイヤーを直接編集しても、エラーなしで失敗します。 必ず setProperties ／インスタンスプロパティを使い、ネストされたインスタンスのテキストノードで .characters を設定しないでください。
• componentKey が機能するのは公開済みのコンポーネントだけです。ローカルまたは未公開のコンポーネントには nodeId を使用してください。