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

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

@@ -94,7 +94,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 +125,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 + 継続で後方互換を維持）:
@@ -274,7 +274,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 +283,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

@@ -146,11 +146,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)) {
@@ -189,7 +193,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
 
@@ -232,8 +236,7 @@ Generate options:
                              だけを実値までリテラル化して指定セレクタの中にラップ出力する
                              （例: '[data-tenant-theme="admin"]'）。-o/--output の指定が必須。
                              --strict / --globals-path とは併用不可（グローバル CSS を
-                             パッチしないため）。詳細は README の「単一バンドルでランタイム
-                             切替する場合」を参照
+                             パッチしないため）。詳細は docs/theming.md の「ケース B」を参照
 
 sparkle.config.json の設定フィールド:
 
@@ -241,7 +244,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 のいずれか。
@@ -409,16 +412,31 @@ async function main() {
 
     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',

package/lib/check.js

@@ -16,7 +16,9 @@ import { loadAntiPatternPlugins } from './load-plugins.js';
 import { MATCH_HELPERS } from './plugin-helpers.js';
 import { REGEX, FONT_DOMAINS } from './constants.js';
 
-const DEFAULT_TARGET = 'src';
+// stop-hook 側も「target 未指定時の既定」を知る必要があるので export する。
+// en: Exported so stop-hook can probe with the same default instead of hardcoding it.
+export const DEFAULT_TARGET = 'src';
 const TEXT_EXTENSIONS = new Set(['.js', '.jsx', '.ts', '.tsx']);
 const CSS_EXTENSIONS = new Set(['.css']);
 
@@ -101,9 +103,28 @@ function toRelativeReportPath(filePath) {
 /**
  * ディレクトリを1回だけ走査し、テキストファイルと CSS ファイルを同時に収集する
  */
-function collectFiles(targetPath, textFiles, cssFiles, visited) {
+function collectFiles(targetPath, textFiles, cssFiles, visited, isUserTarget = false) {
   if (!fs.existsSync(targetPath)) {
-    throw new Error(`Target path does not exist: ${targetPath}`);
+    // cwd の案内を出してよいのは、ユーザーが渡した target を解決した 1 回目だけ。
+    // 再帰の途中で欠けるのは壊れた symlink や走査中の削除で、パスは既に絶対だから
+    // cwd は無関係。そこで「作業ディレクトリを確認してください」と言うと、
+    // 存在しない原因を追わせることになる。
+    // en: Only the user-supplied target can be a cwd problem. Deeper misses come
+    // from broken symlinks or concurrent deletion and are already absolute, so
+    // blaming cwd there sends the reader after a cause that does not exist.
+    if (!isUserTarget) {
+      throw new Error(
+        `Target path does not exist: ${targetPath}\n` +
+          `   走査中にパスが解決できませんでした（壊れた symlink か、走査中に削除された可能性があります）。` +
+          ` / Could not resolve this path while walking the tree (broken symlink or concurrent deletion).`
+      );
+    }
+    throw new Error(
+      `Target path does not exist: ${targetPath}\n` +
+        `   相対 path は現在の作業ディレクトリ（${process.cwd()}）基準で解決しています。` +
+        `別のディレクトリから実行していないか確認してください。` +
+        ` / Relative targets resolve against the current working directory.`
+    );
   }
 
   const realPath = fs.realpathSync(targetPath);
@@ -394,7 +415,7 @@ function createCheckReport(targets = [], options = {}) {
 
   // 1回のディレクトリ走査でテキストファイルと CSS ファイルを同時に収集
   for (const target of resolvedTargets) {
-    collectFiles(path.resolve(process.cwd(), target), textFiles, cssFiles, visited);
+    collectFiles(path.resolve(process.cwd(), target), textFiles, cssFiles, visited, true);
   }
 
   const checkedFiles = [...textFiles, ...cssFiles]

package/lib/load-plugins.js

@@ -113,6 +113,12 @@ export async function loadAntiPatternPlugins({ cwd = process.cwd() } = {}) {
       validatePluginShape(candidate, `${packageName} (${entry})`);
       groups.push(...candidate.groups);
       record.groupIds = candidate.groups.map((group) => group.id);
+      // group の**実体**も持たせる。ID だけだと、別プラグインが同じ group ID を
+      // 宣言したときに所有者を復元できない（plugin-api は ID の名前空間が
+      // ビルトインとも他プラグインとも共有されると明記している）。
+      // en: Keep the group objects, not just ids — ids are not unique across
+      // plugins, so ownership can't be reconstructed from them afterwards.
+      record.groups = candidate.groups;
       if (Array.isArray(candidate.manualReviewReminders)) {
         reminders.push(...candidate.manualReviewReminders);
       }

package/lib/path-utils.js

@@ -1,3 +1,4 @@
+import fs from 'fs';
 import path from 'path';
 
 // setup.js 側と共通の「unsafe な shell メタ文字や quote」を弾く pattern。
@@ -64,3 +65,122 @@ export function assertSafeRelativePath(inputPath, label) {
   }
   return normalized;
 }
+
+/**
+ * 相対 target を解決する基準ディレクトリの**候補**を、優先順に列挙する。
+ *
+ * 1. `startDir`（＝通常は cwd）… 従来の挙動。ここで解決できるなら何も変えない
+ * 2. `CLAUDE_PROJECT_DIR` … Claude Code が hook 実行時に渡す絶対 path
+ * 3. `sparkle.config.json` を持つ祖先（近い順）… CLI 自身の設定ファイル
+ * 4. `package.json` を持つ祖先（近い順）… monorepo では workspace → repo root の順
+ *
+ * monorepo で「最も近い package.json」だけを見ると、cwd が `apps/web` のときに
+ * 基準も `apps/web` になり、hook に書かれた `apps/web/app` が二重化するという
+ * issue #85 と同じ壊れ方を再現してしまう。だから 1 つに決め打たず、repo root まで
+ * 含めて候補を並べ、呼び出し側が「target が実在するか」で選べるようにする。
+ *
+ * en: Enumerate candidate base directories in priority order. Picking a single
+ * "project root" is not enough: in a monorepo the nearest package.json is the
+ * workspace package, which reproduces the very bug this is meant to fix.
+ *
+ * @param {string} [startDir]
+ * @param {{ existsSync?: (p: string) => boolean, env?: Record<string, string> }} [deps]
+ * @returns {Array<{ dir: string, source: string }>} 重複を除いた候補（優先順）
+ */
+export function projectRootCandidates(startDir = process.cwd(), deps = {}) {
+  const exists = deps.existsSync ?? fs.existsSync;
+  const env = deps.env ?? process.env;
+  const candidates = [{ dir: path.resolve(startDir), source: 'cwd' }];
+
+  const fromEnv = env.CLAUDE_PROJECT_DIR;
+  if (typeof fromEnv === 'string' && fromEnv.trim() && exists(fromEnv)) {
+    candidates.push({ dir: path.resolve(fromEnv), source: 'CLAUDE_PROJECT_DIR' });
+  }
+
+  for (const marker of PROJECT_ROOT_MARKERS) {
+    for (const dir of ancestorsContaining(path.resolve(startDir), marker, exists)) {
+      candidates.push({ dir, source: marker });
+    }
+  }
+
+  const seen = new Set();
+  return candidates.filter(({ dir }) => {
+    if (seen.has(dir)) return false;
+    seen.add(dir);
+    return true;
+  });
+}
+
+/**
+ * `targets` がすべて実在する最初の候補ディレクトリを選ぶ。
+ *
+ * hook は AI の作業途中に発火するため、実行時の cwd を前提にできない。AI が調査で
+ * `cd apps/web` したまま戻していないと `apps/web/app` が `apps/web/apps/web/app` に
+ * 解決されて落ちる（issue #85）。候補を順に当てて実在するものを採れば、配布済みの
+ * `.claude/settings.json` を書き換えずに直る。
+ *
+ * cwd を最優先に置いているので、**今まで動いていた呼び出しの挙動は一切変わらない**。
+ * どの候補でも解決できないときも cwd を返し、エラーメッセージは呼び出し側
+ * （`check` の "Target path does not exist"）に任せる。
+ *
+ * en: Pick the first candidate base where every target exists. cwd comes first,
+ * so anything that already worked keeps working; the fallback only kicks in for
+ * the broken case this exists to fix.
+ *
+ * @param {string[]} targets 相対 path の配列（空なら cwd を返す）
+ * @param {{ startDir?: string, existsSync?: (p: string) => boolean, env?: Record<string, string> }} [options]
+ * @returns {{ dir: string, source: string, resolved: boolean }}
+ */
+export function resolveTargetBaseDir(targets, options = {}) {
+  const startDir = path.resolve(options.startDir ?? process.cwd());
+  const exists = options.existsSync ?? fs.existsSync;
+  const fallback = { dir: startDir, source: 'cwd', resolved: false };
+
+  if (!Array.isArray(targets) || targets.length === 0) return fallback;
+
+  for (const candidate of projectRootCandidates(startDir, options)) {
+    if (targets.every((target) => exists(path.resolve(candidate.dir, target)))) {
+      return { ...candidate, resolved: true };
+    }
+  }
+
+  return fallback;
+}
+
+const PROJECT_ROOT_MARKERS = ['sparkle.config.json', 'package.json'];
+
+// 探索を止める境界。ここより上は「別のプロジェクト」とみなす。
+//
+// 境界を設けないと、プロジェクトが別の `package.json` を持つディレクトリの下に
+// 置かれている場合（`/workspace/package.json` の下に `/workspace/project/`）、
+// **target 名を打ち間違えたときに外側の同名 path が拾われて、無関係なファイルを
+// 黙って検査する**。「target が無い」と報告されるべき場面で静かに別の場所を見る
+// のは、このルール一式が防ごうとしている silent failure そのもの。
+//
+// git worktree では `.git` がファイル（`gitdir:` を書いた 1 行）になるが、
+// `existsSync` はどちらでも true を返すので同じく境界として機能する。
+// en: Bound the walk at the repository root. Without it, a typo'd target could
+// resolve against an unrelated outer project and be checked silently.
+const REPOSITORY_BOUNDARY = '.git';
+
+/**
+ * `startDir` から root 方向へ辿り、`marker` を含むディレクトリを近い順に返す。
+ * リポジトリ境界（`.git`）を含むディレクトリまで見たら、そこで打ち切る。
+ * en: All ancestors (nearest first) that contain marker, stopping at the repo root.
+ */
+function ancestorsContaining(startDir, marker, exists) {
+  const found = [];
+  let current = startDir;
+  // path.dirname('/') === '/' なので、変化しなくなった時点が終端。
+  // en: dirname stops changing at the filesystem root — that's the loop guard.
+  for (;;) {
+    if (exists(path.join(current, marker))) found.push(current);
+    // 境界ディレクトリ自身は候補に含めてから打ち切る（repo root がまさに
+    // 探している基準であることが多いため）。
+    // en: Include the boundary directory itself, then stop.
+    if (exists(path.join(current, REPOSITORY_BOUNDARY))) return found;
+    const parent = path.dirname(current);
+    if (parent === current) return found;
+    current = parent;
+  }
+}

package/lib/rules-report.js

@@ -27,6 +27,9 @@ import {
 } from './anti-pattern-rules.js';
 import { loadAntiPatternPlugins } from './load-plugins.js';
 
+/** 利用者の手元に `docs/` は無いので、案内は解決できる場所を指す。 */
+const DOCS_URL = 'https://github.com/goodpatch/sparkle-design-cli/blob/main/docs';
+
 /** 表示順。`check` のレポートと同じ「重いものが先」に揃える。 */
 const SEVERITY_ORDER = [SEVERITY.ERROR, SEVERITY.WARNING, SEVERITY.INFO];
 
@@ -74,7 +77,24 @@ export async function collectActiveRules(options = {}) {
     ...getCheckRules(pluginGroups).map(shape('plugin')),
   ];
 
-  return { rules, plugins: discovered };
+  // 各プラグインが実際に出した rule は、**そのプラグインの group から直接**求める。
+  // 「全 rule の中に同じ id があるか」で絞ると、`check` を持たない group の id が
+  // 組み込みや別プラグインの rule id と衝突したときに、そのプラグインが所有して
+  // いない ID を並べてしまう（`check` は plugin-api で optional なので実際に起きる）。
+  // en: Derive each plugin's rule ids from its own groups. Matching against the
+  // merged list would attribute a built-in (or another plugin's) rule to a plugin
+  // whose `check`-less group merely reuses that id.
+  // 所有関係はローダーが持つ `record.groups`（group の実体）から取る。
+  // ID で引き直すと、別プラグインが同じ group ID を宣言したときに互いの分まで
+  // 拾ってしまう（実測で両方が 2 件ずつ持つ状態になった）。
+  // en: Ownership comes from the loader's group objects. Re-deriving it from ids
+  // credits each plugin with the other's rules when two declare the same id.
+  const plugins = discovered.map((record) => ({
+    ...record,
+    ruleIds: getCheckRules(record.groups ?? []).map((rule) => rule.id),
+  }));
+
+  return { rules, plugins };
 }
 
 function severityRank(severity) {
@@ -116,7 +136,11 @@ export function renderRulesJson({ rules, plugins }) {
         packageName: record.packageName,
         status: record.status,
         error: record.error ?? null,
-        ruleIds: record.groupIds ?? [],
+        // `ruleIds` は collectActiveRules がプラグインごとに算出したもの
+        // （`check` を持つ group だけ）。`groupIds` は宣言した group 全部。
+        // en: `ruleIds` counts only groups that actually define a check.
+        ruleIds: record.ruleIds ?? [],
+        groupIds: record.groupIds ?? [],
       })),
     },
     null,
@@ -151,11 +175,17 @@ export function renderRulesText({ rules, plugins }) {
     ),
   ];
   if (clashes.length > 0) {
+    // 衝突は「組み込み × プラグイン」だけでなく「プラグイン同士」でも起きる
+    // （plugin-api が名前空間を共有すると明記している）。source を見ずに
+    // 「組み込みと同じ」と決め打つと、後者で嘘の案内になる。
+    // en: Clashes also happen plugin-vs-plugin; don't assume a built-in is involved.
     lines.push('');
-    lines.push(`⚠️  組み込みと同じ ID を名乗るプラグインルールがあります: ${clashes.join(', ')}`);
-    lines.push(
-      '    どちらも実行されます。指摘の出所が分からなくなるので、プラグイン側の ID を変えてください。'
-    );
+    for (const id of clashes) {
+      const sources = rules.filter((rule) => rule.id === id).map((rule) => rule.source);
+      const kind = sources.includes('builtin') ? '組み込みと同じ ID' : 'プラグイン同士で同じ ID';
+      lines.push(`⚠️  ${kind}のルールがあります: ${id}（${sources.join(' + ')}）`);
+    }
+    lines.push('    どちらも実行されます。指摘の出所が分からなくなるので ID を変えてください。');
   }
 
   lines.push('');
@@ -169,7 +199,12 @@ export function renderRulesText({ rules, plugins }) {
     }
   }
   lines.push('');
-  lines.push('個別ルールの背景と対処は docs/anti-patterns.md を参照してください。');
+  // 利用者の cwd に `docs/` は無い。npm 同梱の実体か GitHub を指す。
+  // en: `docs/` doesn't exist in the consumer's cwd — point at the real locations.
+  lines.push(
+    `個別ルールの背景と対処: ${DOCS_URL}/anti-patterns.md` +
+      '（npm 経由なら node_modules/sparkle-design-cli/docs/anti-patterns.md）'
+  );
   lines.push('抑制するには `sparkle-disable-next-line <rule-id>` を使います。');
 
   return lines.join('\n');

package/lib/stop-hook.js

@@ -1,5 +1,7 @@
 import fs from 'fs';
-import { countBySeverity, runCheck } from './check.js';
+
+import { DEFAULT_TARGET, countBySeverity, runCheck } from './check.js';
+import { resolveTargetBaseDir } from './path-utils.js';
 
 /**
  * AI assistant の Stop / stop hook 用エントリポイント。
@@ -14,10 +16,21 @@ import { countBySeverity, runCheck } from './check.js';
  * 抜ける。これで「最初の 1 回だけ exit 2 で停止をブロックして findings
  * を通知し、以降はユーザーの判断に委ねる」フローになる。
  *
+ * 相対 path は cwd で解決できなければ**プロジェクトルート基準で解決し直す**。
+ * hook は AI の作業途中に発火するため、AI が調査で `cd` したまま戻していない
+ * ケースが普通に起きる（issue #85）。cwd を最優先で試すので、今まで動いていた
+ * 呼び出しの挙動は変わらない。`check` サブコマンドは人間が直接叩くものなので
+ * 従来どおり cwd 基準のみで、この救済は stop-hook 限定。
+ *
  * en: Run `check --strict` once per session to surface findings, but stop
  * blocking on subsequent invocations within the same Stop hook chain.
  * Claude Code sets `stop_hook_active: true` on re-fires so the hook can
  * exit cleanly instead of looping forever (see Claude Code hooks docs).
+ * Relative targets fall back to the project root when cwd cannot resolve them,
+ * because hooks fire mid-session when the shell may sit in a subdirectory.
+ *
+ * @param {string | string[]} [target] lint 対象 path（複数可）
+ * @returns {Promise<0 | 2>} hook の exit code
  */
 export async function runStopHook(target) {
   const payload = readStdinJsonSafely();
@@ -31,8 +44,20 @@ export async function runStopHook(target) {
     return 0;
   }
 
-  const targets = target ? [target] : [];
-  const { report, blocked } = await runCheck(targets, { strict: true, format: 'text' });
+  const targets = normalizeTargets(target);
+  const restoreCwd = enterTargetBaseDir(targets);
+
+  let result;
+  try {
+    result = await runCheck(targets, { strict: true, format: 'text' });
+  } finally {
+    // check が throw しても cwd は必ず戻す。runStopHook は bin から呼ばれて
+    // すぐ process.exit する経路が主だが、テストや将来の埋め込み利用で
+    // プロセスが生き続ける場合に cwd を汚したままにしない。
+    // en: Always restore cwd, even when the check throws.
+    restoreCwd();
+  }
+  const { report, blocked } = result;
 
   if (blocked) {
     // ブロック理由は「error の findings」と「実行に失敗して未検査のルール」の
@@ -84,6 +109,94 @@ export async function runStopHook(target) {
   return 0;
 }
 
+/**
+ * hook に渡された lint 対象を配列に正規化する。
+ *
+ * 2.5.0-beta.1 までは `bin/sparkle-design.js` が `args[1]` しか渡しておらず、
+ * 実運用で見られる `stop-hook apps/web/app apps/web/components` の**2つ目以降が
+ * 黙って未検査**になっていた（issue #85 の調査で判明）。無指定なら `runCheck`
+ * 側の既定 target（`src`）に委ねるので、空配列をそのまま返す。
+ *
+ * en: Accept multiple targets. Before this, only the first positional arg was
+ * forwarded, so extra paths in a hook command were silently never checked.
+ */
+function normalizeTargets(target) {
+  const list = Array.isArray(target) ? target : [target];
+  return list
+    .filter((value) => typeof value === 'string' && value.trim())
+    .map((value) => value.trim());
+}
+
+/**
+ * target が実在する基準ディレクトリへ `chdir` し、元に戻す関数を返す。
+ *
+ * target path だけを解決し直すのでは足りない。`check` は cwd に依存する処理を
+ * 他にも持っているので、target だけずらすとそれらが元の cwd を見たままになる。
+ *
+ *   - **アンチパターンプラグインの discovery**（`loadAntiPatternPlugins` が
+ *     `cwd/package.json` の `sparkleCli.antiPatterns` を読む）。ここがずれると
+ *     「target は repo root のファイルを見ているのに、有効なルールは apps/web 基準」
+ *     という、**検査したのに一部のルールが効いていない**状態になる
+ *   - Next.js の CSP 設定検出（`cwd` から `next.config.*` を探す）
+ *   - レポートの相対 path 表示（`path.relative(process.cwd(), ...)`）
+ *
+ * cwd ごと合わせるのが最も整合的。
+ *
+ * `resolveTargetBaseDir` は cwd を最優先で試すので、**今まで通り動いていたケースは
+ * chdir されず挙動が変わらない**。移動したときだけ stderr に 1 行出す。黙って別の
+ * ディレクトリを検査していると、findings の差分を追うときに原因が分からなくなる。
+ *
+ * `process.chdir()` はプロセス全体の状態なので、**1 プロセスにつき 1 回だけ
+ * `runStopHook` を呼ぶ**ことが前提。`bin/sparkle-design.js` は subcommand を 1 つ
+ * 処理して `process.exit` するのでこの前提は満たされている。将来 `runStopHook` を
+ * ライブラリとして並行に呼ぶ用途が出たら、cwd を動かさずに基準ディレクトリを
+ * `runCheck` へ引数で渡す形（`check` 側の cwd 依存を全部剥がす）に作り替えること。
+ *
+ * en: chdir to the base where the targets actually exist, rather than only
+ * rebasing target paths — the check pipeline reads config, CSP settings and
+ * report paths from cwd too. cwd is tried first, so working setups don't move.
+ * chdir is process-global, so this assumes one runStopHook per process — true
+ * for the CLI, which exits right after. Concurrent library use would need the
+ * base directory threaded through runCheck instead.
+ */
+function enterTargetBaseDir(targets) {
+  const originalCwd = process.cwd();
+  // target 未指定なら check 側の既定 target で探る。ここで `src` を決め打ちすると
+  // 既定が変わったときに静かにズレるので、check.js の定数をそのまま使う。
+  // en: Probe with check's own default target instead of hardcoding 'src'.
+  const probe = targets.length > 0 ? targets : [DEFAULT_TARGET];
+  const { dir, source, resolved } = resolveTargetBaseDir(probe, { startDir: originalCwd });
+
+  if (!resolved || dir === originalCwd) return () => {};
+
+  try {
+    process.chdir(dir);
+  } catch (error) {
+    // chdir に失敗しても検査自体は続ける価値がある（従来どおり cwd 基準）。
+    // en: Fall back to cwd-relative behaviour instead of aborting the check.
+    process.stderr.write(
+      `sparkle-design-cli stop-hook: ${dir} へ移動できなかったため cwd 基準で検査します (${error.code ?? error.message})` +
+        ` / Could not chdir to the resolved base dir; falling back to cwd.\n`
+    );
+    return () => {};
+  }
+
+  process.stderr.write(
+    `sparkle-design-cli stop-hook: 実行時の cwd (${originalCwd}) では ${probe.join(' / ')} が見つからないため、` +
+      `${dir} 基準で検査します（${source} から判定）。` +
+      ` / Resolved relative targets against ${dir} instead of cwd.\n`
+  );
+
+  return () => {
+    try {
+      process.chdir(originalCwd);
+    } catch {
+      // 元の cwd が消えている場合まで面倒は見ない。
+      // en: Ignore — the original cwd may no longer exist.
+    }
+  };
+}
+
 function readStdinJsonSafely() {
   // stdin が tty / 空 / 非 JSON の場合は「初回呼び出し」として扱う。
   // en: Treat missing or non-JSON stdin as a first invocation.

package/lib/token-migration.js

@@ -606,6 +606,216 @@ export function buildLegacyCssVarPattern() {
   );
 }
 
+// --- Tailwind 既定パレット -> Sparkle セマンティックトークン ------------------
+
+/**
+ * Tailwind 既定パレットのファミリー → Sparkle の意味ファミリー。
+ *
+ * Sparkle のプリミティブは Tailwind の同名変数をそのまま参照している
+ * （`--color-neutral-600: var(--color-gray-600)` / `--color-negative-600:
+ * var(--color-red-600)` など）。そのため `gray` / `red` / `green` / `yellow` /
+ * `blue` の 5 系統は**値が完全に一致する**ので、置き換えても見た目が変わらない。
+ * それ以外（`slate` / `zinc` / `emerald` …）は近いだけで色味が変わるため、
+ * 自動変換可とは扱わず必ず要判断にする。
+ *
+ * - `family`: 対応する旧セマンティックファミリー。`null` は対応する意味が無い
+ * - `exact`: Sparkle のプリミティブが同じ値を指しているか
+ * - `ambiguousWith`: 用途上もう一方の意味も有力な場合（ブランド色かどうかは
+ *   コードからは判断できないため、候補を両方出して人に選ばせる）
+ *
+ * `neutral` は**意図的に載せていない**。Tailwind の既定パレットにも Sparkle の
+ * 旧セマンティック層にも同名のファミリーがあり、`text-neutral-500` は
+ * `legacy-color-token` がすでに検出する。ここにも載せると同じ箇所が 2 回報告される。
+ * en: `neutral` is deliberately absent — it collides with Sparkle's own legacy
+ * family name and is already covered by `legacy-color-token`.
+ *
+ * `gray` を `neutral` ではなく `base` に寄せているのは、`base` が「gray と同値」
+ * かつ surface では Figma 専用の `surface/base/*`（ページ地）が優先されるため。
+ * text / border / object には `base` が無いので `neutral` に自動フォールバックする
+ * （`familyScaleMap` 参照）。
+ */
+export const TAILWIND_PALETTE_FAMILIES = {
+  // 値まで一致する系統
+  gray: { family: 'base', exact: true },
+  red: { family: 'negative', exact: true },
+  green: { family: 'success', exact: true },
+  yellow: { family: 'warning', exact: true },
+  blue: { family: 'info', exact: true, ambiguousWith: 'primary' },
+  // 意味は同じだが色味が変わる系統
+  slate: { family: 'base', exact: false },
+  zinc: { family: 'base', exact: false },
+  stone: { family: 'base', exact: false },
+  rose: { family: 'negative', exact: false },
+  emerald: { family: 'success', exact: false },
+  teal: { family: 'success', exact: false },
+  lime: { family: 'success', exact: false },
+  amber: { family: 'warning', exact: false },
+  orange: { family: 'warning', exact: false },
+  sky: { family: 'info', exact: false, ambiguousWith: 'primary' },
+  cyan: { family: 'info', exact: false, ambiguousWith: 'primary' },
+  indigo: { family: 'info', exact: false, ambiguousWith: 'primary' },
+  // 対応する意味が無い系統
+  violet: { family: null },
+  purple: { family: null },
+  fuchsia: { family: null },
+  pink: { family: null },
+};
+
+/**
+ * Tailwind v4 のパレットは 950 まである。Sparkle の旧セマンティック層は 900 止まり
+ * なので、950 は機械的な対応先が無い（要判断として報告する）。
+ */
+const TAILWIND_ONLY_LEVELS = ['950'];
+const TAILWIND_PALETTE_LEVELS = [...LEGACY_LEVELS, ...TAILWIND_ONLY_LEVELS];
+
+/**
+ * `bg-gray-50` / `hover:text-red-600/50` のような Tailwind 既定パレットの
+ * 色ユーティリティを検出する正規表現。
+ *
+ * `legacy-color-token` の `buildLegacyScalePattern` と同じ境界・variant・modifier
+ * の扱いを共有する（`\b` ではなく `[\w-]` 境界を使う理由は同関数のコメント参照）。
+ */
+export function buildTailwindPalettePattern() {
+  const prefixes = alternation(Object.keys(UTILITY_PREFIX_TO_CATEGORY));
+  const families = alternation(Object.keys(TAILWIND_PALETTE_FAMILIES));
+  const levels = alternation(TAILWIND_PALETTE_LEVELS);
+  return new RegExp(
+    `${NOT_CLASS_CHAR_BEFORE}${VARIANT_CHAIN}${IMPORTANT_PREFIX}(?:${prefixes})-(?:${families})-(?:${levels})${NOT_CLASS_CHAR_AFTER}${MODIFIER_SUFFIX}`,
+    'g'
+  );
+}
+
+/**
+ * Tailwind 既定パレットのユーティリティ 1 個を解析して移行結果を返す。
+ *
+ * 旧セマンティックファミリーに読み替えてから `resolveLegacyUtility` に委譲する。
+ * 対応表・状態の絞り込み・opacity modifier の持ち回りを二重に実装せずに済み、
+ * `legacy-color-token` と同じ移行先を必ず案内できる。
+ *
+ * ただし classification は**そのまま通さない**。
+ * - 値が一致しない系統（`slate` など）は見た目が変わるので必ず `review`
+ * - `info` / `primary` のどちらとも読める系統（`blue` など）は、ブランド色かどうかが
+ *   コードから判断できないので候補を両方出して `review`
+ *
+ * en: Rewrite the Tailwind family to Sparkle's legacy family and delegate, so the
+ * mapping table, state narrowing and modifier handling are never duplicated.
+ * Classification is downgraded to `review` whenever the swap is not value-preserving
+ * or the semantic (info vs primary) cannot be decided from the code.
+ *
+ * @param {string} utility 例 `bg-gray-50` / `hover:text-red-600/50`
+ * @returns {null | { input: string, classification: string, replacement?: string, candidates?: string[], reason?: string }}
+ */
+export function resolveTailwindPaletteUtility(utility) {
+  if (typeof utility !== 'string' || utility.length === 0) return null;
+
+  const lastColon = utility.lastIndexOf(':');
+  const variantPrefix = lastColon === -1 ? '' : utility.slice(0, lastColon + 1);
+  let rawBare = lastColon === -1 ? utility : utility.slice(lastColon + 1);
+
+  const importantPrefix = rawBare.startsWith('!') ? '!' : '';
+  if (importantPrefix) rawBare = rawBare.slice(1);
+
+  const [, bare, modifier] = MODIFIER_SUFFIX_PATTERN.exec(rawBare);
+
+  const dashIndex = bare.indexOf('-');
+  if (dashIndex === -1) return null;
+  const prefix = bare.slice(0, dashIndex);
+  const rest = bare.slice(dashIndex + 1);
+  if (!UTILITY_PREFIX_TO_CATEGORY[prefix]) return null;
+
+  const scaleMatch = /^([a-z]+)-(\d{2,3})$/.exec(rest);
+  if (!scaleMatch) return null;
+  const [, paletteFamily, level] = scaleMatch;
+
+  const mapping = TAILWIND_PALETTE_FAMILIES[paletteFamily];
+  if (!mapping || !TAILWIND_PALETTE_LEVELS.includes(level)) return null;
+
+  const wrap = (result) => ({ input: utility, ...result });
+
+  if (!mapping.family) {
+    return wrap({
+      classification: MIGRATION_CLASS.REVIEW,
+      reason:
+        `${paletteFamily} に対応する意味のトークンが Sparkle にありません。` +
+        'Figma の該当箇所を見て用途（surface / text / border / object）から選び直してください。' +
+        '装飾目的の面であれば surface-accent-1 / 2 / 3 が候補になります。',
+    });
+  }
+
+  if (TAILWIND_ONLY_LEVELS.includes(level)) {
+    return wrap({
+      classification: MIGRATION_CLASS.REVIEW,
+      reason:
+        `Tailwind の ${level} に対応するレベルが Sparkle にありません（Sparkle は 900 まで）。` +
+        `${paletteFamily}-900 相当で足りるかを Figma で確認してください。`,
+    });
+  }
+
+  const delegate = (family) =>
+    resolveLegacyUtility(
+      `${variantPrefix}${importantPrefix}${prefix}-${family}-${level}${modifier}`
+    );
+
+  const primary = delegate(mapping.family);
+  if (!primary) return null;
+
+  // 用途上どちらの意味とも読める系統は、候補を両方並べて人に選ばせる。
+  // en: Surface both semantics when the code cannot tell brand colour from status.
+  if (mapping.ambiguousWith) {
+    const sides = [
+      { family: mapping.family, result: primary },
+      { family: mapping.ambiguousWith, result: delegate(mapping.ambiguousWith) },
+    ];
+    // 片側に該当トークンが無いことがある（例: surface の info には 600 が無い）。
+    // 候補を並べただけでは「なぜ片方しか出ないのか」が分からず、AI が
+    // 残った候補を唯一の正解と誤解するので、欠けている側を明示する。
+    // en: One side can have no matching token; say so, or the remaining
+    // candidate reads as the single correct answer.
+    const missing = sides.filter((side) => toCandidateList(side.result).length === 0);
+    return wrap({
+      classification: MIGRATION_CLASS.REVIEW,
+      candidates: sides.flatMap((side) => toCandidateList(side.result)),
+      reason:
+        `${paletteFamily} は「${mapping.family}（状態・意味を表す色）」とも「${mapping.ambiguousWith}（ブランド色）」とも読めます。` +
+        'どちらの用途かはコードから判断できないため、Figma の該当箇所を見て選んでください。' +
+        (missing.length > 0
+          ? `${missing.map((side) => side.family).join(' / ')} 側には対応するトークンがありません。`
+          : '') +
+        (mapping.exact ? '' : `なお ${paletteFamily} と Sparkle の色は完全には一致しません。`),
+    });
+  }
+
+  if (!mapping.exact) {
+    return wrap({
+      classification: MIGRATION_CLASS.REVIEW,
+      candidates: toCandidateList(primary),
+      reason:
+        `${paletteFamily} は Sparkle の ${mapping.family} に意味は対応しますが、色が完全には一致しません（置き換えると見た目が変わります）。` +
+        'Figma の該当箇所で意図した色かを確認してください。' +
+        (primary.reason ? ` ${primary.reason}` : ''),
+    });
+  }
+
+  // 値が一致する系統は、旧トークンからの移行と同じ確度で案内できる。
+  // en: Value-identical families keep the delegated classification as-is.
+  return wrap({
+    classification: primary.classification,
+    replacement: primary.replacement,
+    candidates: primary.candidates,
+    reason: primary.reason,
+  });
+}
+
+/**
+ * `resolveLegacyUtility` の戻り値を候補リストに正規化する。
+ * en: Flatten a delegated result into a candidate list.
+ */
+function toCandidateList(result) {
+  if (!result) return [];
+  if (result.replacement) return [result.replacement];
+  return result.candidates ?? [];
+}
+
 /**
  * CSS 変数名 1 個を解析して移行結果を返す。
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sparkle-design-cli",
-  "version": "2.5.0-beta.1",
+  "version": "2.5.0-beta.2",
   "description": "Sparkle Design CLI — プロジェクトセットアップ、CSS・フォント生成、アンチパターン検査、AI エージェント（Claude Code / Cursor / Codex）向けのガードと hook 設定まで一括で行う sparkle-design 公式 CLI。",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -19,10 +19,10 @@
   "scripts": {
     "test": "node --test test/*.test.js",
     "test:watch": "node --test --watch test/*.test.js",
-    "lint": "eslint bin/ lib/ test/",
-    "lint:fix": "eslint bin/ lib/ test/ --fix",
-    "format": "prettier --write bin/ lib/ test/ *.md *.json",
-    "format:check": "prettier --check bin/ lib/ test/ *.md *.json",
+    "lint": "eslint bin/ lib/ scripts/ test/",
+    "lint:fix": "eslint bin/ lib/ scripts/ test/ --fix",
+    "format": "prettier --write bin/ lib/ scripts/ test/ docs/ \"*.md\" \"*.json\"",
+    "format:check": "prettier --check bin/ lib/ scripts/ test/ docs/ \"*.md\" \"*.json\"",
     "sync:anti-pattern-docs": "node scripts/sync-anti-pattern-docs.mjs"
   },
   "keywords": [