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

package/docs/theming.md

@@ -0,0 +1,122 @@
+# 複数のテーマ配色を 1 デプロイでサポートしたい場合
+
+管理画面と一般ユーザー画面で配色を出し分けたい、テナントごとに固定の配色バリアントを切り替えたいなど、「少数（数種類程度）の固定配色を 1 つのデプロイでサポートする」ケースの推奨パターンです。**「画面ごとに読み込む CSS を切り替える」場合と「1 つの画面内でランタイムに切り替える」場合とで推奨パターンが異なる**ので、まずどちらのケースかを判断してください。
+
+## ケース A: 画面（ビルド）ごとにバリアントが固定される場合 → config を分割して複数の CSS を生成する
+
+管理画面 / 一般ユーザー画面でレイアウトごと entry CSS を分けられる、role や tenant に応じて import する CSS を切り替えられる、など「1 画面につき常に 1 バリアントだけを読み込む」運用ができる場合の推奨パターンです。
+
+`generate` は `-c/--config` と `-o/--output` を組み合わせることで、任意の config から任意の出力先へ CSS を生成できます。バリアントの数だけ config ファイルを用意し、バリアントの数だけ `generate` を実行してください（1 config に複数テーマをまとめて生成する機能はありませんが、CI やスクリプトで複数回呼び出せば十分に運用できます）。
+
+`config/sparkle.admin.json`:
+
+```json
+{
+  "primary": "blue",
+  "font-pro": "Inter",
+  "font-mono": "JetBrains Mono",
+  "radius": "md"
+}
+```
+
+`config/sparkle.employee.json`:
+
+```json
+{
+  "primary": "green",
+  "font-pro": "Inter",
+  "font-mono": "JetBrains Mono",
+  "radius": "md"
+}
+```
+
+```bash
+npx sparkle-design-cli generate -c ./config/sparkle.admin.json -o ./src/styles/sparkle-admin.css
+npx sparkle-design-cli generate -c ./config/sparkle.employee.json -o ./src/styles/sparkle-employee.css
+```
+
+あとは consumer 側で、表示するバリアントに応じてどちらの CSS を読み込むかを切り替えるだけです（例: role / tenant を判定できるレイアウト単位で `import "./sparkle-admin.css"` と `import "./sparkle-employee.css"` を出し分ける、Next.js のルートグループごとに読み込む entry CSS を分ける、など）。
+
+**重要: この 2 つの CSS を同時に import してはいけません。** これはファイルサイズ最適化の話ではなく **correctness 上のハード制約** です。`generate` が出力する CSS は `@theme inline { ... }` という Tailwind v4 の at-rule を含みますが、Tailwind の仕様上 `@theme`（`@theme inline` を含む）は **stylesheet の top-level にしか置けず、かつ 1 種類のトークン定義として扱われます**。2 つの `generate` 出力を同時 import すると、両方の `@theme inline` が同じ top-level スコープで衝突し、後に読み込んだ方の値で utility class（`bg-primary-500` 等）の意味がビルド時に固定されてしまいます（`data-*` 属性の付け外しのようなランタイム操作では変わりません）。**1 画面につき常に 1 バリアントだけを読み込む**構成でのみ、この方式は安全に使えます。
+
+「1 つの画面内で属性の付け外しだけでテーマを切り替えたい（ページ遷移や再ビルドを伴わない）」場合は、このケース A ではなく次のケース B を使ってください。
+
+## ケース B: 単一バンドル内でランタイムに切り替えたい場合 → `generate --scope`
+
+SPA の 1 つの JS バンドル内で、`<html data-tenant-theme="admin">` のような属性の付け外しだけで配色を切り替えたい（ページ遷移・再デプロイを伴わない）場合のパターンです。ケース A の「config 分割 + 複数 `generate` の CSS を同時 import する」は、上記の理由（`@theme inline` の衝突）でこのケースには使えません。
+
+Tailwind v4 では、この種のランタイム切り替え（dark mode 等）を公式に次のパターンでサポートしています（[Tailwind公式ドキュメント](https://tailwindcss.com/docs/colors#using-css-variables)より）:
+
+```css
+@import 'tailwindcss';
+
+:root {
+  --acme-canvas-color: oklch(0.967 0.003 264.542);
+}
+
+[data-theme='dark'] {
+  --acme-canvas-color: oklch(0.21 0.034 264.665);
+}
+
+@theme inline {
+  --color-canvas: var(--acme-canvas-color);
+}
+```
+
+ポイントは、`@theme inline` は top-level に **1 つだけ** 置いたまま、実際に切り替えたい値は `@theme` を使わない普通の `:root` / `[data-attr]` スコープ付きセレクタで **参照先の CSS 変数** を上書きする、という構成です。`generate --scope` はこの「参照先を差し替える」役割を、`sparkle.config.json` の解決ロジックを再利用しながら自動生成します。
+
+```bash
+# ベース（デフォルト表示）となるバリアントは今まで通り通常の generate
+npx sparkle-design-cli generate -c ./config/sparkle.employee.json -o ./src/styles/sparkle-employee.css
+
+# 追加バリアントは --scope で「セマンティックトークンだけをセレクタでラップした差分 CSS」を生成する
+npx sparkle-design-cli generate -c ./config/sparkle.admin.json \
+  --scope '[data-tenant-theme="admin"]' \
+  -o ./src/styles/sparkle-admin-scope.css
+```
+
+```css
+/* entry CSS: 両方を同時に import してよい */
+@import 'tailwindcss';
+@import './sparkle-employee.css'; /* @theme inline を含む通常の generate 出力（ベース） */
+@import './sparkle-admin-scope.css'; /* --scope の出力。@theme inline は含まない */
+```
+
+```html
+<!-- ランタイムでこの属性を付け外しするだけで配色が切り替わる。ページ遷移・再ビルド不要 -->
+<html data-tenant-theme="admin"></html>
+```
+
+`--scope` の出力は次の性質を持ちます:
+
+- `@theme inline` には一切触れない（ベース側の `generate` 出力にある 1 つだけがそのまま有効であり続ける）ので、ケース A のような衝突は起きません。
+- `--color-primary-*` 等の **セマンティックトークン** を、admin config の解決結果に基づいて実値（`oklch(...)`）までリテラル化した上で `--scope` のセレクタの中に閉じ込めます。プリミティブ（`--color-blue-*` 等）ではなくセマンティックトークンを上書き対象にしているのがポイントで、デフォルトでは `primary` と `info` が同じプリミティブ（例: `blue`）を共有しているため、もしプリミティブ側を上書きしてしまうと `primary` を変えたつもりが `info` まで巻き込んで変わってしまいます。`--scope` はこの巻き込みが起きないよう、セマンティック層で解決してから出力します。
+- `--radius-*` / `--shadow-*` は普遍的な共有スケール値（テナント間で衝突しない）なので `var()` 参照のまま出力されます。`config.radius` がバリアントごとに異なれば、その解決結果もちゃんと反映されます。
+- フォント import・`@source`・SparkleHead.tsx・globals.css パッチ等、ドキュメント全体に関わる**出力**は行いません。これらはベース側の通常 `generate` が既に担っているため、バリアントごとに重複させる必要はありません。ただし `font-pro` / `font-mono` 等の **validation 自体**は通常の `generate` と同様に適用されます（出力しないだけで、config の妥当性チェックは変わりません）。
+- `-o/--output` の指定が必須です（既定の `sparkle-design.css` を誤って上書きしないため）。`--strict` / `--globals-path` とは併用できません（`--scope` はグローバル CSS のパッチを行わないため）。
+- 現状 `primary` は 7 色パレットからの選択のみ対応しています。7 色にないカスタムブランドカラーを `--scope` の変数だけで表現したい場合は、`extend.custom-css` の要領で手動でセレクタ配下に `--color-primary-*` を定義してください（`--scope` の出力とマージして使えます）。
+- **v2.4.1 以降**: ベース側 `generate` が出す `@theme inline` の各宣言は、プリミティブへの直接参照ではなく同名のセマンティック変数への自己参照（例: `--color-primary-500: var(--color-primary-500)`）になっています。Tailwind v4 は `@theme inline` の宣言右辺をそのまま compiled utility class にインライン展開する仕様のため、これが無いと `.bg-primary-500` 等の compiled utility は最初からプリミティブ変数だけを参照し、`--scope` がセマンティック変数だけを上書きしても utility class には一切反映されません（v2.4.0 はこの自己参照が無く、`--scope` の上書きが compiled utility に効かない状態でした）。v2.4.1 以降を使ってください。
+
+このパターンは、次の「非推奨: 属性スコープでの Tailwind クラス上書き」が抱えていた脆さも同時に解消します。`--scope` が上書きするのは Sparkle が公開しているトークン契約（`--color-primary-*` 等の CSS 変数）だけであり、ユーティリティクラス名やコンポーネント内部の specificity には一切依存しません。そのため、Sparkle 側のコンポーネント実装（クラス名の付け方や compound attribute selector 等）が変わっても、`--scope` の出力が壊れることはありません。
+
+## 非推奨: 単一 CSS + 属性スコープでの Tailwind クラス上書き
+
+`sparkle-design.css` を 1 本のまま、`[data-theme="xxx"] .bg-primary-500 { ... }` のような属性セレクタで Tailwind ユーティリティクラスを個別に上書きする方式は **推奨しません**。
+
+- コンポーネント側の実装詳細（クラス名の付け方や CSS の specificity）に依存するため、Sparkle 側の内部実装（例: 状態別カラーリングで compound attribute selector を使っているコンポーネント）が変わると、`!important` を使っても上書きが効かなくなることがあります。上書き対象は Sparkle が公開している契約（config / トークン）ではなく非公開の実装詳細なので、バージョンアップのたびに壊れるリスクを consumer 側が抱え続けることになります。
+- 上書きが必要なクラス／コンポーネントが増えるたびに、手動でセレクタを足していく必要があり、考慮漏れに気づきにくいです。
+
+上記のリスクを踏まえると、テーマ切り替えは「ケース A: config 分割」または「ケース B: `generate --scope`」+ `extend.custom-css` によるトークンレベルの上書き（cascade 順で確実に勝つ）で完結させる方が、Sparkle のバージョンアップに対しても壊れにくく、見通しの良い実装になります。
+
+## トレードオフ
+
+| 観点           | ケース A: config 分割（推奨・画面ごと固定）                                                                                      | ケース B: `generate --scope`（推奨・単一バンドルでランタイム切替）                           | 属性スコープ上書き（非推奨）                                                                                        |
+| -------------- | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| 適用シーン     | 1 画面につき常に 1 バリアントだけを読み込める                                                                                    | 1 バンドル内で属性の付け外しだけで切り替えたい                                               | （非推奨のため参考情報）                                                                                            |
+| ファイルサイズ | バリアントの数だけ CSS が増える（各 CSS は 7 色パレット全体を含む）。1 画面 1 バリアントのみ読み込む運用なら実質的な増分は小さい | ベース CSS 1 本 + バリアントごとの軽量な差分 CSS（セマンティックトークンのみ）               | 単一 CSS + 上書き分の差分のみで増分は小さい                                                                         |
+| FOUC リスク    | サーバー側 / ビルド時にバリアントを決定できるならほぼ無し                                                                        | 属性付与のタイミング次第でリスクがある（初期描画後に属性が付くと一瞬デフォルト配色が見える） | クライアント側で属性を付与するタイミング次第でリスクがある                                                          |
+| 保守性         | Sparkle が公開している config / トークンだけに依存するため、コンポーネント内部実装の変更に影響されにくい                         | 同左（トークンだけに依存し、ユーティリティクラス名や specificity に依存しない）              | コンポーネントの内部実装（クラス名・specificity）に依存するため、Sparkle 側の変更で上書きが効かなくなるリスクがある |
+
+---
+
+[← README に戻る](../README.md)（docs/theming.md）

package/lib/anti-pattern-rules.js

@@ -1,6 +1,94 @@
+import {
+  MIGRATION_CLASS,
+  buildDeprecatedAliasPattern,
+  buildLegacyCssVarPattern,
+  buildLegacyScalePattern,
+  buildLegacyTokenPattern,
+  resolveLegacyCssVar,
+  resolveLegacyUtility,
+} from './token-migration.js';
+import { buildSpacingUtilityPattern, pxToStep, resolveSpacingStep } from './spacing-scale.js';
+
 const COMMON_INTRO =
   '以下は頻繁に発生する誤用パターンです。コンポーネントが提供する専用 props・サブコンポーネントを使ってください。';
 
+/**
+ * ルールの「強さ」。AI がすべてのルールを同じ重みで扱ってしまい、全部を過剰に
+ * 守るか全部を読み流すかの両極端に振れるのを防ぐために付ける（issue #74）。
+ *
+ * - `error`   … 例外なし。`--strict` / stop-hook はこれだけを失敗として扱う
+ * - `warning` … 原則ダメだが理由があれば例外可。報告はするが exit code は変えない
+ * - `info`    … 参考。従わなくてもよい選択肢
+ *
+ * 既存ルールはすべて `error` 相当（`--strict` で落ちる）だったため、severity 未指定は
+ * `error` にフォールバックする。これで**プラグイン rule を含め既存の挙動が一切変わらない**。
+ * en: Unspecified severity falls back to `error`, so existing built-in and plugin
+ * rules keep their current pass/fail behaviour exactly.
+ */
+export const SEVERITY = {
+  ERROR: 'error',
+  WARNING: 'warning',
+  INFO: 'info',
+};
+
+export const DEFAULT_SEVERITY = SEVERITY.ERROR;
+
+/**
+ * ルールを当てるファイル種別。
+ *
+ * 既定は `source`（`.js` / `.jsx` / `.ts` / `.tsx`）で、severity 導入前の
+ * 挙動と同じ。組み込み・プラグインを問わず既存ルールは JSX 前提で書かれて
+ * いるため、既定を広げると既存 consumer に新しい findings が湧いて CI が落ちる。
+ *
+ * トークン移行ルールだけは `css` も対象にする。`--radius-halfModal` のような
+ * CSS 変数の直接参照は `.css` にこそ自然に書かれるうえ、消えてもビルドエラーに
+ * ならず角丸だけ失われる — まさにこのルールが防ごうとしている故障が、CSS では
+ * 検出できないという穴になっていた。
+ * en: Which file kinds a rule applies to. Defaults to source files (previous
+ * behaviour); the token-migration rules opt into `.css` as well, since CSS
+ * variable references live there and fail silently when the alias is removed.
+ */
+export const RULE_TARGET = {
+  SOURCE: 'source',
+  CSS: 'css',
+};
+
+export const DEFAULT_RULE_TARGETS = [RULE_TARGET.SOURCE];
+const KNOWN_RULE_TARGETS = new Set(Object.values(RULE_TARGET));
+
+function normalizeRuleTargets(targets, ruleId) {
+  if (targets === undefined || targets === null) return DEFAULT_RULE_TARGETS;
+  const list = Array.isArray(targets) ? targets : [targets];
+  const unknown = list.filter((target) => !KNOWN_RULE_TARGETS.has(target));
+  if (unknown.length > 0 || list.length === 0) {
+    console.warn(
+      `⚠️  sparkle-design-cli: rule "${ruleId ?? '(unknown)'}" has invalid targets ${JSON.stringify(targets)} — falling back to ${JSON.stringify(DEFAULT_RULE_TARGETS)}`
+    );
+    return DEFAULT_RULE_TARGETS;
+  }
+  return list;
+}
+
+/** `--strict` / stop-hook が失敗として扱う severity */
+export const BLOCKING_SEVERITIES = new Set([SEVERITY.ERROR]);
+
+const KNOWN_SEVERITIES = new Set(Object.values(SEVERITY));
+
+function normalizeSeverity(severity, ruleId) {
+  if (severity === undefined || severity === null) return DEFAULT_SEVERITY;
+  if (KNOWN_SEVERITIES.has(severity)) return severity;
+  // 既定（error）に倒すので CI は落ちる。これは意図した fail-safe —— 「強さが
+  // 分からないルールを黙って非ブロックにする」ほうが危険なため。ただし黙って
+  // 落とすとタイポに気付けないので warn を出す（loadAntiPatternPlugins の
+  // warn-and-skip と同じ方針）。
+  // en: Falling back to `error` is deliberate (fail-safe): silently downgrading
+  // an unknown severity to non-blocking is worse. Warn so the typo is visible.
+  console.warn(
+    `⚠️  sparkle-design-cli: rule "${ruleId ?? '(unknown)'}" has an unknown severity ${JSON.stringify(severity)} — falling back to "${DEFAULT_SEVERITY}"`
+  );
+  return DEFAULT_SEVERITY;
+}
+
 function lines(values) {
   return values.join('\n');
 }
@@ -46,7 +134,7 @@ const BUILTIN_MANUAL_REVIEW_REMINDERS = [
   },
 ];
 
-const BUILTIN_ANTI_PATTERN_GROUPS = [
+const COMPONENT_ANTI_PATTERN_GROUPS = [
   {
     id: 'card-description',
     featureSection: lines([
@@ -57,7 +145,7 @@ const BUILTIN_ANTI_PATTERN_GROUPS = [
       '<CardHeader>',
       '  <CardTitle>',
       '    プロジェクト一覧',
-      '    <CardDescription className="character-3-regular-pro text-text-low">',
+      '    <CardDescription className="character-3-regular-pro text-text-neutral-low">',
       '      全 12 件',
       '    </CardDescription>',
       '  </CardTitle>',
@@ -93,7 +181,7 @@ const BUILTIN_ANTI_PATTERN_GROUPS = [
             '// ✅ Correct',
             '<CardTitle>',
             '  プロジェクト一覧',
-            '  <CardDescription className="character-3-regular-pro text-text-low">',
+            '  <CardDescription className="character-3-regular-pro text-text-neutral-low">',
             '    全 12 件',
             '  </CardDescription>',
             '</CardTitle>',
@@ -297,7 +385,7 @@ const BUILTIN_ANTI_PATTERN_GROUPS = [
       '',
       '```tsx',
       '// ✅ Correct — Sparkle Design の typography / color token を使う',
-      '<CardDescription className="character-3-regular-pro text-text-low">',
+      '<CardDescription className="character-3-regular-pro text-text-neutral-low">',
       '  全 12 件',
       '</CardDescription>',
       '',
@@ -438,7 +526,7 @@ const BUILTIN_ANTI_PATTERN_GROUPS = [
             '<CardHeader>',
             '  <CardTitle>',
             '    タイトル',
-            '    <CardDescription className="character-3-regular-pro text-text-low">',
+            '    <CardDescription className="character-3-regular-pro text-text-neutral-low">',
             '      全 12 件',
             '    </CardDescription>',
             '  </CardTitle>',
@@ -940,7 +1028,7 @@ const BUILTIN_ANTI_PATTERN_GROUPS = [
       '',
       '// 例外 — character-* に対応するサイズが無い場合は arbitrary value を使うか',
       '// suppress コメントを付けて残す',
-      '<span className="text-[10px] text-text-low">12px 未満の極小メタ情報</span>',
+      '<span className="text-[10px] text-text-neutral-low">12px 未満の極小メタ情報</span>',
       '{/* sparkle-disable-next-line tailwind-typography */}',
       '<span className="text-xs">どうしても text-xs で残したいケース</span>',
       '```',
@@ -1205,6 +1293,327 @@ const BUILTIN_ANTI_PATTERN_GROUPS = [
 // Built-in groups always come before plugin-supplied groups in this priority order.
 // Plugin-supplied IDs that aren't in this list fall to the end (stable insertion order).
 // en: Determines `check` finding emission order so the most-important built-in rules surface first.
+// --- 新セマンティックトークンへの移行ルール（beta 期間中は warning） ----------
+//
+// 旧トークンは beta 期間中テンプレートに併存するので、使っていても即座には
+// 壊れない。ここで `error` にすると「まだ移行していないコンポーネントでは
+// 旧トークンが正」という移行期の現実と衝突して CI が通らなくなるため、beta
+// 中は `warning`（報告のみ）に留める。beta 終了で旧トークンを削除するとき
+// `error` に昇格させる（issue #74）。
+// en: Legacy tokens still exist during beta, so flag them as `warning` — an
+// `error` here would collide with the reality that un-migrated components
+// legitimately still use them. Promote to `error` when the legacy layer is
+// removed.
+
+/**
+ * マッチ 1 件ごとに移行先を計算して recommendation にする match 関数を作る。
+ * 「代わりに何を使うか」までルールに含めないと、AI は違反を見つけても直し方を
+ * 発明してしまう（issue #74 の提案3）。
+ * en: Compute the migration target per occurrence — a rule that only says
+ * "don't" makes the AI invent its own replacement.
+ */
+/**
+ * ブロックコメントの中身を同じ長さの空白に置き換える。
+ *
+ * コメント内の言及（「旧 `--color-ring-normal` の移行先」のような説明文）まで
+ * 移行対象として報告すると、生成物やドキュメントコメントが大量の誤検出になる。
+ * 中身を消すのではなく**同じ長さの空白で潰す**ことで、後段が使う index と
+ * 行番号がずれない。
+ *
+ * **行頭（インデント可）から始まるものだけ**を対象にする。任意位置の `/*` を
+ * コメント開始とみなすと、文字列リテラル内の `/*`——`matcher: ['/dashboard/*']`
+ * や `content: "/*"`、glob、正規表現リテラル——を起点に、次の `*\/` までの
+ * **実コードを黙って検査対象から外してしまう**。無言の false negative は、
+ * 未解決の hit をわざわざ表に出しているこのモジュールの方針と正反対なので、
+ * 「コメントは行頭から書く」という緩い前提を取るほうが安全側に倒れる。
+ * 行末コメント（`const x = 1; /* ... *\/`）は潰さないので、そこに書かれた
+ * トークン名は検出されうるが、warning 止まりで抑制コメントも使える。
+ * en: Only mask block comments that start a line. Treating any `/*` as a
+ * comment start would silently blank real code after a string literal such as
+ * `matcher: ['/dashboard/*']` — a false negative, which is worse than the
+ * false positive it avoids.
+ */
+function maskBlockComments(content) {
+  return content.replace(/^[ \t]*\/\*[\s\S]*?\*\//gm, (comment) => comment.replace(/[^\n]/g, ' '));
+}
+
+function migrationMatcher(pattern, resolve, label) {
+  return (rawContent) => {
+    const content = maskBlockComments(rawContent);
+    // そのファイル自身が宣言している変数への参照は「移行対象の使用」ではなく
+    // 定義側の内部配線。CLI が生成した CSS（旧トークンを定義している側）を
+    // 丸ごと報告してしまうのを防ぐ。
+    //
+    // ファイル名（`sparkle-design.css`）で除外していたが、`generate --scope` は
+    // `-o` が必須で出力名が任意になるため、テナント別テーマを使うプロジェクトの
+    // 生成物が素通りしていた。「定義しているファイルは、その変数について正」
+    // という内容ベースの判定なら出力名に依存しない。
+    // en: Skip references to variables the same file declares — those are the
+    // definition side, not usage to migrate. Content-based, so it also covers
+    // `generate --scope` output whose filename is arbitrary.
+    // `{` / `;` 直後も宣言位置として拾う。行頭だけを見ていると、1 行にまとめた
+    // CSS や minify された theme ファイルで**定義側まで「使用」として報告**する。
+    // en: Also treat `{`/`;` as declaration starts so single-line/minified CSS
+    // doesn't get its own definitions reported as usages.
+    const declaredHere = new Set(
+      [...content.matchAll(/(?:^|[{;])\s*(--[\w-]+)\s*:/gm)].map((m) => m[1])
+    );
+
+    const hits = [];
+    for (const match of content.matchAll(pattern)) {
+      const text = match[0];
+      if (text.startsWith('--') && declaredHere.has(text)) continue;
+      const resolved = resolve(text);
+      // 検出パターンが拾ったのに解決できない = 検出側と対応表がずれている。
+      // ここで `continue` すると「旧トークンを使っているのに何も報告されない」
+      // 無記録の drop になるので、要判断として必ず表に出す。
+      // （現状この分岐には到達しないことを token-migration.test.js の全数検証で
+      // 確認しているが、テーブル編集で簡単に壊れるため fail-loud にしておく）
+      // en: A pattern hit that the table cannot resolve means the two have
+      // drifted. Surface it instead of dropping it silently.
+      if (!resolved) {
+        hits.push({
+          index: match.index ?? 0,
+          text,
+          recommendation:
+            `[要判断] ${text}: ${label}として検出しましたが移行先を解決できませんでした。` +
+            'sparkle-design-cli の検出パターンと対応表がずれている可能性があります（issue 報告をお願いします）。',
+        });
+        continue;
+      }
+
+      let recommendation;
+      if (resolved.classification === MIGRATION_CLASS.AUTO) {
+        recommendation = `[自動変換可] ${text} → ${resolved.replacement}${resolved.reason ? `（${resolved.reason}）` : ''}`;
+      } else if (resolved.candidates?.length) {
+        recommendation = `[要判断] ${text} の移行先候補: ${resolved.candidates.join(' / ')}。${resolved.reason ?? ''}`;
+      } else if (resolved.replacement) {
+        // 移行先自体は算出できているが人間の確認が要るケース（`text-placeholder`
+        // の統合など）。せっかく分かっている置換先を捨てない。
+        // en: The target is known but needs a human decision — still show it.
+        recommendation = `[要判断] ${text} → ${resolved.replacement}。${resolved.reason ?? ''}`;
+      } else {
+        recommendation = `[要判断] ${text}: ${resolved.reason ?? `${label} の移行先を Figma で確認してください。`}`;
+      }
+
+      hits.push({ index: match.index ?? 0, text, recommendation });
+    }
+    return hits;
+  };
+}
+
+const SPACING_UTILITY_PATTERN = buildSpacingUtilityPattern();
+
+/**
+ * Figma の spacing スケールから外れた値を拾う。
+ *
+ * 移行ルール（migrationMatcher）と違い「同じファイルが宣言しているか」は見ない。
+ * spacing は CSS 変数として出力していないので、**変数の**定義側という概念が
+ * 無いため。ただし Tailwind がコンパイルした CSS の `.p-7{padding:1.75rem}` は
+ * 素通しで拾う。既定の検査対象が `src` なので通常は踏まないが、`dist` や
+ * vendored CSS を明示的に渡すと大量に報告される。
+ * en: No CSS-variable definition side exists for spacing, but compiled Tailwind
+ * output (`.p-7{…}`) is still matched — only reachable if someone points the
+ * check at `dist`/vendored CSS.
+ */
+function spacingScaleMatcher(rawContent) {
+  const content = maskBlockComments(rawContent);
+  const hits = [];
+  for (const match of content.matchAll(SPACING_UTILITY_PATTERN)) {
+    const { lead, sign: prefixModifiers, step, important } = match.groups;
+    const text = match[0];
+    const offScale = resolveSpacingStep(step);
+    if (!offScale) continue;
+
+    // 負のマージン（`-mt-7`）はステップだけ見ると正数なので、px 表示に符号を
+    // 戻す。クラス名は lead に `-` が入っているので正しいが、「-mt-7 は 28px」
+    // という案内は px 換算の正確さが売りのルールとして嘘になる。
+    // 判定は lead 全体ではなく **ユーティリティ直前の修飾子だけ**を見る。
+    // lead を走査すると `[&:-moz-any-link]:mt-7` の variant 内の `-` を拾う。
+    // en: Restore the sign in the px figures, reading only the modifier right
+    // before the utility — scanning `lead` would misread variants like
+    // `[&:-moz-any-link]:mt-7` as negative.
+    const sign = prefixModifiers.includes('-') ? '-' : '';
+
+    // 候補は variant 連鎖・負号・important をすべて保ったまま数字だけ差し替える。
+    // `p-7!` に対して `p-6` を案内すると、そのまま従った人が important を落とす。
+    // en: Rebuild candidates with every modifier intact — suggesting `p-6` for
+    // `p-7!` would quietly drop the important flag.
+    const neighbours = [offScale.lower, offScale.upper]
+      .filter((px) => px !== null)
+      .map((px) => `${lead}${pxToStep(px)}${important}（${sign}${px}px）`);
+
+    hits.push({
+      index: match.index ?? 0,
+      text,
+      recommendation:
+        `[要判断] ${text} は ${sign}${offScale.px}px で、Figma の Spacing: Primitives に無い値です。` +
+        // スケールに 0 が含まれる限り `lower` は必ず埋まるので、この else には
+        // 到達しない（`upper` が null になるのは 120px 超のときだけで、
+        // そのとき `lower` は 120）。FIGMA_SPACING_PX を空にした場合の保険。
+        // en: Unreachable while the scale contains 0 — kept as a guard.
+        (neighbours.length
+          ? `近いステップは ${neighbours.join(' / ')}。`
+          : 'Figma のスケールを確認してください。') +
+        'デザイン上その値が必要なら、Figma 側にステップを追加するか、' +
+        '`sparkle-disable-next-line use-figma-spacing-scale` で明示的に外してください。',
+    });
+  }
+  return hits;
+}
+
+const LEGACY_SCALE_PATTERN = buildLegacyScalePattern();
+const LEGACY_TOKEN_PATTERN = buildLegacyTokenPattern();
+const LEGACY_CSS_VAR_PATTERN = buildLegacyCssVarPattern();
+const DEPRECATED_ALIAS_PATTERN = buildDeprecatedAliasPattern();
+
+const TOKEN_MIGRATION_GROUPS = [
+  {
+    id: 'legacy-color-token',
+    check: {
+      severity: SEVERITY.WARNING,
+      // `.css` も対象にする（`@apply` のユーティリティ、`var(--color-*)` の直接参照）
+      targets: [RULE_TARGET.SOURCE, RULE_TARGET.CSS],
+      description:
+        '旧セマンティックカラーのユーティリティクラスを使っています（新体系は用途 × 意味 × 強度 × 状態）',
+      recommendation:
+        '用途別セマンティックトークン（bg- → surface / text- → text / border- → border / fill- → object）に置き換えてください。',
+      match: (content) => [
+        ...migrationMatcher(LEGACY_SCALE_PATTERN, resolveLegacyUtility, '旧トークン')(content),
+        ...migrationMatcher(LEGACY_TOKEN_PATTERN, resolveLegacyUtility, '旧トークン')(content),
+      ],
+    },
+    featureSection: lines([
+      '### 旧セマンティックカラーではなく用途別トークンを使う',
+      '',
+      '新体系は「用途 × 意味 × 強度 × **状態**」で、状態がトークン名に内包される。',
+      'そのため**同じ旧クラスでも文脈によって移行先が変わる**。',
+      '',
+      '| if（状況） | then（移行先） |',
+      '|---|---|',
+      '| 通常状態の背景に `bg-primary-600` | `bg-surface-primary-high-enabled` |',
+      '| hover の背景に `hover:bg-primary-700` | `hover:bg-surface-primary-high-hover` |',
+      '| variant 接頭辞なしで `bg-primary-200` | **自動変換しない**（`surface-primary-high-disabled` と `surface-primary-middle-active` のどちらか判断が要る） |',
+      '| 文字色に `text-primary-600` | `text-text-primary-enabled` |',
+      '| 枠線に `border-primary-300` | `border-border-primary-high` |',
+      '| アイコン色に `fill-primary-600` | `fill-object-primary-enabled` |',
+      '',
+      '`secondary` は `neutral` に統合された。ユーティリティ接頭辞がそのまま用途に対応する',
+      '（`bg-` → surface / `text-` → text / `border-`・`divide-`・`outline-`・`ring-` → border / `fill-`・`stroke-` → object）。',
+      '',
+      '判断が付かないときは推測で置換せず、Figma の該当箇所を確認する。',
+    ]),
+    jsdocTargets: [],
+  },
+  {
+    id: 'legacy-color-var',
+    check: {
+      severity: SEVERITY.WARNING,
+      // `.css` も対象にする（`@apply` のユーティリティ、`var(--color-*)` の直接参照）
+      targets: [RULE_TARGET.SOURCE, RULE_TARGET.CSS],
+      description: '旧セマンティックカラーの CSS 変数を直接参照しています',
+      recommendation:
+        '新しい用途別セマンティックトークンの変数に置き換えてください。用途が変数名から決まらない場合は Figma を確認してください。',
+      match: migrationMatcher(LEGACY_CSS_VAR_PATTERN, resolveLegacyCssVar, '旧トークン'),
+    },
+    featureSection: lines([
+      '### 旧セマンティックカラーの CSS 変数を直接参照しない',
+      '',
+      '```tsx',
+      '// ✅ Correct',
+      '<div className="ring-2 ring-[var(--color-border-ring)] ring-offset-2" />',
+      '',
+      '// ❌ Wrong — beta 終了時に削除される旧トークン',
+      '<div className="ring-2 ring-[var(--color-ring-normal)] ring-offset-2" />',
+      '```',
+      '',
+      'フォーカスリングの `--color-ring-normal` は `--color-border-ring`（blue/700 固定）に移行する。',
+      '`--color-primary-600` のようなスケール付きの旧変数は、変数名だけでは用途',
+      '（surface / text / border / object）が決まらないため**自動変換しない**。',
+    ]),
+    jsdocTargets: [],
+  },
+  {
+    id: 'deprecated-radius-alias',
+    check: {
+      severity: SEVERITY.WARNING,
+      // `.css` も対象にする（`@apply` のユーティリティ、`var(--color-*)` の直接参照）
+      targets: [RULE_TARGET.SOURCE, RULE_TARGET.CSS],
+      description: 'beta 期間だけ残している後方互換エイリアスを直接参照しています',
+      recommendation: 'リネーム後の変数を直接参照してください。',
+      match: migrationMatcher(DEPRECATED_ALIAS_PATTERN, resolveLegacyCssVar, '後方互換エイリアス'),
+    },
+    featureSection: lines([
+      '### 削除予定の後方互換エイリアスを直接参照しない',
+      '',
+      '```tsx',
+      '// ✅ Correct',
+      '<div className="rounded-[var(--radius-container)]" />',
+      '',
+      '// ❌ Wrong — beta 終了時に削除され、角丸がサイレントに消える',
+      '<div className="rounded-[var(--radius-halfModal)]" />',
+      '```',
+      '',
+      'Figma の `Borders: Semantics` で `halfModal` は `container` にリネームされた。',
+      '`--radius-halfModal` は beta 期間だけのエイリアスで、消えても CSS としては',
+      '有効なまま（値が空になるだけ）なので**ビルドエラーにならずに角丸だけが失われる**。',
+    ]),
+    jsdocTargets: [],
+  },
+  {
+    id: 'use-figma-spacing-scale',
+    check: {
+      // `info` から始める。既存 consumer にとっては未知の制約で、しかも
+      // 「動かない」わけではなく「スケールから外れている」だけなので、
+      // いきなり warning にすると移行ルールの警告に埋もれて全部読み流される。
+      // en: Ships at `info` — it's a new constraint on working code, and
+      // shouting would drown out the migration warnings that do need action.
+      severity: SEVERITY.INFO,
+      // `.css` も対象にする（`@apply p-7` のような書き方を拾うため）
+      targets: [RULE_TARGET.SOURCE, RULE_TARGET.CSS],
+      description: 'Figma の Spacing: Primitives に無い余白ステップを使っています',
+      recommendation:
+        'Figma のスケールに乗ったステップに寄せてください。判断が付かない場合は Figma の該当箇所を確認してください。',
+      match: spacingScaleMatcher,
+    },
+    featureSection: lines([
+      '### 余白は Figma の Spacing: Primitives のステップだけ使う',
+      '',
+      'Figma の余白は 17 段（0 / 2 / 4 / 6 / 8 / 12 / 16 / 20 / 24 / 32 / 40 / 48 / 56 / 72 / 88 / 104 / 120 px）。',
+      'Tailwind の 1 ステップは 4px なので、`p-4` = 16px、`p-6` = 24px が対応する。',
+      '',
+      '```tsx',
+      '// ✅ Correct — 6=24px / 4=16px / 8=32px はいずれもスケール上にある',
+      '<div className="p-6 gap-4 mt-8" />',
+      '',
+      '// ❌ Wrong — 7 は 28px。24px と 32px の間にステップは無い',
+      '<div className="p-7" />',
+      '```',
+      '',
+      '**Tailwind の数字と Figma の数字は一致しない。** Figma の `padding/16` は 16px、',
+      'Tailwind の `p-16` は 64px で 4 倍違う。Figma の値を見て同じ数字を書かないこと。',
+      '',
+      '| Figma | px | Tailwind |',
+      '|---|---|---|',
+      '| `padding/8` | 8px | `p-2` |',
+      '| `padding/16` | 16px | `p-4` |',
+      '| `padding/24` | 24px | `p-6` |',
+      '| `padding/120` | 120px | `p-30` |',
+      '',
+      'このスケールは **CSS 変数として出力されていない**。`--spacing-16` のような',
+      '名前付きキーを定義すると Tailwind の `p-16` がその値に差し替わり、',
+      '既存コードの余白がビルドも警告も通ったまま変わってしまうため。',
+      'だから「変数を使う」ではなく「使ってよい値を守る」という形の制約になっている。',
+      '',
+      'デザイン上どうしてもスケール外の値が要る場合は、Figma 側にステップを追加するのが本筋。',
+      '個別に外すなら `sparkle-disable-next-line use-figma-spacing-scale` を使う。',
+    ]),
+    jsdocTargets: [],
+  },
+];
+
+const BUILTIN_ANTI_PATTERN_GROUPS = [...COMPONENT_ANTI_PATTERN_GROUPS, ...TOKEN_MIGRATION_GROUPS];
+
 const BUILTIN_CHECK_ORDER = [
   'dialog-form',
   'dialog-button-wrap',
@@ -1219,6 +1628,16 @@ const BUILTIN_CHECK_ORDER = [
   'disabled-vs-is-disabled',
   'button-prefixicon-jsx',
   'icon-children-text',
+  // NOTE: この配列が決めるのは **ルールの評価順** だけで、レポートの表示順では
+  // ない（findings は check.js 側で severity 優先にソートされる）。移行ルールを
+  // 末尾に置いているのは評価順を安定させるためで、「warning が error を埋もれ
+  // させない」保証は severity ソートが担っている。
+  // 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',
+  'legacy-color-var',
+  'deprecated-radius-alias',
+  'use-figma-spacing-scale',
 ];
 
 function getCheckRules(groups = BUILTIN_ANTI_PATTERN_GROUPS) {
@@ -1227,6 +1646,8 @@ function getCheckRules(groups = BUILTIN_ANTI_PATTERN_GROUPS) {
     .map((group) => ({
       id: group.id,
       ...group.check,
+      severity: normalizeSeverity(group.check.severity, group.id),
+      targets: normalizeRuleTargets(group.check.targets, group.id),
     }))
     .sort((left, right) => {
       const leftIndex = BUILTIN_CHECK_ORDER.indexOf(left.id);