Design Tokenシステム実戦：5つのパターンでスケーラブルなテーマ＆マルチブランドアーキテクチャを構築

前端工程

Design Token：デザインシステムの原子レベルインフラ

デザインシステムの最大の課題はコンポーネント不足ではなく、テーマ切り替えはオーバーライド、ブランド拡張はコピー、ダークモードはパッチで対応していること。Design Tokenは色、間隔、フォントなどのデザイン決定をプラットフォーム非依存のキーバリューペアとして抽象化し、「一度定義、マルチプラットフォーム消費」を実現。2026年、W3C Design Token仕様がCandidate Recommendationに到達し、Style Dictionary 4.0+がマルチプラットフォーム出力をサポート、Design Tokenはデザインシステムの標準インフラとなりました。

本記事では5つのコアパターンから、Token階層化→テーマ切り替え→マルチブランド→ビルドパイプライン→ランタイム動的のフルパイプライン実戦を解説します。

コア概念

概念 説明
Design Token デザイン決定の原子レベル表現、キーバリューペア形式
Global Token グローバル生値、例：blue-500: #3b82f6
Alias Token セマンティックエイリアス、例：primary: {blue-500}
Component Token コンポーネントレベルToken、例：button-primary-bg: {primary}
Theme Token値のコレクション、例：ライト/ダークテーマ
Multi-Brand 同一デザインシステムで複数ブランドのTokenセットをサポート
Style Dictionary Tokenコンパイルツール、マルチプラットフォーム出力
W3C DTCG Design Token Community Group仕様

問題分析：Design Tokenシステムの5つの課題

  1. Token階層の混乱：グローバル/セマンティック/コンポーネントの3層境界が不明確、参照チェーンが長すぎる
  2. テーマ切り替えパフォーマンス：ランタイムテーマ切り替えによる再描画フリッカー
  3. マルチブランド拡張：ブランド間のToken差異が大きく、継承関係が複雑
  4. ビルド出力：マルチプラットフォーム（CSS/JS/Swift/Kotlin）で出力形式が異なる
  5. デザインコラボレーション：デザイナーはFigma、開発者はコード、Token同期が困難

ステップバイステップ：5つのDesign Tokenパターン

パターン1：Token3層アーキテクチャ

// tokens/global/color.json
{
  "color": {
    "blue": {
      "100": { "value": "#dbeafe", "type": "color" },
      "500": { "value": "#3b82f6", "type": "color" },
      "900": { "value": "#1e3a8a", "type": "color" }
    },
    "gray": {
      "50": { "value": "#f9fafb", "type": "color" },
      "900": { "value": "#111827", "type": "color" }
    },
    "red": {
      "500": { "value": "#ef4444", "type": "color" }
    },
    "green": {
      "500": { "value": "#22c55e", "type": "color" }
    }
  }
}

// tokens/semantic/color.json
{
  "color": {
    "primary": { "value": "{color.blue.500}", "type": "color" },
    "primary-hover": { "value": "{color.blue.600}", "type": "color" },
    "background": { "value": "{color.gray.50}", "type": "color" },
    "surface": { "value": "#ffffff", "type": "color" },
    "text": { "value": "{color.gray.900}", "type": "color" },
    "text-secondary": { "value": "{color.gray.500}", "type": "color" },
    "error": { "value": "{color.red.500}", "type": "color" },
    "success": { "value": "{color.green.500}", "type": "color" },
    "border": { "value": "{color.gray.200}", "type": "color" }
  }
}

// tokens/component/button.json
{
  "button": {
    "primary": {
      "bg": { "value": "{color.primary}", "type": "color" },
      "bg-hover": { "value": "{color.primary-hover}", "type": "color" },
      "text": { "value": "#ffffff", "type": "color" },
      "border-radius": { "value": "{radius.md}", "type": "borderRadius" },
      "padding-x": { "value": "{spacing.4}", "type": "spacing" },
      "padding-y": { "value": "{spacing.2}", "type": "spacing" }
    },
    "secondary": {
      "bg": { "value": "{color.surface}", "type": "color" },
      "text": { "value": "{color.primary}", "type": "color" },
      "border": { "value": "{color.border}", "type": "color" }
    }
  }
}

パターン2：テーマ切り替え（ライト/ダーク）

// tokens/semantic/color.dark.json
{
  "color": {
    "primary": { "value": "{color.blue.400}", "type": "color" },
    "background": { "value": "{color.gray.900}", "type": "color" },
    "surface": { "value": "#1f2937", "type": "color" },
    "text": { "value": "{color.gray.50}", "type": "color" },
    "text-secondary": { "value": "{color.gray.400}", "type": "color" },
    "border": { "value": "{color.gray.700}", "type": "color" }
  }
}

/* ビルド出力：tokens.css */
:root {
  --color-primary: #3b82f6;
  --color-background: #f9fafb;
  --color-surface: #ffffff;
  --color-text: #111827;
  --color-border: #e5e7eb;
  --button-primary-bg: var(--color-primary);
  --button-primary-text: #ffffff;
}

[data-theme="dark"] {
  --color-primary: #60a5fa;
  --color-background: #111827;
  --color-surface: #1f2937;
  --color-text: #f9fafb;
  --color-border: #374151;
  --button-primary-bg: var(--color-primary);
}

// テーマスイッチャー
type Theme = 'light' | 'dark' | 'system';

class ThemeManager {
  private mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
  private listeners: Set<(theme: Theme) => void> = new Set();

  init() {
    const saved = localStorage.getItem('theme') as Theme | null;
    if (saved && saved !== 'system') {
      this.apply(saved);
    } else {
      this.apply(this.mediaQuery.matches ? 'dark' : 'light');
    }
    this.mediaQuery.addEventListener('change', (e) => {
      if (this.getStored() === 'system') {
        this.apply(e.matches ? 'dark' : 'light');
      }
    });
  }

  setTheme(theme: Theme) {
    localStorage.setItem('theme', theme);
    if (theme === 'system') {
      this.apply(this.mediaQuery.matches ? 'dark' : 'light');
    } else {
      this.apply(theme);
    }
    this.listeners.forEach((fn) => fn(theme));
  }

  private apply(mode: 'light' | 'dark') {
    document.documentElement.setAttribute('data-theme', mode);
  }

  private getStored(): Theme {
    return (localStorage.getItem('theme') as Theme) || 'system';
  }

  onChange(fn: (theme: Theme) => void) {
    this.listeners.add(fn);
    return () => this.listeners.delete(fn);
  }
}

パターン3：マルチブランドToken継承

// brands/brand-a/tokens.json
{
  "color": {
    "primary": { "value": "#3b82f6", "type": "color", "$extensions": { "brand": "A" } },
    "primary-hover": { "value": "#2563eb", "type": "color" }
  },
  "typography": {
    "font-family": { "value": "Inter, sans-serif", "type": "fontFamily" },
    "heading-weight": { "value": "700", "type": "fontWeight" }
  },
  "radius": {
    "base": { "value": "8px", "type": "borderRadius" }
  }
}

// brands/brand-b/tokens.json
{
  "color": {
    "primary": { "value": "#8b5cf6", "type": "color", "$extensions": { "brand": "B" } },
    "primary-hover": { "value": "#7c3aed", "type": "color" }
  },
  "typography": {
    "font-family": { "value": "Poppins, sans-serif", "type": "fontFamily" },
    "heading-weight": { "value": "600", "type": "fontWeight" }
  },
  "radius": {
    "base": { "value": "4px", "type": "borderRadius" }
  }
}

// ブランドスイッチャー
type Brand = 'brand-a' | 'brand-b';

async function switchBrand(brand: Brand) {
  const brandCSS = await fetch(`/tokens/${brand}.css`).then((r) => r.text());
  let style = document.getElementById('brand-tokens') as HTMLStyleElement;
  if (!style) {
    style = document.createElement('style');
    style.id = 'brand-tokens';
    document.head.appendChild(style);
  }
  style.textContent = brandCSS;
  document.documentElement.setAttribute('data-brand', brand);
  localStorage.setItem('brand', brand);
}

パターン4：Style Dictionaryビルドパイプライン

// style-dictionary.config.mjs
import StyleDictionary from 'style-dictionary';

StyleDictionary.registerTransform({
  name: 'size/pxToRem',
  type: 'value',
  matcher: (token) => token.type === 'spacing' || token.type === 'fontSize',
  transformer: (token) => {
    const base = 16;
    const val = parseFloat(token.value);
    return `${val / base}rem`;
  },
});

StyleDictionary.registerTransformGroup({
  name: 'custom/css',
  transforms: [
    'attribute/cti',
    'name/kebab',
    'time/seconds',
    'size/pxToRem',
    'color/css',
  ],
});

const config = {
  source: ['tokens/**/*.json'],
  platforms: {
    css: {
      transformGroup: 'custom/css',
      buildPath: 'dist/css/',
      files: [
        {
          destination: 'tokens.css',
          format: 'css/variables',
          options: { outputReferences: true },
        },
      ],
    },
    js: {
      transformGroup: 'js',
      buildPath: 'dist/js/',
      files: [
        {
          destination: 'tokens.js',
          format: 'javascript/es6',
        },
        {
          destination: 'tokens.d.ts',
          format: 'typescript/es6-declarations',
        },
      ],
    },
    json: {
      transformGroup: 'json',
      buildPath: 'dist/json/',
      files: [
        {
          destination: 'tokens.json',
          format: 'json',
        },
      ],
    },
    ios: {
      transformGroup: 'ios-swift-separate',
      buildPath: 'dist/ios/',
      files: [
        {
          destination: 'DesignTokens.swift',
          format: 'ios-swift/class.swift',
          className: 'DesignTokens',
        },
      ],
    },
    android: {
      transformGroup: 'android',
      buildPath: 'dist/android/',
      files: [
        {
          destination: 'design_tokens.xml',
          format: 'android/resources',
        },
      ],
    },
  },
};

export default config;

# 全プラットフォームをビルド
npx style-dictionary build

# Token変更を監視
npx style-dictionary build --watch

パターン5：ランタイム動的Token

// runtime-token-engine.ts
interface TokenValue {
  value: string;
  type: string;
  description?: string;
}

class RuntimeTokenEngine {
  private tokens: Map<string, TokenValue> = new Map();
  private subscribers: Map<string, Set<(value: string) => void>> = new Map();

  loadFromCSS() {
    const styles = getComputedStyle(document.documentElement);
    const allVars = Array.from(document.styleSheets)
      .flatMap((sheet) => {
        try {
          return Array.from(sheet.cssRules);
        } catch {
          return [];
        }
      })
      .filter((rule) => rule instanceof CSSStyleRule)
      .flatMap((rule: CSSStyleRule) => {
        const props: string[] = [];
        for (let i = 0; i < rule.style.length; i++) {
          const prop = rule.style[i];
          if (prop.startsWith('--')) {
            props.push(prop);
          }
        }
        return props;
      });

    const uniqueVars = [...new Set(allVars)];
    uniqueVars.forEach((v) => {
      const val = styles.getPropertyValue(v).trim();
      if (val) {
        this.tokens.set(v, { value: val, type: 'unknown' });
      }
    });
  }

  setToken(name: string, value: string) {
    const varName = name.startsWith('--') ? name : `--${name}`;
    document.documentElement.style.setProperty(varName, value);
    this.tokens.set(varName, { value, type: 'unknown' });
    this.notify(varName, value);
  }

  getToken(name: string): string | undefined {
    const varName = name.startsWith('--') ? name : `--${name}`;
    return getComputedStyle(document.documentElement)
      .getPropertyValue(varName)
      .trim();
  }

  subscribe(name: string, callback: (value: string) => void) {
    const varName = name.startsWith('--') ? name : `--${name}`;
    if (!this.subscribers.has(varName)) {
      this.subscribers.set(varName, new Set());
    }
    this.subscribers.get(varName)!.add(callback);
    return () => this.subscribers.get(varName)?.delete(callback);
  }

  private notify(name: string, value: string) {
    this.subscribers.get(name)?.forEach((fn) => fn(value));
  }
}

よくある落とし穴

落とし穴1：Token参照チェーンが深すぎる

// ❌ 間違い：5層の参照チェーン、デバッグ困難
{
  "btn-bg": { "value": "{button.primary.bg}" },
  "button.primary.bg": { "value": "{color.primary}" },
  "color.primary": { "value": "{blue.500}" }
}

// ✅ 正しい：3層以内に抑える
{
  "button-primary-bg": { "value": "{color.primary}" },
  "color.primary": { "value": "#3b82f6" }
}

落とし穴2：ハードコードされた色値

/* ❌ 間違い：ハードコードされた色 */
.card { background: #ffffff; border: 1px solid #e5e7eb; }

/* ✅ 正しい：Token変数を使用 */
.card { background: var(--color-surface); border: 1px solid var(--color-border); }

落とし穴3：テーマ切り替えフリッカー

<!-- ❌ 間違い：JS読み込み後にテーマ設定、フリッカー発生 -->

<!-- ✅ 正しい：インラインスクリプトでレンダリングをブロック -->
<script>
  (function() {
    const theme = localStorage.getItem('theme');
    if (theme === 'dark' || (!theme && matchMedia('(prefers-color-scheme: dark)').matches)) {
      document.documentElement.setAttribute('data-theme', 'dark');
    }
  })();
</script>

落とし穴4：コンポーネントTokenの乱用

// ❌ 間違い：各コンポーネントプロパティにTokenを作成
{
  "card-padding-top": { "value": "{spacing.4}" },
  "card-padding-right": { "value": "{spacing.4}" },
  "card-padding-bottom": { "value": "{spacing.4}" },
  "card-padding-left": { "value": "{spacing.4}" }
}

// ✅ 正しい：セマンティックTokenを再利用
{
  "card-padding": { "value": "{spacing.4}" }
}

落とし穴5：Token型検証の無視

// ❌ 間違い：Token型を検証せず、色Tokenに間隔値が渡される
// ✅ 正しい：ビルド時に検証
StyleDictionary.registerFilter({
  name: 'isValidColor',
  matcher: (token) => {
    if (token.type === 'color') {
      return /^#([0-9a-f]{3}){1,2}$/i.test(token.value) ||
             token.value.startsWith('{');
    }
    return true;
  },
});

エラートラブルシューティング

# エラーメッセージ 原因 解決方法
1 Reference not found: {color.xxx} Tokenが存在しないキーを参照 参照パスのスペルを確認
2 Circular reference detected Tokenの循環参照 循環参照チェーンを解消
3 Invalid token value Token値の形式が不正 色/間隔の形式を検証
4 CSS variable not applied セレクタの優先度が上書き CSS変数セレクタの優先度を上げる
5 Theme flash on load テーマ初期化がレンダリングより遅い インラインブロックスクリプトでテーマ設定
6 Style Dictionary build failed Tokenファイル形式エラー JSON構文と$extensionsを確認
7 Token not found in output Tokenがsourceにマッチしない source globパスを確認
8 Platform output mismatch 変換ルールが不一致 transformGroup設定を統一
9 Figma sync conflict Figma Tokenとコードが不一致 Token Studioで双方向同期
10 Runtime token override fails ランタイムオーバーライドが無効 CSS変数の優先度とスコープを確認

高度な最適化

  1. Token Studio統合：FigmaプラグインでデザインとコードのToken双方向同期
  2. Tokenバージョニング：セマンティックバージョニング+自動チェンジログ生成
  3. A/BテストToken：ランタイム動的Token切り替えでビジュアルA/Bテスト
  4. Token Lint：ESLintプラグインでコード内のハードコードされたデザイン値を検出
  5. Tokenドキュメントサイト：自動生成されたTokenビジュアルドキュメント

比較分析

次元 CSS変数 Design Token Tailwind Config CSS-in-JS Theme
プラットフォーム対応 Webのみ Web/iOS/Android Webのみ Webのみ
型安全性 ❌ ✅ ✅ ✅
テーマ切り替え ✅ ✅ ✅ ✅
マルチブランド 手動 ネイティブサポート 設定切り替え 設定切り替え
デザインコラボ ❌ ✅ Figma同期 ❌ ❌
ビルド出力 CSS CSS/JS/Swift/Kotlin CSS/JS JS

まとめ：Design Tokenシステムは、デザインシステムが「コンポーネントライブラリ」から「デザイン言語」へ進化するための重要なインフラです。3層Tokenアーキテクチャ（グローバル→セマンティック→コンポーネント）とStyle Dictionaryのマルチプラットフォーム出力の組み合わせにより、デザイン決定の単一データソースを実現。2026年のW3C DTCG仕様の成熟によりToken標準化が進み、マルチブランドとランタイム動的Tokenがエンタープライズデザインシステムの標準機能となります。

オンラインツール推奨

ブラウザローカルツールを無料で試す →

#Design Token#设计系统#主题切换#CSS变量#2026#前端工程