デザイントークン 05 運用(テーマ・アクセシビリティ・AI・チェックリスト)
更新日:
テーマ(ダークモード・ブランド切替)
- セマンティック層の値だけをモードごとに切り替える。部品のコードは触らない
- ダークモードは単純な反転ではない:
- 真っ黒(#000)ではなく濃いグレーの背景
- 彩度の高い色は少し明るく・彩度を落とす
- 影は効きにくいので、面の明るさの差で高さを表現
- 仕組み:
<html class="dark">やprefers-color-schemeで CSS 変数を上書き(shadcn-ui_03_テーマ・デザイントークン・ダークモード)
アクセシビリティ(トークン設計時に保証する)
| 項目 | 基準(WCAG 2.2 AA) |
|---|---|
| 本文とその背景のコントラスト | 4.5:1 以上 |
| 大きな文字(18pt / 太字14pt 以上) | 3:1 以上 |
| UI 部品・フォーカスリングと背景 | 3:1 以上 |
primaryとprimary-foregroundのようにペアで定義してペアでチェックすると漏れない- 状態を色だけで伝えない(アイコン・文言も)
prefers-reduced-motionで動きを減らすトークンを用意- 画面を白黒にして確認するのも有効(UXデザイン)
変更管理
- トークンは全体に影響する → 変更はレビュー必須(PR)
- 名前の変更・削除は
$deprecatedで予告してから - バージョンを付けて配布(npm パッケージ / レジストリ)、CHANGELOG を残す
- ビジュアルリグレッションテスト(スクリーンショット比較)で意図しない変化を検知
生成 AI と使う時(効果が大きいポイント)
AI は放っておくと毎回それっぽい色や余白を作る → トークンで縛ると出力が安定する。
CLAUDE.md / AGENTS.md / DESIGN.md に書く例:
## デザイントークン
- 色は globals.css のトークンのみ(bg-primary, text-muted-foreground, border-border など)。
カラーコードや任意値(bg-[#...])は禁止
- 余白は Tailwind の標準スケールのみ(p-2, p-4, gap-6 ...)。任意値(p-[13px])禁止
- 角丸は rounded-md / rounded-lg、影は shadow-sm / shadow-md のみ
- 新しい色が必要なら、先にトークンを :root / .dark / @theme inline に追加してから使う
- 主要ボタン(primary)は1画面1つ- レビュー時に AI に「トークン以外の値を使っている箇所を探して」と頼める
- lint で任意値を禁止する方法もある(Tailwind の任意値検出など)
導入チェックリスト
- プリミティブ(パレット・スケール)とセマンティック(役割)を分けた
- 色・余白・文字・角丸・影の最低限を定義した
- ライト/ダークの両方で、全ペアのコントラストを確認した
- 命名規則を文書化した(DESIGN.md)
- コードでは値の直書きがない(lint / AI レビュー)
- デザインツール(Figma)の変数名とコードのトークン名が一致している
- 変更は PR でレビュー、廃止は
$deprecatedで予告