Figma VariablesをJSONへ書き出す方法｜Export modes・DTCG・APIの違い

FigmaのVariablesは、Variables画面のExport mode／Export modesからJSONへ書き出せます。画面で書き出すJSONと、Plugin API・REST APIで取得した変数オブジェクトは同じ形式ではありません。 APIの取得結果をそのまま保存しても、DTCG形式のデザイントークンになったとは限りません。

この記事は2026年10月3日に確認した公式仕様に基づく手順です。2026年10月12日に、Figmaで色の変数1つを書き出し、JSONの中身を確認しました。再読み込みやAPI接続は未検証です。モードのインポート・エクスポート

書き出す方法を選ぶ

変数の作成・適用はVariablesの基本、モードが切り替わらない場合はモードの確認手順を参照してください。

Variables画面からJSONを書き出す

1. 対象のDesignファイルでVariables画面を開きます。
2. 1モードなら、コレクションを開いてそのモードを右クリックします。
3. Export modeを選びます。
4. コレクションの全モードなら、コレクションを右クリックしてExport modesを選びます。
5. 保存されたJSONを開き、名前・型・値・参照を確認します。

名前だけでLight／Darkなどを判断せず、対象モードの値も確認します。読み込む側では既存モードのImport modeを使う方法がありますが、既存値を変更する前に書き出して保管し、コピーで試してください。

2026年10月12日に、Figmaの日本語表示で、Variablesの画面を確認しました。

画面の左に「コレクション」と「グループ」、右に「名前」と「値」の一覧が出ます。

コレクションを右クリックすると、「名前を変更」「エクスポートモード」「削除」のメニューが出ました。

本文の「Export modes」は、日本語表示では「エクスポートモード」にあたります。

あなたはどっち？目的から選ぶ書き出し方法の判定フロー

次の順で、書き出し方法を選びます。

1. 1つのモードの値を、手動で取り出したい：Variables画面で、そのモードを右クリックして Export mode を選びます。
2. コレクションの全モードを取り出したい：コレクションを右クリックして Export modes を選びます。
3. 型・モードID・エイリアスを保持した、独自の監査用JSONを作りたい：Plugin APIを使います。
4. サーバーやCIで取得したい：Variables REST APIを使います。Enterpriseの条件、スコープ、ファイル権限を確認します。
5. Tokens StudioのJSONからCSSを作りたい：Style Dictionaryとsd-transformsを使います。形式、テーマ、単位、ビルド設定を確認します。

画面で書き出すJSONと、Plugin API・REST APIで取得した変数オブジェクトは、同じ形式ではありません。

DTCG形式とFigma固有の型を確認する

DTCG形式では$typeと$valueで型と値を表します。次は説明用の小さな例で、Figmaの実ファイルから取得した値ではありません。

{
  "spacing-small": { "$type": "number", "$value": 8 },
  "spacing-button": { "$type": "number", "$value": "{spacing-small}" },
  "label": { "$type": "string", "$value": "送信" }
}

{spacing-small}はエイリアスです。参照先を落として1項目だけ移すと、参照を解決できなくなる場合があります。また、numberの8をCSSの8pxとして使うかどうかは、出力側の変換設計です。Figmaから数値を取得しただけで単位は決まりません。

FigmaのインポートにはDTCG形式に加え、Figma固有の扱いがあります。dimensionはpx、durationはs、fontFamilyは単一のフォント名文字列が対応条件です。Booleanはnumberとcom.figma.type拡張で表現され、stringは公式DTCGの型として定義されていませんがFigmaでは受け付けられます。すべてのトークン形式を同じまま相互変換できるとは考えないでください。対応する型・拡張・参照

書き出したJSONを、テキストエディタで開いた画面です。

色の変数は、$typeがcolor、$valueにcolorSpaceのsrgb・components・alpha・hexが入っていました。

$extensionsには、com.figma.variableIdとcom.figma.scopesが記録され、全体のモード名はcom.figma.modeNameに「Mode 1」と入っていました。

Plugin APIで変数の元情報を取得する

Plugin APIでは非同期メソッドでローカル変数とコレクションを取得できます。次はプラグインのメインコードへ組み込むための、監査用JSONを作る例です。ファイルのダウンロード処理やDTCG変換までは含みません。

async function variablesSnapshot() {
  const collections = await figma.variables.getLocalVariableCollectionsAsync();
  const variables = await figma.variables.getLocalVariablesAsync();
  return {
    collections: collections.map(c => ({
      id: c.id,
      name: c.name,
      defaultModeId: c.defaultModeId,
      modes: c.modes,
      variableIds: c.variableIds
    })),
    variables: variables.map(v => ({
      id: v.id,
      name: v.name,
      collectionId: v.variableCollectionId,
      type: v.resolvedType,
      valuesByMode: v.valuesByMode
    }))
  };
}
const snapshot = await variablesSnapshot();
console.log(JSON.stringify(snapshot, null, 2));

getLocalVariablesAsync('STRING')のように種類を渡すと、取得対象が絞られます。全型を対象にする場合は引数なしで取得します。コレクションのmodesと変数のvaluesByModeを対応付け、エイリアスをIDのまま残すか名前へ変換するかを決めます。Plugin APIの変数取得

公式のvariables-import-exportサンプルもありますが、基本的な入出力のサンプルです。公式READMEではcolor・number・aliasに対応し、読み込みは1回に1コレクション・1モードという制限を説明しています。Figma本体の全機能を扱う完成版ではありません。開発環境はプラグイン開発入門を参照してください。

REST APIで取得する場合

GET /v1/files/:file_key/variables/localは、公式資料でEnterprise組織のfull member向けとされています。file_variables:readスコープが必要で、Tier 2に分類されます。通常のファイル内容を取得できるトークンでも、同じ条件でVariablesを取得できるとは限りません。Variables REST API

localはファイル内のローカル変数と使用しているリモート変数を列挙します。publishedのエンドポイントはモードを返さないため、モードの値を確認する場合は公開元ファイルのlocalを確認します。返り値をDTCGへ変換するなら、型、モード、エイリアス、色の表現と単位を処理する必要があります。

押さえておきたい最新仕様と注意点

• 画面から書き出すJSONには、色の値だけでなく、変数のIDやスコープ（$extensions）も入る
• ファイル名は、モード名を使った「Mode 1.tokens.json」の形になった
• 日本語表示では、メニューの名前が英語の名称と違う（例：エクスポートモード）
• 読み込む側で参照を解決できるか、書き出したJSONで確認する

2026年10月12日の画面での確認で、Figmaの更新で名前や形式が変わることがあります。

よくある質問：Variablesの書き出しで迷ったときのチェックリスト

Export modeとExport modesは、何が違いますか？

Export modeは1つのモードの値を、Export modesはコレクションの全モードを書き出します。保存されたJSONを開き、名前・型・値・参照を確認してください。

APIで取得した結果は、そのままDTCG形式のトークンになりますか？

なるとは限りません。画面で書き出すJSONと、APIで取得した変数オブジェクトは同じ形式ではありません。APIの取得結果をそのまま保存しても、DTCG形式のデザイントークンになったとは限りません。

エイリアスがあるとき、1項目だけ移せますか？

参照先を落として1項目だけ移すと、参照を解決できなくなる場合があります。{spacing-small}のようなエイリアスは、参照先もあわせて確認してください。

numberの8は、CSSの8pxになりますか？

Figmaから数値を取得しただけで、単位は決まりません。numberの8をCSSの8pxとして使うかどうかは、出力側の変換設計です。

FigmaにインポートできるDTCGの型には、どんな条件がありますか？

dimensionはpx、durationはs、fontFamilyは単一のフォント名文字列が対応条件です。Booleanはnumberとcom.figma.type拡張で表現され、stringはFigmaでは受け付けられます。すべてのトークン形式を同じまま相互変換できるとは考えないでください。

インポートの前に、何をしておくべきですか？

既存値を変更する前に書き出して保管し、コピーで試してください。読み込む側では、既存モードのImport modeを使う方法があります。

JSONをCSSへ変換する前に

JSONの構文が正しいことと、変換先が意味を正しく解釈することは別です。少数のトークンで、色、数値、単位、参照、モード、名前の衝突を確認します。複数モードを全部読み込んで同じ名前へ上書きしないよう、出力するテーマを決めてください。Tokens StudioとStyle DictionaryのCSS出力