sparkle-design-cli 2.5.0-beta.3 → 2.5.0-beta.4

package/README.md

@@ -74,6 +74,9 @@ npx sparkle-design-cli check src --format json
 # 現在有効なアンチパターンルールを一覧表示（プラグイン由来のものも含む）
 npx sparkle-design-cli rules
 
+# 旧セマンティックトークンを新トークンへ移行（既定は dry-run。--write で書き換え）
+npx --yes sparkle-design-cli migrate
+
 # Artifact Registry の npm registry 用トークンを ~/.npmrc に書く（beta）
 npx --yes sparkle-design-cli@beta auth
 ```
@@ -200,6 +203,21 @@ npx sparkle-design-cli rules --format json
 
 AI エージェントや CI からこの `lint:sparkle` を呼ぶ運用にすると、ガイドラインの注意書きだけに頼らず機械的に検査できます。
 
+### migrate: 新セマンティックトークンへの移行
+
+`check` が警告する旧セマンティックトークン（`bg-primary-600` / `var(--radius-halfModal)` など）を新トークンへ書き換えます。
+
+```bash
+npx --yes sparkle-design-cli migrate                       # src を dry-run（変更内容を diff 形式で表示するだけ）
+npx --yes sparkle-design-cli migrate --write               # [自動変換可] の箇所だけ書き換える
+npx --yes sparkle-design-cli migrate --include 'src/components/**/*.tsx'
+```
+
+- **既定は dry-run** で、`--write` を付けたときだけファイルを書き換えます。探索範囲は `check` と同じです（既定 `src`、パスを並べて指定可）
+- 書き換えるのは移行先が一意に決まり値も変わらない `[自動変換可]` だけです。`[要判断]`（候補が複数ある等）と `[構造変更あり]` は報告するだけで置換しません
+
+分類の考え方は [docs/anti-patterns.md](docs/anti-patterns.md#新セマンティックトークンへの移行beta-期間中) を参照してください。
+
 ### auth: Artifact Registry の認証（beta）
 
 社内パッケージの配信先を Google Artifact Registry（AR）に移行するための準備です（goodpatch/sparkle-design-internal#261）。Google の資格情報から AR 用のアクセストークンを取得し、ユーザー単位の `~/.npmrc` に書きます。

package/bin/sparkle-design.js

@@ -8,11 +8,13 @@ import { PLUGIN_SPEC_MARKDOWN } from '../lib/plugin-api.js';
 import { loadAntiPatternPlugins } from '../lib/load-plugins.js';
 import { runRules } from '../lib/rules-report.js';
 import { runAuth } from '../lib/auth.js';
+import { runMigrate } from '../lib/migrate.js';
 
 const SUBCOMMANDS = new Set([
   'generate',
   'check',
   'rules',
+  'migrate',
   'setup',
   'auth',
   'stop-hook',
@@ -179,6 +181,43 @@ function parseRulesOptions(args) {
   return options;
 }
 
+/**
+ * `migrate` のオプション。
+ *
+ * 既定は dry-run。`--write` を付けたときだけファイルを書き換える（不可逆操作を
+ * デフォルトにしない）。`--dry-run` は既定と同じだが、明示したい人のために受け付ける。
+ * 両方指定は意図が矛盾するのでその場で失敗させる。
+ * en: Dry-run by default; only `--write` rewrites files. `--dry-run` together
+ * with `--write` is contradictory and fails fast.
+ */
+function parseMigrateOptions(args) {
+  const options = { targets: [], includes: [], write: false, dryRun: false, help: false };
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === '-h' || arg === '--help') {
+      options.help = true;
+    } else if (arg === '--write') {
+      options.write = true;
+    } else if (arg === '--dry-run') {
+      options.dryRun = true;
+    } else if (arg === '--include') {
+      options.includes.push(requireOptionValue(args, i, '--include'));
+      i += 1;
+    } else if (arg.startsWith('-')) {
+      throw new Error(`Unknown option for migrate: ${arg}`);
+    } else {
+      options.targets.push(arg);
+    }
+  }
+
+  if (options.write && options.dryRun) {
+    throw new Error('--write と --dry-run は同時に指定できません');
+  }
+
+  return options;
+}
+
 /**
  * `auth` のオプション。未知のフラグはその場で失敗させる（他のサブコマンドと同じ）。
  * en: Unknown flags fail fast, same as the other subcommands.
@@ -214,6 +253,7 @@ Commands:
   generate     sparkle.config.json から CSS を生成
   check        Sparkle Design のアンチパターンを検査
   rules        現在有効なアンチパターンルールを一覧表示（プラグイン由来のものも含む）
+  migrate      旧セマンティックトークンを新トークンへ移行（既定は dry-run。--write で書き換え）
   setup        Sparkle Design プロジェクトをセットアップ（パッケージ導入 + 初期ファイル + AI ガード + generate）
   auth         Artifact Registry の npm registry 用アクセストークンを ~/.npmrc に書く（beta）
   stop-hook    AI assistant の Stop hook 用 internal subcommand（severity=error の findings か、
@@ -237,6 +277,12 @@ Check:
   sparkle-design-cli check src --format json
   sparkle-design-cli check src/components src/features
 
+Migrate:
+  sparkle-design-cli migrate                                   # src を dry-run（変更内容を表示するだけ）
+  sparkle-design-cli migrate --include 'src/components/**/*.tsx'
+  sparkle-design-cli migrate --write                           # [自動変換可] の箇所だけ書き換える
+  sparkle-design-cli migrate src/app src/features --write
+
 Rules:
   sparkle-design-cli rules                 # 有効なルールを severity 別に一覧表示
   sparkle-design-cli rules --format json   # CI / AI 向け
@@ -313,6 +359,23 @@ Check options:
                              （warning / info は報告のみで exit code に影響しない）
   --format <text|json>       出力形式 (default: text)
 
+Migrate options:
+  -h, --help                 このヘルプメッセージを表示
+  [path ...]                 探索するパス（default: src。check と同じ探索範囲。
+                             .js / .jsx / .ts / .tsx / .css、node_modules と .git は除外）
+  --dry-run                  ファイルを変更せず、変更内容を diff 形式で表示する（既定）
+  --write                    [自動変換可] の箇所だけを書き換える
+  --include <glob>           対象を cwd からの相対パス（cwd の外は絶対パス）が glob に
+                             マッチするファイルに絞る（複数指定可。** / * / ? / {a,b} に対応）
+
+Migrate の分類:
+  自動変換可     bg- / text- / border- などの用途と variant 接頭辞（hover: 等）から移行先が
+                 一意に決まり、値も変わらないもの。--write のときだけ置換する
+  要判断         移行先候補が複数ある / 対応する新トークンが無いもの。候補を表示するだけで置換しない
+  構造変更あり   トークンの差し替えでは済まない（マークアップ変更を伴う）もの。指摘するだけで置換しない
+  対応表は check の移行ルールと共通（lib/token-migration.js）。check で抑制コメント
+  （sparkle-disable-line <rule-id>）を付けた箇所は migrate でも書き換えない
+
 Auth options:
   -h, --help                 このヘルプメッセージを表示
   --registry <url>           対象の registry（default: プロジェクトの .npmrc の @goodpatch:registry）
@@ -501,6 +564,16 @@ async function main() {
       return;
     }
 
+    if (command === 'migrate') {
+      const options = parseMigrateOptions(args.slice(1));
+      if (options.help) {
+        showHelp();
+        process.exit(0);
+      }
+      runMigrate({ targets: options.targets, includes: options.includes, write: options.write });
+      return;
+    }
+
     if (command === 'plugin-spec') {
       await runPluginSpec(args.slice(1));
       return;

package/docs/anti-patterns.md

@@ -55,6 +55,27 @@ src/Card.tsx:8 [warning] [legacy-color-token] 旧セマンティックカラー
 >
 > 旧→新の対応表は `lib/token-migration.js` に一元化してあり、`test/token-migration.test.js` が**実際に生成した CSS を読んで**「表に書いた移行先が実在し、旧トークンと同じ実値に解決される」ことを検証しています。表とトークン定義が食い違ったらテストが落ちるので、案内が嘘になりません。検出パターンがマッチする文字列は必ず対応表で解決できることも全数検証しています（片方だけ更新すると「検出したのに黙って捨てる」穴になるため）。
 
+### `migrate` で書き換える
+
+`check` が提示する移行先のうち `[自動変換可]` のものは、`migrate` サブコマンドでまとめて書き換えられます。対応表は `check` と同じ `lib/token-migration.js` を使うので、`check` の案内と `migrate` の書き換え先が食い違うことはありません。
+
+```bash
+npx --yes sparkle-design-cli migrate          # dry-run。変更内容を diff 形式で表示するだけ
+npx --yes sparkle-design-cli migrate --write  # [自動変換可] の箇所だけ書き換える
+```
+
+| 分類         | `migrate` の挙動                                                                                                             |
+| ------------ | ---------------------------------------------------------------------------------------------------------------------------- |
+| 自動変換可   | 用途（`bg-` / `text-` / `border-` …）と variant 接頭辞から移行先が一意に決まり、値も変わらない。`--write` のときだけ置換する |
+| 要判断       | 移行先候補が複数ある / 対応する新トークンが無い。候補を列挙するだけで置換しない                                              |
+| 構造変更あり | トークンの差し替えでは済まない（マークアップ変更を伴う）。該当箇所を指摘するだけ                                             |
+
+- variant 接頭辞（`hover:` / `group-hover:` / `dark:` …）、opacity modifier（`/50`）、important（`!`）は置換後もそのまま残ります
+- `check` で報告しないもの（そのファイル自身が宣言している変数・行頭から始まるブロックコメント）は `migrate` も書き換えません。`sparkle-disable-line legacy-color-token` などの抑制コメントを付けた箇所も書き換えません（誤検出を抑制した箇所を黙って書き換えないため）
+- 書き換えた後に 2 回目を実行しても、`migrate` の `[自動変換可]` は 0 件になります（新トークンは検出パターンにマッチしない）
+- **`check` が `[自動変換可]` と案内しても、`migrate` が `[要判断]` として書き換えずに残す箇所があります。** 検出はファイル全体への正規表現なので、パス（`'/img/fill-primary-600.svg'` / `"bg-primary-600/hero.png"`）、import / require の specifier、`url()` の中のようなクラス名でない文字列にもマッチします。`check` は報告するだけなので案内を変えていませんが、`migrate` は資産パスや import を壊さないよう、これらと数値・角括弧以外の modifier（`/data.json` など）付きのものを書き換えません。クラス名として使っている箇所なら手で置き換えてください
+- `--include <glob>` で対象を cwd からの相対パスで絞れます（`**` / `*` / `?` / `{a,b}`）
+
 ## 余白のスケール（`use-figma-spacing-scale`）
 
 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 が対応します。このスケールから外れた値を `info` で報告し、前後の候補を提示します。

package/lib/anti-pattern-rules.js

@@ -10,6 +10,7 @@ import {
   resolveTailwindPaletteUtility,
 } from './token-migration.js';
 import { buildSpacingUtilityPattern, pxToStep, resolveSpacingStep } from './spacing-scale.js';
+import { findOpeningTagEnd } from './plugin-helpers.js';
 
 const COMMON_INTRO =
   '以下は頻繁に発生する誤用パターンです。コンポーネントが提供する専用 props・サブコンポーネントを使ってください。';
@@ -136,6 +137,93 @@ const BUILTIN_MANUAL_REVIEW_REMINDERS = [
   },
 ];
 
+// --- JSX 開きタグを扱う match 用の小道具 ----------------------------------------
+//
+// フォーム系の a11y ルール（form-control-select-root / handwritten-radio-role /
+// handwritten-form-error）は「どのタグの属性か」「直下の子は何か」を見る必要があり、
+// 1 本の regex では prop 値中の `=>` や `{...}` で打ち切られる。プラグインに注入して
+// いる findOpeningTagEnd を組み込みルールでも使い、同じパース実装に揃える。
+// en: Helpers for the form a11y rules, built on the same findOpeningTagEnd that
+// plugins receive, so built-in and plugin rules share one tag scanner.
+
+// カスタム要素（`<my-radio>`）も拾えるよう `-` を許す
+// en: Allow `-` so custom elements such as `<my-radio>` are scanned too.
+const JSX_OPENING_TAG = /<([A-Za-z][\w.-]*)(?=[\s/>])/g;
+
+function blankOut(text) {
+  return text.replace(/[^\n]/g, ' ');
+}
+
+/**
+ * コメント中の疑似 JSX（`// Radix は <button role="radio"> を描画する` のような説明）を
+ * 検出しないよう、コメントを同じ長さの空白で潰す。index と行番号はずれない。
+ * 行頭からのブロックコメント（maskBlockComments と同じ前提）・JSX コメント
+ * `{/* ... *\/}`・行頭からの `//` コメントが対象。
+ * en: Blank out comments (same length, so offsets stay valid) so explanatory
+ * pseudo-JSX inside comments is not reported.
+ */
+function maskSourceComments(content) {
+  return maskBlockComments(content)
+    .replace(/\{\s*\/\*(?:(?!\*\/)[\s\S])*\*\/\s*\}/g, blankOut)
+    .replace(/^[ \t]*\/\/.*$/gm, blankOut);
+}
+
+/**
+ * `index` から始まる開きタグを読む。読めなければ null。
+ * en: Read the opening tag starting at `index`, or null.
+ */
+function readOpeningTag(content, index, tagName) {
+  const bodyStart = index + 1 + tagName.length;
+  const end = findOpeningTagEnd(content, bodyStart);
+  if (end === -1) return null;
+  const props = content.slice(bodyStart, end);
+  return {
+    index,
+    end,
+    tagName,
+    props,
+    selfClosing: props.trimEnd().endsWith('/'),
+    text: content.slice(index, end + 1),
+  };
+}
+
+/**
+ * `index` の直前にある「閉じていない開きタグ」（＝親要素）を返す。直前が
+ * whitespace を挟んで開きタグの `>` で終わっている場合だけを親とみなす
+ * （テキストや兄弟要素を挟む場合は追わない。ヒューリスティック用途のため）。
+ * en: The opening tag that immediately precedes `index` (only whitespace in
+ * between), i.e. the direct parent in the common `<span><Icon /></span>` shape.
+ */
+function findImmediateParentTag(content, index) {
+  const windowStart = Math.max(0, index - 2000);
+  const before = content.slice(windowStart, index);
+  const trimmed = before.trimEnd();
+  if (!trimmed.endsWith('>') || trimmed.endsWith('/>')) return null;
+  const closeAt = windowStart + trimmed.length - 1;
+  // 走査を closeAt までに切る。content 全体を渡すと、閉じ `>` が遠い候補（TS の
+  // ジェネリクスなど）ごとにファイル末尾まで走査してしまう。
+  // en: Bound the scan at closeAt so each candidate can't walk to EOF.
+  const bounded = content.slice(0, closeAt + 1);
+  let parent = null;
+  for (const opener of before.matchAll(JSX_OPENING_TAG)) {
+    const tag = readOpeningTag(bounded, windowStart + opener.index, opener[1]);
+    if (tag && tag.end === closeAt && !tag.selfClosing) parent = tag;
+  }
+  return parent;
+}
+
+// role="radio" / role="radiogroup"（JSX 式 `role={"radio"}` も）。`aria-role` /
+// `data-role` を拾わないよう、直前を空白か先頭に限る。
+// en: role="radio" / role="radiogroup", excluding aria-role / data-role.
+const RADIO_ROLE_ATTR =
+  /(?:^|\s)role\s*=\s*(?:(["'])(?:radio|radiogroup)\1|\{\s*(["'`])(?:radio|radiogroup)\2\s*\})/;
+
+const ERROR_ICON_ATTR = /(?:^|\s)icon\s*=\s*(?:(["'])error\1|\{\s*(["'`])error\2\s*\})/;
+
+// 旧体系 `text-negative-500` と新体系 `text-text-negative-enabled` の両方
+// en: Both the legacy (`text-negative-*`) and new (`text-text-negative-*`) tokens.
+const NEGATIVE_TEXT_COLOR = /(?<![\w-])text-(?:text-)?negative-[\w-]+/;
+
 const COMPONENT_ANTI_PATTERN_GROUPS = [
   {
     id: 'card-description',
@@ -1302,6 +1390,239 @@ const COMPONENT_ANTI_PATTERN_GROUPS = [
     ]),
     jsdocTargets: [],
   },
+  {
+    id: 'form-control-select-root',
+    check: {
+      description: 'FormControl で Select のルートを包まない（ラベルが関連付かない）',
+      recommendation:
+        'FormControl は SelectTrigger を包んでください（<Select><FormControl><SelectTrigger>…</SelectTrigger></FormControl><SelectContent>…</SelectContent></Select>）。FormControl は id / aria-describedby / aria-invalid を直下の子へ渡しますが、Select のルートは DOM を持たないため id がどこにも付かず、FormHeader の <label for> が何も指さなくなります。',
+      // 直下の最初の子要素が <Select> のときだけ。<Select> の中の <FormControl>
+      // （正しい形）や、<FormControl> 直下が <SelectTrigger> のものは拾わない。
+      // en: Only when the first direct child of <FormControl> is <Select>.
+      match: (rawContent) => {
+        const content = maskSourceComments(rawContent);
+        const hits = [];
+        for (const opener of content.matchAll(/<FormControl(?=[\s/>])/g)) {
+          const tag = readOpeningTag(content, opener.index, 'FormControl');
+          if (!tag || tag.selfClosing) continue;
+          const child = /^\s*<([A-Za-z][\w.-]*)(?=[\s/>])/.exec(content.slice(tag.end + 1));
+          if (child?.[1] !== 'Select') continue;
+          hits.push({
+            index: tag.index,
+            text: content.slice(tag.index, tag.end + 1 + child[0].length),
+          });
+        }
+        return hits;
+      },
+    },
+    featureSection: lines([
+      '### Select をフォームで使うときは FormControl で SelectTrigger を包む',
+      '',
+      '```tsx',
+      '// ✅ Correct — FormControl は SelectTrigger を包む',
+      '<FormItem>',
+      '  <FormHeader label="プラン" />',
+      '  <Select value={field.value} onValueChange={field.onChange}>',
+      '    <FormControl>',
+      '      <SelectTrigger>',
+      '        <SelectValue placeholder="選択してください" />',
+      '      </SelectTrigger>',
+      '    </FormControl>',
+      '    <SelectContent>',
+      '      <SelectItem value="free">Free</SelectItem>',
+      '    </SelectContent>',
+      '  </Select>',
+      '</FormItem>',
+      '',
+      '// ❌ Wrong — Select のルートを FormControl で包まない',
+      '<FormControl>',
+      '  <Select value={field.value} onValueChange={field.onChange}>',
+      '    <SelectTrigger>…</SelectTrigger>',
+      '    <SelectContent>…</SelectContent>',
+      '  </Select>',
+      '</FormControl>',
+      '```',
+      '',
+      '`FormControl` は Slot で `id` / `aria-describedby` / `aria-invalid` を直下の子に渡す。`Select` のルートは DOM を持たないので id がどこにも付かず、`FormHeader` の `<label for>` が何も指さない（ラベルを押してもフォーカスせず、読み上げでも関連が伝わらない）。',
+    ]),
+    jsdocTargets: [
+      {
+        file: 'src/components/ui/form/index.tsx',
+        targetName: 'FormControl',
+        section: {
+          bullets: [
+            {
+              ja: '`Select` と組み合わせるときは `Select` のルートではなく `SelectTrigger` を包んでください。`Select` のルートは DOM を持たないため、渡した `id` が付かずラベルが関連付きません。',
+              en: 'With `Select`, wrap `SelectTrigger` rather than the `Select` root. The root renders no DOM, so the forwarded `id` lands nowhere and the label is not associated.',
+            },
+          ],
+          example: lines([
+            '// ✅ Correct',
+            '<Select value={field.value} onValueChange={field.onChange}>',
+            '  <FormControl>',
+            '    <SelectTrigger>',
+            '      <SelectValue placeholder="選択してください" />',
+            '    </SelectTrigger>',
+            '  </FormControl>',
+            '  <SelectContent>...</SelectContent>',
+            '</Select>',
+            '',
+            '// ❌ Wrong - Select のルートを包まない',
+            '<FormControl>',
+            '  <Select>...</Select>',
+            '</FormControl>',
+          ]),
+        },
+      },
+    ],
+  },
+  {
+    id: 'handwritten-radio-role',
+    check: {
+      // 原則ダメだが、Radio / Select / SegmentedControl のどれにも収まらない
+      // 見た目の選択 UI（色見本など）で手組みを選ぶ判断はありうるので warning。
+      // en: warning, not error — a visual picker that none of the components fit
+      // can be a deliberate exception (suppress it with a comment).
+      severity: SEVERITY.WARNING,
+      description: '単一選択を role="radio" / role="radiogroup" で手組みしない',
+      recommendation:
+        '単一選択には Radio（選択肢が少なく常に 1 つ選ばれている）/ Select（選択肢が多い・表示スペースが狭い）/ sparkle-design-internal の SegmentedControl（2〜5 個の切り替え）を使ってください。手組みの role="radio" は矢印キーでの移動・roving tabindex・aria-checked の同期を自前で正しく実装する必要があります。どうしても手組みが必要な場合は `// sparkle-disable-next-line handwritten-radio-role` で理由を添えて残してください。',
+      match: (rawContent) => {
+        if (!/role\s*=\s*\{?\s*["'`]radio/.test(rawContent)) return [];
+        const content = maskSourceComments(rawContent);
+        const hits = [];
+        for (const opener of content.matchAll(JSX_OPENING_TAG)) {
+          // Radio / RadioGroup / SegmentedControl 自身（とその実装の Radix
+          // primitive）は role を持つのが正しいので対象外
+          // en: The components themselves legitimately carry these roles.
+          if (/Radio|SegmentedControl/.test(opener[1])) continue;
+          const tag = readOpeningTag(content, opener.index, opener[1]);
+          if (tag && RADIO_ROLE_ATTR.test(tag.props)) {
+            hits.push({ index: tag.index, text: tag.text });
+          }
+        }
+        return hits;
+      },
+    },
+    featureSection: lines([
+      '### 単一選択を role="radio" で手組みしない',
+      '',
+      '```tsx',
+      '// ✅ Correct — 選択肢が少なく常に 1 つ選ばれている',
+      '<Radio value={value} onValueChange={setValue}>',
+      '  <RadioItem value="sm" label="小" />',
+      '  <RadioItem value="md" label="中" />',
+      '</Radio>',
+      '',
+      '// ✅ Correct — 選択肢が多い・表示スペースが狭い',
+      '<Select value={value} onValueChange={setValue}>…</Select>',
+      '',
+      '// ❌ Wrong — button に role="radio" を付けて手組みしない',
+      '<div role="radiogroup">',
+      '  <button type="button" role="radio" aria-checked={value === "sm"}>小</button>',
+      '  <button type="button" role="radio" aria-checked={value === "md"}>中</button>',
+      '</div>',
+      '```',
+      '',
+      '単一選択は `Radio` / `Select` / sparkle-design-internal の `SegmentedControl`（2〜5 個の切り替え）から選ぶ。手組みの `role="radio"` は矢印キーでの移動や `aria-checked` の同期を自前で実装することになり、漏れやすい。',
+    ]),
+    jsdocTargets: [],
+  },
+  {
+    id: 'handwritten-form-error',
+    check: {
+      // 「error アイコン + negative 系の文字色が並ぶ」というヒューリスティックで、
+      // 入力欄に紐づかないページ全体のエラー表示なども拾いうるので info に留める。
+      // en: Heuristic (error icon next to a negative text color) — it can also hit
+      // page-level errors that aren't tied to a field, so keep it at info.
+      severity: SEVERITY.INFO,
+      description: 'フォームのエラー表示を Icon + negative 色で手組みしない',
+      recommendation:
+        '入力欄のエラーは FormErrorMessage を使ってください。FormErrorMessage は aria-describedby / aria-invalid で入力欄と関連付くため、読み上げでどの欄のエラーかが伝わります（手組みでは伝わりません）。入力欄に紐づかないエラー（ページ全体の失敗など）なら InlineMessage を検討し、意図的な手組みであれば `// sparkle-disable-next-line handwritten-form-error` で残してください。',
+      // `<Icon icon="error">` の (1) 自身 (2) 直上の親 (3) 直後の兄弟 のいずれかに
+      // negative 系の文字色があれば手組みのエラー表示とみなす。親に data-slot が
+      // 付いているもの（FormErrorMessage など Sparkle 本体の実装）は対象外。
+      // en: Flag `<Icon icon="error">` when the icon itself, its immediate parent,
+      // or its next sibling carries a negative text color. Parents with
+      // `data-slot` are Sparkle's own implementation (FormErrorMessage) — skip.
+      match: (rawContent) => {
+        if (!/icon\s*=\s*\{?\s*["'`]error/.test(rawContent)) return [];
+        const content = maskSourceComments(rawContent);
+        const hits = [];
+        for (const opener of content.matchAll(/<Icon(?=[\s/>])/g)) {
+          const icon = readOpeningTag(content, opener.index, 'Icon');
+          if (!icon || !ERROR_ICON_ATTR.test(icon.props)) continue;
+
+          const parent = findImmediateParentTag(content, icon.index);
+          if (
+            parent &&
+            (/(?:^|\s)data-slot\s*=/.test(parent.props) || parent.tagName === 'FormErrorMessage')
+          ) {
+            continue;
+          }
+
+          let sibling = null;
+          if (icon.selfClosing) {
+            const next = /^\s*<([A-Za-z][\w.-]*)(?=[\s/>])/.exec(content.slice(icon.end + 1));
+            if (next) {
+              sibling = readOpeningTag(content, icon.end + 1 + next[0].indexOf('<'), next[1]);
+            }
+          }
+
+          if ([icon, parent, sibling].some((tag) => tag && NEGATIVE_TEXT_COLOR.test(tag.props))) {
+            hits.push({ index: icon.index, text: icon.text });
+          }
+        }
+        return hits;
+      },
+    },
+    featureSection: lines([
+      '### フォームのエラー表示は FormErrorMessage を使う',
+      '',
+      '```tsx',
+      '// ✅ Correct — 入力欄と aria-describedby / aria-invalid で関連付く',
+      '<FormItem>',
+      '  <FormHeader label="招待コード" />',
+      '  <FormControl>',
+      '    <Input {...field} isInvalid={fieldState.invalid} />',
+      '  </FormControl>',
+      '  <FormErrorMessage />',
+      '</FormItem>',
+      '',
+      '// ❌ Wrong — Icon と negative 色でエラー表示を手組みしない',
+      '<span className="flex items-center gap-1 text-text-negative-enabled">',
+      '  <Icon icon="error" size={3} />',
+      '  コードが見つかりません',
+      '</span>',
+      '```',
+      '',
+      '手組みのエラー表示は見た目が同じでも入力欄との関連が無く、スクリーンリーダーではどの欄のエラーかが伝わらない。入力欄に紐づかないエラーは `InlineMessage` を使う。',
+    ]),
+    jsdocTargets: [
+      {
+        file: 'src/components/ui/form/index.tsx',
+        targetName: 'FormErrorMessage',
+        section: {
+          bullets: [
+            {
+              ja: '`<Icon icon="error" />` と negative 系の文字色でエラー表示を手組みしないでください。`FormErrorMessage` は `aria-describedby` / `aria-invalid` で入力欄と関連付きます。',
+              en: 'Do not hand-roll error text with `<Icon icon="error" />` and a negative text color. `FormErrorMessage` is linked to the field via `aria-describedby` / `aria-invalid`.',
+            },
+          ],
+          example: lines([
+            '// ✅ Correct',
+            '<FormErrorMessage />',
+            '',
+            '// ❌ Wrong - 手組みのエラー表示',
+            '<span className="text-text-negative-enabled">',
+            '  <Icon icon="error" size={3} />',
+            '  コードが見つかりません',
+            '</span>',
+          ]),
+        },
+      },
+    ],
+  },
 ];
 
 // Built-in groups always come before plugin-supplied groups in this priority order.
@@ -1351,6 +1672,23 @@ function maskBlockComments(content) {
   return content.replace(/^[ \t]*\/\*[\s\S]*?\*\//gm, (comment) => comment.replace(/[^\n]/g, ' '));
 }
 
+/**
+ * そのファイル自身が宣言している CSS カスタムプロパティ名の集合。
+ *
+ * `check` の移行ルールと `migrate` サブコマンドの両方が「定義側は移行対象の
+ * 使用ではない」という同じ判定を使う。片方だけ直すと、check は黙っているのに
+ * migrate が生成物の定義を書き換える（あるいはその逆）というずれが生まれるため、
+ * 1 箇所にまとめている。
+ * en: Custom properties declared by this file. Shared by `check` and `migrate`
+ * so both agree that definitions are not usages to migrate.
+ *
+ * @param {string} content ブロックコメントをマスク済みの内容
+ * @returns {Set<string>}
+ */
+function collectDeclaredCustomProperties(content) {
+  return new Set([...content.matchAll(/(?:^|[{;])\s*(--[\w-]+)\s*:/gm)].map((m) => m[1]));
+}
+
 function migrationMatcher(pattern, resolve, label) {
   return (rawContent) => {
     const content = maskBlockComments(rawContent);
@@ -1369,9 +1707,7 @@ function migrationMatcher(pattern, resolve, label) {
     // 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 declaredHere = collectDeclaredCustomProperties(content);
 
     const hits = [];
     for (const match of content.matchAll(pattern)) {
@@ -1761,6 +2097,9 @@ const BUILTIN_CHECK_ORDER = [
   'disabled-vs-is-disabled',
   'button-prefixicon-jsx',
   'icon-children-text',
+  'form-control-select-root',
+  'handwritten-radio-role',
+  'handwritten-form-error',
   // NOTE: この配列が決めるのは **ルールの評価順** だけで、レポートの表示順では
   // ない（findings は check.js 側で severity 優先にソートされる）。移行ルールを
   // 末尾に置いているのは評価順を安定させるためで、「warning が error を埋もれ
@@ -1814,9 +2153,11 @@ export {
   BUILTIN_ANTI_PATTERN_GROUPS as ANTI_PATTERN_GROUPS,
   BUILTIN_MANUAL_REVIEW_REMINDERS as MANUAL_REVIEW_REMINDERS,
   COMMON_INTRO,
+  collectDeclaredCustomProperties,
   getAllJSDocTargets,
   getCheckRules,
   getManualReviewReminders,
+  maskBlockComments,
   renderFeatureSections,
   renderJSDocSection,
 };

package/lib/check.js

@@ -696,9 +696,11 @@ export {
   BUILTIN_RULES as RULES,
   blockingFindings,
   coerceSeverity,
+  collectFiles,
   collectFindings,
   countBySeverity,
   createCheckReport,
   hasBlockingIssues,
+  isSuppressed,
   BUILTIN_MANUAL_REVIEW_REMINDERS as MANUAL_REVIEW_REMINDERS,
 };