sparkle-design-cli 2.0.7-beta.0 → 2.0.7-beta.10

package/README.md

@@ -15,7 +15,7 @@ setup は次を自動で行います:
 1. パッケージマネージャー（pnpm / npm / yarn / bun）を自動検出
 2. `sparkle-design` を dependencies、`tailwindcss` + `@tailwindcss/postcss` を devDependencies に追加
 3. 未作成の場合のみ初期ファイルを生成:
-   - `sparkle.config.json`（デフォルトは blue / Inter / JetBrains Mono / md）
+   - `sparkle.config.json`（デフォルトは blue / BIZ UDPGothic / BIZ UDGothic / md — sparkle-design 本体のデフォルトに合わせて統一）
    - `postcss.config.mjs`
    - Tailwind エントリ CSS — Next.js App Router なら `src/app/globals.css`、Vite なら `src/index.css`、それ以外は `src/globals.css`（プロジェクト構成から自動判定）
 4. AI 指示ファイル（`CLAUDE.md` / `AGENTS.md` / Cursor rules）に Sparkle Design Guard ブロックを追加
@@ -35,10 +35,10 @@ npm install -g sparkle-design-cli
 
 npm の dist-tag でチャネルを分離しています。通常は latest を使い、品質保証中の変更を試したい場合のみ beta を指定してください。
 
-| チャネル | dist-tag | 用途 | 指定方法 |
-|---------|---------|------|---------|
-| 安定版 | `latest` | 本番運用向け。`npx --yes sparkle-design-cli` は常にこれを取得 | （デフォルト） |
-| Beta | `beta` | 品質保証中の検証用 | `npx --yes sparkle-design-cli@beta` |
+| チャネル | dist-tag | 用途                                                          | 指定方法                            |
+| -------- | -------- | ------------------------------------------------------------- | ----------------------------------- |
+| 安定版   | `latest` | 本番運用向け。`npx --yes sparkle-design-cli` は常にこれを取得 | （デフォルト）                      |
+| Beta     | `beta`   | 品質保証中の検証用                                            | `npx --yes sparkle-design-cli@beta` |
 
 ```bash
 # beta で setup を試す
@@ -103,6 +103,12 @@ sparkle-design-cli generate --output ./styles/design.css
 
 # 設定ファイルと出力先を両方指定
 sparkle-design-cli generate -c ./config/custom.json -o ./dist/styles.css
+
+# Tailwind エントリ CSS を明示指定
+sparkle-design-cli generate --globals-path src/styles/app.css
+
+# CI 向け: @source 注入や Tailwind import 欠落などの失敗を exit 1 にする
+sparkle-design-cli generate --strict
 ```
 
 #### generate オプション一覧
@@ -110,6 +116,12 @@ sparkle-design-cli generate -c ./config/custom.json -o ./dist/styles.css
 - `-h, --help`: ヘルプメッセージを表示
 - `-c, --config <パス>`: 設定ファイルのパス（デフォルト: `./sparkle.config.json`）
 - `-o, --output <パス>`: 出力ファイルのパス（デフォルト: `./src/app/sparkle-design.css`）
+- `--globals-path <パス>`: Tailwind エントリポイント CSS のパス（デフォルト: 自動検出）。
+  **指定したパスが存在しない場合は `--strict` の有無に関わらず常に exit 1**（`sparkle.config.json` の `extend.globals-path` も同様）
+- `--strict`: 以下を warn ではなく **exit 1** に昇格させる（CI 向け。既定は warn + 継続で後方互換を維持）:
+  - デザインシステムパッケージが `package.json` に入っているのに Tailwind エントリ CSS が見つからない
+  - エントリ CSS はあるが `@import "tailwindcss";` が書かれていない（警告メッセージに追記すべき行まで actionable に表示）
+  - エントリ CSS への書き込みに失敗した
 
 ### check: アンチパターン検査
 
@@ -142,24 +154,15 @@ sparkle-design-cli check --help
 - children なしの Button に prefixIcon / suffixIcon を使わない
 - Material Symbols を className 直書きで使わない
 - shadcn/ui 既定 token を Sparkle Design 内へ持ち込まない
-- Tailwind デフォルト typography（text-sm, font-medium 等）を使わない
-- CardTitle に typography を上書きしない
+- Tailwind デフォルト typography を Sparkle Design コンポーネント内で使わない
+- CardTitle に typography 系クラスを付与しない
 - CardControl に Button / IconButton 以外を入れない
-- CardHeader / CardContent の padding を上書きしない
-- asChild と prefixIcon / suffixIcon / isLoading を併用しない
-- disabled を isDisabled の代わりに使わない
-- Button の prefixIcon に JSX を渡さない
+- Card 系コンポーネントのデフォルト padding を安易に上書きしない
+- asChild 使用時に prefixIcon / suffixIcon / isLoading を使わない
+- Sparkle Design コンポーネントでは isDisabled を使う
+- Button の prefixIcon / suffixIcon に JSX を渡さない
 - Icon の children にテキストを渡さない
-- クリック可能な Card を `<button>` / `<a>` / `role="button"` でラップせず、`ClickableCard` を使う
-
-#### Manual Review Reminders
-
-`--format json` では、機械検出できない観点も `manualReviewReminders` として返します。現在は次を含みます。
-
-- Badge と Tag の意味的な使い分け
-- CardDescription の typography / color token 明示
-- Dialog と Modal の UX 上の使い分け
-- 手書き span が Tag で置き換え可能か
+- クリック可能な Card は ClickableCard を使う（button / a / role="button" でラップしない）
 
 #### 導入先での推奨設定
 
@@ -198,6 +201,7 @@ npx --yes sparkle-design-cli setup --assistant claude --skip-install --skip-scaf
 ```
 
 既存ファイルは上書きされません:
+
 - `sparkle.config.json` / `postcss.config.*` / Tailwind エントリ CSS が存在する場合はそのまま保持
 - 既に依存関係に入っているパッケージはインストールをスキップ
 - `package.json` の既存の `lint:sparkle*` 独自 script は保持（`--force-script-update` で上書き）
@@ -205,6 +209,7 @@ npx --yes sparkle-design-cli setup --assistant claude --skip-install --skip-scaf
 `--target` を省略した場合、lint 対象は `src`, `src/components`, `src/features`, `app`, `components` の順で自動検出されます。
 
 利用できる assistant:
+
 - `claude`: `CLAUDE.md`
 - `codex`: `AGENTS.md`
 - `cursor`: `.cursor/rules/sparkle-design-guard.mdc`
@@ -220,9 +225,117 @@ npx --yes sparkle-design-cli setup --assistant claude --skip-install --skip-scaf
 - `--skip-generate`: `generate` 実行をスキップ
 - `--dry-run`: ファイルを変更せず結果だけ表示
 - `--force-script-update`: 既存の `lint:sparkle` 系 script も上書き
+- `--strict`: `generate` ステージの失敗を exit 1 に昇格（CI 向け）。
+  現状は `generate` の失敗のみ対象（install / scaffold / guard の失敗は従来どおり warn）。
+  `--skip-generate` / `--dry-run` と併用した場合は strict チェック対象が無くなるため警告を出します。
 
 `setup` は通常実行時も JSON サマリーを stdout に表示します。`--dry-run` を付けると、その JSON を表示したままファイル変更だけを抑止します。
 
+### 手動セットアップ（Next.js / Vite 以外のプロジェクト向け）
+
+`setup` コマンドは **Next.js App Router** と **Vite** を前提に scaffold / entry CSS の配置を自動判定します。Remix / Astro / TanStack Start など他のフレームワークや、独自ディレクトリ構成のプロジェクトでは自動判定が外れるため、以下の手順で手動セットアップすることを推奨します。
+
+#### 手順
+
+**1. パッケージをインストール**
+
+```bash
+# 本体
+pnpm add sparkle-design        # or npm install / yarn add / bun add
+
+# Tailwind v4
+pnpm add -D tailwindcss @tailwindcss/postcss
+```
+
+**2. `sparkle.config.json` をプロジェクトルートに作成**
+
+```json
+{
+  "primary": "blue",
+  "font-pro": "Inter",
+  "font-mono": "JetBrains Mono",
+  "radius": "md"
+}
+```
+
+選択肢の詳細は本 README の「[設定オプション](#設定オプション)」を参照してください。
+
+**3. `postcss.config.mjs` をプロジェクトルートに作成**
+
+```js
+export default {
+  plugins: {
+    '@tailwindcss/postcss': {},
+  },
+};
+```
+
+**4. Tailwind エントリ CSS を自前で用意**
+
+既存プロジェクトに組み込む場合、`@import "tailwindcss";` を含む CSS ファイル（例: `src/styles/app.css`）があればそれを使います。無ければ作成してアプリケーションのエントリから import します。
+
+**5. `generate` を実行**
+
+```bash
+npx --yes sparkle-design-cli generate
+```
+
+これで `sparkle-design.css` が `src/app/sparkle-design.css` に生成され、`SparkleHead.tsx` も同じ場所に出ます。エントリ CSS の検出に失敗する場合は `sparkle.config.json` の `extend.globals-path` に明示指定してください。
+
+```json
+{
+  "primary": "blue",
+  "extend": {
+    "globals-path": "src/styles/app.css"
+  }
+}
+```
+
+**6. フォントの `<link>` タグを手動で配置**
+
+Next.js / Vite 以外ではアプリケーションフレームワークごとに「`<head>` 相当」の配置方法が異なります。自動生成される `SparkleHead.tsx` はそのまま使えるはずですが、使えない場合は中身（`preconnect` + Google Fonts の `<link>` タグ群）を自前のレイアウトにコピーしてください。
+
+たとえば Astro なら `src/layouts/BaseLayout.astro` の `<head>` に直接書きます:
+
+```html
+<link rel="preconnect" href="https://fonts.googleapis.com" />
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Material+Symbols+Rounded:FILL,wght@0..1,500&display=block" />
+<!-- sparkle.config.json の font-pro / font-mono に合わせた Google Fonts URL -->
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap" />
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;700&display=swap" />
+```
+
+**7. アンチパターン検査を package.json に追加（任意）**
+
+```json
+{
+  "scripts": {
+    "lint:sparkle": "npx --yes sparkle-design-cli check src --strict",
+    "lint:sparkle:json": "npx --yes sparkle-design-cli check src --format json"
+  }
+}
+```
+
+**8. AI エージェントを使うなら Guard ブロックと hook を手動で配置**
+
+AI ガード（`CLAUDE.md` / `AGENTS.md` / `.cursor/rules/*.mdc`）と hook 設定（`.claude/settings.json` / `.cursor/hooks.json` / `.codex/hooks.json`）は `setup` に任せるのが最も楽です。
+
+```bash
+# ガード追加・hook 設定のみ（パッケージインストールや scaffold はスキップ）
+npx --yes sparkle-design-cli setup --assistant claude --skip-install --skip-scaffold --skip-generate
+```
+
+この `--skip-*` 組み合わせは手動セットアップ済みのプロジェクトに対して Guard + hook だけ差し込むのに使えます。
+
+#### 既知の未対応ケース
+
+- **モノレポ（workspaces）**: `generate` は実行した cwd からパッケージマネージャーを遡及検出しないため、サブパッケージで直接実行するのが確実です。
+- **CSS 以外のエントリ（CSS-in-JS / vanilla-extract 等）**: Sparkle Design は Tailwind v4 の `@source` + CSS variable 前提で作られているため、ビルドパイプラインの外で CSS を扱うソリューションは対象外です。
+- **Tailwind v3**: `@source` ディレクティブ依存のため v4 必須です。
+
+Next.js / Vite 以外で導入したい方で困ったときは Issue で教えていただけると助かります。
+
 ## 設定ファイル (sparkle.config.json)
 
 ### 設定ファイルの作成
@@ -259,9 +372,7 @@ Figma プラグインが出力する基本4項目に加えて、プロジェク
         { "family": "Montserrat", "weights": [500, 600, 700] },
         { "family": "Noto Sans JP", "weights": [400, 500, 600, 700] }
       ],
-      "mono": [
-        { "family": "Roboto Mono", "weights": [400, 700] }
-      ]
+      "mono": [{ "family": "Roboto Mono", "weights": [400, 700] }]
     },
     "source-packages": ["@goodpatch/sparkle-design-internal"],
     "custom-css": "./src/app/custom-tokens.css"

package/bin/sparkle-design.js

@@ -19,6 +19,7 @@ function parseGenerateOptions(args) {
     configPath: null,
     outputPath: null,
     globalsPath: null,
+    strict: false,
     help: false,
   };
 
@@ -36,6 +37,8 @@ function parseGenerateOptions(args) {
     } else if (arg === '--globals-path') {
       options.globalsPath = requireOptionValue(args, i, '--globals-path');
       i += 1;
+    } else if (arg === '--strict') {
+      options.strict = true;
     } else {
       throw new Error(`Unknown option for generate: ${arg}`);
     }
@@ -86,6 +89,7 @@ function parseSetupOptions(args) {
     skipInstall: false,
     skipScaffold: false,
     skipGenerate: false,
+    strict: false,
     help: false,
   };
 
@@ -113,6 +117,8 @@ function parseSetupOptions(args) {
       options.skipScaffold = true;
     } else if (arg === '--skip-generate') {
       options.skipGenerate = true;
+    } else if (arg === '--strict') {
+      options.strict = true;
     } else {
       throw new Error(`Unknown option for setup: ${arg}`);
     }
@@ -161,6 +167,8 @@ Generate options:
   -c, --config <path>        設定ファイルのパス (default: ./sparkle.config.json)
   -o, --output <path>        出力ファイルのパス (default: ./src/app/sparkle-design.css)
   --globals-path <path>      Tailwind エントリポイント CSS のパス (default: 自動検出)
+  --strict                   globals.css への @source 注入等が失敗したら exit 1
+                             (CI 向け。既定は warn + 継続で後方互換を維持)
 
 sparkle.config.json の設定フィールド:
 
@@ -204,6 +212,7 @@ Setup options:
   --skip-install             パッケージインストール（sparkle-design, tailwindcss）をスキップ
   --skip-scaffold            初期ファイル（sparkle.config.json, postcss.config, エントリ CSS）生成をスキップ
   --skip-generate            generate 実行をスキップ
+  --strict                   generate の失敗を exit 1 に昇格（CI 向け）
 
 Setup の動作:
   1. パッケージマネージャー検出（pnpm / npm / yarn / bun）
@@ -257,7 +266,9 @@ function main() {
         process.exit(0);
       }
 
-      generateCSS(options.configPath, options.outputPath, options.globalsPath);
+      generateCSS(options.configPath, options.outputPath, options.globalsPath, {
+        strict: options.strict,
+      });
       return;
     }
 

package/lib/anti-pattern-rules.js

@@ -23,7 +23,6 @@ function renderJSDocSection(section) {
   return output.map((line) => (line ? ` * ${line}` : ' *')).join('\n');
 }
 
-
 const MANUAL_REVIEW_REMINDERS = [
   {
     id: 'badge-tag-semantics',
@@ -492,7 +491,8 @@ const ANTI_PATTERN_GROUPS = [
   {
     id: 'card-clickable-wrap',
     check: {
-      description: 'クリック可能な Card は ClickableCard を使う（button / a / role="button" でラップしない）',
+      description:
+        'クリック可能な Card は ClickableCard を使う（button / a / role="button" でラップしない）',
       recommendation:
         '`<Card>` を `<button>` / `<a>` / `role="button"` を持つ要素で包まず、`ClickableCard` を使ってください。`ClickableCard` が適切な role / keyboard 対応 / focus ring を担保します。',
       // <button> / <a> / role="button" が直接 <Card> を子に持つケース
@@ -949,7 +949,8 @@ const ANTI_PATTERN_GROUPS = [
       description: 'CardTitle に typography 系クラスを付与しない',
       recommendation:
         'CardTitle は character-4-bold-pro を内蔵しています。className で typography を上書きしないでください。',
-      pattern: /<CardTitle\b[^>]*\bclassName\s*=\s*(?:"[^"]*\bcharacter-[^"]*"|'[^']*\bcharacter-[^']*'|\{[^}]*\bcharacter-[^}]*\})[^>]*>/g,
+      pattern:
+        /<CardTitle\b[^>]*\bclassName\s*=\s*(?:"[^"]*\bcharacter-[^"]*"|'[^']*\bcharacter-[^']*'|\{[^}]*\bcharacter-[^}]*\})[^>]*>/g,
     },
     featureSection: lines([
       '### CardTitle に typography を上書きしない',
@@ -970,7 +971,35 @@ const ANTI_PATTERN_GROUPS = [
       description: 'CardControl に Button / IconButton 以外を入れない',
       recommendation:
         'CardControl はアクションボタン用です。ステータス表示には CardDescription を使ってください。',
-      pattern: /<CardControl\b[^>]*>[\s\S]*?<(?!Button\b|IconButton\b|\/CardControl)\w+/g,
+      // 2-pass matcher。1 本の regex に入れ子 negative lookahead を押し込む代わりに、
+      // まず <CardControl>…</CardControl> ブロックを抽出し、次にブロック内部だけを
+      // スキャンして Button / IconButton / 入れ子 CardControl 以外の開始タグを見つける。
+      //   1. 入れ子 negative lookahead が無くなり読みやすい
+      //   2. 自己閉じ `<CardControl />` は 1st pass でそもそも拾わない（special case 不要）
+      //   3. O(総コンテンツ長) で評価が済むため、大規模 JSX でも backtracking で
+      //      処理時間が跳ねない
+      // en: Two-pass matcher. First pass extracts `<CardControl>…</CardControl>`
+      // blocks (self-closing variants are skipped because the opening-tag regex
+      // requires the previous char not to be `/`). Second pass scans the inner
+      // content for any element that is not Button / IconButton / nested
+      // CardControl. This replaces the nested tempered-lazy regex with a shape
+      // that is easier to reason about and stays linear in total content length.
+      match: (content) => {
+        const BLOCK_PATTERN = /<CardControl\b[^>]*(?<!\/)>([\s\S]*?)<\/CardControl\b[^>]*>/g;
+        const NON_BUTTON_CHILD = /<(?!Button\b|IconButton\b|CardControl\b)[A-Za-z][\w.]*/g;
+        const results = [];
+        for (const blockMatch of content.matchAll(BLOCK_PATTERN)) {
+          const openingEnd = blockMatch.index + blockMatch[0].indexOf('>') + 1;
+          const inner = blockMatch[1];
+          for (const childMatch of inner.matchAll(NON_BUTTON_CHILD)) {
+            results.push({
+              index: openingEnd + childMatch.index,
+              text: childMatch[0],
+            });
+          }
+        }
+        return results;
+      },
     },
     featureSection: lines([
       '### CardControl にはアクションボタンのみを入れる',
@@ -1020,7 +1049,8 @@ const ANTI_PATTERN_GROUPS = [
       description: 'Card 系コンポーネントのデフォルト padding を安易に上書きしない',
       recommendation:
         'CardHeader / CardContent のデフォルト padding（px-6 py-2）をそのまま使ってください。上書きは本当に必要な場合のみ。',
-      pattern: /<Card(?:Header|Content)\b[^>]*\bclassName\s*=\s*(?:"[^"]*\b(?:p-|px-|py-|pt-|pb-|pl-|pr-)[^"]*"|'[^']*\b(?:p-|px-|py-|pt-|pb-|pl-|pr-)[^']*'|\{[^}]*\b(?:p-|px-|py-|pt-|pb-|pl-|pr-)[^}]*\})[^>]*>/g,
+      pattern:
+        /<Card(?:Header|Content)\b[^>]*\bclassName\s*=\s*(?:"[^"]*\b(?:p-|px-|py-|pt-|pb-|pl-|pr-)[^"]*"|'[^']*\b(?:p-|px-|py-|pt-|pb-|pl-|pr-)[^']*'|\{[^}]*\b(?:p-|px-|py-|pt-|pb-|pl-|pr-)[^}]*\})[^>]*>/g,
     },
     featureSection: lines([
       '### Card 系コンポーネントの padding を上書きしない',
@@ -1045,7 +1075,8 @@ const ANTI_PATTERN_GROUPS = [
       description: 'asChild 使用時に prefixIcon / suffixIcon / isLoading を使わない',
       recommendation:
         'asChild モードでは prefixIcon / suffixIcon / isLoading は無視されます。アイコン付きの Link が必要なら asChild を外してください。',
-      pattern: /<Button\b(?=[^>]*\basChild\b)(?=[^>]*\b(?:prefixIcon|suffixIcon|isLoading)\b)[^>]*>/g,
+      pattern:
+        /<Button\b(?=[^>]*\basChild\b)(?=[^>]*\b(?:prefixIcon|suffixIcon|isLoading)\b)[^>]*>/g,
     },
     featureSection: lines([
       '### asChild と prefixIcon / suffixIcon / isLoading を併用しない',
@@ -1133,7 +1164,21 @@ const ANTI_PATTERN_GROUPS = [
 ];
 
 function getCheckRules() {
-  const order = ['dialog-form', 'dialog-button-wrap', 'button-icon-only', 'material-symbols-direct', 'shadcn-token', 'tailwind-typography', 'card-title-typography', 'card-control-non-button', 'card-padding-override', 'aschild-with-icon-props', 'disabled-vs-is-disabled', 'button-prefixicon-jsx', 'icon-children-text'];
+  const order = [
+    'dialog-form',
+    'dialog-button-wrap',
+    'button-icon-only',
+    'material-symbols-direct',
+    'shadcn-token',
+    'tailwind-typography',
+    'card-title-typography',
+    'card-control-non-button',
+    'card-padding-override',
+    'aschild-with-icon-props',
+    'disabled-vs-is-disabled',
+    'button-prefixicon-jsx',
+    'icon-children-text',
+  ];
 
   return ANTI_PATTERN_GROUPS.filter((group) => group.check)
     .map((group) => ({

package/lib/check.js

@@ -12,7 +12,12 @@ const BASE_MANUAL_REVIEW_REMINDERS = getManualReviewReminders();
 
 const SPARKLE_HEAD_JSX_PATTERN = /<SparkleHead\s*\/?\s*>/;
 const CSP_PATTERN = /content-security-policy|contentSecurityPolicy|Content-Security-Policy/i;
-const NEXT_CONFIG_CANDIDATES = ['next.config.js', 'next.config.ts', 'next.config.mjs', 'next.config.cjs'];
+const NEXT_CONFIG_CANDIDATES = [
+  'next.config.js',
+  'next.config.ts',
+  'next.config.mjs',
+  'next.config.cjs',
+];
 
 function toRelativeReportPath(filePath) {
   return path.relative(process.cwd(), filePath).split(path.sep).join('/');
@@ -65,10 +70,30 @@ function formatMatch(match) {
   return match[0].replace(/\s+/g, ' ').trim().slice(0, 120);
 }
 
+function formatSnippet(text) {
+  return text.replace(/\s+/g, ' ').trim().slice(0, 120);
+}
+
 function collectFindings(filePath, content) {
   const findings = [];
 
   for (const rule of RULES) {
+    if (typeof rule.match === 'function') {
+      // rule.match(content) -> Array<{ index: number, text: string }>
+      // 複雑な照合が必要なルール向けの opt-in API。2-pass 方式などで regex 単体の
+      // backtracking リスクを回避したいときに使う。index は content 内の絶対オフセット。
+      for (const hit of rule.match(content)) {
+        findings.push({
+          filePath,
+          id: rule.id,
+          description: rule.description,
+          recommendation: rule.recommendation,
+          line: getLineNumber(content, hit.index ?? 0),
+          snippet: formatSnippet(hit.text ?? ''),
+        });
+      }
+      continue;
+    }
     for (const match of content.matchAll(rule.pattern)) {
       findings.push({
         filePath,
@@ -96,8 +121,10 @@ function collectFontImportFindings(cssFiles) {
       findings.push({
         filePath,
         id: 'font-import-in-css',
-        description: 'CSS にフォント @import が残っています。SparkleHead コンポーネントに移行してください。',
-        recommendation: 'sparkle-design-cli generate を再実行すると、フォント読み込みが SparkleHead.tsx に移行され、globals.css から @import が除去されます。',
+        description:
+          'CSS にフォント @import が残っています。SparkleHead コンポーネントに移行してください。',
+        recommendation:
+          'sparkle-design-cli generate を再実行すると、フォント読み込みが SparkleHead.tsx に移行され、globals.css から @import が除去されます。',
         line: getLineNumber(content, match.index ?? 0),
         snippet: match[0].slice(0, 120),
       });
@@ -140,12 +167,20 @@ function collectNextjsCspFindings(cwd) {
     if (!CSP_PATTERN.test(content)) continue;
 
     const missingDomains = [
-      { domain: 'fonts.googleapis.com', directive: 'style-src', pattern: new RegExp(FONT_DOMAINS.GOOGLEAPIS.replace('https://', '')) },
-      { domain: 'fonts.gstatic.com', directive: 'font-src', pattern: new RegExp(FONT_DOMAINS.GSTATIC.replace('https://', '')) },
+      {
+        domain: 'fonts.googleapis.com',
+        directive: 'style-src',
+        pattern: new RegExp(FONT_DOMAINS.GOOGLEAPIS.replace('https://', '')),
+      },
+      {
+        domain: 'fonts.gstatic.com',
+        directive: 'font-src',
+        pattern: new RegExp(FONT_DOMAINS.GSTATIC.replace('https://', '')),
+      },
     ].filter(({ pattern }) => !pattern.test(content));
 
     if (missingDomains.length > 0) {
-      const missing = missingDomains.map(d => `${d.domain} (${d.directive})`).join(', ');
+      const missing = missingDomains.map((d) => `${d.domain} (${d.directive})`).join(', ');
       findings.push({
         filePath: configPath,
         id: 'csp-font-block',
@@ -206,7 +241,8 @@ function createCheckReport(targets = []) {
   if (!hasSparkleHeadUsage(fileContents)) {
     manualReviewReminders.push({
       id: 'sparkle-head-missing',
-      message: 'SparkleHead がソースコード内に見つかりませんでした。ルートレイアウトの <head> 内に <SparkleHead /> を配置してフォントの早期読み込みを有効にしてください。',
+      message:
+        'SparkleHead がソースコード内に見つかりませんでした。ルートレイアウトの <head> 内に <SparkleHead /> を配置してフォントの早期読み込みを有効にしてください。',
     });
   }
 
@@ -232,9 +268,37 @@ function printTextReport(report, options = {}) {
     }
   }
 
-  console.log('Manual review reminders:');
-  for (const reminder of report.manualReviewReminders) {
-    console.log(`- [${reminder.id}] ${reminder.message}`);
+  const reminders = report.manualReviewReminders ?? [];
+  if (reminders.length === 0) {
+    // 0 件のときは従来通り静かに済ます。
+    // en: Nothing to review — keep quiet.
+  } else {
+    // Guard block から参照される acknowledgment フォーマットと合わせるため、
+    // AI 向けに「各 ID を response に echo して確認したことを示してほしい」
+    // と明示的に要求する。hook による exit blocking はしない（判断事項のため）。
+    // en: Ask the AI to echo each reminder ID in its final response, so humans
+    // can see which reminders were considered. This is not enforced by hook
+    // exit code — reminders are judgment calls, not hard failures.
+    console.log('');
+    console.log('=== Manual review reminders (must acknowledge each ID in your response) ===');
+    console.log(
+      'These are judgment calls the linter cannot detect. For every item below,'
+    );
+    console.log(
+      'explicitly state the reminder ID in your reply together with whether the'
+    );
+    console.log(
+      'current code already satisfies it, or what change is needed. Silence = skipped.'
+    );
+    console.log('');
+    for (const reminder of reminders) {
+      console.log(`- [${reminder.id}] ${reminder.message}`);
+    }
+    console.log('');
+    console.log(
+      'Example acknowledgment: "[badge-tag-semantics] reviewed — Badge used only for counts (OK). [dialog-modal-ux] reviewed — changed Dialog to Modal for form case."'
+    );
+    console.log('=========================================================================');
   }
 
   if (options.strict && report.findings.length > 0) {
@@ -245,6 +309,7 @@ function printTextReport(report, options = {}) {
 function printJsonReport(report, options = {}) {
   const strictMode = Boolean(options.strict);
   const passed = !(strictMode && report.findings.length > 0);
+  const reminders = report.manualReviewReminders ?? [];
 
   console.log(
     JSON.stringify(
@@ -253,6 +318,18 @@ function printJsonReport(report, options = {}) {
           targetCount: report.targets.length,
           checkedFileCount: report.checkedFiles.length,
           findingCount: report.findings.length,
+          reminderCount: reminders.length,
+          // AI 向けの attention フラグ。reminder が 1 件でもあれば true になり、
+          // AI は最終 response で各 reminder ID を echo する必要がある。
+          // exit code には寄与しない（判断事項を hook で block するのは過剰）。
+          // en: AI attention flag. When reminders exist, the AI MUST echo each
+          // reminder ID in its final reply. Not tied to exit code — reminders
+          // are judgment calls, not hard errors.
+          manualReviewRequired: reminders.length > 0,
+          reminderAcknowledgmentFormat:
+            reminders.length > 0
+              ? 'Respond with each reminder ID followed by your review, e.g. `[badge-tag-semantics] reviewed — Badge is used only for counts (OK)`.'
+              : null,
           strictMode,
           passed,
           exitCode: passed ? 0 : 1,
@@ -277,4 +354,9 @@ export function checkProject(targets = [], options = {}) {
   return report.findings.length > 0;
 }
 
-export { RULES, collectFindings, createCheckReport, BASE_MANUAL_REVIEW_REMINDERS as MANUAL_REVIEW_REMINDERS };
+export {
+  RULES,
+  collectFindings,
+  createCheckReport,
+  BASE_MANUAL_REVIEW_REMINDERS as MANUAL_REVIEW_REMINDERS,
+};

package/lib/constants.js

@@ -18,6 +18,21 @@ export const PATHS = {
   TEMPLATE_DIR: ['templates', 'sparkle-variables'],
 };
 
+// プロジェクト root から Tailwind エントリ CSS を探索するときの候補パス（優先順）。
+// `setup` の scaffold 判定と、`generate` の `resolveGlobalsPath` の project-root
+// fallback で同じ配列を参照することで二重化 drift を防ぐ。
+// en: Candidate paths (priority-ordered) used both by `setup` scaffold and by
+// `generate`'s project-root fallback in `resolveGlobalsPath`. Sharing the array
+// prevents drift between "where we create the entry CSS" and "where we look
+// for it later".
+export const GLOBALS_CSS_CANDIDATES = [
+  'src/app/globals.css',
+  'app/globals.css',
+  'src/globals.css',
+  'src/index.css',
+  'src/styles/globals.css',
+];
+
 // 正規表現パターン
 export const REGEX = {
   // フォント関連
@@ -29,13 +44,30 @@ export const REGEX = {
     /\/\*\s*フォントのインポート[^*]*\*\/\s*\n?(?:@import\s+(?:url\([^)]+fonts\.googleapis\.com[^)]+\)|['"][^"']*fonts\.googleapis\.com[^"']*['"]);?\s*\n?)*\n?/g,
 
   // Sparkle Design関連
+  // `@import "sparkle-design.css"` / `@import "./sparkle-design.css"` だけでなく
+  // `@import "./app/sparkle-design.css"` 等、任意の相対パスを含む variant も
+  // 除去対象にする。Vite のように entry CSS (src/index.css) と sparkle-design.css
+  // (src/app/sparkle-design.css) が別ディレクトリに置かれるレイアウトでは
+  // 後者のような path になるので、同一 dir 前提の regex だと AI が手で直したもの
+  // を除去できず二重 import が残ってしまう。
+  // en: Match any relative path ending in `sparkle-design.css`, including layouts
+  // like Vite where the entry CSS and sparkle-design.css live in different dirs.
   SPARKLE_IMPORT:
-    /\/\*\s*Sparkle Design[^*]*\*\/\s*\n?|@import\s+['"](\.\/)?sparkle-design\.css['"];?\s*\n?/g,
+    /\/\*\s*Sparkle Design[^*]*\*\/\s*\n?|@import\s+['"][^"']*sparkle-design\.css['"];?\s*\n?/g,
   TAILWIND_IMPORT: /@import\s+['"]tailwindcss['"];?/,
 
   // @source ディレクティブ関連
+  // ※ 単体の SOURCE_DIRECTIVE は「ユーザーが手書きした @source も含めて全部」
+  // マッチしてしまうので、removeExistingImports では使わない（ユーザー記述を
+  // 消してしまう）。CLI が挿入した block（コメント + それに続く連続 @source 行）
+  // だけを除去するために MANAGED_SOURCE_BLOCK を使う。
+  // en: SOURCE_DIRECTIVE alone matches user-authored @source lines too, so
+  // removeExistingImports uses MANAGED_SOURCE_BLOCK instead to remove only the
+  // comment-prefixed block that the CLI itself wrote.
   SOURCE_DIRECTIVE: /@source\s+["'][^"']*["'];?\s*\n?/g,
   SOURCE_COMMENT: /\/\*\s*npm パッケージのコンテンツスキャン[^*]*\*\/\s*\n?/g,
+  MANAGED_SOURCE_BLOCK:
+    /\/\*\s*npm パッケージのコンテンツスキャン[^*]*\*\/\s*\n?(?:@source\s+["'][^"']*["'];?\s*\n?)*/g,
 
   // カスタムCSS関連
   CUSTOM_CSS_IMPORT:
@@ -107,11 +139,17 @@ export const COMMENTS = {
   FONT_IMPORT: '/* フォントのインポート（CSSの仕様上、@importは最初に記述する必要がある） */',
   SPARKLE_IMPORT: '/* Sparkle Design のカスタム定義（Tailwindの後にインポート） */',
   TAILWIND_IMPORT: '/* Tailwindのインポート */',
-  SOURCE_DIRECTIVE: '/* npm パッケージのコンテンツスキャン（Tailwind がクラスを検出するために必要） */',
+  SOURCE_DIRECTIVE:
+    '/* npm パッケージのコンテンツスキャン（Tailwind がクラスを検出するために必要） */',
   CUSTOM_CSS: '/* プロジェクト固有のカスタムトークン */',
 };
 
 // インポート文のテンプレート
+// SPARKLE_DESIGN は entry CSS と sparkle-design.css が同じディレクトリにある
+// 場合のデフォルト。異なる場合は buildSparkleImportStatement() で相対 path を
+// 計算して差し替える（Vite の src/index.css → src/app/sparkle-design.css 等）。
+// en: Default when entry CSS and sparkle-design.css share a directory. Use
+// buildSparkleImportStatement() for layouts that place them in different dirs.
 export const IMPORTS = {
   SPARKLE_DESIGN: '@import "./sparkle-design.css";',
   TAILWIND: '@import "tailwindcss";',
@@ -145,7 +183,11 @@ export const MESSAGES = {
   FONT_REMOVE_SKIPPED: 'ℹ️  globals.css の更新に失敗したため、フォントimport削除をスキップします。',
 
   // 警告メッセージ
-  TAILWIND_NOT_FOUND: '⚠️  globals.css に Tailwind import が見つかりません。',
+  // 指定された globals.css に Tailwind import が無いと @source / sparkle-design.css
+  // の挿入ができないため、どのファイルに何を書けばよいかを示す actionable なメッセージにする。
+  // en: Make the warning actionable — tell the user which file to edit and what to add.
+  TAILWIND_NOT_FOUND: (path) =>
+    `⚠️  ${path} に Tailwind import が見つかりません。ファイル先頭に \`@import "tailwindcss";\` を追記してください。`,
   GLOBALS_UPDATE_FAILED: (error) => `⚠️  globals.css の更新に失敗しました: ${error}`,
   FONT_MANAGEMENT_ERROR: (error) => `⚠️  フォント管理処理でエラーが発生しました: ${error}`,
   COLOR_CONVERSION_FAILED: (hex) => `⚠️ 色の変換に失敗しました: ${hex}`,