CLI

design-token-lint のコマンドライン使用方法とオプション。

design-token-lint CLI はファイルをスキャンして禁止された Tailwind クラス名を検出し、違反を報告します。

基本的な使い方

# Scan default patterns (from config.patterns or built-in defaults)
design-token-lint

# Scan specific files or globs
design-token-lint "src/**/*.tsx" "pages/**/*.tsx"

# Scan a single file
design-token-lint src/App.tsx

オプション

design-token-lint --help
design-token-lint --version
design-token-lint --json
design-token-lint --format github

- で始まるが上記のいずれでもない未知のオプションは、glob パターンとして黙って扱われるのではなく、エラーかつ終了コード 2 として拒否されます。

終了コード

CI で違反があった場合にビルドを失敗させるには終了コード 1 を利用します:

# .github/workflows/lint.yml
- run: pnpm design-token-lint

環境変数

出力フォーマット

デフォルト(human フォーマット)では、違反はファイルごとにグループ化されます。各行は行番号、違反クラス、理由を表示します:

Scanning 1 file(s)...

src/App.tsx
  L12: p-4 — Numeric spacing "p-4" — use a semantic spacing token or arbitrary value
  L12: bg-gray-500 — Default Tailwind color "bg-gray-500" — use a design system color token

Found 2 violation(s) in 1 file(s).

すべての出力は stderr に送られるため、stdout をパイプするスクリプトに干渉しません — 例外は --json(JSON 配列を stdout に出力)と --format github(::error アノテーションを stdout に出力)です。

JSON 出力

--json を渡すと、通常の stderr への人間可読表示に加えて、結果が JSON 配列として stdout に出力されます:

design-token-lint --json > violations.json

[
  { "filePath": "src/App.tsx", "line": 12, "className": "p-4", "reason": "Numeric spacing \"p-4\" — use a semantic spacing token or arbitrary value" }
]

GitHub Actions アノテーション

--format github を渡す(または GitHub Actions 上でそのまま実行する — GITHUB_ACTIONS は自動検出されます)と、人間可読表示の代わりに各違反が ::error ワークフローコマンドとして出力されます:

::error file=src/App.tsx,line=12::p-4 — Numeric spacing "p-4" — use a semantic spacing token or arbitrary value

GitHub はこれらを PR の差分表示と Checks タブ上のインラインアノテーションとしてレンダリングします。--json と --format を組み合わせた場合、stdout に何が出力されるかは --json が優先されます。

ファイルパターン解決

引数なしで呼び出された場合、CLI はこの順序でファイルを解決します:

1. config.patterns が設定されていればそれを使用

2. それ以外は組み込みデフォルトを使用: src/**/*.{tsx,jsx,astro}、components/**/*.{tsx,jsx,astro}、lib/**/*.{tsx,jsx}、app/**/*.{tsx,jsx}

オプトインの css 設定セクションが css.patterns を設定している場合、それらの glob は上で解決された Tailwind パターンに 加えて スキャンされます(CLI パターンが明示的に渡されなかった場合のみ)。

引数ありで呼び出された場合、各引数はファイルパスまたは glob として扱われます。ignore の設定は引き続き適用されます。

組み込み無視 glob

2 つの glob パターンは、設定に関係なく、あらゆるスキャンから常に除外されます — **/node_modules/** と **/dist/** です。これらは、設定自身の ignore リスト(デフォルトは **/*.test.*、**/*.stories.*)より前にマージされるため、いずれのディレクトリにも誤ってスキャンが入り込む余地はありません。

これらの組み込み glob は CLI 自身の glob 解決の性質です — プログラマティック API を通じて直接行われる lintFile()/lintContent() 呼び出しには影響しません。これらの呼び出しは、ファイルツリーの走査を一切行わず、与えられた内容をそのままリントします。

package.json との統合

便利な呼び出し用にスクリプトを追加:

{
  "scripts": {
    "lint:tokens": "design-token-lint"
  }
}

実行:

pnpm lint:tokens

lefthook との統合

lefthook でプッシュ時に実行:

# lefthook.yml
pre-push:
  commands:
    design-token-lint:
      run: npx design-token-lint

CI との統合

GitHub Actions ステップを追加:

- name: Lint design tokens
  run: pnpm design-token-lint

違反があればコード 1 で終了し、ワークフローが失敗します。Actions の実行では GITHUB_ACTIONS が自動的に設定されるため、明示的に --format github を指定しなくても ::error アノテーション形式(「GitHub Actions アノテーション」参照)で自動出力されます。