Tokens StudioとStyle Dictionaryの連携｜JSONからCSS変数を出力する

Tokens StudioはFigmaでデザイントークンを扱うプラグイン、Style DictionaryはJSONのトークンをCSSなどへ変換するツールです。Tokens Studioの形式を扱う場合は、sd-transformsを登録し、設定にtokens-studioのpreprocessorも指定します。

この記事ではGitHub同期の準備と、小さなJSONからCSSを生成する例を説明します。2026年10月3日に、Windows・Node.js 24.15.0・Style Dictionary 5.5.5・sd-transforms 2.0.3で掲載サンプルのローカル変換を確認しました。Figmaプラグインの操作、GitHubへのpush・pull、プロジェクト全体のテーマ変換は未検証です。Tokens Studioの変換ガイド

全体の流れ

1. Tokens Studioでトークンを作成し、JSONとして保存・同期します。
2. 使用するトークンセット・テーマを決めます。
3. Style Dictionaryとsd-transformsで、名前・値・単位をCSS向けに変換します。
4. 生成したCSSを確認して、アプリやWebサイトへ読み込みます。

Figma本体のVariablesとTokens Studioは同じデータ管理機能ではありません。Figmaのモードから取り出す方法はVariablesのJSON書き出しで説明しています。

GitHub同期を準備する

Tokens Studioの公式ガイドは、空でないリポジトリを用意するよう案内しています。新規の場合はREADMEを追加します。同期用の個人アクセストークンはGitHubのもので、Figma用PATとは別です。GitHub同期の公式手順

プラグインのSettings → Sync providersでGitHubを追加し、owner/repo、ブランチ、保存先のファイルまたはフォルダーを設定します。書き込みには、fine-grainedトークンの対象リポジトリでContentsのRead and Writeが必要です。classicのrepoスコープを使う方式もありますが、アクセス範囲を確認してください。

Pushはプラグインからリポジトリへ、Pullはリポジトリからプラグインへ反映する方向です。既存JSONを上書きする前に差分を確認します。フォルダーへの複数ファイル同期、ブランチ切り替え、ThemesなどはPro機能に関係するため、現在の契約条件も確認してください。

Node.jsとパッケージを用意する

今回確認したStyle Dictionary 5.5.5はNode.js 22以上が必要です。sd-transforms 2.0.3のpeerDependenciesはStyle Dictionaryの^5.0.0です。以下は再現範囲をそろえるために版を固定したコマンドで、「常に最新」という意味ではありません。

node --version
npm install style-dictionary@5.5.5 @tokens-studio/sd-transforms@2.0.3

sd-transformsはESMです。次のビルドファイルは.mjsで保存すると、既存package.jsonのtypeを変更せず実行できます。sd-transformsの公式README、Style Dictionary公式

小さなトークンJSONを用意する

tokens/base.jsonへ次を保存します。色、単位を持つ余白、参照を含む説明用データです。Figmaファイルから実際に取得したトークンではありません。

{
  "color": {
    "brand": { "type": "color", "value": "#167ac6" },
    "button": { "type": "color", "value": "{color.brand}" }
  },
  "space": {
    "small": { "type": "spacing", "value": "12px" }
  }
}

この例はtype・valueの形式です。DTCGの$type・$valueを使う場合は、同じ入力群に両形式を混在させないようにします。Tokens Studioからの単一ファイル出力ではセット名やテーマの管理データが付く場合があり、下の平坦なサンプルと同じ構造とは限りません。Style Dictionaryのトークン形式

build-tokens.mjsでCSSを生成する

import StyleDictionary from 'style-dictionary';
import { register } from '@tokens-studio/sd-transforms';

register(StyleDictionary);
const dictionary = new StyleDictionary({
  source: ['tokens/base.json'],
  preprocessors: ['tokens-studio'],
  platforms: {
    css: {
      transformGroup: 'tokens-studio',
      transforms: ['name/kebab'],
      buildPath: 'build/css/',
      files: [{ destination: 'variables.css', format: 'css/variables' }]
    }
  }
});
await dictionary.buildAllPlatforms();

node build-tokens.mjs

CSSはbuild/css/variables.cssへ出力されます。今回のサンプルでは、--color-brandと--color-buttonに同じ色が出力され、--space-smallは12pxになりました。参照を残すCSS設定ではなく、値へ解決した結果です。

sourceは入力ファイル、preprocessorsはTokens Studioの形式を整える前処理、transformGroupは値の変換、name/kebabはCSS変数名の形式、formatは出力の種類を指定します。JSON以外のpackage.jsonやテーマ管理ファイルまで、広いglobで取り込まないようにします。

セット・テーマ・複合トークンの注意

単一ファイルに複数のセットが入る場合、セット名を残すか除外するかでCSS名と参照の解決が変わります。sd-transformsにはexcludeParentKeysがありますが、必要なテーマと有効なセットを選ぶ処理まで省略できる設定ではありません。

Light／Darkを一度に読み込んで同名トークンを上書きするより、テーマごとの出力を作る方法を検討します。TypographyやShadowなどの複合トークンを展開する場合は、Style Dictionaryのexpandとsd-transformsのtypesMapが必要になることがあります。単純な色・余白のサンプル成功を、全テーマの成功として扱わないでください。

出力されない・値が違うとき

生成CSSを読むだけでなく、実際に読み込む画面でも色・余白・文字を確認してください。JSON→CSSのローカル変換と、Figma・GitHub・アプリ全体の同期は別々に検証します。