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

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,21 @@ const ANTI_PATTERN_GROUPS = [
       description: 'CardControl に Button / IconButton 以外を入れない',
       recommendation:
         'CardControl はアクションボタン用です。ステータス表示には CardDescription を使ってください。',
-      pattern: /<CardControl\b[^>]*>[\s\S]*?<(?!Button\b|IconButton\b|\/CardControl)\w+/g,
+      // 以前の regex は `[\s\S]*?` が `</CardControl>` を越えて貪欲に探索してしまい、
+      // 隣接する <CardContent> 等を非 Button 子要素として誤検知していた。
+      // 内部コンテンツが `</CardControl>` を越えないよう lazy 側に停止条件を入れ、
+      // 開始タグの直後から終了タグ直前までの範囲だけを検査する。
+      // 加えて (1) 開始タグ自体が自己閉じ `/>` で終わっていたら子要素は存在しない
+      // ので検査対象外とする（`[^>/]*[^>/]?`）、(2) ネストした `<CardControl>` も
+      // Button/IconButton 扱いのスキップリストに加えて誤発報を防ぐ。
+      // en: The previous pattern let `[\s\S]*?` leak past `</CardControl>`,
+      // flagging adjacent siblings (e.g. `<CardContent>`) as non-Button children.
+      // We now (a) constrain the lazy body so it cannot cross the closing tag,
+      // (b) skip self-closing tags `<CardControl />` entirely, and
+      // (c) treat a nested `<CardControl>` as an allowed child so we don't
+      // report the inner wrapper of a pathological nested structure.
+      pattern:
+        /<CardControl\b(?:[^>]*[^>/])?>(?:(?!<\/CardControl\b)[\s\S])*?<(?!Button\b|IconButton\b|CardControl\b|\/CardControl\b)[A-Za-z][\w.]*/g,
     },
     featureSection: lines([
       '### CardControl にはアクションボタンのみを入れる',
@@ -1020,7 +1035,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 +1061,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 +1150,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/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 = {
   // フォント関連
@@ -34,8 +49,17 @@ export const REGEX = {
   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,7 +131,8 @@ 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: '/* プロジェクト固有のカスタムトークン */',
 };
 
@@ -145,7 +170,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}`,

package/lib/font-manager.js

@@ -5,7 +5,7 @@
 
 import fs from 'fs';
 import path from 'path';
-import { REGEX, COMMENTS, IMPORTS, MESSAGES } from './constants.js';
+import { REGEX, COMMENTS, IMPORTS, MESSAGES, GLOBALS_CSS_CANDIDATES } from './constants.js';
 
 /**
  * sparkle-design.css からフォントの@import文を抽出する
@@ -58,8 +58,8 @@ function resolveNodeModulesRelPath(globalsPath) {
  */
 function createSourceBlock(sourcePackages = [], nodeModulesRel = '../node_modules') {
   const defaultPackage = 'sparkle-design';
-  const allPackages = [defaultPackage, ...sourcePackages.filter(p => p !== defaultPackage)];
-  const sourceLines = allPackages.map(pkg => `@source "${nodeModulesRel}/${pkg}/dist";`);
+  const allPackages = [defaultPackage, ...sourcePackages.filter((p) => p !== defaultPackage)];
+  const sourceLines = allPackages.map((pkg) => `@source "${nodeModulesRel}/${pkg}/dist";`);
   return [COMMENTS.SOURCE_DIRECTIVE, ...sourceLines].join('\n');
 }
 
@@ -126,8 +126,14 @@ function removeExistingImports(globalsContent) {
   // 既存のフォントimportを削除
   cleaned = cleaned.replace(REGEX.EXISTING_FONT_IMPORT_BLOCK, '');
 
-  // 既存の @source ディレクティブを削除
-  cleaned = cleaned.replace(REGEX.SOURCE_DIRECTIVE, '');
+  // CLI が過去に書き込んだ「コメント + @source 連続行」ブロックのみを削除する。
+  // ユーザーが手書きした `@source "..."` は保持する（以前は SOURCE_DIRECTIVE
+  // を単体で全削除していたため、手書き @source が消える退行があった）。
+  // en: Remove only the managed comment + @source block that the CLI itself
+  // wrote in the past. User-authored @source lines must survive this step.
+  cleaned = cleaned.replace(REGEX.MANAGED_SOURCE_BLOCK, '');
+  // 念のため CLI コメント単独で孤立している残骸も掃除。
+  // en: Sweep up any orphan comment lines left over from historical writes.
   cleaned = cleaned.replace(REGEX.SOURCE_COMMENT, '');
 
   // 既存のsparkle-design.css importを削除
@@ -174,28 +180,46 @@ function reconstructGlobalsCss(globalsContent, sparkleImportBlock, tailwindInfo)
   const afterTailwind = globalsContent.substring(tailwindInfo.afterIndex);
 
   // Tailwind + sparkle-design.css + 残りのコンテンツ（フォント @import なし）
-  return (
-    beforeTailwind +
-    tailwindInfo.match +
-    sparkleImportBlock +
-    afterTailwind.trimStart()
-  );
+  return beforeTailwind + tailwindInfo.match + sparkleImportBlock + afterTailwind.trimStart();
 }
 
 /**
  * globals.css を構造化して管理する
- * - フォントimportを先頭に配置
+ * - フォントimportを先頭に配置（v2.0.0 以降は SparkleHead.tsx に移行したため空配列が渡る）
  * - Tailwind importを確保
  * - sparkle-design.css importをTailwindの後に配置
+ * - 自動検出した sourcePackages から @source ディレクティブを挿入
+ *
+ * **v2.0.7-beta.2**: 戻り値を真偽値から `{ status, reason }` の状態付きに変更。
+ * 呼び出し側が「作業不要でスキップ」「失敗したがデフォルトは warn 継続」を
+ * 区別できるようにし、`--strict` モードで失敗を exit code に反映できるよう
+ * にした（#31）。`skipped` は後方互換のため `false` に、`updated` は `true`
+ * に toBoolean で扱える想定。
+ *
  * @param {Array<string>} fontImports フォントimport文の配列
  * @param {string} globalsPath globals.cssのパス
  * @param {Array<string>|null} sourcePackages 追加パッケージ名の配列（null の場合は @source を生成しない）
  * @param {string|null} customCssPath custom-css ファイルの相対パス
- * @returns {boolean} globals.css の更新に成功した場合は true
+ * @returns {{ status: 'skipped' | 'updated' | 'failed', reason?: string }}
+ *   skipped: 触る理由がない (fonts/sourcePackages/customCss すべて空)
+ *   updated: globals.css を正常に書き換えた
+ *   failed: 書き換え対象だったが失敗した (TAILWIND_IMPORT 欠落、write 失敗等)
  */
-export function updateGlobalsWithFonts(fontImports, globalsPath, sourcePackages = null, customCssPath = null) {
-  if (fontImports.length === 0) {
-    return false;
+export function updateGlobalsWithFonts(
+  fontImports,
+  globalsPath,
+  sourcePackages = null,
+  customCssPath = null
+) {
+  const hasFonts = fontImports.length > 0;
+  const hasSourcePackages = sourcePackages !== null && sourcePackages !== undefined;
+  const hasCustomCss = Boolean(customCssPath);
+
+  // フォント import も @source も custom-css もないなら globals.css に触る
+  // 理由がないので skip。
+  // en: Nothing to inject, so leave globals.css alone.
+  if (!hasFonts && !hasSourcePackages && !hasCustomCss) {
+    return { status: 'skipped', reason: 'no-work' };
   }
 
   try {
@@ -208,8 +232,12 @@ export function updateGlobalsWithFonts(fontImports, globalsPath, sourcePackages
     // 3. Tailwind import の位置を見つける
     const tailwindInfo = findTailwindImport(globalsContent);
     if (!tailwindInfo) {
-      console.warn(MESSAGES.TAILWIND_NOT_FOUND);
-      return false;
+      // 表示はプロジェクト相対パスにする。絶対パスだと「どのファイルをいじるのか」
+      // が一目で分かりにくく、リポジトリ間で絶対パスが変わるので diff も読みにくい。
+      // en: Show the project-relative path so it's obvious which file to edit.
+      const displayPath = path.relative(process.cwd(), globalsPath) || globalsPath;
+      console.warn(MESSAGES.TAILWIND_NOT_FOUND(displayPath));
+      return { status: 'failed', reason: 'tailwind-import-missing' };
     }
 
     // 4. importブロックを生成（フォント @import は SparkleHead に移行したため生成しない）
@@ -225,14 +253,45 @@ export function updateGlobalsWithFonts(fontImports, globalsPath, sourcePackages
     // 6. 更新したglobals.cssを書き込む
     fs.writeFileSync(globalsPath, reconstructedContent, 'utf8');
     console.log(MESSAGES.GLOBALS_UPDATED(globalsPath));
-    return true;
+    return { status: 'updated' };
   } catch (error) {
     console.error(MESSAGES.GLOBALS_UPDATE_FAILED(error.message));
-    // globals.cssの更新は必須ではないので、エラーでも処理を続行
-    return false;
+    return { status: 'failed', reason: `write-error: ${error.code ?? error.message}` };
   }
 }
 
+// Vite プロジェクト判定用の config 候補。setup.js 側の `VITE_CONFIG_FILES` と
+// 同じ対象を見る必要がある（判定ロジックが分かれると scaffold と generate で
+// 挙動が食い違う）。
+// en: Vite config candidates used for project detection. Must stay in sync with
+// setup.js's VITE_CONFIG_FILES so scaffold and generate agree on the layout.
+const VITE_CONFIG_FILES = [
+  'vite.config.ts',
+  'vite.config.js',
+  'vite.config.mjs',
+  'vite.config.cjs',
+  'vite.config.mts',
+  'vite.config.cts',
+];
+
+function isViteProject(cwd) {
+  return VITE_CONFIG_FILES.some((name) => fs.existsSync(path.join(cwd, name)));
+}
+
+// Vite プロジェクトで候補をソートするときの優先度。setup の
+// `defaultGlobalsCssTarget` に合わせて `src/index.css` を `src/globals.css`
+// より手前に引き上げる。それ以外は元の順序（数字昇順）を保つ。
+// en: When the project is Vite, promote `src/index.css` ahead of
+// `src/globals.css` so that `generate` patches the same file `setup` scaffolds.
+function vitePriority(candidate) {
+  if (candidate === 'src/index.css') return 0;
+  if (candidate === 'src/globals.css') return 1;
+  // それ以外の候補は元の GLOBALS_CSS_CANDIDATES 順序を保つため、index を
+  // オフセット付きで返す。
+  // en: Preserve the original order for everything else.
+  return 10 + GLOBALS_CSS_CANDIDATES.indexOf(candidate);
+}
+
 /**
  * sparkle-design.css と同じディレクトリで Tailwind のエントリポイント CSS を自動検出する
  * @param {string} dir 検索対象ディレクトリ
@@ -242,7 +301,16 @@ function detectTailwindEntrypoint(dir) {
   let entries;
   try {
     entries = fs.readdirSync(dir, { withFileTypes: true });
-  } catch {
+  } catch (err) {
+    // ENOENT / ENOTDIR はよくある（dir 自体が無い / ファイルを渡された）ので
+    // 静かにスキップ。権限 (EACCES) などは debugging 価値があるので表に出す。
+    // en: ENOENT / ENOTDIR are expected (dir missing / path is a file). Surface
+    // permission-style failures so the user can debug.
+    if (err.code !== 'ENOENT' && err.code !== 'ENOTDIR') {
+      console.warn(
+        `⚠️  ${dir} の読み込みに失敗したため同階層 detection をスキップします (${err.code ?? err.message})`
+      );
+    }
     return null;
   }
 
@@ -251,9 +319,20 @@ function detectTailwindEntrypoint(dir) {
     if (entry.name === 'sparkle-design.css') continue;
 
     const filePath = path.join(dir, entry.name);
-    const content = fs.readFileSync(filePath, 'utf8');
-    if (REGEX.TAILWIND_IMPORT.test(content)) {
-      return filePath;
+    try {
+      const content = fs.readFileSync(filePath, 'utf8');
+      if (REGEX.TAILWIND_IMPORT.test(content)) {
+        return filePath;
+      }
+    } catch (err) {
+      // 1 候補が読めなくても他の候補で続行できるようログを出してスキップする。
+      // 以前はここで throw させて外側の catch に落としていたため、同階層に
+      // 壊れた CSS が 1 つあると全部の detection が死んでいた。
+      // en: Keep scanning even if a single candidate file fails to read —
+      // previously a single unreadable CSS poisoned the whole detection.
+      console.warn(
+        `⚠️  ${entry.name} の読み込みに失敗したためスキップします (${err.code ?? err.message})`
+      );
     }
   }
 
@@ -262,10 +341,16 @@ function detectTailwindEntrypoint(dir) {
 
 /**
  * globals パスを解決する
- * 優先順位: 明示的指定 > 自動検出 > デフォルト（globals.css）
+ * 優先順位: 明示的指定 > sparkle-design.css 同階層で自動検出 > プロジェクト root の既知候補 > デフォルト（globals.css）
+ *
+ * **v2.0.7-beta.1**: Vite プロジェクトのように `sparkle-design.css` を `src/app/`
+ * に、entry CSS を `src/index.css` に置くレイアウトで `@source` が挿入されない
+ * 不具合があったため、同階層で見つからない場合はプロジェクト root からも
+ * 既知の候補を探すように拡張した（setup が scaffold に使う候補と同一）。
+ *
  * @param {string} sparkleDesignPath sparkle-design.css のパス
  * @param {string|null} explicitGlobalsPath 明示的に指定された globals パス
- * @returns {{ path: string, source: 'explicit' | 'detected' | 'default' } | null}
+ * @returns {{ path: string, source: 'explicit' | 'detected' | 'project' | 'default' } | null}
  */
 function resolveGlobalsPath(sparkleDesignPath, explicitGlobalsPath = null) {
   const dir = path.dirname(sparkleDesignPath);
@@ -275,11 +360,23 @@ function resolveGlobalsPath(sparkleDesignPath, explicitGlobalsPath = null) {
     if (fs.existsSync(resolved)) {
       return { path: resolved, source: 'explicit' };
     }
-    console.warn(`⚠️  指定された globals パスが見つかりません: ${explicitGlobalsPath}`);
-    return null;
+    // 明示指定は settings bug / typo なので silent warn ではなく throw に
+    // 昇格させる。--strict の有無に関わらず呼び出し元で伝播させたいので、
+    // error.code を付けて上流で識別できるようにする。
+    // en: An explicit --globals-path value that doesn't exist is almost
+    // always a typo. We tag the error so manageFontImports's catch knows
+    // to re-throw regardless of strict mode.
+    const err = new Error(
+      `指定された globals パスが見つかりません: ${explicitGlobalsPath} (cwd 基準で解決: ${resolved})`
+    );
+    err.code = 'E_EXPLICIT_GLOBALS_PATH_NOT_FOUND';
+    throw err;
   }
 
-  // 自動検出: @import "tailwindcss" を含む CSS ファイルを探す
+  // 1. 自動検出: sparkle-design.css と同じディレクトリで @import "tailwindcss" を含む
+  //    CSS ファイルを探す。Next.js App Router のように両者が同階層に居るケース用。
+  // en: Look next to sparkle-design.css for a Tailwind entry CSS. Covers the
+  // Next.js App Router layout where both live under `src/app/`.
   const detected = detectTailwindEntrypoint(dir);
   if (detected) {
     const basename = path.basename(detected);
@@ -289,7 +386,43 @@ function resolveGlobalsPath(sparkleDesignPath, explicitGlobalsPath = null) {
     return { path: detected, source: 'detected' };
   }
 
-  // デフォルト: globals.css
+  // 2. プロジェクト root から既知の候補を探す。Vite のように sparkle-design.css
+  //    が src/app/ に、entry CSS が src/index.css にあるレイアウトに対応。
+  //    Vite プロジェクトでは `setup` の scaffold が `src/index.css` を選ぶので、
+  //    `src/globals.css` と両方存在していても index.css を優先する（scaffold
+  //    した場所と generate が patch する場所が食い違わないように）。
+  // en: Fall back to project-wide candidates. For Vite projects, promote
+  // `src/index.css` above `src/globals.css` so that `generate` patches the same
+  // file `setup` would have scaffolded.
+  const cwd = process.cwd();
+  const candidates = isViteProject(cwd)
+    ? GLOBALS_CSS_CANDIDATES.slice().sort((a, b) => vitePriority(a) - vitePriority(b))
+    : GLOBALS_CSS_CANDIDATES;
+  for (const candidate of candidates) {
+    const absolute = path.resolve(cwd, candidate);
+    if (!fs.existsSync(absolute)) continue;
+    // 自身（sparkle-design.css）は除外
+    // en: Skip sparkle-design.css itself just in case a candidate points at it.
+    if (path.resolve(absolute) === path.resolve(sparkleDesignPath)) continue;
+    try {
+      const content = fs.readFileSync(absolute, 'utf8');
+      if (REGEX.TAILWIND_IMPORT.test(content)) {
+        console.log(`📝 Tailwind エントリポイントを検出しました（project root）: ${candidate}`);
+        return { path: absolute, source: 'project' };
+      }
+    } catch (err) {
+      // ENOENT 系は existsSync で既に弾いているので、ここに来るのは権限不足や
+      // ディレクトリ衝突などデバッグ価値のあるケース。silent に消さずに理由を出す。
+      // en: ENOENT is already filtered by existsSync above, so surfacing the
+      // error code here catches permission / type issues worth debugging.
+      console.warn(
+        `⚠️  候補 ${candidate} の読み込みに失敗したためスキップします (${err.code ?? err.message})`
+      );
+    }
+  }
+
+  // 3. デフォルト: sparkle-design.css と同じディレクトリの globals.css
+  // en: Last resort — a globals.css next to sparkle-design.css.
   const defaultPath = path.join(dir, 'globals.css');
   if (fs.existsSync(defaultPath)) {
     return { path: defaultPath, source: 'default' };
@@ -301,19 +434,54 @@ function resolveGlobalsPath(sparkleDesignPath, explicitGlobalsPath = null) {
 /**
  * フォント管理の自動処理を実行する
  * sparkle-design.css からフォントimportを抽出し、Tailwind エントリポイント CSS に @source 等を挿入する
+ *
+ * **v2.0.7-beta.2**: 戻り値を `{ status, reason? }` に変更し、呼び出し側が
+ * 「作業不要のスキップ」「作業すべき状態だが失敗」を区別できるようにした
+ * (#31)。`options.strict` が true のとき、`status === 'failed'` になる状態は
+ * throw に昇格させて `bin/sparkle-design.js` の outer catch で exit 1 に
+ * 繋げる。
+ *
  * @param {string} sparkleDesignPath sparkle-design.cssのパス
  * @param {Array<string>|null} sourcePackages 追加パッケージ名の配列（null の場合は @source を生成しない）
  * @param {string|null} customCssPath custom-css ファイルの相対パス
  * @param {string|null} globalsPathOverride 明示的に指定された globals パス
+ * @param {{ strict?: boolean }} [options] strict=true のとき失敗を throw する
+ * @returns {{ status: 'skipped' | 'updated' | 'failed', reason?: string }}
  */
-export function manageFontImports(sparkleDesignPath, sourcePackages = null, customCssPath = null, globalsPathOverride = null) {
+export function manageFontImports(
+  sparkleDesignPath,
+  sourcePackages = null,
+  customCssPath = null,
+  globalsPathOverride = null,
+  options = {}
+) {
+  const strict = Boolean(options.strict);
+  const hasWork =
+    (sourcePackages !== null && sourcePackages !== undefined) || Boolean(customCssPath);
+
+  const raiseOrReturn = (result) => {
+    if (strict && result.status === 'failed') {
+      throw new Error(
+        `globals.css の更新に失敗しました (${result.reason ?? 'unknown'})。--strict モードでは exit 1 で終了します。`
+      );
+    }
+    return result;
+  };
+
   try {
     // 1. globals パスを解決
     const resolved = resolveGlobalsPath(sparkleDesignPath, globalsPathOverride);
 
     if (!resolved) {
+      // 作業すべき状態（sourcePackages 等あり）で entry CSS が見つからないのは
+      // 事実上の不具合。strict なら throw、非 strict なら従来どおり情報ログ。
+      // en: With work queued, missing entry CSS is effectively a misconfiguration.
+      if (hasWork) {
+        console.warn(MESSAGES.GLOBALS_NOT_FOUND);
+        return raiseOrReturn({ status: 'failed', reason: 'entry-css-not-found' });
+      }
       console.log(MESSAGES.GLOBALS_NOT_FOUND);
-      return;
+      return { status: 'skipped', reason: 'entry-css-not-found-no-work' };
     }
 
     const globalsPath = resolved.path;
@@ -322,27 +490,45 @@ export function manageFontImports(sparkleDesignPath, sourcePackages = null, cust
     const sparkleContent = fs.readFileSync(sparkleDesignPath, 'utf8');
     const fontImports = extractFontImports(sparkleContent);
 
-    if (fontImports.length === 0) {
-      console.log(MESSAGES.NO_FONT_IMPORTS);
-      return;
+    // v2.0.0 以降はフォント @import が SparkleHead.tsx に移行したため、
+    // sparkle-design.css に font @import が残らないのが通常状態。それでも
+    // 既存 globals.css には `@source` / sparkle-design.css import /
+    // custom-css import を挿入する必要があるので、単に fonts が空だからと
+    // いって早期 return せず、下流の update 関数に判断を委ねる。
+    // en: Fonts moved to SparkleHead in v2.0.0, so "no font imports in
+    // sparkle-design.css" is now the normal case. Don't bail out here —
+    // `updateGlobalsWithFonts` still needs to inject `@source` and the
+    // sparkle-design.css import into existing globals.css.
+    if (fontImports.length > 0) {
+      console.log(MESSAGES.FONT_DETECTED(fontImports.length));
     }
 
-    console.log(MESSAGES.FONT_DETECTED(fontImports.length));
+    // 4. globals.css に import / @source を追加
+    const result = updateGlobalsWithFonts(fontImports, globalsPath, sourcePackages, customCssPath);
 
-    // 4. globals.css にフォントimportを追加
-    const globalsUpdated = updateGlobalsWithFonts(fontImports, globalsPath, sourcePackages, customCssPath);
-
-    if (!globalsUpdated) {
-      console.log(MESSAGES.FONT_REMOVE_SKIPPED);
-      return;
+    if (result.status === 'skipped') {
+      return result;
+    }
+    if (result.status === 'failed') {
+      return raiseOrReturn(result);
     }
 
-    // 5. sparkle-design.css からフォントimportを削除
-    const cleanedSparkleContent = removeFontImportsFromCSS(sparkleContent);
-    fs.writeFileSync(sparkleDesignPath, cleanedSparkleContent, 'utf8');
-    console.log(MESSAGES.FONT_REMOVED);
+    // 5. fonts が sparkle-design.css 側に残っていれば削除（globals 側に移動済みの前提）
+    // en: If there were fonts to move, strip them from sparkle-design.css.
+    if (fontImports.length > 0) {
+      const cleanedSparkleContent = removeFontImportsFromCSS(sparkleContent);
+      fs.writeFileSync(sparkleDesignPath, cleanedSparkleContent, 'utf8');
+      console.log(MESSAGES.FONT_REMOVED);
+    }
+    return result;
   } catch (error) {
     console.error(MESSAGES.FONT_MANAGEMENT_ERROR(error.message));
-    // フォント管理は必須ではないので、エラーでも処理を続行
+    // strict モード、または明示指定された globals path の not-found は
+    // ユーザーが必ず気付くべきなので非 strict でも再 throw する。
+    // en: Always re-throw explicit --globals-path typos; respect strict for the rest.
+    if (strict || error.code === 'E_EXPLICIT_GLOBALS_PATH_NOT_FOUND') {
+      throw error;
+    }
+    return { status: 'failed', reason: `manage-error: ${error.code ?? error.message}` };
   }
 }

package/lib/generate-css.js

@@ -68,7 +68,7 @@ function dedupeFontImports(cssContent) {
 
   return cssContent
     .split('\n')
-    .filter(line => {
+    .filter((line) => {
       if (!line.includes('fonts.googleapis.com')) {
         return true;
       }
@@ -96,7 +96,7 @@ function normalizeFontsEntry(entry) {
     return [{ family: entry, weights: FONT_DEFAULTS.WEIGHTS }];
   }
   if (Array.isArray(entry)) {
-    return entry.map(item => {
+    return entry.map((item) => {
       if (typeof item === 'string') {
         return { family: item, weights: FONT_DEFAULTS.WEIGHTS };
       }
@@ -132,7 +132,7 @@ function resolveFontConfig(config) {
  * @returns {string} CSS font-family 値（例: 'Montserrat', 'Noto Sans JP', sans-serif）
  */
 function generateFontFamilyValue(fonts, genericFamily) {
-  const quoted = fonts.map(f => `'${f.family}'`);
+  const quoted = fonts.map((f) => `'${f.family}'`);
   return [...quoted, genericFamily].join(', ');
 }
 
@@ -169,9 +169,10 @@ function generateMergedFontImports(allFonts) {
  * @returns {string} フォント import ブロック
  */
 function generateFontImportsBlock(configOrResolved) {
-  const { pro, mono } = configOrResolved.pro && configOrResolved.mono
-    ? configOrResolved
-    : resolveFontConfig(configOrResolved);
+  const { pro, mono } =
+    configOrResolved.pro && configOrResolved.mono
+      ? configOrResolved
+      : resolveFontConfig(configOrResolved);
 
   const imports = [
     FONT_DEFAULTS.MATERIAL_SYMBOLS_IMPORT,
@@ -206,7 +207,7 @@ function generateSparkleHeadContent(resolvedFonts) {
     `      <link rel="preconnect" href="${FONT_DOMAINS.GOOGLEAPIS}" />`,
     `      <link rel="preconnect" href="${FONT_DOMAINS.GSTATIC}" crossOrigin="anonymous" />`,
     `      <link rel="stylesheet" href="${materialSymbolsUrl}" />`,
-    ...fontUrls.map(url => `      <link rel="stylesheet" href="${url}" />`),
+    ...fontUrls.map((url) => `      <link rel="stylesheet" href="${url}" />`),
   ];
 
   return `/**
@@ -289,7 +290,15 @@ function processTemplate(template, config, grayMapping, radiusMapping, colors) {
   // 5. 基本的な設定値による置換（オブジェクト・配列・拡張フィールドはスキップ）
   Object.entries(config).forEach(([key, value]) => {
     // 配列・オブジェクト・拡張フィールドはスキップ
-    if (Array.isArray(value) || (typeof value === 'object' && value !== null) || key === 'custom-css' || key === 'fonts' || key === 'extend' || key === 'source-packages' || key === 'globals-path') {
+    if (
+      Array.isArray(value) ||
+      (typeof value === 'object' && value !== null) ||
+      key === 'custom-css' ||
+      key === 'fonts' ||
+      key === 'extend' ||
+      key === 'source-packages' ||
+      key === 'globals-path'
+    ) {
       return;
     }
     // 通常のプレースホルダー（CSS用 - スペースはそのまま）
@@ -336,9 +345,7 @@ function processTemplate(template, config, grayMapping, radiusMapping, colors) {
 // `sparkle-design` は CLI 側のデフォルトパッケージなのでリストには加えず「存在判定」にだけ使う。
 // en: Known design-system packages to auto-detect. `sparkle-design` is the CLI's
 //     default source package, so it only acts as an "enables @source" signal.
-const KNOWN_DESIGN_SYSTEM_PACKAGES = [
-  '@goodpatch/sparkle-design-internal',
-];
+const KNOWN_DESIGN_SYSTEM_PACKAGES = ['@goodpatch/sparkle-design-internal'];
 
 /**
  * package.json の dependencies / devDependencies から既知のデザインシステムパッケージを検出する。
@@ -394,8 +401,17 @@ function writeCSS(cssContent, outputPath = null) {
  * メイン処理
  * @param {string|null} configPath カスタム設定ファイルのパス（オプション）
  * @param {string|null} outputPath カスタム出力パス（オプション）
+ * @param {string|null} globalsPath 明示指定の globals.css パス（オプション）
+ * @param {{ strict?: boolean }} [options] strict=true のとき、
+ *   globals.css パッチ失敗などを throw に昇格させる（exit 1 に繋げるため）
+ * @returns {{ globalsResult: { status: 'skipped'|'updated'|'failed', reason?: string } }}
  */
-export function generateCSS(configPath = null, outputPath = null, globalsPath = null) {
+export function generateCSS(
+  configPath = null,
+  outputPath = null,
+  globalsPath = null,
+  options = {}
+) {
   console.log(MESSAGES.START);
 
   // 1. 設定ファイルを読み込み
@@ -413,7 +429,13 @@ export function generateCSS(configPath = null, outputPath = null, globalsPath =
   const radiusMapping = loadRadiusMapping();
 
   // 5. テンプレートを設定値で処理（resolvedFonts も返す）
-  const { css: processedCSS, resolvedFonts } = processTemplate(template, config, grayMapping, radiusMapping, colors);
+  const { css: processedCSS, resolvedFonts } = processTemplate(
+    template,
+    config,
+    grayMapping,
+    radiusMapping,
+    colors
+  );
 
   // 6. CSSファイルを書き出し
   const defaultOutputPath = path.resolve(
@@ -437,16 +459,23 @@ export function generateCSS(configPath = null, outputPath = null, globalsPath =
   //     with explicit config entries. If neither surfaces anything, @source is skipped.
   console.log(MESSAGES.FONT_MANAGEMENT_START);
   const detectedPackages = detectSourcePackagesFromPackageJson();
-  const explicitPackages = 'source-packages' in config ? (config['source-packages'] || []) : null;
+  const explicitPackages = 'source-packages' in config ? config['source-packages'] || [] : null;
   const sourcePackages =
     detectedPackages !== null || explicitPackages !== null
       ? [...new Set([...(detectedPackages ?? []), ...(explicitPackages ?? [])])]
       : null;
   const customCssPath = config['custom-css'] || null;
   const globalsPathOverride = globalsPath || config['globals-path'] || null;
-  manageFontImports(resolvedOutputPath, sourcePackages, customCssPath, globalsPathOverride);
+  const globalsResult = manageFontImports(
+    resolvedOutputPath,
+    sourcePackages,
+    customCssPath,
+    globalsPathOverride,
+    { strict: Boolean(options.strict) }
+  );
 
   console.log(MESSAGES.SUCCESS);
+  return { globalsResult };
 }
 
 // スクリプトが直接実行された場合のみメイン処理を実行

package/lib/setup.js

@@ -2,6 +2,7 @@ import fs from 'fs';
 import path from 'path';
 import { spawnSync } from 'child_process';
 import { generateCSS } from './generate-css.js';
+import { GLOBALS_CSS_CANDIDATES } from './constants.js';
 
 // デフォルトの sparkle.config.json テンプレート
 // en: Default sparkle.config.json template
@@ -41,16 +42,6 @@ const config = {
 export default config;
 `;
 
-// globals.css 候補パス（優先順）
-// en: globals.css candidate paths in priority order
-const GLOBALS_CSS_CANDIDATES = [
-  'src/app/globals.css',
-  'app/globals.css',
-  'src/globals.css',
-  'src/index.css',
-  'src/styles/globals.css',
-];
-
 const ASSISTANT_CONFIG = {
   claude: {
     path: 'CLAUDE.md',
@@ -192,12 +183,13 @@ function buildInstructionBlock(target, assistant) {
     BLOCK_START,
     heading,
     '',
+    '- **必ず読む**: Sparkle Design のコンポーネントを使う前に、インストール済みパッケージの型定義 `node_modules/<パッケージ名>/dist/components/ui/<コンポーネント名>/index.d.ts` を必ず読んでください。Prop 仕様・使用例・アンチパターンは JSDoc に書かれている（✅ / ❌ 例込み）ので、これが Source of Truth です。`node_modules/sparkle-design/dist/` や `node_modules/@goodpatch/sparkle-design-internal/dist/` を対象に、`index.d.ts` の JSDoc まで読み切ること。',
+    "- **Required reading**: Before using any Sparkle Design component, read the installed package's type definitions at `node_modules/<package>/dist/components/ui/<component>/index.d.ts` — prop specs, usage, and anti-patterns (with ✅ / ❌ examples) live in the JSDoc and are the source of truth. Target the installed package(s), e.g. `sparkle-design` and/or `@goodpatch/sparkle-design-internal`, and read the full JSDoc, not just the type signature.",
     '- **必ず実行**: UI コンポーネントを作成・変更した後は、終了前に `lint:sparkle` を実行してください。Sparkle Design のアンチパターンを検出します。',
     '- **Required**: After creating or modifying any UI component, run `lint:sparkle` before finishing. This catches Sparkle Design anti-patterns.',
     `- For AI review, prefer \`lint:sparkle:json\` or run \`npx --yes sparkle-design-cli check ${target} --format json\` directly.`,
     '- JSON 出力の `findings` に加えて、**`manualReviewReminders` の内容も必ず 1 項目ずつ確認**してください。機械検出できない Badge/Tag の使い分けなどが含まれます。',
     '- You must inspect every entry in both `findings` and `manualReviewReminders` — the reminders flag judgment calls (Badge vs Tag etc.) that the linter cannot detect.',
-    '- If semantic guidance is still needed, consult Sparkle Design docs and JSDoc examples.',
     BLOCK_END,
   ].join('\n');
 }
@@ -464,13 +456,31 @@ function runAssistantGuard(cwd, packageJsonPath, options, assistantConfig) {
   };
 }
 
-function runGenerate({ skipGenerate, dryRun }) {
+function runGenerate({ skipGenerate, dryRun, strict }) {
+  // --skip-generate / --dry-run と --strict が同時指定された場合、strict チェックを
+  // 走らせる対象 (generate) そのものがスキップされるため strict は事実上無意味。
+  // サイレントに無効化するとユーザーが CI で気付けないので警告を出す。
+  // en: --strict has no effect if generate is skipped — warn the user rather
+  // than silently no-op, which would mask CI misconfiguration.
+  if (strict && (skipGenerate || dryRun)) {
+    console.warn(
+      '⚠️  --strict は generate の失敗のみ検出します。--skip-generate / --dry-run と併用した場合は strict チェックは走りません。'
+    );
+  }
   if (skipGenerate || dryRun) return { skipped: true, ran: false };
   try {
     console.log('🎨 sparkle-design.css を生成中...');
-    generateCSS();
-    return { skipped: false, ran: true };
+    const result = generateCSS(null, null, null, { strict: Boolean(strict) });
+    return { skipped: false, ran: true, globalsResult: result?.globalsResult };
   } catch (error) {
+    // strict モード、または sparkle.config.json の `globals-path` typo などの
+    // 明示指定 not-found は、非 strict でもユーザーが必ず気付くべきなので
+    // 再 throw する（#33 の挙動を setup 経由でも保つ）。
+    // en: Always re-throw explicit --globals-path typos so `setup` surfaces
+    // them via exit code, matching the behaviour of `generate` directly.
+    if (strict || error.code === 'E_EXPLICIT_GLOBALS_PATH_NOT_FOUND') {
+      throw error;
+    }
     console.warn(`⚠️  generate 実行をスキップしました: ${error.message}`);
     return { skipped: false, ran: false, error: error.message };
   }
@@ -501,7 +511,11 @@ export function setupAssistant(options = {}) {
     { ...options, assistant, dryRun },
     assistantConfig
   );
-  const generate = runGenerate({ skipGenerate: Boolean(options.skipGenerate), dryRun });
+  const generate = runGenerate({
+    skipGenerate: Boolean(options.skipGenerate),
+    dryRun,
+    strict: Boolean(options.strict),
+  });
 
   const summary = {
     assistant,
@@ -562,9 +576,11 @@ function printPostSetupReminder(target, packageManager) {
   const lines = [
     '',
     '📝 次のステップ / Next steps:',
-    `  1. UI コンポーネントを作成・変更したら、必ず \`${lintCmd}\` (または \`npx --yes sparkle-design-cli check ${lintTarget} --strict\`) を実行してください。`,
+    '  1. Sparkle Design のコンポーネントを使う前に、必ず `node_modules/<パッケージ名>/dist/components/ui/<コンポーネント名>/index.d.ts` の JSDoc を読んでください。Prop 仕様・使用例・アンチパターンは JSDoc が Source of Truth です。',
+    '     Before using any Sparkle Design component, read `node_modules/<package>/dist/components/ui/<name>/index.d.ts` — the JSDoc includes prop specs, usage, and anti-pattern examples.',
+    `  2. UI コンポーネントを作成・変更したら、必ず \`${lintCmd}\` (または \`npx --yes sparkle-design-cli check ${lintTarget} --strict\`) を実行してください。`,
     '     After creating or modifying UI components, always run `lint:sparkle` to catch Sparkle Design anti-patterns.',
-    '  2. AI でレビューする場合は `lint:sparkle:json` を使い、`findings` に加えて `manualReviewReminders` の各項目まで必ず確認してください。',
+    '  3. AI でレビューする場合は `lint:sparkle:json` を使い、`findings` に加えて `manualReviewReminders` の各項目まで必ず確認してください。',
     '     For AI review, use `lint:sparkle:json` and inspect every entry of both `findings` and `manualReviewReminders`.',
     '',
   ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sparkle-design-cli",
-  "version": "2.0.7-beta.0",
+  "version": "2.0.7-beta.2",
   "description": "Sparkle Design CSS Generator - デザインシステムCSSを設定ファイルから生成するツール",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",