🎨

Figma Variables を CSS に自動変換したい

に公開
CSS
Figma
デザイン
idea

Figma で定義した Variables を、自動でCSS カスタムプロパティに変換するワークフローを検討してみました。

はじめに

フロントエンドの作業をしていると、FigmaでデザイナーがVariables を定義し、それをエンジニアが手作業でCSS に落とし込むという作業が発生します。この手作業は同期ずれの原因になります。

本記事では、以下のワークフローを実現するサンプルプロジェクト (GitHub)を作成し、要点をまとめておきます。

Figma Variables → TokensBrücke → Terrazzo → CSS

技術構成

使用したツール

ツール 役割 選定理由
Figma SDS デザイン定義 Variables の実装例として完成度が高い
TokensBrücke Figma エクスポート DTCG keys format に対応
Terrazzo トークン変換 DTCG準拠でCSS生成が可能

プロジェクト構成

sample-terrazzo/
├── design.tokens.json          # Figmaからエクスポートした生データ
├── tokens.json                 # 正規化後のトークンファイル
├── terrazzo.config.mjs         # Terrazzoの設定
├── dist/
│   └── index.css              # 生成されたCSSファイル
├── scripts/
│   ├── fix-token-types.js     # 型修正スクリプト
│   └── analyze-token-error.js # エラー分析ツール
└── .claude/
    └── commands/
        └── fix-token-types.md # Claude Code用カスタムコマンド

TokensBrücke の設定とエクスポート

プラグインの設定

Figma SDS から TokensBrücke プラグインを使ってトークンをエクスポートする際の設定は下記のようにしました。細かいことは README を見てください。

  "Include variable scopes": true,
  "Use DTCG keys format": true,
  "Include .value string for aliases": false,
  "Include Figma metadata": false

エクスポート結果例

{
  "Typography Primitives": {
    "Scale": {
      "100": {
        "$type": "dimension",
        "$value": "12px",
        "scopes": ["FONT_SIZE"]
      }
    }
  },
  "Typography": {
    "Body": {
      "Font Family": {
        "$type": "string",
        "$value": "Inter",
        "scopes": ["FONT_FAMILY"]
      }
    }
  }
}

Terrazzo による CSS 生成

設定ファイル

terrazzo.config.mjs:

import { defineConfig } from '@terrazzo/cli';
import css from '@terrazzo/plugin-css';

export default defineConfig({
  tokens: ['./tokens.json'],
  plugins: [
    css(),
  ],
  outDir: './dist/',
});

実行コマンド

# トークンの正規化
# TokensBrücke でエクスポートしたトークンは、型の不一致が発生することがあるので型修正も行う
npm run normalize

# トークンの検証
npm run check

# CSSファイルの生成
npm run build

生成されるCSS例

:root {
  --typography-primitives-scale-100: 12px;
  --typography-body-font-family: 'Inter';
}

トークンの正規化時に起きる型不一致問題の対応

エラーの内容としては下記のようなものです。

Invalid alias: expected $type: fontFamily, received $type: string

これは、Figma Variables では string 型だったものが、DTCG 仕様では fontFamily 型として扱われるべき場合に発生します。

修正できるようにする

スクリプトを書いて修正ルールを書くことで対応できるようにしました。あとはルールを追加するだけです。

const TYPE_FIX_RULES = [
  {
    name: 'fontFamily',
    condition: (key, token) => {
      return (
        (key.includes('Font Family') || key.includes('Family Sans')) && 
        token.$type === 'string' && 
        token.scopes && 
        token.scopes.includes('FONT_FAMILY')
      );
    },
    targetType: 'fontFamily'
  }
];

Claude Code カスタムコマンドによるルール作成の自動化

/fix-token-types コマンドを用意しました。

下記のことをやってくれます。Figmaファイルに合わせてルールを変更する必要があるので、このような自動化が有用だと感じています。

  1. Normalizeを実行してエラーを確認
  2. 発見されたエラーを分析
  3. 問題のあるトークンを特定
  4. 修正ルールを更新
  5. 修正をテスト
  6. 成功を確認

まとめ

Figma Variables から CSS カスタムプロパティを半自動生成することができました。
完全自動化には至っていませんが、TokensBrücke の GitHub 連携機能などを使えば完全自動化も可能であることを確認できました。

参考リンク

Discussion