Design Token Lint

Type to search...

to open search from anywhere

メソドロジー

作成2026年4月10日Takeshi Takatsudo

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

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

問題

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

  1. 一貫性のなさが静かに忍び寄る。 開発者がある場所で p-4、別の場所で p-6、さらに別の場所で p-3 と書く。どれも間違いではありません。どれもフラグが立ちません。デザインがドリフトしていきます。
  2. リファクタリングのコストが高い。 デザインシステムが変わったとき — 例えば間隔の基本単位を 4px から 6px に移行するとき — すべてのハードコードされた p-4 を監査して場合によっては更新する必要があります。
  3. 意図が失われる。 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   # 小さな水平パディング
m-vgap-lg   # 大きな垂直マージン
gap-hgap-md # 中程度のギャップ

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

カラー

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

bg-surface     # あらゆるサーフェス(カード、パネル)
bg-surface-alt # 代替サーフェスの濃淡
text-fg        # 基本前景
text-muted     # 控えめなテキスト
border-muted   # 微妙なボーダー
bg-accent      # プライマリアクションカラー

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

bg-zd-black    # プロジェクト固有のパレット
text-p7        # プライマリパレットのスロット 7

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

引き続き動くもの

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

  • レイアウト: flex、grid、block、hidden、w-full、h-screen
  • タイポグラフィ: font-bold、text-lg、leading-tight、tracking-wide
  • エフェクト: shadow、rounded、opacity-50、transition
  • ゼロおよび 1px の間隔: p-0、m-0、gap-0、p-1px
  • 任意値: w-[28px]、bg-[#123]、p-[10px]

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

エスケープハッチ

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

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

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

参考資料

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

このページを編集

Revision History