mcpField
E
export-tokens-figma

export-tokens-figma

github.com/southleftデザイン・UI2082 回インストール21 週間前に更新
リポジトリ

export-tokens-figma について

Figma ファイルのローカル変数をデザイントークンとして書き出すスキルです。デザインとコード間でトークンを扱うチーム向けに、Figma Plugin API で変数を読み取り、エイリアスや複数モードの値を解決して、決定的な変換処理で複数形式を生成します。

主な機能

  1. 01Figma のローカル変数を読み取り
  2. 02エイリアスと複数モードの値を解決
  3. 03DTCG などのトークン形式で出力
  4. 04CSS、Tailwind、SCSS、TS などに変換
  5. 05名前の衝突やウェイトの問題を警告

活用シーン

  1. 01Figma のデザイントークンをコード用に書き出す
  2. 02複数モードの変数をテーマファイルに変換
  3. 03大規模なデザインシステムでコレクションを絞って出力

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/southleft/skills-for-figma --skill export-tokens-figma

インストール後、Claude Code で/export-tokens-figmaを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

references/
token-formats.md
scripts/
convert-tokens.mjs
read-variables.js

詳細

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

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 を使ったプレーンな JavaScript（IIFE や figma.closePlugin() は使わないこと。console.log は返されません）、各スクリプトの先頭で入力を const としてインライン化すること、色の値は 0～1 の範囲にすること、テキスト操作の前にフォントを読み込むこと、await figma.getNodeByIdAsync(...) を使うこと、そして アトミックなエラー処理（スクリプトが失敗した場合、何も適用されません。エラーを読み、修正して再試行してください）。
  • 逆方向（コード → Figma 変数）には、import-tokens-figma スキルを使ってください。

ワークフロー

  1. 対象範囲と形式を確認します。 出力形式（安全なデフォルトは dtcg）、モード／コレクションごとに分割するかどうか、出力先のパスを質問するか、推測します。アクティブな Figma ファイル、またはユーザーから提供された URL からファイルキーを取得します。
  2. 変数を読み取ります。 use_figma 経由で scripts/read-variables.js を実行します（skillNames: "export-tokens-figma"）。正規化されたコレクション／モード／変数のツリーが返されます。これには、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 フォーマッターと同じ形式です。手作業の変換で間違いやすい次の項目を正確に処理します：型ごとの単位（不透明度／行の高さは単位なし、間隔／角丸は 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} になります。参照を解決できるよう、すべてのコレクションをまとめてエクスポートしてください。

コメント

Markdown 対応