figma-export-tokens

figma-export-tokens — Figma variables → デザイントークン

Figma ファイル内のすべてのローカル変数を読み取り、デザイントークンファイルを出力します。標準の出力形式は DTCG（W3C Design Tokens Community Group JSON）で、CSS、Tailwind、SCSS、TS、JSON はこれを基に生成されます。

生の REST エクスポートより優れている理由： Figma の Variables REST API は Enterprise 専用です（Starter／Pro／Org では 403）。このスキルは use_figma 経由で Plugin API を使って読み取るため、すべてのプランで動作し、get_variable_defs（デフォルトモードのみ）が取りこぼすエイリアスと複数モードの値も解決します。

スキルの範囲

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

ワークフロー

1. 対象範囲と形式を確認します。 出力形式（安全なデフォルトは dtcg）、モード／コレクションごとに分割するかどうか、出力パスを確認するか、必要に応じて推定します。アクティブな Figma ファイル、またはユーザーが提示した URL からファイルキーを取得します。
2. 変数を読み取ります。 scripts/read-variables.js を use_figma 経由で実行します（skillNames: "figma-export-tokens"）。16 進数カラー、解決済みのエイリアス参照、スコープ、コード構文を含む、正規化されたコレクション／モード／変数のツリーが返されます。
3. 読み取り結果をファイルに保存します。 例：variables.json。
4. 決定的に変換します。 同梱のコンバーターを実行します（Node 18 以上、依存関係ゼロ）。変換を手作業で書かないでください — このスクリプトが信頼できる唯一の情報源であり、実行のたびに同一の出力を生成します。

   node scripts/convert-tokens.mjs variables.json --format dtcg --out tokens/
   # --format: dtcg (default) | css-vars | tailwind-v4 | tailwind-v3 | scss | ts-module
   #           | json-flat | json-nested | style-dictionary-v3 | tokens-studio
   #           (aliases: css, tailwind, ts)
   # --out <dir>  write file(s) — tokens-studio writes several; omit to print to stdout
   # --prefix <p>            prefix CSS/SCSS var names
   # --modes Light,Dark      include only these modes (default: all)
   # --collection <substr>   include only collections whose name contains <substr>
   

   これは Console の figma_export_tokens フォーマッターと一致します。手作業の変換で誤りやすい点を正確に処理します。型ごとの単位（opacity／line-height は単位なし、spacing／radius は px）；複数モード（CSS と Tailwind v4 は :root と .dark／[data-theme] を出力、TS／JSON は {mode: value} を出力、SCSS はモード名を接尾辞として付加、DTCG は $extensions 内に保持）；エイリアス → var()／{ref}；フォントウェイト名 → 数値；DTCG のラウンドトリップ用メタデータ。また、スラッグの衝突や数値以外のウェイトについて警告します。（style-dictionary-v3 と tailwind-v3 は Console と同様にプライマリモードを使用します。これらの形式にはネイティブな複数モードの表現方法がありません。）
5. 結果を報告します。 保存したパスと、コンバーターが出力した警告（衝突／ウェイトの問題は Figma ファイルに関する重要な検出事項なので、ユーザーに伝えてください）を提示します。

注意事項

• コンバーターは決定的で、正式な実装です。 references/token-formats.md に出力形式が記載されています。これは参照用であり、手作業で再実装するものではありません。
• 実行環境： read-variables.js は use_figma 経由でどこでも実行できます。convert-tokens.mjs は Node 用なので、ターミナルを利用できるエージェント（Claude Code、Claude Desktop の Code タブ、Cursor、Codex、Gemini CLI）が必要です。シェルのない通常の Desktop／Web チャットでは、保存した variables.json を使って自分のマシンでコンバーターを実行するか、DTCG のみを対象としたベストエフォートのインライン変換を利用してください。
• 大規模なシステム： 読み取り結果が大きい場合は、保存する前に対象を特定のコレクション名に絞ってください。
• コレクションをまたぐエイリアスは var(--…)／{ref} になります。これらの参照を解決できるよう、すべてのコレクションをまとめてエクスポートしてください。