壊れないデザインシステムは「セマンティック・トークン」から始まる

トークンには 2 階層ある

Primitive  →  Semantic  →  Component
  red.500       color.danger    Button.bg

• Primitive: ただの色 (red.500, #ef4444)
• Semantic: 用途 (color.danger, color.surface)
• Component: 各 UI への適用

なぜ Semantic を挟むか

bg-red-500 を直接書くと、ダークモードもリブランドも全箇所書き換えになる。

/* ❌ 用途と色がカップリングしている */
.alert { background: #ef4444; }

/* ✅ 用途で渡し、色は変数で */
.alert { background: var(--color-danger); }

テーマ切り替えは、:root と [data-theme="dark"] で 変数の指す primitive を差し替える だけ。

命名のコツ

• 見た目 で名付けない (color.lightBlue)
• 用途 で名付ける (color.info, color.surface.subtle)
• 階層は深くしすぎない（3 段が限度）

ペイオフ

半年後に「ブランドカラーを変えたい」と言われたとき、

• 直書き派 → grep して 300 箇所書き換え
• トークン派 → primitive を 1 行差し替えて終了

未来の自分への投資としては、コスパが異常に高い。