CSSカスタムプロパティによるセマンティックカラートークン

セマンティックカラートークン

セマンティックトークンは、カラーパレットとコンポーネントの間に抽象化レイヤーを追加します。--blue-500を直接参照する代わりに、コンポーネントはパレット値に解決される--color-primaryを使用します。この間接参照がスケーラブルなテーマの基盤です。

2層アーキテクチャ

/* レイヤー1: パレット（プリミティブトークン） */
:root {
  --blue-500: #3b82f6;
  --blue-600: #2563eb;
  --gray-50:  #fafafa;
  --gray-900: #18181b;
  --red-500:  #ef4444;
  --green-500: #22c55e;
}

/* レイヤー2: セマンティックトークン */
:root {
  --color-bg:       var(--gray-50);
  --color-text:     var(--gray-900);
  --color-primary:  var(--blue-500);
  --color-primary-hover: var(--blue-600);
  --color-error:    var(--red-500);
  --color-success:  var(--green-500);
}

メリット

1. テーマ切り替え — セマンティックトークンのみをオーバーライドし、すべてのコンポーネントではなく。
2. デザインの一貫性 — 開発者は任意の16進数値ではなくロールから選択。
3. リファクタリングの安全性 — パレットカラーを一度変更すれば、すべてのセマンティック参照が更新。
4. ドキュメント — トークン名が意図を伝える（--color-error vs --red-500）。

命名規則

パターン	例	使用場面
ロールベース	--color-primary	汎用テーマ
コンポーネントスコープ	--button-bg	コンポーネントライブラリ
インタラクティブ状態	--color-primary-hover	hover/focus状態を持つシステム

アンチパターン

• トークン過多: 200個のセマンティックトークンがある場合、抽象化が負担になっています。15〜30個のコアトークンを目指します。
• プリミティブの漏洩: コンポーネントがセマンティックトークンと並んで--blue-500を直接参照している場合、レイヤーが壊れています。
• フォールバックの欠如: 移行中の安全のために常にフォールバックを提供：var(--color-primary, #3b82f6)。