デザイントークン 02 設計と命名(カテゴリ別)

更新日: 2026-09-29

命名の基本ルール

役割(何に使うか)で名付ける。見た目(色名・数値)はプリミティブ層だけ
- ✗ button-yellow → ○ button-primary-bg
大 → 小の順: カテゴリ-用途-状態(color-text-muted、color-bg-danger-hover)
面と文字をペアに: primary / primary-foreground(shadcn/ui の規約)
W3C 形式では名前に { } . を使えない、$ で始められない
チームで規約を決めて統一(略語、区切り文字、状態の語彙: hover / active / disabled / focus)

各色相を明るさ 50〜950 の段階で用意(Tailwind と同じ考え方):
gray-50 … gray-950、blue-50 … blue-950、red-*、green-*、yellow-*

トークン	用途
`background` / `foreground`	ページの背景 / 本文
`muted` / `muted-foreground`	控えめな面 / 補足テキスト
`card` / `popover` (+ `-foreground`)	浮いた面
`primary` (+ `-foreground`)	主要アクション・ブランド
`secondary` / `accent` (+ `-foreground`)	副次アクション / ホバー・選択
`border` / `input` / `ring`	枠線 / 入力枠 / フォーカス
`destructive` / `success` / `warning` / `info`	状態色
`link`	テキストリンク

基準値の倍数で作る(4px 基準: 4, 8, 12, 16, 24, 32, 48, 64 / 8px 基準: 8, 16, 24, 32 ...)
名前は数値(space-4 = 16px)か T シャツサイズ(sm md lg)。Tailwind は数値方式(1 単位 = 4px)
関係の近さで使い分ける(デザインの4原則の「近接」):
- 小(2〜4px): 一体に見せたい要素(タイトルと補足)
- 中(8〜16px): 独立した操作の間、カード内側
- 大(32〜64px): セクションの区切り
中途半端な値(6px、13px)が欲しくなったら、構造の見直しのサイン

トークン	例
`font-sans` / `font-mono`	`"Noto Sans JP", system-ui, sans-serif`
`text-xs … text-4xl`	12 / 14 / 16 / 18 / 20 / 24 / 30 / 36px
`font-weight-regular/medium/bold`	400 / 500 / 700
`leading-tight/normal/relaxed`	1.25 / 1.5 / 1.75(日本語は 1.6〜1.8 が読みやすい)

用途別の複合トークン(W3C の typography 型): heading-1 = { fontFamily, fontSize, fontWeight, lineHeight }
本文は 16px 以上が基本(スマホ)

カテゴリ	例	ポイント
radius	`radius-sm/md/lg/xl/full`	基準値1つから計算すると統一しやすい(shadcn: `--radius` から sm〜4xl を算出)
shadow	`shadow-sm`(カード)/ `shadow-lg`(モーダル)	高さ(elevation)の段階として定義
motion	`duration-fast 150ms` / `duration-normal 300ms`、`ease-out`	「動きを減らす」設定(prefers-reduced-motion)に対応
breakpoints	`sm 640 / md 768 / lg 1024 / xl 1280`	Tailwind の既定に合わせると楽
z-index	`z-dropdown 1000 / z-modal 1100 / z-toast 1200`	重なり順の衝突を防ぐ

転職サービス向けに公開されているデザインシステムの例(出典: https://ui.jobantenna.jp/rules/color , https://ui.jobantenna.jp/rules/spacing)。

小さい余白で要素を「結合」し、大きい余白で面を「区切る」2層構造
- 2px: 意味が地続きの行(求人タイトルと会社名)/ 4px: 同種の要素を横に詰める / 8px: 独立した操作を離す / 16px: カード内側
- 32px / 48px / 64px: 発言単位・空状態・セクション間
中間値(6px など)は使用禁止 → 使いたくなったら階層設計を見直すサイン(デザインの4原則の「近接」のルール化)
AI への指示例: 「色は globals.css のトークンだけを使い、余白は 2/4/8/16/32/48/64px のみ」

最初から完璧にしなくてよい。まずこれだけ: