設定

.design-token-lint.json で design-token-lint を設定 — 禁止パターン、許可例外、無視ファイル、スキャンパターン。

プロジェクトルートに .design-token-lint.json または design-token-lint.config.json ファイルを作成します。リンターは最初に見つかったファイルを読み込み、どちらも存在しない場合は組み込みのデフォルトにフォールバックします。

完全な例

{
  "prohibited": [
    "p-{n}",
    "px-{n}",
    "py-{n}",
    "m-{n}",
    "gap-{n}",
    "bg-{color}-{shade}",
    "text-{color}-{shade}",
    "border-{color}-{shade}"
  ],
  "allowed": ["p-0", "m-0", "gap-0", "p-1px"],
  "ignore": ["**/*.test.*", "**/*.stories.*"],
  "patterns": [
    "src/**/*.{tsx,jsx,astro}",
    "components/**/*.{tsx,jsx,astro}"
  ],
  "classAttributes": ["className", "class", "inputClassName", "wrapperClass"],
  "classFunctions": ["cn", "clsx", "classNames", "twMerge", "cva", "tv"]
}

フィールド

すべてのフィールドはオプションで、省略時は組み込みのデフォルトにフォールバックします。

prohibited

フラグを立てるクラス名パターンの配列。各パターンはプレースホルダー構文を使います:

• {n} — 4、8、0.5、16 などの数値に一致。間隔(padding、margin、gap、inset、top/left/right/bottom など)に使用

• {color} — 標準的な Tailwind カラー名に一致: slate、gray、zinc、neutral、stone、red、orange、amber、yellow、lime、green、emerald、teal、cyan、sky、blue、indigo、violet、purple、fuchsia、pink、rose

• {shade} — 50、100、500、950 などの 2〜3 桁のシェード値に一致

例:

• p-{n} は p-4、p-8、p-0.5 に一致

• bg-{color}-{shade} は bg-red-500、bg-blue-300 に一致

• gap-x-{n} は gap-x-2、gap-x-6 に一致

構造化エントリ

プレーンな文字列の代わりに、エントリをオブジェクトにすることで、デフォルトの違反メッセージを上書きし、ルールにカテゴリのタグを付けられます:

{
  "prohibited": [
    "p-{n}",
    {
      "pattern": "w-{n}",
      "reason": "Numeric width \"{CLASS}\" — use a semantic sizing token or arbitrary value",
      "category": "sizing"
    }
  ]
}

• pattern(必須)— プレーンな文字列エントリと同じプレースホルダー構文。

• reason(オプション)— 違反メッセージを丸ごと置き換えます。{CLASS} プレースホルダー(実際のクラス名に置換される)をサポートします。省略時は、プレーンな文字列エントリと同様に、パターン形状から推論されたデフォルトメッセージが使用されます。

• category(オプション)— 自由形式のタグ(例: "sizing"、"z-index")で、このルールが一致したときに得られる Violation.category にコピーされます。これにより、ツールが違反をルールファミリごとにグループ化・フィルタリングできます。プレーンな文字列エントリは決して category を生成しません。

プレーンな文字列エントリは、常に reason/category のオーバーライドなしの { pattern: theString } と等価です — 同じ prohibited 配列内で文字列とオブジェクトのエントリを混在させても問題ありません。

allowed

禁止パターンとの照合より前にチェックされる許可リストです。各エントリは次のいずれかの形式を取れます:

• ベア/正規化形式 — そこから作られるすべてのバリアント、負の値、important 修飾子の形式も許可します。マッチングでは、比較前にバリアントプレフィックス(最後の : まで)、! important 修飾子、先頭の - 負号、/N 不透明度サフィックスが取り除かれます:

  • ベアな p-4 は hover:p-4、-p-4、p-4!、sm:-p-4! もカバーします。

  • ベアな bg-red-500 は、その不透明度形式(例: bg-red-500/50、hover:bg-red-500/50)もカバーします。

• 完全一致/そのままの形式(例: hover:p-2、-mt-4、bg-red-500/50)— その特定の文字列のみを許可します。違反メッセージからそのままコピーしたクラスを、ベア形式や他のすべてのバリアントを開放することなく、その 1 つのバリアントだけ許可したい場合に便利です。

p-0、m-0 のようなエスケープハッチはよくあるエントリです — もっとも、ゼロは allowed に関係なく あらゆる 間隔/サイズルールで自動的に通るため(自動的に通るものを参照)、これらは厳密には必須ではなく、防御的・明示的な意味合いです。

extends

完全なデフォルトリストを複製する代わりに、1 つ以上の組み込みプリセットから prohibited/allowed パターンを継承します。プリセット名、または名前の配列を取ります:

{
  "extends": ["default"]
}

現在、登録済みのプリセットは 2 つあります:

• default — 下記の 組み込みのデフォルト で説明する組み込みの prohibited/allowed リスト。

• z-index — オプトインの数値 z-index 禁止: z-{n}(例: z-10、z-50)を z-index 固有のメッセージでフラグし、z-0 を許可します。default には含まれません — 有効にするには明示的に列挙してください:

  {
    "extends": ["default", "z-index"]
  }

extends が配列の場合、レイヤーは指定された順にマージされます。プリセットが default と勝手に自動合成されることは決してありません — デフォルトに加えて別のプリセットが欲しい場合は、両方を明示的に列挙してください: "extends": ["default", "some-other-preset"]。"extends": ["z-index"] だけでは、デフォルトルールを一切含まず、z-index ルールのみが有効になります。

未知のプリセット名は設定エラーです(CLI は明確なメッセージとともに終了します)。

prohibitedAdd / allowedAdd

prohibited/allowed が解決された内容 — extends 経由で継承したプリセットリスト、あるいは extends もプレーンな prohibited/allowed も設定されていない場合は組み込みデフォルト — の上に、追加のエントリを付け足します。プロジェクト固有のルールや例外を少数追加したいだけのときは、prohibited/allowed を丸ごと上書きする代わりにこれらを使ってください:

{
  "extends": ["default"],
  "prohibitedAdd": ["z-{n}"],
  "allowedAdd": ["z-0"]
}

これは、約 70 個の組み込み prohibited パターンを再列挙することなく、すべてのデフォルトルールを保持したまま、z-{n} の間隔スタイルのルールと z-0 の例外を追加します。

プレーンな prohibited/allowed(存在する場合)は 置換 セマンティクスを保ちます — extends に対して完全に勝り、prohibitedAdd/allowedAdd はその明示的なリストの上にさらに追加します:

{
  "prohibited": ["hidden"],
  "prohibitedAdd": ["block"]
}

この例は、あらゆるデフォルト/プリセットパターンを無視し、ちょうど hidden と block を禁止します。

ignore

完全にスキップするファイル glob パターン。よくあるパターン:

{
  "ignore": [
    "**/*.test.*",
    "**/*.stories.*",
    "**/*.spec.*"
  ]
}

デフォルト: ["**/*.test.*", "**/*.stories.*"]。

patterns

CLI が明示的なファイル引数なしで呼び出されたときにスキャンするファイル glob パターン。省略時、CLI はデフォルトセット(src/**、components/**、lib/**、app/**)を使用します。

suggestionSuffix

— セパレーターの後で違反メッセージに付加される文字列で、デフォルトの提案テキストを置き換えます。プロジェクト固有のトークン命名規則を開発者に案内するために使用します。

デフォルトメッセージ(suggestionSuffix なし):

• 間隔: Numeric spacing "p-4" — use a semantic spacing token or arbitrary value

• カラー: Default Tailwind color "bg-gray-500" — use a design system color token

suggestionSuffix を設定した場合:

{
  "suggestionSuffix": "use hgap-*/vgap-* or zd-* tokens"
}

• 間隔: Numeric spacing "p-4" — use hgap-*/vgap-* or zd-* tokens

• カラー: Default Tailwind color "bg-gray-500" — use hgap-*/vgap-* or zd-* tokens

suggestions

禁止クラスから、そのプロジェクトのセマンティックな置き換えトークンへの、プロジェクトレベルのマッピングです。違反の正規化ベースクラス(allowed エントリが使うのと同じ、バリアント/負値/important/不透明度を取り除いた形)がここにエントリを持つ場合、マップされた値が違反メッセージに — did you mean "<value>"? として付加されます。

{
  "suggestions": {
    "p-4": "p-hsp-xs",
    "bg-gray-100": "bg-surface"
  }
}

この設定では、p-4 は次を生成します:

Numeric spacing "p-4" — use a semantic spacing token or arbitrary value — did you mean "p-hsp-xs"?

suggestions にエントリのないクラスは、通常のメッセージのまま変わらずフラグされます。

これは suggestionSuffix と組み合わさります: サフィックスはベースの理由テンプレートをカスタマイズし続け、提案はその後に付加されます。

{
  "suggestionSuffix": "use hsp-*/vsp-* tokens",
  "suggestions": { "p-4": "p-hsp-xs" }
}

Numeric spacing "p-4" — use hsp-*/vsp-* tokens — did you mean "p-hsp-xs"?

semanticPrefixes

セマンティックトークン語彙のための名前空間プレフィックスです。列挙された名前空間で始まる値は、その名前空間が取り除かれ、残った末尾が同じルールで再テストされます — 自動的に通るわけではありません。

デフォルト: ["hgap-", "vgap-", "hsp-", "vsp-"]

プロジェクトの命名規則に合わせてオーバーライドできます:

{
  "semanticPrefixes": ["hsp-", "vsp-"]
}

ストリップの仕組み

1. 設定済みのエントリは、値がそのエントリで始まる場合にマッチします。末尾の - は設定でオプションです — "hgap" と "hgap-" は同一に振る舞います。

2. マッチしたエントリが - で終わっているか、値の中でそのエントリの直後に - が続く場合、それは 名前空間マッチ です。その 末尾(tail) は、取り除かれた名前空間(および、エントリ自体が - を含んでいなかった場合はその後の -)の後に残るすべてです。デフォルトのリストのすべてのエントリ、およびこのセクションのすべての例は - で終わっているため、常に名前空間マッチになります。

3. エントリがマッチしても名前空間マッチではない場合 — p-12 の途中にマッチする "1" のようなダッシュのないエントリや、p-2 に対する "2" のように後に何も残らない完全一致の場合 — そのクラスは 末尾の再テストなしに、無条件で通ります。これは後方互換性のために変更されずに保持されている、元の 1.x の許可リストの挙動です。組み込みのデフォルトのような - で終わるエントリには決して適用されず、通常とは異なる、名前空間の形をしていないエントリにのみ適用されます。

4. 複数のエントリが名前空間としてマッチする場合、最も長い ものが勝ちます — これにより結果は配列の順序に依存しなくなります。

5. 末尾は、このルールに対する通常の値とまったく同じように判定されます: 空または "0" は通ります(すべての間隔/サイズルールがすでに持つのと同じゼロバイパス)。ルール自身の数値パターンにマッチする末尾は フラグされ、sm や 2xs のようなトークン名などそれ以外は通ります。

6. ストリップは 一度だけ 行われ、再帰しません: p-hgap-vgap-2 は外側の hgap- だけを取り除き、末尾 vgap-2 を残しますが、これは数値ではないため通ります。

7. マッチングは 大文字小文字を区別 します(p-HGAP-2 は hgap- エントリにマッチしません)。

これは 値のプレースホルダーが完全一致の {n} 形式であるすべてのルール に一律に適用されます — すべての組み込み間隔ルール、数値サイズスケール(w-{n}、h-{n}、size-{n} など)、オプトインの z-index プリセットの z-{n}、そして追加したカスタムの {n} ルールです。ファミリごとの例外はありません — このストリップは特定のルールではなく {n} プレースホルダーそのものの性質です。

名前空間マッチでフラグされた場合、違反メッセージには、著者が記述したままのマッチしたエントリを名指しする丸括弧が、suggestions のヒントより前に付加されます:

Numeric spacing "p-hgap-2" — use a semantic spacing token or arbitrary value (numeric tail after the "hgap-" semantic prefix)

Numeric spacing "p-hgap-2" — use a semantic spacing token or arbitrary value (numeric tail after the "hgap-" semantic prefix) — did you mean "p-hgap-sm"?

semanticPrefixes は置換セマンティクスを持つ

prohibited/allowed とは異なり、semanticPrefixes は extends/プリセットによって供給されず、加算的でもありません — extends と組み合わせても、設定するとデフォルトを丸ごと置き換えます:

{
  "extends": ["default"],
  "semanticPrefixes": ["hsp-"]
}

ここでは compiled.semanticPrefixes はちょうど ["hsp-"] になります — hgap-、vgap-、vsp- はマージされるのではなく消えます。これは下記のエスケープハッチ 3 に関わってきます。

新たにフラグされたクラスのエスケープハッチ

新しいデフォルトの下で失敗し始める p-hgap-2 のようなクラスに対して、優先順に:

1. トークンを改名する、数値スケールを偽装しないようにする(p-hgap-2 → p-hgap-sm)— これがこのルールの狙いです。

2. 特定のクラスを許可する: "allowed": ["p-hgap-2"] — allowed はどのルールよりも先にチェックされるため、常に勝ちます。

3. その名前空間を semanticPrefixes から外す(例: hgap- を含まない ["vgap-", "hsp-", "vsp-"] を列挙する)— その名前空間下の値については、エントリの有無に関わらず数値でない末尾は通るため、正確に 1.x の挙動が復元されます。

4. 任意値を使う: p-[8px]。

v2.0.0 での変更

classAttributes

エクストラクターがクラス名を探す属性名の配列。このリストにある JSX/HTML 属性はクラス属性として扱われ、その文字列値が抽出されてリントされます。

デフォルト: ["className", "class"]

コンポーネントライブラリが非標準の prop 名でクラス名を受け取る場合に使用します:

{
  "classAttributes": ["className", "class", "inputClassName", "wrapperClass"]
}

これは、Headless UI、Radix UI、あるいは複数の prop でクラス名を渡すカスタムコンポーネントライブラリなどに便利です。

注記: class:list(Astro のディレクティブ構文)は、この設定に関係なく常にスキャンされます。

classFunctions

エクストラクターがクラス名引数を探すユーティリティ関数名の配列。これらの関数への呼び出しが抽出され、その文字列引数がリントされます。

デフォルト: ["cn", "clsx", "classNames", "twMerge"]

プロジェクトで追加のクラスマージユーティリティをサポートするために使用します:

{
  "classFunctions": ["cn", "clsx", "classNames", "twMerge", "cva", "tv", "twJoin"]
}

これは、class-variance-authority(cva)、tailwind-variants(tv)、あるいは tailwind-merge の twJoin のような追加ユーティリティを使う場合に便利です。

css

プレーンな CSS/SCSS 宣言値 のオプトインスキャン — Tailwind クラス属性を超えた拡張です。このセクション全体は デフォルトでは存在せず、その中の各ルールも デフォルトで OFF です。そのため、css セクションを追加し、かつルールを ON にするまで、何も変わりません。

{
  "css": {
    "zIndex": true,
    "colorLiterals": true,
    "patterns": ["src/**/*.css", "src/**/*.scss"]
  }
}

css.patterns は、CLI が明示的なファイル引数なしで実行されたとき、通常の patterns とともにスキャンされます。CSS のみ をスキャンするには、トップレベルの "patterns": [] を設定し、CSS glob を css.patterns に列挙してください。

違反は Tailwind の違反と同じフラットな形で報告され、問題の宣言が className フィールドに安定した property: value 形式(例: z-index: 9999)で入ります。

zIndex

生の整数 z-index 値を禁止し、セマンティックな z-index 階層システムを強制します。z-index 戦略の許可/禁止テーブルをミラーします:

calc() は var() 参照を含む場合にのみ許可としてカウントされます。calc(100 + 1)(生の算術)は依然としてフラグされます。末尾の !important は生の整数を免除しません。

colorLiterals

宣言値に埋め込まれた生のカラーリテラルを禁止します:

フラグされる形式は #hex(3/4/6/8 桁)、rgb()/rgba()、hsl()/hsla()、oklch()/oklab() です。名前付きカラーやその他のキーワードのみの値は許可されます — このルールはリテラル値を対象とし、すべての色を対象とするわけではありません。

エスケープハッチ

Tailwind クラスルールと同じ design-token-lint-ignore コメントを使います。CSS ではこれは 次の行 を抑制します(末尾コメントとして置いた場合は自身の行を抑制します):

/* Legacy third-party widget — remove once migrated, tracked at #123. */
/* design-token-lint-ignore */
.legacy-widget {
  z-index: 9999;
}

コメントは すぐ次の行にある宣言 を抑制するため、セレクタの上ではなく、z-index: / カラー宣言のすぐ上に置いてください。末尾の理由(/* design-token-lint-ignore - why */)は許容されます。design-token-lint-ignore-file はファイル全体を抑制します。

スコープと既知の制限事項(v1)

CSS スキャン v1 は厳密に 宣言ベース で、行/正規表現駆動です(PostCSS なし、AST なし — Tailwind エクストラクターと一貫)。/* */ コメント(複数行にまたがるものを含む)、文字列リテラル、url(...) 値、SCSS の // 行コメントを正しく扱います。以下は 既知の偽陰性 です — リテラルを埋め込んでいるが、設計上 v1 では フラグされない 値です:

• リテラルを保持する カスタムプロパティ定義(--brand: #f00;)。パレット定義ゾーン(:root、@theme)と、パレットを参照すべきセマンティックトークンとを区別するにはゾーン認識が必要で、これは後回しにされた後続パスです。

• SCSS 変数宣言($brand: #f00;)— カスタムプロパティと同じ理由。

• SCSS マップ やその他のネスト/補間された SCSS 構造。

• 単一宣言を超える複雑な複数行構文にまたがって分割された値。

ゾーン認識スキャン(パレット定義ゾーンでのみリテラルを許可する)は、このバージョンのスコープ外です。

requireIgnoreReason / reportUnusedIgnores

どちらも デフォルト false の 2 つのオプトインフラグで、無視コメントが黙って文書化されないエスケープハッチになるのを防ぎます:

{
  "requireIgnoreReason": true,
  "reportUnusedIgnores": true
}

どちらのフラグも、無視構文ガイドで説明されているのと同じ design-token-lint-ignore / design-token-lint-ignore-file コメントを読み取ります — 新しいコメント形式を覚える必要はありません。これらは、無視コメントが尊重されるあらゆる場所に適用されます: Tailwind クラス属性/ユーティリティ呼び出し、および css 宣言スキャンのパス。

requireIgnoreReason

通常、design-token-lint-ignore コメントは、理由の有無に関わらず、それがカバーするクラス/宣言を抑制します。requireIgnoreReason: true の場合、実際の違反 を隠す 素の 無視(末尾の理由テキストなし)は、黙って消える代わりに報告されます:

// design-token-lint-ignore
<div className="p-4">

L2: p-4 — suppressed without documented reason

-、–、—、: のいずれかのセパレーターの後に理由を追加すると、同じ無視は以前とまったく同じように黙って抑制します:

// design-token-lint-ignore - vendor requires literal p-4
<div className="p-4">

実際の違反を隠さない無視は、このフラグの影響を受けません(下記の reportUnusedIgnores を参照)。また、design-token-lint-ignore-file はこのバージョンではこのフラグの対象外です — 素のファイルレベル無視がこの検出をトリガーすることはありません。

reportUnusedIgnores

ESLint の reportUnusedDisableDirectives に相当します。reportUnusedIgnores: true の場合、何も 抑制しなかった design-token-lint-ignore コメント — カバーするすべてのクラス/宣言がすでに通っていた — 自体が、コメント自身の行にアンカーされて報告されます:

// design-token-lint-ignore
<div className="flex">

L1: design-token-lint-ignore — Unused design-token-lint-ignore comment — suppressed no violation

この検出の className はリテラル文字列 "design-token-lint-ignore" です(名指しすべき違反クラスがない — コメント自体が問題です)。そのため、--json と --format github の出力は、他のすべての検出と同じフラットな LintResult の形を保ちます。少なくとも 1 つの実際の違反を抑制する無視コメントは、たとえ他のすでにクリーンな行もカバーしていたとしても、未使用として報告されることはありません — そして、理由付きの無視も素のものと同じくここでは報告対象になります。このフラグは、コメントが文書化されているかどうかではなく、何かをしたかどうかに関するものだからです。

組み込みのデフォルト

設定ファイルが存在しない場合、リンターは以下のデフォルトを使用します。この同じ prohibited/allowed のペアは、extends で使用する default プリセットとしても登録されています:

• Prohibited: すべての標準的な間隔ユーティリティ(p-*、m-*、gap-*、inset-*、scroll-*)の数値版、およびすべてのカラーユーティリティ(bg-*、text-*、border-*、ring-* など)のデフォルト Tailwind カラーとシェードの組み合わせ

• 論理・v4 カラーユーティリティ: border-s-*、border-e-*、ring-offset-*、inset-ring-*、inset-shadow-*、text-shadow-* のデフォルト Tailwind カラーとシェードの組み合わせ

• 数値サイズスケール: w-{n}、h-{n}、size-{n}、min-w-{n}、max-w-{n}、min-h-{n}、max-h-{n}、basis-{n} — それぞれサイズ固有のメッセージとともにフラグされ、得られる Violation に category: "sizing" が付きます(構造化エントリを参照)。分数ユーティリティ(w-1/2)、任意値(w-[32px])、ゼロ(w-0)は引き続き通ります — 下記の 自動的に通るもの を参照。

• Allowed: p-0、m-0、gap-0、p-1px — p-1px はここでは実質的に不活性です(理由は下記の 自動的に通るもの を参照)。「ゼロ相当」のエスケープハッチの文書化として、主にリストに残っています。

• Ignore: **/*.test.*、**/*.stories.*

完全なデフォルトリストはパッケージの READMEを参照してください。

自動的に通るクラス

これらのクラスは allowed に含まれていなくても常に通ります:

• セマンティック間隔トークン: p-hgap-sm、gap-vgap-xs、m-hgap-md(hgap-* または vgap-* サフィックスを持つクラス)

• デフォルト以外のカラー: bg-surface、text-fg、bg-zd-black(標準 Tailwind パレット名ではないカラー名)

• 任意値: w-[28px]、bg-[#123]、p-[10px]

• 間隔・色以外のユーティリティ: flex、grid、hidden、w-full、font-bold など

• ゼロ、あらゆる 数値間隔/サイズルールに対して: p-0、mt-0、px-0、inset-0、w-0、gap-0、top-0 など、すべて通ります — allowed にたまたま列挙された、ごく一部の 0 サフィックス付きクラスだけではありません。リンターには専用のランタイムチェック(「このルールの数値は 0 に等しいか?」)があり、allowed の内容に関係なく、すべての {n} 形状の間隔/サイズパターンに対して発火します。

• 数値でない間隔形状の値: p-1px、mt-1px、inset-1px なども通ります — ただし、上記のゼロの場合とは異なる、より単純な理由によります。{n} プレースホルダーは純粋な数値(^\d+(\.\d+)?$)にのみ一致し、1px のように文字を含む値はそもそもそのパターンを満たしません。したがって、デフォルトの allowed リストにある p-1px は不活性です — そのエントリの有無に関わらず通ります。