Figmaからコードへ：デザイントークン「真の単一ソース」構築の極意
多くのチームが「Figmaで変数を定義し、GitHubで管理する」という幻想を追いかけている。しかし、現実にはFigmaのVariablesとコードベースのデザイントークンは、常に「同期不全」というエントロピーの増大に苦しんでいる。
Component 4.0以降、Figmaは単なる描画ツールから、設計データという「構造化データ」のソースへと進化した。今日は、この神聖な設計データを、Style Dictionaryをハブとして、CI/CDでコードへ自動変換・デプロイする「完全自動化パイプライン」の深淵を解説する。
—
1. 乖離を防ぐための「データ構造」の定義
Figma Variablesは強力だが、そのままではコードの型としては脆弱だ。我々がまず行うべきは、「Figma上の階層」と「コード上のスキーマ」の厳密なマッピングである。
アーキテクチャの鉄則
- Primitive Tokens (Global): カラーパレットやスペースの定数。Figmaの「Collection」として定義。
- Semantic Tokens: `bg-surface-primary` のような意味を持つトークン。Primitiveへの参照として定義。
- Component Tokens: 最も具象的なトークン。
これらをFigmaのAPI経由で取得する際、中間層であるW3C Design Tokens Formatを介すのが唯一の解だ。これにより、Figmaの「UI上の制約」をコードの「静的型付け」から切り離すことができる。
—
2. Style Dictionaryによる「双方向同期」の高度な実装
単にFigmaからJSONを吐き出すだけでは素人だ。真のプロは、GitHubのトークンを「Truth」とし、FigmaのVariablesを「キャッシュ」として扱う。
プロダクション環境の自動化フロー
1. Figma API (REST) で `GET /v1/files/:file_key/variables/local` を叩く。
2. 取得したRawデータを、`token-transformer` を用いて、Figma独自のエイリアス（`alias: 1234:5678`）を解決する。
3. Style Dictionary を通じて、CSS Variables, SCSS, Tailwind config, TypeScript型定義へ変換する。
実践：CLIによる同期自動化スクリプト (`sync-tokens.ts`)
// メモリ効率を考慮し、大規模ファイルでもストリーム処理を行う
import { registerTransforms } from ‘@tokens-studio/sd-transforms’;
import StyleDictionary from ‘style-dictionary’;
// 1. Figmaのエイリアスを解決し、標準フォーマットに正規化
async function transformFigmaData(rawData: any) {
// ここでメモリ消費を抑えるため、大規模なデータはchunk分割して処理
const transformed = await expandFigmaVariables(rawData);
return transformed;
}
// 2. Style Dictionaryのビルド設定
const sd = StyleDictionary.extend({
source: [‘tokens//.json’],
platforms: {
css: {
transformGroup: ‘css’,
buildPath: ‘dist/css/’,
files: [{ destination: ‘_variables.css’, format: ‘css/variables’ }]
},
ts: {
transformGroup: ‘js’,
buildPath: ‘dist/types/’,
files: [{ destination: ‘tokens.d.ts’, format: ‘typescript/es6-declarations’ }]
}
}
});
sd.buildAllPlatforms();
—
3. CI/CDパイプライン：デザイン変更を即座にコードへ
デザイン変更がGitのコミットをトリガーするように設計せよ。
究極のパイプライン構成
1. Webhook Trigger: Figmaの「File Update」Webhooksを検知。
2. Validation Step: GitHub Action上で、新しいトークンが型安全性を毀損していないか、`zod` でスキーマバリデーションを実行。
3. Automated Pull Request: 変更点を検知した場合、自動的にブランチを作成し、デザイントークンの差分を `PR` として投げる。
.github/workflows/sync-tokens.yml
name: Sync Design Tokens
on:
repository_dispatch:
types: [figma-update]
jobs:
sync:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Fetch and Transform
run: node scripts/sync-tokens.ts
- name: Create Pull Request
uses: peter-evans/create-pull-request@v5
with:
commit-message: “chore: update design tokens from figma”
branch: “chore/sync-figma-tokens”
title: “Design Tokens Update”
—
4. パフォーマンスとメモリの最適化ハック
大規模なデザインシステムになると、JSONファイルが数メガバイトに達し、CIのビルド時間が肥大化する。これを避けるための極限チューニングを伝授する。
- Tree Shaking: 必要なトークンのみをファイル単位で分割して管理し、Style Dictionaryのビルド時に必要なグループのみを読み込む。
- Incremental Builds: 変更があったコレクションのIDのみをFigma APIから取得し、差分更新を行う。全取得（`local`全量）はAPIレートリミットに直撃するため、`last_modified` のヘッダー情報を活用したキャッシュ機構を自作すること。
- Memory Management: Node.jsで実行する場合、`–max-old-space-size=4096` を設定し、巨大なJSONツリーの探索時には `JSONStream` を用いてオンメモリを回避せよ。
結びに：デザインを「コード」と認識する覚悟
FigmaのVariablesを単なる「カラーパレット置き場」として扱う時代は終わった。これらは、プロダクトのUIアーキテクチャそのものである。
エンジニアよ、デザイナーと共用するトークンを「ドキュメント」ではなく「API」として扱え。デザインの変更がコードのビルドを走らせる、その静かなる自動化の中にこそ、プロダクトの寿命を延ばす鍵がある。
次の一歩は、君たちが構築するそのパイプラインの「堅牢性」だ。FigmaのAPIが落ちても、コードベースが壊れない。その多重防壁を構築できた時、君は真のプロダクトアーキテクトと言えるだろう。