sparkle-design-cli 2.5.0-beta.1 → 2.5.0-beta.3

package/CONTRIBUTING.md

@@ -27,6 +27,15 @@ npm run sync:anti-pattern-docs  # ルールの解説を隣接リポジトリの
 ```
 
 > **`sync:anti-pattern-docs` の注意:** ワークスペース内の隣接リポジトリ（`../sparkle-design` / `../sparkle-design-internal`）のファイルを書き換える横断スクリプトです。両リポジトリが隣にある Sparkle ワークスペース内で実行してください（worktree からは sibling が解決できず落ちます）。**このリポジトリの README は書き換えません** — ルール一覧は `rules` コマンドが出すためです。
+>
+> **共有チェックアウトに向けて実行しないこと。** 隣接リポジトリで誰かが作業中だと、その未コミット変更に自分の生成物が混ざります。実行後に `git checkout -- .` で戻そうとして**他人の変更まで消す事故が実際に起きました**。同期専用の worktree を切り、`SPARKLE_DESIGN_ROOT` / `SPARKLE_DESIGN_INTERNAL_ROOT` でそこを指してください。
+>
+> ```bash
+> git -C ../sparkle-design worktree add .claude/worktrees/docs-sync -b chore/sync-anti-pattern-docs
+> SPARKLE_DESIGN_ROOT=../sparkle-design/.claude/worktrees/docs-sync npm run sync:anti-pattern-docs
+> ```
+>
+> 実行前に対象リポジトリが clean であることを `git status` で確認し、戻すときも**自分が触ったファイルだけを明示的に指定**してください（`git checkout -- <path>`）。
 
 ## リリース手順（メンテナ向け）
 

package/README.md

@@ -73,6 +73,9 @@ npx sparkle-design-cli check src --format json
 
 # 現在有効なアンチパターンルールを一覧表示（プラグイン由来のものも含む）
 npx sparkle-design-cli rules
+
+# Artifact Registry の npm registry 用トークンを ~/.npmrc に書く（beta）
+npx --yes sparkle-design-cli@beta auth
 ```
 
 ### generate: 基本的な使用方法
@@ -94,7 +97,7 @@ npx sparkle-design-cli rules
 npx sparkle-design-cli generate
 ```
 
-3. `src/app/sparkle-design.css` に CSS ファイルが生成されます。
+3. CSS ファイルが生成されます（既定は `src/app/sparkle-design.css`。`extend.globals-path` や `--globals-path` で Tailwind エントリ CSS を明示していて、それが実在する場合はそのディレクトリに出ます）。
 
 ### generate: コマンドオプション
 
@@ -125,7 +128,7 @@ sparkle-design-cli generate -c ./config/sparkle.admin.json --scope '[data-tenant
 
 - `-h, --help`: ヘルプメッセージを表示
 - `-c, --config <パス>`: 設定ファイルのパス（デフォルト: `./sparkle.config.json`）
-- `-o, --output <パス>`: 出力ファイルのパス（デフォルト: `./src/app/sparkle-design.css`）
+- `-o, --output <パス>`: 出力ファイルのパス。未指定時は、明示された Tailwind エントリ CSS（`--globals-path` / `extend.globals-path`）が実在すればそのディレクトリ、無ければ `./src/app/sparkle-design.css`
 - `--globals-path <パス>`: Tailwind エントリポイント CSS のパス（デフォルト: 自動検出）。
   **指定したパスが存在しない場合は `--strict` の有無に関わらず常に exit 1**（`sparkle.config.json` の `extend.globals-path` も同様）
 - `--strict`: 以下を warn ではなく **exit 1** に昇格させる（CI 向け。既定は warn + 継続で後方互換を維持）:
@@ -197,6 +200,23 @@ npx sparkle-design-cli rules --format json
 
 AI エージェントや CI からこの `lint:sparkle` を呼ぶ運用にすると、ガイドラインの注意書きだけに頼らず機械的に検査できます。
 
+### auth: Artifact Registry の認証（beta）
+
+社内パッケージの配信先を Google Artifact Registry（AR）に移行するための準備です（goodpatch/sparkle-design-internal#261）。Google の資格情報から AR 用のアクセストークンを取得し、ユーザー単位の `~/.npmrc` に書きます。
+
+```bash
+gcloud auth login                         # 初回のみ（ADC を使う場合は gcloud auth application-default login）
+npx --yes sparkle-design-cli@beta auth    # プロジェクトの .npmrc の @goodpatch:registry が対象
+pnpm install
+```
+
+- 対象の registry は `--registry <url>`、無ければプロジェクトの `.npmrc`（親ディレクトリも辿る）の `@goodpatch:registry=` です。プロジェクトの `.npmrc` には registry 行だけを置けばよく、そのままコミットできます
+- トークンの取得は ADC → `gcloud auth print-access-token` の順です。どちらも使えなければ `gcloud auth login` を案内して終了します
+- **トークンは約 60 分で失効します。** `pnpm install` が 401 で落ちたら（npm は `npm adduser` を案内しますが、AR では解決しません）もう一度 `auth` を実行してください
+- 同じ registry の行は置き換えるので、何度実行しても `~/.npmrc` に行は積み上がりません。`always-auth` は書きません
+- トークンは Artifact Registry（`<location>-npm.pkg.dev`）以外には書きません。`cloud-platform` スコープの Google トークンなので、ほかのホストに渡すと資格情報の漏えいになるためです
+- トークンを画面に出さず、refresh token などの長期クレデンシャルもコピーしません（gcloud の管理下に置いたまま）
+
 ### setup: プロジェクトのフルセットアップ
 
 `sparkle-design-cli setup` は、Sparkle Design の導入に必要な作業をまとめて行います：
@@ -274,7 +294,7 @@ npx --yes sparkle-design-cli setup --assistant claude --skip-install --skip-scaf
 
 ## 出力
 
-- デフォルト出力先: `src/app/sparkle-design.css`
+- 既定の出力先: `src/app/sparkle-design.css`（Tailwind エントリ CSS を明示していて実在する場合はそのディレクトリ）
 - カスタム出力先: `-o` オプションで指定可能
 - 実行場所を基準として相対パスで処理されます
 
@@ -283,7 +303,7 @@ npx --yes sparkle-design-cli setup --assistant claude --skip-install --skip-scaf
 CLI は **Tailwind エントリ CSS（`@import "tailwindcss"` を含む CSS ファイル）** を自動検出し、以下を 1 回で揃えます:
 
 - `sparkle-design.css` の `@import`
-- `@source "../node_modules/sparkle-design/dist"`（v4 が node_modules のクラスを拾うのに必要）
+- `@source "<エントリ CSS から node_modules への相対パス>/sparkle-design/dist"`（v4 が node_modules のクラスを拾うのに必要）。相対パスはエントリ CSS の位置から毎回計算されるので、`src/app/globals.css` なら `../../node_modules/...` になります
 - フォント `<link>` タグ（React 向けは `SparkleHead.tsx`、Vite 向けは `index.html` の managed block に自動注入）
 
 CSS 仕様上 `@import` は他の at-rule より前に書く必要があるため、順序も適切に整えます。`@import "tailwindcss"` が欠けている場合は先頭に自動追記されます。

package/bin/sparkle-design.js

@@ -7,8 +7,17 @@ import { runStopHook } from '../lib/stop-hook.js';
 import { PLUGIN_SPEC_MARKDOWN } from '../lib/plugin-api.js';
 import { loadAntiPatternPlugins } from '../lib/load-plugins.js';
 import { runRules } from '../lib/rules-report.js';
-
-const SUBCOMMANDS = new Set(['generate', 'check', 'rules', 'setup', 'stop-hook', 'plugin-spec']);
+import { runAuth } from '../lib/auth.js';
+
+const SUBCOMMANDS = new Set([
+  'generate',
+  'check',
+  'rules',
+  'setup',
+  'auth',
+  'stop-hook',
+  'plugin-spec',
+]);
 
 function requireOptionValue(args, index, flags) {
   const value = args[index + 1];
@@ -146,11 +155,15 @@ function parseSetupOptions(args) {
  * and exit 0, handing non-JSON stdout to a caller that asked for JSON.
  */
 function parseRulesOptions(args) {
-  const options = { format: 'text' };
+  const options = { format: 'text', help: false };
   const FORMATS = new Set(['text', 'json']);
 
   for (let i = 0; i < args.length; i += 1) {
     const arg = args[i];
+    if (arg === '-h' || arg === '--help') {
+      options.help = true;
+      continue;
+    }
     if (arg === '--format') {
       const value = requireOptionValue(args, i, '--format');
       if (!FORMATS.has(value)) {
@@ -166,6 +179,30 @@ function parseRulesOptions(args) {
   return options;
 }
 
+/**
+ * `auth` のオプション。未知のフラグはその場で失敗させる（他のサブコマンドと同じ）。
+ * en: Unknown flags fail fast, same as the other subcommands.
+ */
+function parseAuthOptions(args) {
+  const options = { registry: null, help: false };
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === '-h' || arg === '--help') {
+      options.help = true;
+      continue;
+    }
+    if (arg === '--registry') {
+      options.registry = requireOptionValue(args, i, '--registry');
+      i += 1;
+      continue;
+    }
+    throw new Error(`Unknown option for auth: ${arg}`);
+  }
+
+  return options;
+}
+
 function showHelp() {
   console.log(`
 Sparkle Design CLI
@@ -178,6 +215,7 @@ Commands:
   check        Sparkle Design のアンチパターンを検査
   rules        現在有効なアンチパターンルールを一覧表示（プラグイン由来のものも含む）
   setup        Sparkle Design プロジェクトをセットアップ（パッケージ導入 + 初期ファイル + AI ガード + generate）
+  auth         Artifact Registry の npm registry 用アクセストークンを ~/.npmrc に書く（beta）
   stop-hook    AI assistant の Stop hook 用 internal subcommand（severity=error の findings か、
                実行に失敗して未検査のルールがあるときに exit 2 で 1 度だけ停止をブロック / 再発火は自動回避。
                warning / info はブロックせず件数の要約を stderr に出す）
@@ -189,7 +227,7 @@ Generate:
   sparkle-design-cli generate --output ./styles/design.css
   sparkle-design-cli generate -c ./config/custom.json -o ./dist/styles.css
 
-  # 単一バンドル内でランタイムにテーマ切替したい場合（--scope。詳細は README 参照）
+  # 単一バンドル内でランタイムにテーマ切替したい場合（--scope。詳細は docs/theming.md 参照）
   sparkle-design-cli generate -c ./config/sparkle.employee.json -o ./src/styles/sparkle-employee.css
   sparkle-design-cli generate -c ./config/sparkle.admin.json --scope '[data-tenant-theme="admin"]' -o ./src/styles/sparkle-admin-scope.css
 
@@ -207,6 +245,10 @@ Plugin spec:
   sparkle-design-cli plugin-spec           # アンチパターン拡張プラグインの契約仕様を出力
   sparkle-design-cli plugin-spec --list    # 現在のプロジェクトで発見されたプラグインを表示
 
+Auth (beta):
+  sparkle-design-cli auth                  # プロジェクトの .npmrc の @goodpatch:registry を対象に認証
+  sparkle-design-cli auth --registry https://asia-northeast1-npm.pkg.dev/<project>/<repository>/
+
 Setup:
   sparkle-design-cli setup                                        # フルセットアップ（推奨・新規導入時）
   sparkle-design-cli setup --assistant claude                     # Claude 向けガードも同時にセットアップ
@@ -232,8 +274,7 @@ Generate options:
                              だけを実値までリテラル化して指定セレクタの中にラップ出力する
                              （例: '[data-tenant-theme="admin"]'）。-o/--output の指定が必須。
                              --strict / --globals-path とは併用不可（グローバル CSS を
-                             パッチしないため）。詳細は README の「単一バンドルでランタイム
-                             切替する場合」を参照
+                             パッチしないため）。詳細は docs/theming.md の「ケース B」を参照
 
 sparkle.config.json の設定フィールド:
 
@@ -241,7 +282,7 @@ sparkle.config.json の設定フィールド:
   primary                    プライマリカラー (必須。blue, red, orange, yellow, purple, green, pink の
                              いずれか。未指定、またはそれ以外の値は generate 実行時にエラーになります。
                              7色にないブランドカラーを使いたい場合は extend.custom-css で
-                             --color-primary-* / --color-gray-* を再定義してください。詳細は README を参照)
+                             --color-primary-* / --color-gray-* を再定義してください。詳細は docs/config.md を参照)
   font-pro                   プロポーショナルフォント (Google Fonts の名前)
   font-mono                  モノスペースフォント (Google Fonts の名前)
   radius                     角丸設定 (必須。none, xs, sm, md, lg, xl, 2xl, 3xl のいずれか。
@@ -272,6 +313,19 @@ Check options:
                              （warning / info は報告のみで exit code に影響しない）
   --format <text|json>       出力形式 (default: text)
 
+Auth options:
+  -h, --help                 このヘルプメッセージを表示
+  --registry <url>           対象の registry（default: プロジェクトの .npmrc の @goodpatch:registry）
+
+Auth の動作:
+  1. Google の資格情報（ADC → gcloud auth print-access-token の順）からアクセストークンを取得
+     どちらも無い / 期限切れなら gcloud auth login を案内して終了
+  2. ユーザー単位の ~/.npmrc（NPM_CONFIG_USERCONFIG があればそちら）に、同じ registry の行を
+     置き換えて書く（プロジェクトの .npmrc は registry 行のみのまま、コミットできる状態を保つ）
+  3. 有効期限（約 60 分）を表示する。切れたらもう一度 auth を実行する
+  トークンは Artifact Registry（<location>-npm.pkg.dev）にだけ書き、画面には出しません。
+  refresh token などの長期クレデンシャルは gcloud の管理下に置いたままで、コピーしません。
+
 Setup options:
   -h, --help                 このヘルプメッセージを表示
   --assistant <name>         claude / codex / cursor / generic (default: generic)
@@ -407,18 +461,43 @@ async function main() {
       return;
     }
 
+    if (command === 'auth') {
+      const options = parseAuthOptions(args.slice(1));
+      if (options.help) {
+        showHelp();
+        process.exit(0);
+      }
+      await runAuth(options);
+      return;
+    }
+
     if (command === 'stop-hook') {
       // setup で各 agent の hook 設定ファイルから呼ばれる internal subcommand。
-      // 第 2 引数は lint 対象 path（setup 時に決まったもの）。option flag は未対応。
-      // en: Internal subcommand invoked by agent stop hooks. The single positional
-      // arg is the lint target path determined at setup time.
-      const target = args[1];
-      const exitCode = await runStopHook(target);
+      // 以降の引数はすべて lint 対象 path。setup が書き出す hook は 1 つだが、
+      // 利用側が `stop-hook apps/web/app apps/web/components` のように手で複数
+      // 並べている実例があり、以前は args[1] しか読まず 2 つ目以降が黙って
+      // 未検査になっていた（issue #85）。option flag は未対応なので、`-` 始まりは
+      // path として渡さず警告する。
+      // en: Forward every positional arg. Previously only the first was used, so
+      // extra paths in a hand-written hook command were silently never checked.
+      const positional = args.slice(1).filter((arg) => !arg.startsWith('-'));
+      const flags = args.slice(1).filter((arg) => arg.startsWith('-'));
+      if (flags.length > 0) {
+        console.warn(
+          `⚠️  stop-hook はオプションを受け付けません。無視します: ${flags.join(' ')} / stop-hook takes target paths only.`
+        );
+      }
+      const exitCode = await runStopHook(positional);
       process.exit(exitCode);
     }
 
     if (command === 'rules') {
-      await runRules(parseRulesOptions(args.slice(1)));
+      const options = parseRulesOptions(args.slice(1));
+      if (options.help) {
+        showHelp();
+        process.exit(0);
+      }
+      await runRules(options);
       return;
     }
 

package/docs/config.md

@@ -34,13 +34,38 @@ Figma プラグインが出力する基本4項目に加えて、プロジェク
 }
 ```
 
+## extend.globals-path
+
+Tailwind のエントリポイント CSS（`@import "tailwindcss";` を書いているファイル）のパスです。未指定なら自動検出します。CLI の `--globals-path` でも同じ指定ができ、そちらが優先されます。
+
+```json
+{
+  "primary": "blue",
+  "extend": {
+    "globals-path": "src/styles/app.css"
+  }
+}
+```
+
+指定すると次の 2 つに効きます。
+
+| 効き先                                         | 内容                                                                                                                     |
+| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `@source` と `sparkle-design.css` の import 先 | そのファイルにパッチする（**フォントの `@import` は入りません**。フォント読み込みは `SparkleHead.tsx` 側に移っています） |
+| `generate` の出力先                            | `-o/--output` 未指定なら**そのファイルと同じディレクトリ**に `sparkle-design.css` と `SparkleHead.tsx` を出す            |
+
+後者が重要です。既定の `src/app/` に固定されるのは globals-path を明示していない場合だけなので、`src/index.css` や `src/styles/app.css` 構成のプロジェクトで意図しない `src/app/` ディレクトリが増えることはありません。
+
+> [!WARNING]
+> **指定したパスが存在しない場合は `--strict` の有無に関わらず常に exit 1** です。typo に気付かないまま誤ったディレクトリを掘るより、その場で止めるほうが安全なためです。相対パスのみで、`..` を含む traversal や絶対パスは弾かれます。
+
 ## extend.fonts
 
 フォントごとにウェイトを個別指定。`extend.fonts` がない場合は `font-pro` / `font-mono` + デフォルトウェイト `[400, 700]` が使われます。`extend.fonts` が存在しても `fonts.pro` / `fonts.mono` のどちらかが未指定なら、そのスロットのみ `font-pro` / `font-mono` にフォールバックします。同じフォントファミリーが `pro` と `mono` で重複する場合、ウェイトはマージされ import は 1 行に統合されます。
 
 ## extend.source-packages
 
-既知のデザインシステムパッケージ（`sparkle-design` など）は `package.json` から**自動検出**されるので、通常は指定不要です。クライアント固有のパッケージなど自動検出の対象外を追加したいときだけ指定してください。指定分は自動検出分とマージされ、Tailwind エントリ CSS（自動検出）に `@source` ディレクティブとして挿入されます。両方とも空のときだけ `@source` を出力しません。
+既知のデザインシステムパッケージ（`sparkle-design` など）は `package.json` から**自動検出**されるので、通常は指定不要です。クライアント固有のパッケージなど自動検出の対象外を追加したいときだけ指定してください。指定分は自動検出分とマージされ、Tailwind エントリ CSS（自動検出）に `@source` ディレクティブとして挿入されます。`@source` をまったく出さないのは、**自動検出がゼロで、かつ `source-packages` キー自体を書いていない**ときだけです（キーがあれば空配列でも既定の `sparkle-design` 1 行が出ます）。
 
 ## extend.custom-css
 
@@ -50,7 +75,7 @@ Figma プラグインが出力する基本4項目に加えて、プロジェク
 
 ### カスタムブランドカラーを primary にしたい場合
 
-`primary` は 7 色のいずれかしか受け付けません（前述の Core セクション参照）。7 色にないブランドカラーを使いたい場合は、`primary` は 7 色から見た目が近いものを仮に選んだ上で、`extend.custom-css` で `--color-primary-*` と `--color-gray-*` をブランドカラー基準の値で丸ごと再定義してください。`primary` の選択自体は `custom-css` 側の定義で完全に上書きされるため実質的な意味を持たなくなりますが、フィールドとしては有効な値を入れておく必要があります。
+`primary` は 7 色のいずれかしか受け付けません（[README の「設定オプション」](../README.md#設定オプション) を参照）。7 色にないブランドカラーを使いたい場合は、`primary` は 7 色から見た目が近いものを仮に選んだ上で、`extend.custom-css` で `--color-primary-*` と `--color-gray-*` をブランドカラー基準の値で丸ごと再定義してください。`primary` の選択自体は `custom-css` 側の定義で完全に上書きされるため実質的な意味を持たなくなりますが、フィールドとしては有効な値を入れておく必要があります。
 
 ```css
 /* custom-tokens.css */

package/lib/anti-pattern-rules.js

@@ -4,8 +4,10 @@ import {
   buildLegacyCssVarPattern,
   buildLegacyScalePattern,
   buildLegacyTokenPattern,
+  buildTailwindPalettePattern,
   resolveLegacyCssVar,
   resolveLegacyUtility,
+  resolveTailwindPaletteUtility,
 } from './token-migration.js';
 import { buildSpacingUtilityPattern, pxToStep, resolveSpacingStep } from './spacing-scale.js';
 
@@ -378,7 +380,10 @@ const COMPONENT_ANTI_PATTERN_GROUPS = [
       description: 'shadcn/ui 既定 token を Sparkle Design 内へ持ち込まない',
       recommendation:
         'text-muted-foreground / bg-background / border-border などは Sparkle Design token に置き換えてください。',
-      pattern: /\b(text-muted-foreground|bg-background|border-border)\b/g,
+      // 新セマンティックトークン（border-border-neutral-* 等）へ前方一致しないよう、
+      // 直後にハイフン／単語構成文字が続くケースを除外する
+      // en: exclude prefix matches against new semantic tokens (e.g. border-border-neutral-*)
+      pattern: /\b(text-muted-foreground|bg-background|border-border)(?![\w-])/g,
     },
     featureSection: lines([
       '### shadcn/ui 由来の class / token をそのまま使わない',
@@ -1013,8 +1018,17 @@ const COMPONENT_ANTI_PATTERN_GROUPS = [
     check: {
       description: 'Tailwind デフォルト typography を Sparkle Design コンポーネント内で使わない',
       recommendation:
-        'text-sm / text-xs / text-base / font-medium / font-semibold / font-bold は character-* utility に置き換えてください。ただし character-* に対応する token が無いサイズ（text-[10px] 等の arbitrary value、あるいは意図的に token 外のサイズを使う場合）は、同一行または直前行に `// sparkle-disable-line tailwind-typography` コメントを付けて例外扱いとして残すこともできます。font-medium(500) / font-semibold(600) は character-* に対応する token が無いため、`extend.custom-css` で独自クラスを定義してください（詳細は README の「character-* に無いウェイトを使いたい場合」参照）。',
-      pattern: /\b(text-(?:xs|sm|base|lg|xl|2xl)|font-(?:medium|semibold|bold|normal|light))\b/g,
+        'text-xs 〜 text-9xl / font-medium / font-semibold / font-bold は character-* utility に置き換えてください。ただし character-* に対応する token が無いサイズ（text-[10px] 等の arbitrary value、あるいは意図的に token 外のサイズを使う場合）は、同一行または直前行に `// sparkle-disable-line tailwind-typography` コメントを付けて例外扱いとして残すこともできます。font-medium(500) / font-semibold(600) は character-* に対応する token が無いため、`extend.custom-css` で独自クラスを定義してください（詳細は README の「character-* に無いウェイトを使いたい場合」参照）。',
+      // text-base は旧カラートークンの text-base-50 〜 text-base-900 へ前方一致するため、
+      // shadcn-token と同様に直後のハイフン／単語構成文字を除外する
+      // en: exclude prefix matches such as text-base-900 (legacy color token)
+      //
+      // `2xl` までしか見ておらず text-3xl 以上が漏れていた（issue #84）。見出しほど
+      // 大きいサイズを使うので、抜けていた側のほうが目立つ誤りだった。Tailwind の
+      // 既定スケールは text-9xl まで。
+      // en: Sizes above 2xl were missed entirely; Tailwind's scale goes to 9xl.
+      pattern:
+        /\b(text-(?:xs|sm|base|lg|xl|[2-9]xl)|font-(?:medium|semibold|bold|normal|light))(?![\w-])/g,
     },
     featureSection: lines([
       '### Tailwind デフォルト typography を使わない',
@@ -1402,6 +1416,70 @@ function migrationMatcher(pattern, resolve, label) {
   };
 }
 
+const TAILWIND_PALETTE_PATTERN = buildTailwindPalettePattern();
+
+/**
+ * そのファイルが Sparkle Design を使っているか判定する材料。
+ *
+ * Tailwind 既定パレットの色は「Sparkle を導入したプロジェクトなのに色だけ移行が
+ * 取り残されている」箇所を拾うためのルールなので、Sparkle と無関係なファイル
+ * （素の React コード、管理用スクリプト、vendored なコード）まで報告すると
+ * ノイズになる（issue #84）。
+ *
+ * 2 つの材料を見る:
+ *   1. Sparkle パッケージからの import — `sparkle-design` / `@goodpatch/sparkle-design-internal`
+ *      のほか、`sparkle-design/components/...` のようなサブパスも拾えるよう部分一致にする
+ *   2. `character-*` typography の使用 — Sparkle 固有のユーティリティで、
+ *      **これが使われている時点でそのファイルは Sparkle に載っている**。
+ *      issue #84 の実例はまさに「typography は character-* に移行済みなのに色だけ
+ *      Tailwind 既定パレットのまま」という形で、import 判定だけだと
+ *      re-export 経由（`@/components/ui/...`）のファイルを取りこぼす
+ *
+ * en: Gate the rule to files that actually use Sparkle — either an import from a
+ * Sparkle package, or a `character-*` utility (Sparkle-specific, and the exact
+ * signal in issue #84 where typography had migrated but colours had not).
+ */
+const SPARKLE_USAGE_PATTERNS = [
+  /\b(?:from|import)\s*\(?\s*['"][^'"]*sparkle-design[^'"]*['"]/,
+  /\brequire\(\s*['"][^'"]*sparkle-design[^'"]*['"]\s*\)/,
+  /(?<![\w-])character-\d/,
+];
+
+function usesSparkle(content) {
+  return SPARKLE_USAGE_PATTERNS.some((pattern) => pattern.test(content));
+}
+
+/**
+ * Tailwind 既定パレットの色ユーティリティを拾う。
+ *
+ * `shadcn-token` の説明文は Tailwind パレット色（`text-slate-500`）も Wrong として
+ * 示していたのに、実際の `check.pattern` は shadcn 由来の 3 語しか見ていなかった。
+ * 「説明が禁止しているものを検査が拾っていない」状態を解消する（issue #84）。
+ *
+ * 生の hex（`#6b7280`）は**検出しない**。SVG・チャート描画・ユーザー定義色など、
+ * 移行対象ではない動的な用途が大半を占めるため（報告元のプロジェクトでは 43 件中
+ * 32 件がこれ）、ルール化すると偽陽性で埋まる。
+ * en: Raw hex values are intentionally out of scope — most of them are dynamic
+ * (SVG, charts, user-defined colours) and would drown the report in false positives.
+ *
+ * `targets` を指定していないので対象はソースファイルのみ。`legacy-color-token` が
+ * `.css` も見るのに対し、こちらは `@apply` を拾わない。CSS には import が無く、
+ * `usesSparkle` の 2 材料のうち `character-*` しか効かないため、対象に加えると
+ * 「CSS の一部だけ検査される」という説明しにくい半端なカバレッジになる。
+ * **意図的な線引きなので、featureSection と description に明記してある。**
+ * en: Source files only. CSS has no imports, so the Sparkle gate would work only
+ * half the time there — an unexplainable partial coverage. The limitation is
+ * stated in the rule's description and feature section rather than left implicit.
+ */
+function tailwindPaletteMatcher(rawContent) {
+  if (!usesSparkle(maskBlockComments(rawContent))) return [];
+  return migrationMatcher(
+    TAILWIND_PALETTE_PATTERN,
+    resolveTailwindPaletteUtility,
+    'Tailwind 既定パレットの色'
+  )(rawContent);
+}
+
 const SPACING_UTILITY_PATTERN = buildSpacingUtilityPattern();
 
 /**
@@ -1505,6 +1583,61 @@ const TOKEN_MIGRATION_GROUPS = [
     ]),
     jsdocTargets: [],
   },
+  {
+    id: 'tailwind-palette-color',
+    check: {
+      severity: SEVERITY.WARNING,
+      description:
+        'Tailwind 既定パレットの色ユーティリティを使っています（Sparkle のセマンティックトークンに置き換えます）',
+      recommendation:
+        'text-gray-* / bg-slate-* / border-red-* のような Tailwind 既定パレットの色は、用途別セマンティックトークン（bg- → surface / text- → text / border- → border / fill- → object）に置き換えてください。検査対象はソースファイルのみで、.css の @apply と生の hex 値は見ていません。',
+      match: tailwindPaletteMatcher,
+    },
+    featureSection: lines([
+      '### Tailwind 既定パレットの色をそのまま使わない',
+      '',
+      '```tsx',
+      '// ✅ Correct — 用途別セマンティックトークンを使う',
+      '<main className="bg-surface-base-100">',
+      '  <h1 className="character-6-bold-pro text-text-negative-enabled">認証エラー</h1>',
+      '</main>',
+      '',
+      '// ❌ Wrong — Tailwind 既定パレットの色を直接指定する',
+      '<main className="bg-gray-50">',
+      '  <h1 className="character-6-bold-pro text-red-600">認証エラー</h1>',
+      '</main>',
+      '```',
+      '',
+      'Sparkle のプリミティブは Tailwind の同名変数をそのまま参照しているため',
+      '（`--color-negative-600: var(--color-red-600)`）、`gray` / `red` / `green` / `yellow` / `blue`',
+      'の 5 系統は**置き換えても値が変わらない**。それ以外（`slate` / `zinc` / `emerald` …）は',
+      '色味が変わるので、移行先は候補として提示するだけで自動変換はしない。',
+      '',
+      '| if（状況） | then（移行先） |',
+      '|---|---|',
+      '| 背景に `bg-gray-100` | `bg-surface-base-100`（ページ地の専用トークン） |',
+      '| 文字色に `text-red-600` | `text-text-negative-enabled` |',
+      '| 枠線に `border-gray-200` | `border-border-neutral-*` |',
+      '| アイコン色に `fill-red-600` | `fill-object-negative-enabled` |',
+      '| `bg-blue-600` | ブランド色なら `surface-primary-*`、状態表示なら `surface-info-*`。**Figma を見て決める** |',
+      '| `text-purple-500` など対応する意味が無い色 | 用途から選び直す。装飾用の面なら `bg-surface-accent-1` 〜 `3` |',
+      '',
+      '`surface-base-*` は `0` / `100` / `200` の 3 段しか無い。`bg-gray-50` のように対応する',
+      '段が無いレベルは `surface-neutral-*` 側に案内される。**移行先は check の出力に従うこと**',
+      '（この表は用途の考え方を示すもので、レベルごとの対応はコマンドが出す）。',
+      '',
+      '`text-neutral-*` は Sparkle の旧セマンティック層と同名なので、このルールではなく',
+      '`legacy-color-token` が扱う（同じ箇所を二重に報告しないため）。',
+      '',
+      'このルールは **Sparkle を使っているファイルにだけ**適用される（Sparkle からの import か',
+      '`character-*` の使用がある場合）。素の React コードや、Sparkle と無関係なユーティリティは対象外。',
+      '',
+      '検査対象は `.js` / `.jsx` / `.ts` / `.tsx` のみで、**`.css` の `@apply` は見ていない**',
+      '（`legacy-color-token` は `.css` も見るので、そちらとは対象範囲が違う）。CSS 側に',
+      'Tailwind 既定パレットの色が残っていないかは手で確認すること。',
+    ]),
+    jsdocTargets: [],
+  },
   {
     id: 'legacy-color-var',
     check: {
@@ -1635,6 +1768,7 @@ const BUILTIN_CHECK_ORDER = [
   // en: This only orders rule *evaluation*. Report ordering is by severity in
   // check.js — don't read this list as a display-order guarantee.
   'legacy-color-token',
+  'tailwind-palette-color',
   'legacy-color-var',
   'deprecated-radius-alias',
   'use-figma-spacing-scale',