import-tokens-figma

import-tokens-figma — デザイントークン → 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 → コード）→ export-tokens-figma。

ワークフロー

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

   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: "import-tokens-figma"）経由で実行します。2 回のパスで処理されます。最初にリテラル、次にエイリアスを処理し、{ created, updated, errors, variableIds } を返します。
4. 報告して検証します。 作成数と更新数、および errors を提示します。読み戻し（export-tokens-figma の読み取りスクリプト、または get_variable_defs）を実行して、値が正しく反映されたことを確認します。

注意点と落とし穴

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