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

package/lib/token-migration.js

@@ -0,0 +1,888 @@
+/**
+ * 旧セマンティックトークン → 新セマンティックトークンの移行マッピング。
+ *
+ * このファイルが移行知識の唯一の 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'
+  );
+}
+
+// --- 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 個を解析して移行結果を返す。
+ *
+ * スケール付きの旧トークン（`--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 };