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

package/lib/anti-pattern-rules.js

@@ -1,6 +1,96 @@
+import {
+  MIGRATION_CLASS,
+  buildDeprecatedAliasPattern,
+  buildLegacyCssVarPattern,
+  buildLegacyScalePattern,
+  buildLegacyTokenPattern,
+  buildTailwindPalettePattern,
+  resolveLegacyCssVar,
+  resolveLegacyUtility,
+  resolveTailwindPaletteUtility,
+} 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 +136,7 @@ const BUILTIN_MANUAL_REVIEW_REMINDERS = [
   },
 ];
 
-const BUILTIN_ANTI_PATTERN_GROUPS = [
+const COMPONENT_ANTI_PATTERN_GROUPS = [
   {
     id: 'card-description',
     featureSection: lines([
@@ -57,7 +147,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 +183,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>',
@@ -290,14 +380,17 @@ const BUILTIN_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 をそのまま使わない',
       '',
       '```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 +531,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>',
@@ -925,8 +1018,17 @@ const BUILTIN_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 を使わない',
@@ -940,7 +1042,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 +1307,446 @@ 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 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();
+
+/**
+ * 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: '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: {
+      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 +1761,17 @@ 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',
+  'tailwind-palette-color',
+  'legacy-color-var',
+  'deprecated-radius-alias',
+  'use-figma-spacing-scale',
 ];
 
 function getCheckRules(groups = BUILTIN_ANTI_PATTERN_GROUPS) {
@@ -1227,6 +1780,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);