デザイントークンの設計と実装ガイド：FigmaからCSS・ReactNativeへの一貫したスタイル管理

デザイントークンは、デザインの意思決定（色・フォントサイズ・スペーシングなど）を「名前付きの値」として抽象化したものです。デザインシステムの根幹をなすデザイントークンを適切に管理することで、デザインと実装の一貫性を保ちながら、テーマ変更やブランドアップデートを効率的に行えます。本記事では、デザイントークンの概念から実践的な実装まで解説します。

デザイントークンとは

概念：

「プライマリーカラーは #3B82F6 である」という決定を color-brand-primary: #3B82F6 という名前付きトークンとして管理します。UIコンポーネントはこのトークンを参照するため、#3B82F6 をハードコードしません。ブランドカラーが変われば、トークンの値を変えるだけで全コンポーネントに反映されます。

トークンの利点：

• デザインと実装の「語彙」を統一する
• テーマ切り替え（ライト/ダーク・ブランドテーマ）を効率化する
• コードレビューで意図が伝わりやすくなる
• デザインと開発の引き継ぎコストを削減する

デザイントークンの種類と階層

グローバルトークン（Global/Primitive Tokens）：

色・サイズ・フォントの全バリューを網羅した最下層のトークン。

{
  "color": {
    "blue": {
      "500": "#3B82F6",
      "600": "#2563EB",
      "700": "#1D4ED8"
    }
  }
}

エイリアストークン（Alias/Semantic Tokens）：

グローバルトークンに意味を与えたトークン。コンポーネントはこのレイヤーを参照します。

{
  "color": {
    "action": {
      "primary": "{color.blue.500}",
      "primaryHover": "{color.blue.600}"
    }
  }
}

コンポーネントトークン（Component Tokens）：

特定のコンポーネントに限定したトークン。大規模なデザインシステムでのみ設定します。

{
  "button": {
    "background": "{color.action.primary}",
    "backgroundHover": "{color.action.primaryHover}"
  }
}

命名規則

推奨パターン：

[カテゴリ]-[要素/意味]-[状態/バリアント]

例：

• color-text-primary
• color-text-secondary
• color-bg-surface
• spacing-md
• font-size-body
• border-radius-button

避けるべき命名：

• 具体的な値を名前に含める（color-blue-500 はグローバルトークンにのみ使用し、セマンティックトークンでは color-brand-primary にする）
• スタイルの説明をそのまま名前にする（bold-font より font-weight-heading）

Figma Variablesとの連携

FigmaのVariables機能（2023年導入）でデザイントークンをFigma内で管理できるようになりました。

Variablesの設定：

「Variables」パネルでコレクションを作成し、String・Number・Color・Boolean型の変数を定義します。モード（ライトモード/ダークモード）を追加して値を切り替えることができます。

Figma Variables → コードへのエクスポート：

FigmaプラグインやAPI経由でVariablesをJSON形式にエクスポートし、Style Dictionaryなどのツールで各プラットフォーム向けのコードに変換します。

Style Dictionary

W3C Design Tokens Community Groupの仕様に準拠したトークン管理ツール。JSONで定義したトークンを、CSS Custom Properties・SCSS変数・JavaScript/TypeScriptオブジェクト・Android XML・iOS Swift等の形式に自動変換します。

設定例（config.json）：

{
  "source": ["tokens/**/*.json"],
  "platforms": {
    "css": {
      "transformGroup": "css",
      "buildPath": "dist/css/",
      "files": [{ "destination": "tokens.css", "format": "css/variables" }]
    },
    "js": {
      "transformGroup": "js",
      "buildPath": "dist/js/",
      "files": [{ "destination": "tokens.js", "format": "javascript/es6" }]
    }
  }
}

CSS Custom Propertiesとの実装

Style Dictionaryで生成したCSSを使うとこのようになります：

:root {
  --color-brand-primary: #3B82F6;
  --color-text-primary: #111827;
  --spacing-md: 16px;
  --border-radius-button: 8px;
}

[data-theme="dark"] {
  --color-brand-primary: #60A5FA;
  --color-text-primary: #F9FAFB;
}

コンポーネントは直接カラーコードを使わず、トークン変数を参照します：

.button-primary {
  background-color: var(--color-brand-primary);
  border-radius: var(--border-radius-button);
}

まとめ

デザイントークンは、デザインと開発が共通の「語彙」を持つことで一貫性と効率を生む仕組みです。グローバル・セマンティック・コンポーネントの3層構造で設計し、Figma VariablesとStyle Dictionaryを連携させることで、デザインの変更が全プラットフォームに効率的に反映されます。UI ZUKANではデザインシステムの構築事例を紹介しています。