デザインシステムアーキテクチャ実践：デザイントークンからコンポーネントライブラリまでの完全構築パス

デザインシステムの三層アーキテクチャ

┌─────────────────────────────────┐
│  コンポーネント層               │  Button, Card, Modal...
├─────────────────────────────────┤
│  パターン層                     │  フォーム、ナビゲーション、データテーブル
├─────────────────────────────────┤
│  トークン層（Design Tokens）     │  色、間隔、フォントサイズ、シャドウ
└─────────────────────────────────┘

トークンが基盤、パターンが組み合わせ、コンポーネントがエンドポイントです。ボトムアップで構築し、トップダウンで消費します。

---

デザイントークン体系

1. カラートークン

/* 意味論的三層トークン */

/* 第一層：プリミティブ値 */
:root {
  --blue-50: #eff6ff;
  --blue-500: #3b82f6;
  --blue-700: #1d4ed8;
  --gray-50: #f9fafb;
  --gray-900: #111827;
  --red-500: #ef4444;
  --green-500: #22c55e;
}

/* 第二層：意味マッピング */
:root {
  --color-primary: var(--blue-500);
  --color-primary-hover: var(--blue-700);
  --color-surface: var(--gray-50);
  --color-text: var(--gray-900);
  --color-danger: var(--red-500);
  --color-success: var(--green-500);
}

/* 第三層：コンポーネント専用 */
:root {
  --button-bg: var(--color-primary);
  --button-bg-hover: var(--color-primary-hover);
  --button-text: white;
  --input-border: var(--color-border);
  --input-border-focus: var(--color-primary);
}

2. 間隔トークン（8ptグリッドシステム）

:root {
  --space-0: 0;
  --space-1: 0.25rem;  /* 4px */
  --space-2: 0.5rem;   /* 8px */
  --space-3: 0.75rem;  /* 12px */
  --space-4: 1rem;     /* 16px */
  --space-5: 1.5rem;   /* 24px */
  --space-6: 2rem;     /* 32px */
  --space-8: 3rem;     /* 48px */
  --space-10: 4rem;    /* 64px */
}

3. タイポグラフィトークン

:root {
  /* フォントサイズ */
  --text-xs: 0.75rem;    /* 12px */
  --text-sm: 0.875rem;   /* 14px */
  --text-base: 1rem;     /* 16px */
  --text-lg: 1.125rem;   /* 18px */
  --text-xl: 1.25rem;    /* 20px */
  --text-2xl: 1.5rem;    /* 24px */
  --text-3xl: 1.875rem;  /* 30px */

  /* 行の高さ */
  --leading-tight: 1.25;
  --leading-normal: 1.5;
  --leading-relaxed: 1.75;

  /* フォントウェイト */
  --font-normal: 400;
  --font-medium: 500;
  --font-semibold: 600;
  --font-bold: 700;
}

4. シャドウトークン

:root {
  --shadow-xs: 0 1px 2px rgba(0,0,0,0.05);
  --shadow-sm: 0 1px 3px rgba(0,0,0,0.1), 0 1px 2px rgba(0,0,0,0.06);
  --shadow-md: 0 4px 6px rgba(0,0,0,0.07), 0 2px 4px rgba(0,0,0,0.06);
  --shadow-lg: 0 10px 15px rgba(0,0,0,0.1), 0 4px 6px rgba(0,0,0,0.05);
  --shadow-xl: 0 20px 25px rgba(0,0,0,0.1), 0 8px 10px rgba(0,0,0,0.04);
}

---

テーマ切り替え機構

CSS変数方式

/* ライトテーマ（デフォルト） */
:root {
  --color-surface: #ffffff;
  --color-text: #111827;
  --color-border: #e5e7eb;
  --color-primary: #3b82f6;
}

/* ダークテーマ */
[data-theme="dark"] {
  --color-surface: #1f2937;
  --color-text: #f9fafb;
  --color-border: #374151;
  --color-primary: #60a5fa;
}

/* ハイコントラストテーマ */
[data-theme="high-contrast"] {
  --color-surface: #000000;
  --color-text: #ffffff;
  --color-border: #ffffff;
  --color-primary: #ffff00;
}

Reactテーマ切り替え

import { useEffect, useState } from 'react';

type Theme = 'light' | 'dark' | 'system';

function useTheme() {
  const [theme, setTheme] = useState<Theme>(() => {
    return (localStorage.getItem('theme') as Theme) || 'system';
  });

  useEffect(() => {
    const root = document.documentElement;
    const systemDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
    const resolved = theme === 'system' ? (systemDark ? 'dark' : 'light') : theme;

    root.setAttribute('data-theme', resolved);
    localStorage.setItem('theme', theme);
  }, [theme]);

  return { theme, setTheme };
}

Tailwind CSS v4 ダークモード

/* tailwind.config.tsでCSS変数モードを使用 */
@custom-variant dark (&:where([data-theme="dark"], [data-theme="dark"] *));

<!-- テーマに自動応答 -->
<div class="bg-white dark:bg-gray-800 text-gray-900 dark:text-gray-100">
  コンテンツが現在のテーマに自動適応
</div>

---

コンポーネントAPI設計原則

1. 単一責任 + コンポジション優先

// ❌ 過剰カプセル化：すべての機能を1つのコンポーネントに詰め込む
<SuperButton variant="primary" size="lg" icon="save" loading disabled />

// ✅ コンポジションパターン：子コンポーネントで組み立て
<Button variant="primary" size="lg">
  <Icon name="save" />
  <Button.Label>保存</Button.Label>
  <Button.Loading />
</Button>

2. 制御 vs 非制御

// 制御モード：状態は外部で管理
<Input value={value} onChange={setValue} />

// 非制御モード：状態はコンポーネント内部で管理
<Input defaultValue="hello" onChange={handleChange} />

// 両方に対応
interface InputProps {
  value?: string;          // 制御
  defaultValue?: string;   // 非制御
  onChange?: (value: string) => void;
}

3. ポリモーフィックコンポーネント

// Buttonはbutton、a、またはNext.js Linkとしてレンダリング可能
type ButtonProps<C extends React.ElementType = 'button'> = {
  as?: C;
} & React.ComponentPropsWithoutRef<C>;

function Button<C extends React.ElementType = 'button'>(
  { as, ...props }: ButtonProps<C>
) {
  const Component = as || 'button';
  return <Component className="btn" {...props} />;
}

// 使用例
<Button>Click</Button>
<Button as="a" href="/link">Link</Button>
<Button as={Link} to="/page">Route Link</Button>

4. Slotsパターン

// CardコンポーネントのSlots設計
interface CardSlots {
  header?: React.ReactNode;
  media?: React.ReactNode;
  content: React.ReactNode;
  footer?: React.ReactNode;
  actions?: React.ReactNode;
}

function Card({ header, media, content, footer, actions }: CardSlots) {
  return (
    <div className="card">
      {header && <div className="card-header">{header}</div>}
      {media && <div className="card-media">{media}</div>}
      <div className="card-content">{content}</div>
      {footer && <div className="card-footer">{footer}</div>}
      {actions && <div className="card-actions">{actions}</div>}
    </div>
  );
}

---

マルチブランド適応

ブランドオーバーレイ層

/* ベーストークン（ブランドA） */
:root {
  --brand-primary: #3b82f6;
  --brand-radius: 8px;
  --brand-font: 'Inter', sans-serif;
}

/* ブランドBの上書き */
[data-brand="b"] {
  --brand-primary: #8b5cf6;
  --brand-radius: 12px;
  --brand-font: 'Poppins', sans-serif;
}

/* ブランドCの上書き */
[data-brand="c"] {
  --brand-primary: #f59e0b;
  --brand-radius: 4px;
  --brand-font: 'Roboto', sans-serif;
}

トークンコンパイルパイプライン

デザインソースファイル（Figma）
  ↓
Style Dictionaryコンパイル
  ↓
├── CSS変数（Web）
├── Tailwind設定（Tailwindプロジェクト）
├── iOS Swiftファイル
├── Android Kotlinファイル
└── JSON（ドキュメントサイト）

// style-dictionary.config.js
const StyleDictionary = require('style-dictionary');

module.exports = {
  source: ['tokens/**/*.json'],
  platforms: {
    css: {
      transformGroup: 'css',
      buildPath: 'dist/css/',
      files: [{ destination: 'variables.css', format: 'css/variables' }],
    },
    tailwind: {
      transformGroup: 'js',
      buildPath: 'dist/tailwind/',
      files: [{ destination: 'theme.js', format: 'javascript/module' }],
    },
  },
};

---

ToolsKuのデザインシステム実践

ToolsKuはTailwind CSS v4 + CSS変数でデザインシステムを構築しています：

/* ToolsKuテーマトークン */
:root {
  --color-primary: #2563eb;
  --color-surface: #ffffff;
  --color-text: #1f2937;
  --radius: 8px;
  --font-sans: 'Inter', system-ui, sans-serif;
}

/* ツールカードコンポーネント */
.tool-card {
  padding: var(--space-4);
  border-radius: var(--radius);
  background: var(--color-surface);
  border: 1px solid var(--color-border);
  transition: transform 0.2s, box-shadow 0.2s;
}

.tool-card:hover {
  transform: translateY(-2px);
  box-shadow: var(--shadow-md);
}

---

デザインシステムガバナンス

バージョン管理

@toolsku/tokens     v2.4.0  → デザイントークンパッケージ
@toolsku/components v3.1.0  → コンポーネントライブラリ
@toolsku/patterns   v1.2.0  → パターンライブラリ

依存関係：patterns → components → tokens

変更フロー

1. デザイナーがFigmaでトークンを変更
2. Gitリポジトリに自動同期（Figma Plugin）
3. CIがStyle Dictionaryコンパイルを実行
4. ビジュアルリグレッションテスト（Chromatic/Storybook）
5. 新バージョンを自動公開（Changesets）

ドキュメントサイト

Storybook
├── Tokens      → 色、間隔、フォントサイズの表示
├── Components  → コンポーネントインタラクションドキュメント
├── Patterns    → パターン使用ガイド
└── Guidelines  → デザイン仕様説明

---

まとめ

デザインシステムはコンポーネントライブラリではなく、トークンからコンポーネント、パターンまでの完全なアーキテクチャです。三層トークン（プリミティブ→セマンティック→コンポーネント）は拡張性の基盤であり、コンポジションパターンは過剰カプセル化より優れており、CSS変数 + Tailwindは2026年で最も実用的な技術選択です。覚えておいてください：優れたデザインシステムはデザイナーと開発者に同じ言語を話させ、トークンはその言語の語彙です。