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

package/templates/sparkle-variables/scripts/validate-tokens.mjs

@@ -0,0 +1,734 @@
+#!/usr/bin/env node
+/**
+ * sparkle-variables のトークン定義に「嘘」が混入していないかを機械的に検証する。
+ *
+ * このリポジトリは sparkle-design-cli と sparkle-design-theme-settings の
+ * 2 つのツールから submodule として直接参照される純粋なデータで、これまで
+ * 検証が無かった。人間の目視では見つからない不整合（同じ情報が 2 箇所に
+ * あって片方が古い、リネームの片側だけ直っている等）を CI で止めるのが目的。
+ *
+ * en: Machine-checks the token definitions for the failure modes a human
+ * reviewer cannot reliably catch — duplicated sources of truth, half-applied
+ * renames, dangling variable references.
+ *
+ * ## 設計方針: 「0 件マッチ = 成功」を作らない
+ *
+ * 集合比較だけの検査は、対象が 1 件も取れなかったときに黙って合格する。
+ * 接頭辞を一括リネームしたら検査が丸ごと無効化された、という事故が起きても
+ * CI は緑のままになる。そのため各検査は「最低これだけの件数を実際に見た」
+ * ことを `expect()` で表明してから判定する。
+ * en: Every check asserts a minimum number of inspected items, so a check that
+ * silently stops matching anything fails instead of vacuously passing.
+ *
+ * 使い方: node scripts/validate-tokens.mjs
+ * 終了コード: 0 = 全て OK / 1 = 違反あり
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const read = (f) => fs.readFileSync(path.join(ROOT, f), 'utf8');
+const readJSON = (f) => JSON.parse(read(f));
+
+const failures = [];
+const checks = [];
+
+/**
+ * @param {string} name 検証名（失敗時に表示される）
+ * @param {() => string | null} fn 問題があれば説明文字列、無ければ null を返す
+ */
+function check(name, fn) {
+  let detail = null;
+  try {
+    detail = fn();
+  } catch (err) {
+    // 検査コード自身のバグ（TypeError 等）をトークン不整合と誤読しないよう、
+    // スタックトレースまで残す。
+    // en: Keep the stack so a bug in the check isn't mistaken for bad data.
+    detail = `検証自体が失敗しました: ${err.message}\n${err.stack ?? ''}`;
+  }
+  checks.push({ name, ok: !detail });
+  if (detail) failures.push({ name, detail });
+}
+
+/** 「実際に N 件以上を検査した」ことを表明する。下回ったら検査が空振りしている。 */
+function expect(count, minimum, what) {
+  if (count < minimum) {
+    throw new Error(
+      `${what}を ${count} 件しか検査できませんでした（最低 ${minimum} 件を想定）。` +
+        '検査対象の命名やファイル構造が変わって、検査が空振りしている可能性があります。'
+    );
+  }
+}
+
+/** 違反リストを表示用に切り詰める。省略した件数は必ず明示する。 */
+function summarize(items, limit = 5) {
+  if (items.length <= limit) return items.join(', ');
+  return `${items.slice(0, limit).join(', ')} ほか ${items.length - limit} 件`;
+}
+
+// CSS コメントは検査対象から外す。説明文の中に架空の変数名を書いた瞬間に
+// CI が落ちる、という理不尽を避ける。
+// en: Strip comments so prose examples don't count as real references.
+const stripComments = (css) => css.replace(/\/\*[\s\S]*?\*\//g, '');
+
+// `var(--x)` と `var(--x, fallback)` の両方にマッチする。
+// en: Matches both `var(--x)` and `var(--x, fallback)`.
+const varRefPattern = () => /var\(\s*(--[a-zA-Z0-9_-]+)\s*[,)]/g;
+
+// ---------------------------------------------------------------------------
+// 入力の読み込み（壊れた入力でも他の検査結果を出せるよう check の中で行う）
+// ---------------------------------------------------------------------------
+let colors;
+let gray;
+let template;
+let templateNoComments;
+let radiusCsv;
+let RADIUS_HEADER = [];
+let RADIUS_ROWS = [];
+
+check('入力ファイルが読み込めること', () => {
+  const problems = [];
+  try {
+    colors = readJSON('colors.json');
+  } catch (err) {
+    problems.push(`colors.json: ${err.message}`);
+  }
+  try {
+    gray = readJSON('gray.json');
+  } catch (err) {
+    problems.push(`gray.json: ${err.message}`);
+  }
+  try {
+    template = read('sparkle-design.template.css');
+    templateNoComments = stripComments(template);
+  } catch (err) {
+    problems.push(`sparkle-design.template.css: ${err.message}`);
+  }
+  try {
+    // radius.csv は CRLF 改行。単純な split('\n') だと末尾カラムに '\r' が残り
+    // ヘッダー名が "round\r" になる。CLI 側（lib/file-loader.js の
+    // loadRadiusMapping）も同じ理由で /\r?\n/ を使っているので合わせる。
+    // en: radius.csv uses CRLF; matches the CLI's own loadRadiusMapping.
+    radiusCsv = read('radius.csv')
+      .trim()
+      .split(/\r?\n/)
+      .map((l) => l.split(','));
+    RADIUS_HEADER = radiusCsv[0].slice(1);
+    RADIUS_ROWS = radiusCsv.slice(1);
+  } catch (err) {
+    problems.push(`radius.csv: ${err.message}`);
+  }
+  return problems.length ? problems.join(' / ') : null;
+});
+
+// 後続の検査は入力が揃っている前提。1 つでも読めなければここで止める。
+if (failures.length > 0) {
+  console.error('❌ 入力ファイルの読み込みに失敗しました:\n');
+  for (const { detail } of failures) console.error(`   ${detail}\n`);
+  process.exit(1);
+}
+
+// gray.json のキー 0–9 は CLI の GRAY_LEVEL_MAP で 50–900 に展開される。
+const GRAY_LEVEL_MAP = {
+  0: '50',
+  1: '100',
+  2: '200',
+  3: '300',
+  4: '400',
+  5: '500',
+  6: '600',
+  7: '700',
+  8: '800',
+  9: '900',
+};
+
+// colors.json のうち「primary として選べる色相」ではないキー。
+// alpha スケールと、beta 期間の互換用に残している ring。
+const NON_PALETTE_COLOR_KEYS = new Set([
+  'black',
+  'white',
+  'black-alpha',
+  'white-alpha',
+  'ring',
+]);
+
+// テンプレートのブロック境界
+const PRIMITIVE_MARKER = '/* Primitive Tokens */';
+const SEMANTIC_MARKER = '/* セマンティックトークン - CSS変数としてランタイムで利用可能にする */';
+const THEME_INLINE_MARKER = '@theme inline {';
+// `@theme static`。`@theme inline {` には部分一致しないので取り違えない。
+const THEME_MARKER = '@theme static {';
+
+function blockAfter(marker) {
+  const start = template.indexOf(marker);
+  if (start === -1) throw new Error(`マーカーが見つかりません: ${marker}`);
+  const braceStart = template.indexOf('{', start);
+  const end = template.indexOf('\n}', braceStart);
+  if (braceStart === -1 || end === -1) throw new Error(`ブロックの範囲を特定できません: ${marker}`);
+  return stripComments(template.slice(braceStart + 1, end));
+}
+
+function declaredNames(block, prefixPattern = '[a-zA-Z0-9_-]+') {
+  return [...block.matchAll(new RegExp(`^\\s*(--${prefixPattern})\\s*:`, 'gm'))].map((m) => m[1]);
+}
+
+// ---------------------------------------------------------------------------
+// 1. gray の source of truth が 1 箇所であること
+// ---------------------------------------------------------------------------
+// colors.json と gray.json の両方に gray があると、CLI の generateColorTokens が
+// --color-gray-* を二重に出力し、後から出る gray.json 側が colors.json 側を
+// サイレントに上書きする。見た目は壊れないので目視では気付けない。
+check('gray の source of truth が gray.json 一本であること', () => {
+  if ('gray' in colors) {
+    return 'colors.json に `gray` キーがあります。gray は primary ごとに切り替わるため gray.json が正で、両方にあると CLI が --color-gray-* を二重出力し gray.json 側が後勝ちで上書きします。';
+  }
+  return null;
+});
+
+// ---------------------------------------------------------------------------
+// 2. primary 候補の整合（双方向）
+// ---------------------------------------------------------------------------
+// CLI は「colors.json と gray.json の両方にキーがある色」を primary として
+// 使える色とみなす。片方にしか無い色は、選べそうに見えて選べない／選ぶと
+// 壊れる、という分かりにくい状態になる。
+check('colors.json と gray.json の色相が双方向で揃っていること', () => {
+  const grayKeys = Object.keys(gray);
+  const paletteKeys = Object.keys(colors).filter(
+    (k) => !NON_PALETTE_COLOR_KEYS.has(k) && typeof colors[k] === 'object' && colors[k] !== null
+  );
+  expect(grayKeys.length, 5, 'gray.json の色相');
+  expect(paletteKeys.length, 5, 'colors.json のパレット色相');
+
+  const problems = [];
+  const missingInColors = grayKeys.filter((h) => !(h in colors));
+  if (missingInColors.length) {
+    problems.push(`colors.json に存在しない色相が gray.json にあります: ${missingInColors.join(', ')}`);
+  }
+  const missingInGray = paletteKeys.filter((h) => !(h in gray));
+  if (missingInGray.length) {
+    problems.push(
+      `gray.json に対応が無いパレット色相があります: ${missingInGray.join(', ')}（primary に選べそうに見えて選ぶと gray が生成されません）`
+    );
+  }
+  // CLI の getValidPrimaryColors はネストしたオブジェクトのみを候補とする。
+  // gray.json 側にスカラーが紛れると CLI と validator で判定がずれる。
+  const nonObject = grayKeys.filter((h) => typeof colors[h] !== 'object' || colors[h] === null);
+  if (nonObject.length) {
+    problems.push(`gray.json にあるがパレットではない（スカラー）色: ${nonObject.join(', ')}`);
+  }
+  return problems.length ? problems.join(' / ') : null;
+});
+
+check('gray.json の各色相が 0–9 の 10 段を持つこと', () => {
+  const entries = Object.entries(gray);
+  expect(entries.length, 5, 'gray.json の色相');
+  const bad = entries
+    .filter(([, v]) => Object.keys(v).sort().join(',') !== '0,1,2,3,4,5,6,7,8,9')
+    .map(([k]) => k);
+  return bad.length ? `段数が 0–9 になっていない色相: ${bad.join(', ')}` : null;
+});
+
+// ---------------------------------------------------------------------------
+// 3. radius.csv の構造
+// ---------------------------------------------------------------------------
+check('radius.csv の行・列構造が壊れていないこと', () => {
+  const problems = [];
+  if (RADIUS_HEADER.length === 0) problems.push('ヘッダー行にセマンティック列がありません');
+  if (RADIUS_ROWS.length === 0) problems.push('プリセット行がありません');
+  expect(RADIUS_HEADER.length, 3, 'radius.csv のセマンティック列');
+  expect(RADIUS_ROWS.length, 3, 'radius.csv のプリセット行');
+
+  const width = RADIUS_HEADER.length + 1;
+  const ragged = RADIUS_ROWS.filter((row) => row.length !== width).map((row) => row[0] || '(空行)');
+  if (ragged.length) {
+    problems.push(`列数がヘッダー（${width}）と違う行: ${summarize(ragged)}`);
+  }
+  const empty = RADIUS_ROWS.flatMap((row) =>
+    row.some((cell) => cell.trim() === '') ? [row[0] || '(空行)'] : []
+  );
+  if (empty.length) problems.push(`空セルを含む行: ${summarize(empty)}`);
+  return problems.length ? problems.join(' / ') : null;
+});
+
+// ---------------------------------------------------------------------------
+// 4. radius.csv とテンプレートのリネーム整合（双方向）
+// ---------------------------------------------------------------------------
+// CLI は `--radius-<列名>:` への正規表現置換で radius.csv の値を流し込む。
+// 片側だけリネームすると、旧名の変数が残ったまま新名の変数が生成されない、
+// あるいはプロファイルの値が流し込まれない、という事故になる。
+check('radius.csv の列名とテンプレートの --radius-* 変数が双方向で一致すること', () => {
+  // プリミティブは「プリミティブ :root ブロックで宣言されている --radius-*」と
+  // して**動的に**求める。ハードコードすると、正当な新プリミティブを足したときに
+  // 事実と違うメッセージで CI が落ちる（このリポジトリ自身が「同じ情報を 2 箇所に
+  // 持つな」と言っている以上、許可リストの二重管理は避ける）。
+  // en: Derive primitives from the primitive :root block instead of hardcoding,
+  // so adding a legitimate new primitive doesn't fail with a bogus reason.
+  const primitives = new Set(declaredNames(blockAfter(PRIMITIVE_MARKER), 'radius-[a-zA-Z0-9-]+').map((n) => n.slice('--radius-'.length)));
+  expect(primitives.size, 5, 'radius のプリミティブ');
+
+  const declared = new Set(
+    declaredNames(templateNoComments, 'radius-[a-zA-Z0-9-]+').map((n) => n.slice('--radius-'.length))
+  );
+  expect(declared.size, primitives.size + 3, 'テンプレートの --radius-* 宣言');
+
+  const problems = [];
+
+  const missing = RADIUS_HEADER.filter((k) => !declared.has(k));
+  if (missing.length) {
+    problems.push(
+      `radius.csv に列があるのにテンプレートに --radius-<列名> が無い: ${missing.join(', ')}（CSV だけリネームすると CLI の置換が効きません）`
+    );
+  }
+
+  // 逆方向。テンプレートだけリネームすると、新名の変数は CSV に列が無いので
+  // プロファイルの値が流し込まれず、置換前のデフォルトのまま出荷される。
+  // `halfModal` は「CSV に列を持たない意図的なエイリアス」なので、
+  // テンプレート側のコメントで @deprecated と宣言されていることを条件に許す。
+  const deprecatedAliases = new Set(
+    [...template.matchAll(/@deprecated[^*]*?--radius-([a-zA-Z0-9-]+)/g)].map((m) => m[1])
+  );
+  const orphan = [...declared].filter(
+    (k) => !primitives.has(k) && !deprecatedAliases.has(k) && !RADIUS_HEADER.includes(k)
+  );
+  if (orphan.length) {
+    problems.push(
+      `テンプレートに --radius-* があるのに radius.csv に列が無い: ${orphan.join(', ')}（プロファイルの値が流し込まれず置換前のデフォルトのまま出力されます。意図的なエイリアスなら @deprecated コメントに変数名を書いてください）`
+    );
+  }
+
+  // 後方互換エイリアスと同名の列が CSV に残っていると、CLI の置換が
+  // `--radius-halfModal: var(--radius-container)` を上書きしてしまい、
+  // 「container に追従する」というエイリアスの意味が壊れる。
+  const shadowed = [...deprecatedAliases].filter((k) => RADIUS_HEADER.includes(k));
+  if (shadowed.length) {
+    problems.push(
+      `後方互換エイリアスと同名の列が radius.csv に残っています: ${shadowed.join(', ')}（CLI の置換がエイリアスの参照先を上書きします）`
+    );
+  }
+
+  // CSV のセル値（= 置換後の参照先）が実在するプリミティブであること。
+  // これを見ないと、CLI が `--radius-action: var(--radius-4xl)` のような
+  // dangling reference を生成しても validator は緑のまま通る。
+  // テンプレート単体の dangling 検査（下の検査）と合わせて、
+  // 「置換後の CSS にも dangling が無い」ことが担保される。
+  // en: Verify every CSV cell resolves to a real primitive — otherwise the CLI
+  // emits a dangling `var(--radius-<x>)` that a template-only scan can't see.
+  const badCells = [];
+  for (const row of RADIUS_ROWS) {
+    for (const value of row.slice(1)) {
+      if (!primitives.has(value)) badCells.push(`${row[0]} 行の "${value}"`);
+    }
+    // プロファイル名は `{{RADIUS}}` に代入されて `var(--radius-<プロファイル名>)`
+    // になるため、これもプリミティブとして実在する必要がある。
+    if (!primitives.has(row[0])) badCells.push(`プロファイル名 "${row[0]}"`);
+  }
+  if (badCells.length) {
+    problems.push(
+      `radius.csv の値に対応する --radius-* プリミティブがテンプレートにありません: ${summarize(badCells)}`
+    );
+  }
+
+  return problems.length ? problems.join(' / ') : null;
+});
+
+// CLI の lib/constants.js が依存している不変条件。プリセット値（none/xs/…）が
+// セマンティックキー名（divide/minimum/…）と文字列衝突すると、置換用の
+// 正規表現が意図しないマッチをする。
+check('radius のプリセット値がセマンティックキー名と衝突しないこと', () => {
+  const semanticKeys = new Set(RADIUS_HEADER);
+  const collisions = [];
+  let inspected = 0;
+  for (const row of RADIUS_ROWS) {
+    for (const value of row.slice(1)) {
+      inspected += 1;
+      if (semanticKeys.has(value)) collisions.push(value);
+    }
+  }
+  expect(inspected, 20, 'radius.csv のセル');
+  return collisions.length
+    ? `プリセット値がセマンティックキー名と衝突しています: ${[...new Set(collisions)].join(', ')}`
+    : null;
+});
+
+// ---------------------------------------------------------------------------
+// 5. Spacing / Sizing の扱い
+// ---------------------------------------------------------------------------
+// Figma の `Spacing: Primitives` は **CSS 変数として出力してはいけない**。
+// Tailwind v4 の `p-N` / `m-N` / `gap-N` は `calc(var(--spacing) * N)` に
+// コンパイルされるが、`--spacing-<N>` という名前付きキーを定義するとその N だけ
+// 名前付きの値が優先される。`--spacing-2: 2px` を足した瞬間に、既存 consumer の
+// `p-2` が 8px から 2px に変わる。ビルドは通り、警告も出ず、見た目だけが崩れる。
+// Figma のステップは代わりに sparkle-design-cli の `check` ルールで
+// 「使ってよい値」として検査する予定（`use-figma-spacing-scale`。
+// goodpatch/sparkle-design-cli#76 でリリース予定で、**まだ released な CLI には
+// 入っていない**）。
+// en: Never emit `--spacing-*`. Tailwind v4 compiles `p-2` to
+// `calc(var(--spacing) * 2)`; defining `--spacing-2` silently overrides it and
+// changes every consumer's padding. The allowed steps will be enforced by the
+// CLI's `check` rule instead — not in a released CLI yet (cli#76).
+check('テンプレートが --spacing / --spacing-* を定義していないこと', () => {
+  const declared = declaredNames(templateNoComments, 'spacing(?:-[a-zA-Z0-9-]+)?');
+  return declared.length
+    ? `${summarize([...new Set(declared)])} が定義されています。Tailwind v4 の動的スペーシング（\`p-N\` = \`calc(var(--spacing) * N)\`）を名前付きキーが上書きするため、既存 consumer の余白がサイレントに変わります。Figma のステップは CSS 変数ではなく sparkle-design-cli の check ルールで担保する方針です（\`use-figma-spacing-scale\`。goodpatch/sparkle-design-cli#76 でリリース予定）。`
+    : null;
+});
+
+// `Sizing: Primitives` は逆に衝突しない。Tailwind の `--container-*` 名前空間は
+// 元から名前付きキーだけで構成されていて、動的な計算式を持たないため。
+const FIGMA_MAX_WIDTH_KEYS = [
+  'xs',
+  'sm',
+  'md',
+  'lg',
+  'xl',
+  '2xl',
+  '3xl',
+  '4xl',
+  '5xl',
+  '6xl',
+  '7xl',
+];
+
+check('--container-* が Figma の Sizing: Primitives と過不足なく一致すること', () => {
+  const block = blockAfter(THEME_MARKER);
+  const declared = declaredNames(block, 'container-[a-zA-Z0-9-]+').map((n) =>
+    n.slice('--container-'.length)
+  );
+
+  const problems = [];
+  const declaredSet = new Set(declared);
+  const missing = FIGMA_MAX_WIDTH_KEYS.filter((k) => !declaredSet.has(k));
+  if (missing.length) {
+    problems.push(`Figma の max-width/* に対応する変数がありません: ${missing.join(', ')}`);
+  }
+  const extra = declared.filter((k) => !FIGMA_MAX_WIDTH_KEYS.includes(k));
+  if (extra.length) {
+    problems.push(
+      `Figma の Sizing: Primitives に無い --container-* があります: ${extra.join(', ')}（Tailwind のデフォルト 3xs/2xs は「定義しない」ことで既定値のまま残す設計です）`
+    );
+  }
+  // 同名を 2 回書いても `missing` にも `extra` にも出ない（集合で比較しているため）。
+  // CSS は後勝ちなので、2 つ目が最初の値をサイレントに上書きする。
+  // en: A repeated key shows up in neither set-difference, yet CSS last-wins makes
+  // the second declaration silently override the first.
+  const duplicated = [...new Set(declared.filter((k, i) => declared.indexOf(k) !== i))];
+  if (duplicated.length) {
+    problems.push(
+      `同じ --container-* が複数回宣言されています: ${duplicated.join(', ')}（後に書いたほうが勝つのでサイレントに上書きされます）`
+    );
+  }
+
+  // 値が昇順であること。character/4 と /5 の line-height が入れ替わっていた
+  // 事故と同じクラス（名前は正しいが対応する値だけが入れ替わる）を拾う。
+  // en: Catch swapped values — the same failure class as the line-height mix-up.
+  // 値は **リテラルの rem** でなければならない。`var(...)` を書くと、
+  // container query バリアント（`@xl:` 等）は条件に var() を置けないため
+  // **ユーティリティごと生成されなくなる**（ビルドは成功する）。
+  // en: Literal rem only. A `var()` here silently drops the `@xl:`-style
+  // container-query utilities, because `@container (width >= …)` can't use var().
+  const values = FIGMA_MAX_WIDTH_KEYS.map((key) => {
+    const m = block.match(
+      new RegExp(`^\\s*--container-${key}\\s*:\\s*(\\d+(?:\\.\\d+)?)rem\\s*;`, 'm')
+    );
+    return m ? Number(m[1]) : null;
+  });
+  const unparsed = FIGMA_MAX_WIDTH_KEYS.filter((_, i) => values[i] === null);
+  if (unparsed.length) {
+    problems.push(
+      `リテラルの rem 値として読めない --container-*: ${unparsed.join(', ')}（var() や calc() を書くと container query バリアントが生成されなくなります）`
+    );
+  } else {
+    const outOfOrder = [];
+    for (let i = 1; i < values.length; i += 1) {
+      if (values[i] <= values[i - 1]) {
+        outOfOrder.push(
+          `${FIGMA_MAX_WIDTH_KEYS[i - 1]}(${values[i - 1]}rem) → ${FIGMA_MAX_WIDTH_KEYS[i]}(${values[i]}rem)`
+        );
+      }
+    }
+    if (outOfOrder.length) {
+      problems.push(`値が昇順になっていません（値の取り違え）: ${outOfOrder.join(', ')}`);
+    }
+  }
+
+  // 他のトークンに合わせて「プレーン :root ＋ @theme inline の自己参照」へ
+  // 直したくなるが、それをやると container query バリアントが壊れる。
+  // 善意のリファクタで静かに壊れる箇所なので、機械で止める。
+  // en: Refactoring these into the `:root` + `@theme inline` shape used by every
+  // other token silently breaks the container-query variants — block it.
+  const misplaced = [];
+  for (const [label, marker] of [
+    ['プリミティブ :root', PRIMITIVE_MARKER],
+    ['セマンティック :root', SEMANTIC_MARKER],
+    ['@theme inline', THEME_INLINE_MARKER],
+  ]) {
+    const found = declaredNames(blockAfter(marker), 'container-[a-zA-Z0-9-]+');
+    if (found.length) misplaced.push(`${label}: ${summarize(found)}`);
+  }
+  if (misplaced.length) {
+    problems.push(
+      `--container-* は @theme static にだけ書いてください（${misplaced.join(' / ')}）。プレーン :root だと \`@sm:\` などの container query バリアントが Tailwind のデフォルト値のまま据え置かれ、@theme inline の自己参照だとそのバリアント自体が生成されなくなります`
+    );
+  }
+
+  // 空振り検出は最後に置く。先頭で expect() すると、置き場所を移した場合に
+  // 「10 件しか検査できませんでした」という**原因を取り違えたメッセージ**だけが
+  // 出て、上で組み立てた「@theme static に書いてください」が表に出ない。
+  // en: Run the vacuity guard last — asserting up front would replace the real
+  // diagnosis ("wrong block") with a misleading "the check found nothing" error.
+  if (problems.length === 0) {
+    expect(declared.length, FIGMA_MAX_WIDTH_KEYS.length, '--container-* の宣言');
+  }
+
+  return problems.length ? problems.join(' / ') : null;
+});
+
+// ---------------------------------------------------------------------------
+// 6. テンプレートに未定義変数への参照が無いこと
+// ---------------------------------------------------------------------------
+// primary をどれに切り替えても解決できることを、全 primary 候補で確認する。
+check('全 primary 候補で dangling な var(--*) 参照が無いこと', () => {
+  const primaries = Object.keys(gray).filter((h) => h in colors);
+  expect(primaries.length, 5, 'primary 候補');
+
+  const problems = [];
+  for (const primary of primaries) {
+    const declared = new Set();
+    for (const [name, value] of Object.entries(colors)) {
+      if (value && typeof value === 'object') {
+        for (const level of Object.keys(value)) declared.add(`--color-${name}-${level}`);
+      } else {
+        declared.add(`--color-${name}`);
+      }
+    }
+    for (const level of Object.keys(gray[primary])) {
+      declared.add(`--color-gray-${GRAY_LEVEL_MAP[level]}`);
+    }
+
+    const resolved = templateNoComments
+      .replace(/\{\{PRIMARY\}\}/g, primary)
+      .replace(/\{\{RADIUS\}\}/g, RADIUS_ROWS[0][0])
+      .replace(/\{\{FONT_FAMILY_PRO\}\}/g, 'Inter')
+      .replace(/\{\{FONT_FAMILY_MONO\}\}/g, 'monospace');
+
+    for (const m of resolved.matchAll(/^\s*(--[a-zA-Z0-9_-]+)\s*:/gm)) declared.add(m[1]);
+
+    const references = [...new Set([...resolved.matchAll(varRefPattern())].map((m) => m[1]))];
+    expect(references.length, 100, `primary=${primary} の var() 参照`);
+
+    const dangling = references.filter((ref) => !declared.has(ref));
+    if (dangling.length) problems.push(`primary=${primary}: ${summarize(dangling)}`);
+  }
+  return problems.length ? problems.join(' / ') : null;
+});
+
+// ---------------------------------------------------------------------------
+// 7. セマンティック層が 2 ブロックで揃っていること
+// ---------------------------------------------------------------------------
+// テンプレートは同じセマンティック変数を「プレーンな :root」と「@theme inline」
+// の 2 箇所に持つ（issue #229 の設計）。片方にだけ追加すると、ランタイム上書きが
+// 効かない／utility が生成されない、という気付きにくい欠落になる。
+// 対象は color / radius / shadow の全系統。接頭辞を絞ると、その接頭辞を
+// リネームしただけで検査が丸ごと無効化される。
+check('セマンティック層が :root と @theme inline で揃っていること', () => {
+  const themeIndex = template.indexOf(THEME_INLINE_MARKER);
+  if (themeIndex < 0) return `テンプレートに ${THEME_INLINE_MARKER} が見つかりません`;
+
+  const semanticStart = template.indexOf(SEMANTIC_MARKER);
+  if (semanticStart < 0) return `テンプレートに ${SEMANTIC_MARKER} が見つかりません`;
+
+  const pattern = '(?:color|radius|shadow)-[a-zA-Z0-9-]+';
+  const plain = new Set(
+    declaredNames(stripComments(template.slice(semanticStart, themeIndex)), pattern)
+  );
+  const themed = new Set(
+    declaredNames(stripComments(template.slice(themeIndex)), pattern)
+  );
+
+  expect(plain.size, 100, 'プレーン :root のセマンティック宣言');
+  expect(themed.size, 100, '@theme inline のセマンティック宣言');
+
+  const onlyPlain = [...plain].filter((n) => !themed.has(n));
+  const onlyThemed = [...themed].filter((n) => !plain.has(n));
+  if (onlyPlain.length || onlyThemed.length) {
+    return `:root のみ: ${summarize(onlyPlain) || 'なし'} / @theme inline のみ: ${summarize(onlyThemed) || 'なし'}`;
+  }
+  return null;
+});
+
+// 同じブロック内に同名変数が 2 回あると後勝ちでサイレント上書きされる。
+// colors.json と gray.json の gray 二重定義で実際に踏んだのと同じ事故クラス。
+check('同一ブロック内に重複した変数宣言が無いこと', () => {
+  const blocks = {
+    'プリミティブ :root': blockAfter(PRIMITIVE_MARKER),
+    'セマンティック :root': blockAfter(SEMANTIC_MARKER),
+    '@theme static': blockAfter(THEME_MARKER),
+    '@theme inline': blockAfter(THEME_INLINE_MARKER),
+  };
+  const problems = [];
+  let inspected = 0;
+  for (const [label, block] of Object.entries(blocks)) {
+    const counts = new Map();
+    for (const name of declaredNames(block)) {
+      counts.set(name, (counts.get(name) ?? 0) + 1);
+      inspected += 1;
+    }
+    const dupes = [...counts.entries()].filter(([, n]) => n > 1).map(([name]) => name);
+    if (dupes.length) problems.push(`${label}: ${summarize(dupes)}`);
+  }
+  expect(inspected, 300, '変数宣言');
+  return problems.length ? `重複宣言（後勝ちでサイレント上書きされます）— ${problems.join(' / ')}` : null;
+});
+
+// ---------------------------------------------------------------------------
+// 8. タイポグラフィのクラスが自分の変数だけを参照していること
+// ---------------------------------------------------------------------------
+// 72 クラス × 5 プロパティを手作業で変数参照に貼り替えた変更なので、
+// 「別クラスの変数を参照してしまう」取り違えが最も起きやすい。宣言名と
+// 参照名の集合一致だけでは、2 クラスが互いの変数を参照し合っていても通る。
+check('character-* / icon-* クラスが自分の変数だけを参照していること', () => {
+  const problems = [];
+  let inspectedClasses = 0;
+  let inspectedRefs = 0;
+
+  for (const m of templateNoComments.matchAll(/\.((?:character|icon)-[a-z0-9-]+)\s*\{([^}]*)\}/g)) {
+    const className = m[1];
+    inspectedClasses += 1;
+    for (const ref of m[2].matchAll(/var\(\s*(--(?:character|icon)-[a-z0-9-]+)\s*[,)]/g)) {
+      inspectedRefs += 1;
+      if (!ref[1].startsWith(`--${className}-`)) {
+        problems.push(`.${className} が ${ref[1]} を参照`);
+      }
+    }
+  }
+  expect(inspectedClasses, 60, 'タイポグラフィのクラス');
+  expect(inspectedRefs, 200, 'タイポグラフィ変数の参照');
+
+  // 宣言したのに誰も参照しない変数（＝貼り替え漏れ）も拾う
+  const declaredVars = new Set(declaredNames(templateNoComments, '(?:character|icon)-[a-z0-9-]+'));
+  const referenced = new Set(
+    [...templateNoComments.matchAll(/var\(\s*(--(?:character|icon)-[a-z0-9-]+)\s*[,)]/g)].map(
+      (r) => r[1]
+    )
+  );
+  const unused = [...declaredVars].filter((v) => !referenced.has(v));
+  const undeclared = [...referenced].filter((v) => !declaredVars.has(v));
+  if (unused.length) problems.push(`参照されていない変数: ${summarize(unused)}`);
+  if (undeclared.length) problems.push(`未定義の参照: ${summarize(undeclared)}`);
+
+  return problems.length ? problems.join(' / ') : null;
+});
+
+// ---------------------------------------------------------------------------
+// 9. テンプレートの構造が壊れていないこと
+// ---------------------------------------------------------------------------
+// `--font-size-16: 1rem; /* 16px */` のように、同じ値を rem とコメントの px で
+// 2 度書いている行がテンプレートに 42 行ある。Figma の値は px で来るので、
+// 実務では「コメントの px を先に直して rem を直し忘れる」が普通に起きる。
+// 変数名（--font-size-16 等）も px を名乗っているものが多く、目視だと合って
+// いるように見えてしまう。
+// en: The template states each value twice — as rem and as a `/* Npx */`
+// comment. Figma hands values over in px, so updating one and not the other is
+// a routine mistake that reads as correct.
+// 数値は `[\d.]+` ではなく `\d+(?:\.\d+)?` で厳密に取る。前者だと `1.2.3rem` に
+// マッチしてしまい、`Number.parseFloat` が黙って `1.2` に切り詰めるため、
+// **無効な CSS が検査を通過する**。変換も parseFloat ではなく Number を使い、
+// 末尾のゴミを許さない。
+// en: Strict numeric form — `[\d.]+` would accept `1.2.3rem`, which parseFloat
+// silently truncates, letting invalid CSS pass.
+check('rem の値と行末コメントの px が一致していること', () => {
+  const rows = [
+    ...template.matchAll(
+      /^[ \t]*(--[\w-]+)\s*:\s*(0|\d+(?:\.\d+)?rem)\s*;[ \t]*\/\*\s*(\d+(?:\.\d+)?)px\s*\*\//gm
+    ),
+  ];
+  // 現在 42 行。下限を実数に張り付けず 30 にしているのは、この検査が守りたいのが
+  // 「1 行減った」ではなく「検査が丸ごと空振りしている」ことだから。行末コメントの
+  // 書式を変えたり接頭辞を一括リネームすれば 0 件に落ちるので、そこで止まる。
+  // en: The floor guards against the pattern silently matching nothing, not
+  // against losing a single line — hence a floor well below the current 42.
+  expect(rows.length, 30, 'px コメント付きの rem 宣言');
+
+  const mismatched = rows
+    .filter(([, , rem, px]) => {
+      const asRem = rem === '0' ? 0 : Number(rem.slice(0, -'rem'.length));
+      return Math.abs(asRem * 16 - Number(px)) > 1e-9;
+    })
+    .map(([, name, rem, px]) => `${name}: ${rem} なのにコメントは ${px}px`);
+
+  return mismatched.length
+    ? `値とコメントが食い違っています（16px = 1rem 換算）: ${summarize(mismatched)}`
+    : null;
+});
+
+check('テンプレートの波括弧が釣り合っていること', () => {
+  const stripped = template.replace(/\{\{[A-Za-z_]+\}\}/g, '');
+  const open = (stripped.match(/\{/g) || []).length;
+  const close = (stripped.match(/\}/g) || []).length;
+  return open === close ? null : `開き ${open} / 閉じ ${close}`;
+});
+
+// CLI はプレースホルダーを **完全一致の正規表現**で置換する。大文字小文字の
+// タイポや、コメントの体裁を整えただけでも置換が no-op になり、
+// 「CLI は成功終了するのにプリミティブカラーが 1 つも出ない」状態になる。
+check('プレースホルダーが CLI の期待どおりの字面であること', () => {
+  const KNOWN = new Set([
+    '{{FONT_IMPORTS}}',
+    '{{COLOR_TOKENS}}',
+    '{{FONT_FAMILY_PRO}}',
+    '{{FONT_FAMILY_MONO}}',
+    '{{FONT_PRO}}',
+    '{{FONT_MONO}}',
+    '{{FONT_PRO_URL}}',
+    '{{FONT_MONO_URL}}',
+    '{{PRIMARY}}',
+    '{{RADIUS}}',
+  ]);
+
+  const problems = [];
+
+  // 大文字小文字を問わず `{{...}}` を拾う。`[A-Z_]+` 限定だと `{{primary}}` の
+  // ようなタイポが「そもそも検出されない」＝合格になってしまう。
+  const found = [...new Set([...template.matchAll(/\{\{[A-Za-z0-9_]+\}\}/g)].map((m) => m[0]))];
+  expect(found.length, 4, 'プレースホルダー');
+  const unknown = found.filter((p) => !KNOWN.has(p));
+  if (unknown.length) {
+    problems.push(`CLI が知らないプレースホルダー: ${unknown.join(', ')}（大文字小文字も一致させてください）`);
+  }
+
+  // CLI 側の正規表現（lib/constants.js）はコメント内側のスペースを 1 個ずつ
+  // 要求する。`/*{{COLOR_TOKENS}}*/` のように整形すると静かに置換されなくなる。
+  const CLI_BLOCK_PLACEHOLDERS = [
+    { name: '{{COLOR_TOKENS}}', pattern: /[ \t]*\/\* \{\{COLOR_TOKENS\}\} \*\/[ \t]*\n?/ },
+    { name: '{{FONT_IMPORTS}}', pattern: /[ \t]*\/\* \{\{FONT_IMPORTS\}\} \*\/[ \t]*\n?/ },
+  ];
+  for (const { name, pattern } of CLI_BLOCK_PLACEHOLDERS) {
+    if (!pattern.test(template)) {
+      problems.push(
+        `${name} が CLI の置換正規表現にマッチしません（\`/* ${name} */\` の形で、コメント記号の内側にスペースを 1 個ずつ入れてください）`
+      );
+    }
+  }
+
+  return problems.length ? problems.join(' / ') : null;
+});
+
+// ---------------------------------------------------------------------------
+// 結果
+// ---------------------------------------------------------------------------
+for (const { name, ok } of checks) {
+  console.log(`${ok ? '✅' : '❌'} ${name}`);
+}
+
+if (failures.length) {
+  console.error(`\n${failures.length} 件の不整合が見つかりました:\n`);
+  for (const { name, detail } of failures) {
+    console.error(`❌ ${name}\n   ${detail}\n`);
+  }
+  process.exit(1);
+}
+
+console.log(`\n${checks.length} 件すべて OK`);