figma-import-tokens

figma-import-tokens — デザイントークン → Figma 変数

トークンソース（DTCG の tokens.json、Tailwind/SCSS のエクスポート、またはプレーンなトークンオブジェクト）から Figma 変数を作成・更新します。エイリアスと複数モードの値に対応しています。再実行しても安全です。保存済みの Figma ID → キー → 完全一致する名前の順に変数を照合するため、重複を作成せず、既存の変数を更新します。

スキルの範囲

• use_figma のルール — まず公式の figma-use スキルを読み込んでください。Figma Plugin API の完全なリファレンスです。これらのスクリプトが前提とする要点は、トップレベルの await と return を使ったプレーンな JS（IIFE は不可。figma.closePlugin() は使用せず、console.log の内容は返されません）、各スクリプトの先頭で入力を const としてインラインで定義すること、色は 0～1 の範囲で指定すること、テキスト操作の前にフォントを読み込むこと、await figma.getNodeByIdAsync(...) を使うこと、そして アトミックエラー（スクリプトが失敗すると変更は一切適用されません。エラーを読み、修正して再試行してください）です。
• 逆方向（Figma → コード）には → figma-export-tokens を使います。

ワークフロー

1. ソースを正規のトークンリストに、決定的な方法で解析します。 DTCG 入力の場合（figma-export-tokens が生成したものを含む）は、手作業でフラット化せず、同梱のパーサーを実行してください。

   node scripts/parse-tokens.mjs tokens.tokens.json --default-mode Light --collection Brand
   # --strip-prefix "ds-"   drops a leading name prefix on import (e.g. ds-color/x → color/x)
   

   パーサーは、適用スクリプトに貼り付ける正確な COLLECTION_NAME / MODES / TOKENS 定数を出力します。$type → Figma の型、{ref} エイリアス、複数モード（$extensions…modes）、dimension の単位の除去、variableId の往復変換を処理します。DTCG 以外のソース（Tailwind/SCSS エクスポート）の場合は、まず DTCG にエクスポートするか、TOKENS 配列を手作業で作成してください。 { name: "Color/Brand/Primary", type: "COLOR"|"FLOAT"|"STRING"|"BOOLEAN", values: { <mode>: literal | { reference: "{Color.Brand.500}" } }, figmaVariableId? }。
2. 競合ポリシーを決めます。 デフォルトでは値はコード側を優先しますが、確認せずに Figma のみに存在する変数を削除することはありません。対象のコレクション名とモードのリスト（最初のモードがデフォルト）を確認してください。
3. 適用します。 解析したデータを scripts/apply-tokens.js の先頭にある定数に設定し、use_figma を介して実行します（skillNames: "figma-import-tokens"）。スクリプトは 2 回のパス（まずリテラル、次にエイリアス）を実行し、{ created, updated, errors, variableIds } を返します。
4. 報告して検証します。 作成・更新件数と errors を提示します。読み戻し（figma-export-tokens の読み込みスクリプトまたは get_variable_defs）を実行し、値が反映されたことを確認します。

注意点と落とし穴

• 2 パスでの処理が必須です — createVariableAlias の前にエイリアスの参照先が存在している必要があります。スクリプトが対応するため、1 パスにまとめないでください。
• 色には 3 桁、6 桁、8 桁の 16 進文字列を使用でき、自動的に {r,g,b,a} の 0～1 の値に変換されます。
• スコープ：新しい変数のデフォルトは ALL_SCOPES で、すべてのピッカーに表示されます。インポート後に、適切な対象範囲に合わせて variable.scopes を設定することを検討してください（figma-manage-variables を参照）。
• 往復変換：figma-export-tokens が以前に生成したファイルをインポートするのが最適な方法です。保存された variableId により、正確に照合できます。