figma-component-properties

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

関連する作業は 2 つあります。

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

スキルの範囲

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

プロパティの種類

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

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

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

ワークフロー — インスタンスの作成とプロパティ設定

1. コンポーネントの ID を取得します。 公開済みライブラリの 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 を使ってください。