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

package/lib/token-migration.js

@@ -0,0 +1,678 @@
+/**
+ * 旧セマンティックトークン → 新セマンティックトークンの移行マッピング。
+ *
+ * このファイルが移行知識の唯一の source of truth。`check`（アンチパターン
+ * ルールの recommendation 文面）と、将来の `migrate` サブコマンド
+ * （goodpatch/sparkle-design-cli#73）の両方がここを参照する。同じ対応表を
+ * 2 箇所に書くと必ず片方だけ更新されて「ルールが嘘をつく」状態になるため。
+ *
+ * en: Single source of truth for the legacy -> new semantic token migration.
+ * Both the `check` anti-pattern rules and the planned `migrate` subcommand
+ * read from here, so the mapping can never drift between them.
+ *
+ * ## 設計の背景
+ *
+ * 旧セマンティック層は「意味名 + スケール値」（`bg-primary-500`）、新体系は
+ * 「用途 + 意味 + 強度 + 状態」（`bg-surface-primary-high-enabled`）で設計思想が
+ * 異なる。とくに **状態がトークン名に内包された**ことで、同じ旧クラスでも
+ * 文脈（Tailwind の variant 接頭辞）によって移行先が変わる。
+ *
+ * そのため単純な文字列置換表ではなく、次の 3 分類で返す:
+ *
+ * - `auto`       … 移行先が一意に決まる。値も変わらない
+ * - `review`     … 候補が複数ある / 対応する新トークンが無い。人間の判断が要る
+ * - `structural` … トークン差し替えでは済まない（マークアップ変更を伴う）
+ *
+ * ## 用途プレフィックスの対応
+ *
+ * Tailwind のユーティリティ接頭辞は、そのまま Figma の「用途」軸に対応する。
+ * `bg-` → surface（背景） / `text-` → text（文字） / `border-`・`divide-`・
+ * `outline-`・`ring-` → border（枠線） / `fill-`・`stroke-` → object（図形）。
+ *
+ * ## 値が変わらないことの保証
+ *
+ * 下の SCALE_MAP は「旧トークンが指していたプリミティブのレベル」を key に
+ * 「同じプリミティブを指す新トークン」を並べて作ってある（例: 旧
+ * `primary-600` と新 `surface-primary-high-enabled` はどちらも
+ * `var(--color-<primary>-600)`）。つまり `auto` 分類の変換は**見た目が変わらない**。
+ * この不変条件は test/token-migration.test.js が実際に生成した CSS を読んで
+ * 継続的に検証する（表と sparkle-variables のテンプレートが食い違ったら落ちる）。
+ * en: Every `auto` mapping is value-preserving by construction, and
+ * test/token-migration.test.js re-verifies that against generated CSS.
+ */
+
+export const MIGRATION_CLASS = {
+  AUTO: 'auto',
+  REVIEW: 'review',
+  STRUCTURAL: 'structural',
+};
+
+/** Tailwind ユーティリティ接頭辞 → Figma の用途カテゴリ */
+export const UTILITY_PREFIX_TO_CATEGORY = {
+  bg: 'surface',
+  text: 'text',
+  // placeholder-* も文字色。LEGACY_TOKEN_MAP 側で `placeholder-text-placeholder`
+  // を扱っているのにここに無いと、`placeholder-neutral-500` のようなスケール
+  // 形式だけが素通りする。
+  // en: `placeholder-*` is a text colour too — without it the scale form slips
+  // through while the standalone form is detected.
+  placeholder: 'text',
+  border: 'border',
+  divide: 'border',
+  outline: 'border',
+  ring: 'border',
+  fill: 'object',
+  stroke: 'object',
+};
+
+/** 旧セマンティック層のファミリー名。`secondary` は `neutral` に統合された */
+export const LEGACY_FAMILY_ALIASES = {
+  secondary: 'neutral',
+};
+
+export const LEGACY_FAMILIES = [
+  'primary',
+  'secondary',
+  'info',
+  'success',
+  'warning',
+  'negative',
+  'neutral',
+  'base',
+];
+
+export const LEGACY_LEVELS = ['50', '100', '200', '300', '400', '500', '600', '700', '800', '900'];
+
+/**
+ * 用途カテゴリ × ファミリー × 旧レベル → 新トークン名（`--color-` を除いた部分）。
+ * 値が配列のときは候補が複数あるという意味で、variant 接頭辞で絞れなければ
+ * `review` になる。
+ */
+const SCALE_MAP = {
+  surface: {
+    primary: {
+      600: 'surface-primary-high-enabled',
+      700: 'surface-primary-high-hover',
+      800: 'surface-primary-high-active',
+      50: ['surface-primary-middle-enabled', 'surface-primary-middle-disabled'],
+      100: 'surface-primary-middle-hover',
+      200: ['surface-primary-high-disabled', 'surface-primary-middle-active'],
+    },
+    negative: {
+      600: 'surface-negative-high-enabled',
+      700: 'surface-negative-high-hover',
+      800: 'surface-negative-high-active',
+      50: ['surface-negative-middle-enabled', 'surface-negative-middle-disabled'],
+      100: 'surface-negative-middle-hover',
+      200: ['surface-negative-high-disabled', 'surface-negative-middle-active'],
+    },
+    neutral: {
+      600: 'surface-neutral-high-enabled',
+      700: 'surface-neutral-high-hover',
+      800: 'surface-neutral-high-active',
+      50: ['surface-neutral-middle-enabled', 'surface-neutral-middle-disabled'],
+      100: 'surface-neutral-middle-hover',
+      200: ['surface-neutral-high-disabled', 'surface-neutral-middle-active'],
+    },
+    info: { 500: 'surface-info-high', 100: 'surface-info-middle', 50: 'surface-info-low' },
+    success: {
+      500: 'surface-success-high',
+      100: 'surface-success-middle',
+      50: 'surface-success-low',
+    },
+    warning: {
+      600: 'surface-warning-high',
+      100: 'surface-warning-middle',
+      50: 'surface-warning-low',
+    },
+    base: { 100: 'surface-base-100', 200: 'surface-base-200' },
+  },
+  text: {
+    primary: {
+      600: 'text-primary-enabled',
+      700: 'text-primary-hover',
+      800: 'text-primary-active',
+      200: 'text-primary-disabled',
+    },
+    negative: {
+      600: 'text-negative-enabled',
+      700: 'text-negative-hover',
+      800: 'text-negative-active',
+      200: 'text-negative-disabled',
+    },
+    neutral: {
+      900: 'text-neutral-high',
+      700: 'text-neutral-middle',
+      500: 'text-neutral-low',
+      300: 'text-neutral-disabled',
+    },
+    info: { 600: 'text-info' },
+    success: { 700: 'text-success' },
+    warning: { 700: 'text-warning' },
+  },
+  border: {
+    primary: {
+      500: 'border-primary-extra-high',
+      300: 'border-primary-high',
+      100: 'border-primary-low',
+    },
+    negative: {
+      500: 'border-negative-extra-high-enabled',
+      600: 'border-negative-extra-high-hover',
+      200: 'border-negative-extra-high-disabled',
+      300: 'border-negative-high',
+      100: 'border-negative-low',
+    },
+    neutral: {
+      500: 'border-neutral-extra-high-enabled',
+      600: 'border-neutral-extra-high-hover',
+      200: ['border-neutral-extra-high-disabled', 'border-neutral-middle'],
+      300: 'border-neutral-high',
+      100: 'border-neutral-low',
+    },
+    info: { 300: 'border-info' },
+    success: { 300: 'border-success' },
+    warning: { 300: 'border-warning' },
+  },
+  object: {
+    primary: {
+      600: 'object-primary-enabled',
+      700: 'object-primary-hover',
+      800: 'object-primary-active',
+      200: 'object-primary-disabled',
+    },
+    negative: {
+      600: 'object-negative-enabled',
+      700: 'object-negative-hover',
+      800: 'object-negative-active',
+      200: 'object-negative-disabled',
+    },
+    neutral: {
+      900: 'object-neutral-high',
+      700: 'object-neutral-middle',
+      500: 'object-neutral-low',
+      300: 'object-neutral-disabled',
+    },
+    info: { 600: 'object-info' },
+    success: { 700: 'object-success' },
+    warning: { 700: 'object-warning' },
+  },
+};
+
+/**
+ * スケールを持たない旧トークン（`--color-text-high` 等）の 1:1 対応。
+ * `sameValue` はどちらも同じプリミティブを指す＝見た目が変わらないという意味。
+ */
+export const LEGACY_TOKEN_MAP = [
+  { from: 'text-high', to: 'text-neutral-high', utilities: ['text'], sameValue: true },
+  { from: 'text-middle', to: 'text-neutral-middle', utilities: ['text'], sameValue: true },
+  { from: 'text-low', to: 'text-neutral-low', utilities: ['text'], sameValue: true },
+  { from: 'text-disabled', to: 'text-neutral-disabled', utilities: ['text'], sameValue: true },
+  {
+    from: 'text-placeholder',
+    to: 'text-neutral-low',
+    utilities: ['text', 'placeholder'],
+    sameValue: true,
+    classification: MIGRATION_CLASS.REVIEW,
+    reason:
+      'placeholder 専用トークンは新体系には無く、`text/neutral/low` に統合された（値は同じ gray/500）。' +
+      'placeholder と通常の低強度テキストを将来別の色にしたい場合は、統合してよいかを確認してから置換してください。',
+  },
+  {
+    from: 'divider-low',
+    to: 'border-neutral-low',
+    utilities: ['border', 'divide'],
+    sameValue: true,
+  },
+  {
+    from: 'divider-middle',
+    to: 'border-neutral-middle',
+    utilities: ['border', 'divide'],
+    sameValue: true,
+  },
+  {
+    from: 'divider-high',
+    to: 'border-neutral-high',
+    utilities: ['border', 'divide'],
+    sameValue: true,
+  },
+  { from: 'ring-normal', to: 'border-ring', utilities: ['ring', 'border'], sameValue: true },
+  {
+    from: 'skeleton-fill',
+    to: null,
+    utilities: ['bg'],
+    classification: MIGRATION_CLASS.REVIEW,
+    reason:
+      'Figma の `Colors: Semantics` に対応するトークンが無い。値が同じ `surface/neutral/middle/active`（gray/200）に寄せるか、' +
+      'スケルトン専用トークンを Figma 側に追加してもらうかをデザイナーと決めてください。',
+  },
+];
+
+/**
+ * beta 期間の後方互換エイリアス。beta 終了時に削除されるため、直接参照は
+ * 消えた瞬間にサイレントで壊れる（角丸が none になる）。
+ */
+export const DEPRECATED_VAR_ALIASES = [
+  {
+    from: '--radius-halfModal',
+    to: '--radius-container',
+    reason:
+      'Figma の `Borders: Semantics` で `halfModal` は `container` にリネームされた。' +
+      '`--radius-halfModal` は beta 期間だけ残す後方互換エイリアスで、削除されると角丸がサイレントに消える。',
+  },
+];
+
+/** Tailwind の variant 接頭辞 → 新トークンが内包する状態 */
+const VARIANT_TO_STATE = {
+  hover: 'hover',
+  active: 'active',
+  disabled: 'disabled',
+  'aria-disabled': 'disabled',
+  'data-disabled': 'disabled',
+};
+
+/**
+ * variant チェーン全体から、新トークンが内包する状態を割り出す。
+ *
+ * 最後のセグメントだけを見ると `group-hover:` / `peer-hover:` / `dark:hover:` を
+ * 取りこぼす。実コードで最頻の `group-hover:` が「候補が 1 件しか無いのに要判断」
+ * に落ちていたため、全セグメントを走査し `group-` / `peer-` 接頭と `[` `]` を
+ * 剥がしてから対応表を引く。
+ *
+ * `not-hover:` のような否定 variant は剥がした後も対応表に無いので `null` に
+ * なる（= 状態で絞り込まない）。ここで hover 扱いにすると意味が反転するため、
+ * 部分一致ではなく完全一致で引くことが重要。
+ * en: Scan every variant segment (not just the last) and strip `group-`/`peer-`
+ * so `group-hover:` resolves. Uses exact lookup, never substring matching —
+ * `not-hover:` must not be read as `hover`.
+ *
+ * @param {string} variantPrefix 例 `dark:group-hover:`
+ * @returns {string | null}
+ */
+function splitVariantSegments(variantPrefix) {
+  // `supports-[display:grid]:` のように角括弧の中に `:` を含む variant があるため、
+  // 素朴な `split(':')` では `grid]` のような壊れたセグメントができる。さらに
+  // `supports-[&:hover]:` だと `hover]` → 角括弧を剥がすと `hover` になり、
+  // **hover 状態のトークンだと誤判定して意味の違うトークンを案内してしまう**
+  // （同じレベルの候補は同じプリミティブを指すので色は変わらないが、
+  // トークン名が表す意味がずれる）。角括弧の外側の `:` だけで区切る。
+  // en: Split only on colons outside brackets — `supports-[&:hover]:` would
+  // otherwise yield a `hover]` segment and be misread as the hover state.
+  const segments = [];
+  let current = '';
+  let depth = 0;
+  for (const char of variantPrefix) {
+    if (char === '[') depth += 1;
+    else if (char === ']') depth = Math.max(0, depth - 1);
+    if (char === ':' && depth === 0) {
+      if (current) segments.push(current);
+      current = '';
+      continue;
+    }
+    current += char;
+  }
+  if (current) segments.push(current);
+  return segments;
+}
+
+function variantState(variantPrefix) {
+  for (const segment of splitVariantSegments(variantPrefix)) {
+    // `group-` / `peer-` を先に剥がしてから判定する。順序を逆にすると
+    // `group-data-[disabled]:` が「括弧つき = 判定に使わない」に落ちて、
+    // `group-hover:` は解決できるのにこちらはできない、という不整合になる。
+    const withoutScope = segment.replace(/^(?:group|peer)-/, '');
+    // 角括弧つきの arbitrary variant（`supports-[...]` / `[&:hover]`）は
+    // 状態の判定に使わない。`data-[disabled]` のような Tailwind 標準形だけ
+    // 括弧を剥がして引く。
+    const normalized = /^(?:data|aria)-\[[a-z-]+\]$/.test(withoutScope)
+      ? withoutScope.replace(/[[\]]/g, '')
+      : withoutScope;
+    if (normalized.includes('[')) continue;
+    if (VARIANT_TO_STATE[normalized]) return VARIANT_TO_STATE[normalized];
+  }
+  return null;
+}
+
+const STATE_SUFFIXES = ['enabled', 'hover', 'active', 'disabled'];
+
+function tokenState(tokenName) {
+  const last = tokenName.split('-').pop();
+  return STATE_SUFFIXES.includes(last) ? last : null;
+}
+
+/**
+ * `base-*` は旧体系では gray（= `neutral`）と同値。ただし Figma には
+ * `surface/base/*`（ページ地の背景）という専用トークンがあるので、surface では
+ * それを優先し、対応レベルが無いところだけ `neutral` で埋める。
+ * text / border / object には `base` が無いので全面的に `neutral` を使う。
+ * en: `base-*` equals gray. Prefer Figma's dedicated `surface/base/*` where it
+ * exists and fall back to `neutral` elsewhere — both resolve to the same
+ * primitive, so the substitution stays value-preserving.
+ */
+function familyScaleMap(category, family) {
+  const byFamily = SCALE_MAP[category] ?? {};
+  if (family !== 'base') return byFamily[family];
+  const merged = { ...(byFamily.neutral ?? {}), ...(byFamily.base ?? {}) };
+  return Object.keys(merged).length > 0 ? merged : undefined;
+}
+
+// Tailwind の opacity modifier（`/50`・`/[0.6]`）と important（末尾 `!`）。
+// これらを落としたまま「自動変換可」として置換先を案内すると、案内どおりに
+// 直したときに**不透明度や詳細度が黙って変わる**。`auto` は見た目が変わらない、
+// という本モジュールの中心的な保証が破れる唯一の経路なので、必ず持ち回して
+// 置換先の末尾に付け直す。
+// en: Carry the opacity modifier / important flag through to the replacement.
+// Dropping them would silently change opacity or specificity, breaking the
+// "auto conversions are value-preserving" guarantee.
+// 角括弧つきの arbitrary value（`/[var(--x)]` `/[calc(1/3)]`）は括弧の中に
+// `(` `/` を含むため、単純な文字クラスでは途中で切れてしまう。切れたまま
+// 「自動変換可」として案内すると、案内どおり直したクラスが壊れる。
+// en: Bracketed arbitrary modifiers contain `(` and `/`, so a plain character
+// class truncates them and would emit a broken replacement.
+const MODIFIER_BODY = '(?:\\[[^\\]\\s]*\\]|[A-Za-z0-9._%-]+)';
+const MODIFIER_SUFFIX_PATTERN = new RegExp(`^(.*?)((?:\\/${MODIFIER_BODY})?!?)$`);
+
+/**
+ * ユーティリティクラス 1 個を解析して移行結果を返す。
+ *
+ * @param {string} utility 例 `hover:bg-primary-700` / `text-text-high`
+ * @returns {null | {
+ *   input: string,
+ *   classification: 'auto'|'review'|'structural',
+ *   replacement?: string,
+ *   candidates?: string[],
+ *   reason?: string,
+ * }} 旧トークンを使っていなければ null
+ */
+export function resolveLegacyUtility(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);
+
+  // Tailwind v3 形式の先頭 `!` を切り離して置換先に付け直す
+  const importantPrefix = rawBare.startsWith('!') ? '!' : '';
+  if (importantPrefix) rawBare = rawBare.slice(1);
+
+  // opacity modifier / important を切り離してから解析し、置換先に付け直す
+  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);
+
+  const wrap = (result) => ({ input: utility, ...result });
+  const withVariant = (tokenName) =>
+    `${variantPrefix}${importantPrefix}${prefix}-${tokenName}${modifier}`;
+
+  // 1. スケールを持たない旧トークン
+  const direct = LEGACY_TOKEN_MAP.find(
+    (entry) => entry.from === rest && entry.utilities.includes(prefix)
+  );
+  if (direct) {
+    if (!direct.to) {
+      return wrap({ classification: MIGRATION_CLASS.REVIEW, reason: direct.reason });
+    }
+    return wrap({
+      classification: direct.classification ?? MIGRATION_CLASS.AUTO,
+      replacement: withVariant(direct.to),
+      reason: direct.reason,
+    });
+  }
+
+  // 2. 「意味名 + スケール値」形式
+  const category = UTILITY_PREFIX_TO_CATEGORY[prefix];
+  if (!category) return null;
+
+  const scaleMatch = /^([a-z]+)-(\d{2,3})$/.exec(rest);
+  if (!scaleMatch) return null;
+  const rawFamily = scaleMatch[1];
+  const level = scaleMatch[2];
+  if (!LEGACY_FAMILIES.includes(rawFamily) || !LEGACY_LEVELS.includes(level)) return null;
+
+  const family = LEGACY_FAMILY_ALIASES[rawFamily] ?? rawFamily;
+  const familyMap = familyScaleMap(category, family);
+  if (!familyMap) {
+    return wrap({
+      classification: MIGRATION_CLASS.REVIEW,
+      reason:
+        `${prefix}-（用途: ${category}）と ${rawFamily} の組み合わせに対応する新トークンがありません。` +
+        'Figma の該当箇所を見て用途から選び直してください。',
+    });
+  }
+
+  const raw = familyMap[level];
+  if (!raw) {
+    return wrap({
+      classification: MIGRATION_CLASS.REVIEW,
+      reason:
+        `${rawFamily}-${level} をそのまま引き継ぐ ${category} トークンはありません（新体系は用途ごとに使うレベルを絞っている）。` +
+        `利用可能: ${Object.values(familyMap).flat().join(', ')}`,
+    });
+  }
+
+  const candidates = Array.isArray(raw) ? raw : [raw];
+
+  // variant 接頭辞（hover: / group-hover: / disabled: 等）があれば状態で絞り込む
+  const variantName = variantPrefix.replace(/:$/, '') || '(なし)';
+  const wantedState = variantState(variantPrefix);
+  if (wantedState) {
+    const matched = candidates.filter((token) => tokenState(token) === wantedState);
+    if (matched.length === 1) {
+      return wrap({ classification: MIGRATION_CLASS.AUTO, replacement: withVariant(matched[0]) });
+    }
+    if (matched.length > 1) {
+      // 状態で絞ってもなお複数残る場合。絞り込み前の candidates を出すと
+      // 状態が合わない候補まで並べてしまうので、絞った結果だけを見せる。
+      // en: Report the state-filtered candidates, not the unfiltered set.
+      return wrap({
+        classification: MIGRATION_CLASS.REVIEW,
+        candidates: matched,
+        reason:
+          `variant \`${variantName}:\` で状態を絞っても移行先が一意に決まりません（${matched.join(' / ')}）。` +
+          '用途を確認して選んでください。',
+      });
+    }
+    if (matched.length === 0 && candidates.some((token) => tokenState(token) !== null)) {
+      // `hover:bg-primary-600` のように「variant は hover なのにレベルは enabled 相当」なケース。
+      // 機械的に置換すると hover 時の色が変わってしまうので必ず人間に返す。
+      return wrap({
+        classification: MIGRATION_CLASS.REVIEW,
+        candidates,
+        reason:
+          `variant は \`${variantName}:\` ですが、${rawFamily}-${level} が対応するのは ` +
+          `${candidates.join(' / ')} で状態が一致しません。意図した状態のトークンを選んでください。`,
+      });
+    }
+  }
+
+  if (candidates.length === 1) {
+    const token = candidates[0];
+    const state = tokenState(token);
+    if (state && state !== 'enabled' && !wantedState) {
+      // 状態つきトークンなのに variant が無い＝どの状態で使っているか判断できない
+      return wrap({
+        classification: MIGRATION_CLASS.REVIEW,
+        candidates,
+        reason:
+          `${rawFamily}-${level} の移行先 \`${token}\` は状態を内包しています。` +
+          `variant 接頭辞が無いため、どの状態で使っているかコードを見て判断してください。`,
+      });
+    }
+    return wrap({ classification: MIGRATION_CLASS.AUTO, replacement: withVariant(token) });
+  }
+
+  return wrap({
+    classification: MIGRATION_CLASS.REVIEW,
+    candidates,
+    reason:
+      `${rawFamily}-${level} の移行先が一意に決まりません（${candidates.join(' / ')}）。` +
+      'variant 接頭辞が無いか、強度違いで同じレベルを共有しているためです。',
+  });
+}
+
+// --- check ルール用のパターン生成 -------------------------------------------
+
+// Tailwind のクラス名は `-` で連結されるため `\b` だと `border-ring-normal` の
+// 中の `ring-normal` にもマッチしてしまう。`[\w-]` を境界にして誤検出を防ぐ。
+// en: Use `[\w-]` boundaries — `\b` would match `ring-normal` inside
+// `border-ring-normal` and double-report.
+const NOT_CLASS_CHAR_BEFORE = '(?<![\\w-])';
+const NOT_CLASS_CHAR_AFTER = '(?![\\w-])';
+
+// 空配列を `join('|')` すると空文字になり、`(?:)` が**あらゆる位置の空文字に
+// マッチする**正規表現ができてしまう（ルールが死ぬのではなく、全ファイルが
+// 誤検出で埋まる）。beta 終了時に DEPRECATED_VAR_ALIASES / LEGACY_TOKEN_MAP を
+// 空にする計画があるため、そのときに踏む地雷を今のうちに潰しておく。
+// en: `join('|')` on an empty list yields `(?:)`, which matches the empty string
+// everywhere. Emptying these tables is planned for the end of beta, so guard now.
+function alternation(values) {
+  if (values.length === 0) {
+    throw new Error(
+      'alternation() に空配列が渡されました。空の選択肢は「全位置にマッチする正規表現」になるため許容しません。' +
+        '対象のテーブルが空になったなら、対応するルール自体を削除してください。'
+    );
+  }
+  // 長いものを先に並べて、部分一致で短い方が先に食われないようにする
+  return [...values].sort((a, b) => b.length - a.length).join('|');
+}
+
+// Tailwind の variant 接頭辞チェーン（`hover:` / `focus-visible:` /
+// `group-hover:` / `data-[state=open]:` …）をマッチに含める。
+//
+// これが無いと `hover:bg-primary-700` のマッチ文字列が `bg-primary-700` だけに
+// なり、状態を内包する新トークンへの移行先が「variant が無いので判断不能」と
+// 誤って要判断に落ちる。実コードでは状態つきの旧クラスはほぼ必ず variant と
+// セットで書かれているため、ここを取りこぼすと自動変換可のものが大量に
+// 要判断へ流れてしまう。
+// en: Include Tailwind's variant chain in the match. Without it,
+// `hover:bg-primary-700` matches as bare `bg-primary-700` and gets
+// misclassified as "needs review" for lack of a variant — which is most of
+// the state-bearing legacy classes in real code.
+const VARIANT_CHAIN = '(?:[a-z][a-z0-9-]*(?:\\[[^\\]\\s]*\\])?:)*';
+
+// opacity modifier（`/50` `/[0.6]`）と important（末尾 `!`）もマッチに含める。
+// 含めないと `bg-primary-600/50` が `bg-primary-600` として拾われ、案内する
+// 置換先から `/50` が消えて不透明度が黙って変わる（MODIFIER_SUFFIX_PATTERN
+// のコメント参照）。
+// en: Include the opacity modifier / important flag in the match so they can be
+// carried over to the replacement instead of being silently dropped.
+const MODIFIER_SUFFIX = `(?:\\/${MODIFIER_BODY})?!?`;
+// Tailwind v3 形式の先頭 `!`（`!bg-primary-600`）。v4 は末尾 `!` だが、
+// 移行対象のコードベースには v3 記法が残っていることがある。
+const IMPORTANT_PREFIX = '!?';
+
+/** `bg-primary-500` / `hover:bg-primary-700/50` のような「意味名 + スケール値」形式を検出する */
+export function buildLegacyScalePattern() {
+  const prefixes = alternation(Object.keys(UTILITY_PREFIX_TO_CATEGORY));
+  const families = alternation(LEGACY_FAMILIES);
+  const levels = alternation(LEGACY_LEVELS);
+  return new RegExp(
+    `${NOT_CLASS_CHAR_BEFORE}${VARIANT_CHAIN}${IMPORTANT_PREFIX}(?:${prefixes})-(?:${families})-(?:${levels})${NOT_CLASS_CHAR_AFTER}${MODIFIER_SUFFIX}`,
+    'g'
+  );
+}
+
+/** `text-text-high` / `bg-divider-low` のようなスケール無し旧トークンを検出する正規表現 */
+export function buildLegacyTokenPattern() {
+  const classNames = LEGACY_TOKEN_MAP.flatMap((entry) =>
+    entry.utilities.map((prefix) => `${prefix}-${entry.from}`)
+  );
+  return new RegExp(
+    `${NOT_CLASS_CHAR_BEFORE}${VARIANT_CHAIN}${IMPORTANT_PREFIX}(?:${alternation(classNames)})${NOT_CLASS_CHAR_AFTER}${MODIFIER_SUFFIX}`,
+    'g'
+  );
+}
+
+/**
+ * `var(--color-ring-normal)` のような **CSS 変数の直接参照**を検出する正規表現。
+ *
+ * 実際のコードでは `ring-[var(--color-ring-normal)]` のように arbitrary value
+ * 経由で参照されることが多く（sparkle-design だけで 14 箇所）、ユーティリティ
+ * クラスのパターンだけでは 1 件も拾えない。
+ * en: Real code references these through arbitrary values, so the utility-class
+ * pattern alone would miss every occurrence.
+ */
+export function buildLegacyCssVarPattern() {
+  const standalone = LEGACY_TOKEN_MAP.map((entry) => `--color-${entry.from}`);
+  const scaled = LEGACY_FAMILIES.flatMap((family) =>
+    LEGACY_LEVELS.map((level) => `--color-${family}-${level}`)
+  );
+  return new RegExp(
+    `${NOT_CLASS_CHAR_BEFORE}(?:${alternation([...standalone, ...scaled])})${NOT_CLASS_CHAR_AFTER}`,
+    'g'
+  );
+}
+
+/**
+ * CSS 変数名 1 個を解析して移行結果を返す。
+ *
+ * スケール付きの旧トークン（`--color-primary-600`）は、変数名だけでは用途
+ * （surface / text / border / object）が分からないため必ず `review` になる。
+ * どの用途で使っているかは参照側のコードを見ないと決まらない。
+ *
+ * @param {string} varName 例 `--color-ring-normal`
+ * @returns {null | { input: string, classification: string, replacement?: string, candidates?: string[], reason?: string }}
+ */
+export function resolveLegacyCssVar(varName) {
+  if (typeof varName !== 'string') return null;
+  const alias = DEPRECATED_VAR_ALIASES.find((entry) => entry.from === varName);
+  if (alias) {
+    return {
+      input: varName,
+      classification: MIGRATION_CLASS.AUTO,
+      replacement: alias.to,
+      reason: alias.reason,
+    };
+  }
+
+  if (!varName.startsWith('--color-')) return null;
+  const tokenName = varName.slice('--color-'.length);
+
+  const direct = LEGACY_TOKEN_MAP.find((entry) => entry.from === tokenName);
+  if (direct) {
+    if (!direct.to) {
+      return { input: varName, classification: MIGRATION_CLASS.REVIEW, reason: direct.reason };
+    }
+    return {
+      input: varName,
+      classification: direct.classification ?? MIGRATION_CLASS.AUTO,
+      replacement: `--color-${direct.to}`,
+      reason: direct.reason,
+    };
+  }
+
+  const scaleMatch = /^([a-z]+)-(\d{2,3})$/.exec(tokenName);
+  if (!scaleMatch) return null;
+  const rawFamily = scaleMatch[1];
+  const level = scaleMatch[2];
+  if (!LEGACY_FAMILIES.includes(rawFamily) || !LEGACY_LEVELS.includes(level)) return null;
+
+  const family = LEGACY_FAMILY_ALIASES[rawFamily] ?? rawFamily;
+  const candidates = Object.keys(SCALE_MAP)
+    .flatMap((category) => familyScaleMap(category, family)?.[level] ?? [])
+    .map((token) => `--color-${token}`);
+
+  return {
+    input: varName,
+    classification: MIGRATION_CLASS.REVIEW,
+    candidates,
+    reason:
+      candidates.length > 0
+        ? `変数名だけでは用途（surface / text / border / object）が決まらないため自動変換しません。用途に応じて選んでください。`
+        : `${rawFamily}-${level} に対応する新トークンがありません。Figma の該当箇所を見て選び直してください。`,
+  };
+}
+
+/** `--radius-halfModal` のような削除予定エイリアスへの直接参照を検出する正規表現 */
+export function buildDeprecatedAliasPattern() {
+  const names = DEPRECATED_VAR_ALIASES.map((entry) => entry.from);
+  return new RegExp(
+    `${NOT_CLASS_CHAR_BEFORE}(?:${alternation(names)})${NOT_CLASS_CHAR_AFTER}`,
+    'g'
+  );
+}
+
+export { SCALE_MAP, familyScaleMap };