メソドロジー

design-token-lint の背景にある考え方 — なぜ生の Tailwind ユーティリティを禁止し、セマンティックトークンで置き換えるのか。

design-token-lint は Tailwind CSS でデザインシステムを構築するための特定のアプローチを強制します。このページではその理由を説明します。

問題

Tailwind には数百のユーティリティクラスとデフォルトカラーパレットが付属しています。プロトタイプには最適ですが、スケールすると問題が生じます:

一貫性のなさが静かに忍び寄る。 開発者がある場所で p-4、別の場所で p-6、さらに別の場所で p-3 と書く。どれも間違いではありません。どれもフラグが立ちません。デザインがドリフトしていきます。
リファクタリングのコストが高い。 デザインシステムが変わったとき — 例えば間隔の基本単位を 4px から 6px に移行するとき — すべてのハードコードされた p-4 を監査して場合によっては更新する必要があります。
意図が失われる。 p-4 は「4 単位のパディング」と言っているだけで、なぜかは何も語りません。カードのパディング? ボタンのインセット? セクションのガター? クラスからは手がかりが得られません。

解決策

生の数値ユーティリティをセマンティックトークンに置き換えます:

- <div class="p-4 gap-6 bg-gray-100 text-gray-900">
+ <div class="p-hgap-md gap-vgap-sm bg-surface text-fg">

セマンティック版は:

意図を伝える(surface、fg、md、sm)
すべてのコンポーネントに触れることなく中央で再調整できる
語彙が有限なので一貫性を保ちやすい

トークンのカテゴリ

間隔

hgap-*(水平)と vgap-*(垂直)サフィックスを使用:

p-hgap-sm   # small horizontal padding
m-vgap-lg   # large vertical margin
gap-hgap-md # medium gap

スケール名(2xs、xs、sm、md、lg、xl、2xl、...)は Tailwind の設定で定義され、実際のピクセル値にマップされます。

カラー

色相ではなく役割を表すセマンティックな名前を使用:

bg-surface     # any surface (cards, panels)
bg-surface-alt # alternate surface tint
text-fg        # primary foreground
text-muted     # de-emphasized text
border-muted   # subtle borders
bg-accent      # primary action color

またはプロジェクトスコープのトークンを使用:

bg-zd-black    # project-specific palette
text-p7        # primary palette slot 7

正確な名前はデザインシステム次第です — リンターはデフォルトの Tailwind カラー(gray、blue、red など)をブロックするだけです。

サイズ

同じドリフトの問題は、間隔だけでなく寸法にも当てはまります: w-64、h-96、size-40 は p-5 と同じくらい恣意的です。デフォルトでは、リンターは数値の幅/高さ/サイズのスケール(w-{n}、h-{n}、size-{n}、min-w-{n}、max-w-{n}、min-h-{n}、max-h-{n}、basis-{n})も禁止し、同じ種類のセマンティックなスケール、または明示的な任意値へと導きます:

w-[240px]   # explicit, one-off dimension
h-avatar-lg # semantic sizing token, if your design system defines one

間隔/カラーとは異なり、このプロジェクトは独自の意見を持つサイズトークンの語彙を同梱しません — デザインシステムが名前付きのサイズトークンを定義するまでは、任意値(w-[240px])が現実的なデフォルトのエスケープハッチです。

引き続き動くもの

このリンターは Tailwind を禁止しようとしているわけではありません。ほとんどのユーティリティは引き続き動作します:

レイアウト: flex、grid、block、hidden、w-full、h-screen
タイポグラフィ: font-bold、text-lg、leading-tight、tracking-wide
エフェクト: shadow、rounded、opacity-50、transition
ゼロ、あらゆる数値間隔/サイズユーティリティに対して: p-0、mt-0、px-0、inset-0、w-0、gap-0 など — リンターはリテラルの 0 値を自動的に許可します。allowed に列挙されたクラスだけではありません
p-1px、mt-1px のような数値でない間隔形状の値: これらはそもそも数値の {n} パターンに一致しないため、allowed エントリを必要とせずに通ります
任意値: w-[28px]、bg-[#123]、p-[10px]

生の数値間隔/サイズとデフォルトパレットの色のみがフラグされます。

エスケープハッチ

本当に生の値が必要な場合があります。次のいずれかを使用します:

任意値: p-[14px] — 明示的で検索可能、レビュアーに見える
無視コメント: 前の行に {/* design-token-lint-ignore */} — 無視構文を参照
許可リスト: クラスを設定の allowed 配列に追加

一度限りのものには任意値を優先してください。繰り返される正当な例外には許可リストを予約してください。

参考資料

このリンターは、より広い zudo-css-wisdom メソドロジー(Tailwind CSS で一貫性のあるメンテナンス可能なデザインシステムを構築するためのパターン集)の具体的な強制実装です。理論的背景の全貌についてはそちらを参照してください。