FigmaのVariablesは、Variables画面のExport mode／Export modesからJSONへ書き出せます。画面で書き出すJSONと、Plugin API・REST APIで取得した変数オブジェクトは同じ形式ではありません。 APIの取得結果をそのまま保存しても、DTCG形式のデザイントークンになったとは限りません。
この記事は2026年10月3日に確認した公式仕様に基づく手順です。Figmaでの実際の書き出し・再読み込みやAPI接続は未検証です。モードのインポート・エクスポート
書き出す方法を選ぶ
| 目的 | 方法 | 確認すること |
|---|---|---|
| 1モードの値を手動で取り出す | Export mode | 対象コレクションとモード |
| コレクションの全モードを取り出す | Export modes | モードごとの値・参照 |
| 独自の監査用JSONを作る | Plugin API | 型・モードID・エイリアスの保持 |
| サーバーやCIで取得する | Variables REST API | Enterpriseの条件・スコープ・ファイル権限 |
| Tokens StudioのJSONからCSSを作る | Style Dictionaryとsd-transforms | 形式、テーマ、単位、ビルド設定 |
変数の作成・適用はVariablesの基本、モードが切り替わらない場合はモードの確認手順を参照してください。
Variables画面からJSONを書き出す
- 対象のDesignファイルでVariables画面を開きます。
- 1モードなら、コレクションを開いてそのモードを右クリックします。
- Export modeを選びます。
- コレクションの全モードなら、コレクションを右クリックしてExport modesを選びます。
- 保存されたJSONを開き、名前・型・値・参照を確認します。
名前だけでLight／Darkなどを判断せず、対象モードの値も確認します。読み込む側では既存モードのImport modeを使う方法がありますが、既存値を変更する前に書き出して保管し、コピーで試してください。
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では受け付けられます。すべてのトークン形式を同じまま相互変換できるとは考えないでください。対応する型・拡張・参照
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をCSSへ変換する前に
JSONの構文が正しいことと、変換先が意味を正しく解釈することは別です。少数のトークンで、色、数値、単位、参照、モード、名前の衝突を確認します。複数モードを全部読み込んで同じ名前へ上書きしないよう、出力するテーマを決めてください。Tokens StudioとStyle DictionaryのCSS出力