連載：AIエージェントチームと編み上げるデジタルクラフト共同開発記④

2026年6月20日 13:35

第４回：Figma Tokensからコードへ：デザイナーの意図を自動反映する同期ワークフロー

「ブランドカラーの緑を、少しだけ明るくしたいんだけど」
デザイナーからそう言われた瞬間、私たちの頭の中で「検索と置換」の旅が始まります。Figmaを開き、カラーコードを確認し、エディタを立ち上げて該当する値を検索し、影響範囲を脳内でシミュレートしながら、漏れがないように #10B981 から #059669 へ手動で書き換えていく――。
たったひとつの色変更なのに、なぜこれほど人間の注意力をすり減らす作業が発生してしまうのでしょうか。
手作業による転記は、単純でありながら、置換漏れやタイポといったヒューマンエラーが発生しやすい「伝達摩擦」の多い工程です。
そこで私たちは、手作業で値を書き換える手間をなくし、Figma上での変更意図をPull Request（PR）としてコードベースまでレビュー可能な形で届ける**「デザイントークン自動同期ワークフロー」**を構築しました。今回は、その具体的な仕組みと、実務へ導入する際に直面する注意点を交えてご紹介します。

デザインの「自動宅配システム」という例え話

このワークフローは、いわばデザイン値の「自動宅配システム」です。

【デザイナー】Figmaで値を変更し、GitHubへ送信ボタンを押す
       ↓
【配送業者】GitHub Actions（自動で変更を検知してビルドジョブを実行）
       ↓
【配送センター】Style Dictionary（各プラットフォームの形式に荷造り・変換）
       ↓
【開発者】GitHubのPull Request（現場に自動で配達完了。差分を確認し、影響範囲を見たうえでマージする）

デザイナーがFigma上でデザイン仕様を更新すると、ベルトコンベアが動き出し、各プラットフォームに最適な形で荷造りされた「Pull Request」として自動的にエンジニアの元へ届けられます。開発者は自動生成された差分確認し、必要に応じて影響範囲を見たうえでマージします。値の転記作業ではなく、変更の妥当性レビューに集中できる点が、このワークフローの大きな利点です。

図解：Figmaからコードまでの同期パイプライン

➀Figma (Tokens Studio for Figma):

デザイナーはFigmaのプラグイン「Tokens Studio for Figma」を使用して、色や余白、角丸などのデザイン決定値を、構造化された「トークン（JSON）」として一元管理し、リポジトリにプッシュします。

➁GitHub Actions:

トークン情報の更新を検知して自動的に同期ビルドジョブが起動します。

➂Style Dictionary:

配送センターである「Style Dictionary」が、JSON形式のデザイン定義を解析し、Web用やネイティブアプリ用などの形式へ自動変換します。

➃コードベース適用:

変換されたCSS変数はマージされることで、Tailwind CSS等のスタイリング設定へ自動的に適用され、画面へ反映されます。

Tokens Studio for Figmaでデザイン値をJSON管理する

Figmaから書き出されるデータは、構造化されたプレーンなJSONデータです。

{
  "color": {
    "brand": {
      "value": "#10b981",
      "type": "color"
    }
  }
}

※ここでは説明を簡単にするため、従来形式のJSONで示しています。W3CのDesign Tokens Community Group（DTCG）の仕様に準拠する場合は、$value や $type のようにドル記号から始まるキーで表現されます。Style Dictionary v4等ではどちらの形式もサポートされています。

Style Dictionary：1つの定義からマルチプラットフォームへ

この「自動宅配システム」で最も重要な変換エンジンを担うのが Style Dictionary です。Figmaから出力された生データを、Web用のCSS変数、iOS用のSwiftコード、Android用のXMLリソースへと、それぞれの宛先（プラットフォーム）に合わせた形式へ自動変換します。

これによって、プロダクトがWebやiOS、Androidなどのマルチプラットフォームで展開されていても、デザイナーが管理する「Figma上のマスター定義」を変更するだけで、すべてのアプリのデザイン値が一貫したブランド品質で安全に更新されます。

手作業と自動同期の違い

デザイン変更における手作業の摩擦と、自動同期の恩恵を比較してみましょう。

自動同期ワークフローが導入されていると、エンジニアがカラー値を手で探して書き換える作業は、原則として不要になります。代わりに確認するのは、GitHub上に自動で立ち上がったPull Requestの差分です。
たとえば、実際のPRの変更差分は以下のように極めてシンプルかつ明解に表示されます。

:root {
-  --color-brand: #10b981;
+  --color-brand: #059669;
}

開発者はこの差分情報だけを確認すればよいため、確認の負荷が大幅に軽減され、本質的なレビュー作業に集中できるようになります。

導入時に気をつけたい3つのポイント

一見すると夢のようなシステムですが、実務へ導入するためには以下の3つの注意点をクリアしなければ、かえってワークフローを混乱させることになります。

① トークン命名ルール（Naming Convention）を先に決める

「Figmaの色が自動で同期される」ためには、デザイナーとエンジニアが完全に同一の共通語彙（トークン名）を使う必要があります。
命名ルールが曖昧だと、「どのトークンをどこに適用すべきか」で摩擦が発生します。
実務では、以下のようなセマンティック（役割）を意識した階層構造をあらかじめ定義・合意しておくことが推奨されます。

color.brand.primary          # プライマリーのブランドカラー
color.brand.primary.hover    # マウスホバー時のブランドカラー
color.text.default           # 標準のテキスト色
color.background.surface     # カードなどの背景色
spacing.4                    # 16pxに相当する余白定義
radius.button                # ボタンの角丸定義

② Figmaとコードの責任範囲（境界線）を分ける

自動化できるのは「デザインの『値』をコードへ引き渡すこと」だけです。
その変更が、カラーコントラスト比などのアクセシビリティ基準を満たしているか、ブランドイメージと乖離していないか、といった「デザインの妥当性評価」は依然としてデザイナーやPMの責任範囲です。自動化に頼り切らず、Figma側でのデザイン確認プロセスを運用に組み込むことが重要です。

③ 自動PRでも人間のレビューは省かない

「全自動」で動くワークフローだからといって、Pull Requestの自動マージを設定することは推奨されません。
意図しないトークンの変更が、予期せぬコンポーネントの崩れを引き起こす可能性があるからです。自動生成されたPRであっても、必ずエンジニアが目視でコードの差分を確認し、デザインの影響範囲を合意した上で手動でマージする防波堤を残しておくことが、本番環境の品質を守る上で不可欠です。

この仕組みが守るのは、作業時間ではなくデザインの意図

この自動同期ワークフローを導入することの本当の価値は、単に「コピペ作業が減ること」だけではありません。
color.brand.primary という同じ言葉を、デザイナーもエンジニアも同じ共通言語として使っていること。Figma上のデザイン意図とコード上のCSS変数が、別々の記憶やドキュメントではなく、常に同じマスターデータから出力され続けている状態を作ることです。
この一貫性があるだけで、「この緑、どれが最新だっけ？」という不毛な確認や調整のやり直しが防げます。コミュニケーションの摩擦を未然に防ぐことで、チームの信頼関係とデザイン品質を高いレベルで守り続けることができます。
たったひとつの色変更でも、その裏側にはデザイナーの確固たる意図があります。
その意図を、チャットの依頼文や人間の記憶のような曖昧なものに預けるのではなく、トークンという共通言語に乗せて、レビュー可能な形でコードまで届ける。Figma Tokensからコードへの同期ワークフローは、単なる自動化ではありません。デザインの意図を最後の実装まで裏切らないためのチームの約束です。

次回予告

Figmaからの自動同期によって、私たちは型安全で美しいCSS変数を手に入れました。
しかし、これらのトークン（変数）を画面上で動かすUI部品（コンポーネント）が、デザイン変更のたびに表示崩れを起こしてしまっては意味がありません。
次回は、これらのデザイントークンをProps（設定値）として安全に受け取り、拡張性を損なわずに画面を組み立てる「React×TypeScriptで組む変更に強いコンポーネント設計」の美学に迫ります。

この連載「AIエージェントチームと編み上げるデジタルクラフト：FTF Flow共同開発記」は、FTF Flow開発チームがお届けしています。

note内の回遊導線

前回は、共通のHTML骨格に対してCSS変数を差し替え、京都とイスタンブールという異なる世界観を表現する「CSSマテリアルオーバーライド」を紹介しました。
今回の自動同期ワークフローは、そのCSS変数をFigma上のデザイン意図から安全に届けるための仕組みです。あわせて読むと、表現と運用のつながりが見えてきます。