sparkle-design-cli 2.0.6 → 2.0.7-beta.1

package/README.md

@@ -31,6 +31,25 @@ npm install -g sparkle-design-cli
 
 > `npx --yes sparkle-design-cli ...` で都度実行する運用を推奨します（常に最新版が利用されます）。
 
+### リリースチャネル
+
+npm の dist-tag でチャネルを分離しています。通常は latest を使い、品質保証中の変更を試したい場合のみ beta を指定してください。
+
+| チャネル | dist-tag | 用途 | 指定方法 |
+|---------|---------|------|---------|
+| 安定版 | `latest` | 本番運用向け。`npx --yes sparkle-design-cli` は常にこれを取得 | （デフォルト） |
+| Beta | `beta` | 品質保証中の検証用 | `npx --yes sparkle-design-cli@beta` |
+
+```bash
+# beta で setup を試す
+npx --yes sparkle-design-cli@beta setup --assistant claude
+
+# beta で check を試す
+npx --yes sparkle-design-cli@beta check src --strict
+```
+
+Beta バージョンは `X.Y.Z-beta.N` 形式で publish されます。GA（正式版）へ昇格するときは、beta の -beta.N を外した `X.Y.Z` を改めて publish します。
+
 ## 使用方法
 
 ### サブコマンド
@@ -362,6 +381,39 @@ sparkle-design-cli generate --help
 sparkle-design-cli check src --strict
 ```
 
+### リリース手順（メンテナ向け）
+
+npm publish は GitHub Actions (`Publish to npm`) 経由で行います。ローカルから `npm publish` しないでください。
+
+#### 安定版（latest）
+
+1. `main` ブランチに変更をマージ
+2. `package.json` の `version` を SemVer で更新（例: `2.0.6` → `2.1.0`）し、`CHANGELOG.md` に該当セクションを追加
+3. PR をマージ後、Actions の **Publish to npm** を `channel: auto`（または `latest`）で手動実行
+4. workflow は lint / test を流したうえで `npm publish`（dist-tag = latest）を実行
+
+#### Beta（beta）
+
+品質保証中の変更を先行公開したいときに使います。latest には影響しません。
+
+1. `package.json` の `version` を `X.Y.Z-beta.N` 形式に更新（例: `2.1.0-beta.0`、次の beta は `2.1.0-beta.1`）
+2. `CHANGELOG.md` に `[X.Y.Z-beta.N]` セクションを追加
+3. PR をマージ後、Actions の **Publish to npm** を `channel: auto`（または `beta`）で手動実行
+4. workflow が version を判定して `npm publish --tag beta` を実行
+5. 利用者側は `npx --yes sparkle-design-cli@beta ...` で検証
+
+#### Beta から GA（latest）へ昇格
+
+同じ成果物を latest にする場合は、新しい安定版 `X.Y.Z` を publish するか、既存 beta バージョンに latest タグを付け替えます。
+
+```bash
+# 選択肢 A: 新たに X.Y.Z を publish する（推奨）
+#   version を X.Y.Z に更新 → workflow を latest で実行
+
+# 選択肢 B: 既存の X.Y.Z-beta.N に latest タグを付け替える
+npm dist-tag add sparkle-design-cli@X.Y.Z-beta.N latest
+```
+
 ## ライセンス
 
 MIT License - 詳細は [LICENSE](LICENSE) ファイルを参照してください。

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: '/* プロジェクト固有のカスタムトークン */',
 };
 

package/lib/font-manager.js

@@ -5,7 +5,7 @@
 
 import fs from 'fs';
 import path from 'path';
-import { REGEX, COMMENTS, IMPORTS, MESSAGES, FONT_DEFAULTS } from './constants.js';
+import { REGEX, COMMENTS, IMPORTS, MESSAGES, GLOBALS_CSS_CANDIDATES } from './constants.js';
 
 /**
  * sparkle-design.css からフォントの@import文を抽出する
@@ -26,15 +26,6 @@ export function removeFontImportsFromCSS(cssContent) {
   return cssContent.replace(REGEX.FONT_IMPORT_WITH_COMMENT, '');
 }
 
-/**
- * フォントimportブロックを生成する
- * @param {Array<string>} fontImports フォントimport文の配列
- * @returns {string} フォントimportブロック
- */
-function createFontImportBlock(fontImports) {
-  return [COMMENTS.FONT_IMPORT, ...fontImports, ''].join('\n');
-}
-
 /**
  * globals.css から node_modules への相対パスを計算する
  * @param {string} globalsPath globals.css の絶対パス
@@ -67,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');
 }
 
@@ -135,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を削除
@@ -183,27 +180,43 @@ 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.1 以前の不具合**: 早期 return が `fontImports.length === 0` 単独で
+ * 行われていたため、フォントを SparkleHead に移行済みかつ既存 globals.css が
+ * ある（Vite の `src/index.css` など）プロジェクトでは `@source` が一切挿入
+ * されなかった。条件を「フォント・sourcePackages・customCssPath のすべてが
+ * 空なら skip」に変更し、パッケージの自動検出結果だけでも globals.css が
+ * patch されるようにした。
+ *
  * @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
  */
-export function updateGlobalsWithFonts(fontImports, globalsPath, sourcePackages = null, customCssPath = null) {
-  if (fontImports.length === 0) {
+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 false;
   }
 
@@ -242,6 +255,38 @@ export function updateGlobalsWithFonts(fontImports, globalsPath, sourcePackages
   }
 }
 
+// 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 検索対象ディレクトリ
@@ -251,7 +296,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;
   }
 
@@ -260,9 +314,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})`
+      );
     }
   }
 
@@ -271,10 +336,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);
@@ -288,7 +359,10 @@ function resolveGlobalsPath(sparkleDesignPath, explicitGlobalsPath = null) {
     return null;
   }
 
-  // 自動検出: @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);
@@ -298,7 +372,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' };
@@ -315,7 +425,12 @@ function resolveGlobalsPath(sparkleDesignPath, explicitGlobalsPath = null) {
  * @param {string|null} customCssPath custom-css ファイルの相対パス
  * @param {string|null} globalsPathOverride 明示的に指定された globals パス
  */
-export function manageFontImports(sparkleDesignPath, sourcePackages = null, customCssPath = null, globalsPathOverride = null) {
+export function manageFontImports(
+  sparkleDesignPath,
+  sourcePackages = null,
+  customCssPath = null,
+  globalsPathOverride = null
+) {
   try {
     // 1. globals パスを解決
     const resolved = resolveGlobalsPath(sparkleDesignPath, globalsPathOverride);
@@ -331,25 +446,40 @@ 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を追加
-    const globalsUpdated = updateGlobalsWithFonts(fontImports, globalsPath, sourcePackages, customCssPath);
+    // 4. globals.css に import / @source を追加
+    const globalsUpdated = updateGlobalsWithFonts(
+      fontImports,
+      globalsPath,
+      sourcePackages,
+      customCssPath
+    );
 
     if (!globalsUpdated) {
-      console.log(MESSAGES.FONT_REMOVE_SKIPPED);
+      // fonts が元々無く sourcePackages / customCss も空なら更新不要。
+      // en: Nothing to do — not an error.
       return;
     }
 
-    // 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);
+    }
   } catch (error) {
     console.error(MESSAGES.FONT_MANAGEMENT_ERROR(error.message));
     // フォント管理は必須ではないので、エラーでも処理を続行

package/lib/setup.js

@@ -2,17 +2,20 @@ 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
+// sparkle-design 本体の既定値（BIZ UDPGothic / BIZ UDGothic）に揃えておくことで、
+// README やドキュメントサイトと見た目が一致する状態で初回セットアップが完了する。
 // @source ディレクティブの生成は generate 側が package.json から既知のデザインシステム
 // パッケージ（sparkle-design / @goodpatch/sparkle-design-internal 等）を自動検出して
 // 行うため、ここで extend.source-packages を指定する必要はない。独自パッケージを
 // 追加する場合のみユーザーが extend.source-packages に追記する。
 const DEFAULT_SPARKLE_CONFIG = {
   primary: 'blue',
-  'font-pro': 'Inter',
-  'font-mono': 'JetBrains Mono',
+  'font-pro': 'BIZ UDPGothic',
+  'font-mono': 'BIZ UDGothic',
   radius: 'md',
 };
 
@@ -39,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',
@@ -74,7 +67,6 @@ function buildCheckScript(target, mode) {
   return `npx --yes sparkle-design-cli check ${target} ${trailingArgs}`;
 }
 
-
 function ensureDir(filePath) {
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
 }
@@ -191,10 +183,13 @@ function buildInstructionBlock(target, assistant) {
     BLOCK_START,
     heading,
     '',
-    '- Run `lint:sparkle` when Sparkle Design changes are involved.',
+    '- **必ず読む**: 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.`,
-    '- Always inspect both `findings` and `manualReviewReminders` from the JSON output.',
-    '- If semantic guidance is still needed, consult Sparkle Design docs and JSDoc examples.',
+    '- 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.',
     BLOCK_END,
   ].join('\n');
 }
@@ -226,7 +221,12 @@ function resolveScriptUpdate(existingValue, nextValue, mode, force) {
   }
 
   if (force || isManagedSparkleScript(existingValue, mode)) {
-    return { value: nextValue, changed: true, conflict: false, reason: force ? 'forced' : 'updated' };
+    return {
+      value: nextValue,
+      changed: true,
+      conflict: false,
+      reason: force ? 'forced' : 'updated',
+    };
   }
 
   return { value: existingValue, changed: false, conflict: true, reason: 'preserved-custom' };
@@ -280,7 +280,8 @@ const PM_COMMANDS = {
  */
 function detectPackageManager(cwd) {
   if (fs.existsSync(path.join(cwd, 'pnpm-lock.yaml'))) return 'pnpm';
-  if (fs.existsSync(path.join(cwd, 'bun.lockb')) || fs.existsSync(path.join(cwd, 'bun.lock'))) return 'bun';
+  if (fs.existsSync(path.join(cwd, 'bun.lockb')) || fs.existsSync(path.join(cwd, 'bun.lock')))
+    return 'bun';
   if (fs.existsSync(path.join(cwd, 'yarn.lock'))) return 'yarn';
   return 'npm';
 }
@@ -289,7 +290,12 @@ function detectPackageManager(cwd) {
  * package.json に未登録のパッケージだけをインストールする
  * en: Install only packages not yet listed in package.json
  */
-function ensurePackagesInstalled(cwd, packageManager, candidates, { dev = false, dryRun = false } = {}) {
+function ensurePackagesInstalled(
+  cwd,
+  packageManager,
+  candidates,
+  { dev = false, dryRun = false } = {}
+) {
   const packageJson = readJson(path.join(cwd, 'package.json'));
   const deps = { ...(packageJson.dependencies ?? {}), ...(packageJson.devDependencies ?? {}) };
   const missing = candidates.filter((pkg) => !Object.prototype.hasOwnProperty.call(deps, pkg));
@@ -356,7 +362,12 @@ function buildScaffoldTargets(cwd) {
     },
     {
       name: 'postcssConfig',
-      candidates: ['postcss.config.mjs', 'postcss.config.js', 'postcss.config.cjs', 'postcss.config.ts'],
+      candidates: [
+        'postcss.config.mjs',
+        'postcss.config.js',
+        'postcss.config.cjs',
+        'postcss.config.ts',
+      ],
       target: 'postcss.config.mjs',
       write: (abs) => fs.writeFileSync(abs, INITIAL_POSTCSS_CONFIG, 'utf8'),
     },
@@ -400,7 +411,10 @@ function runInstall(cwd, packageManager, { skipInstall, dryRun }) {
   return {
     skipped: false,
     sparkle: ensurePackagesInstalled(cwd, packageManager, SPARKLE_PACKAGES, { dryRun }),
-    tailwind: ensurePackagesInstalled(cwd, packageManager, TAILWIND_PACKAGES, { dev: true, dryRun }),
+    tailwind: ensurePackagesInstalled(cwd, packageManager, TAILWIND_PACKAGES, {
+      dev: true,
+      dryRun,
+    }),
   };
 }
 
@@ -415,7 +429,10 @@ function runAssistantGuard(cwd, packageJsonPath, options, assistantConfig) {
     ? normalizePath(cwd, options.target, 'Target path')
     : normalizePath(cwd, detectTarget(cwd), 'Target path');
   const instructionPath = options.instructionsPath
-    ? path.resolve(cwd, normalizePath(cwd, options.instructionsPath, 'Instructions path', { checkParentOnly: true }))
+    ? path.resolve(
+        cwd,
+        normalizePath(cwd, options.instructionsPath, 'Instructions path', { checkParentOnly: true })
+      )
     : path.resolve(cwd, assistantConfig.path);
 
   const packageResult = updatePackageJson(packageJsonPath, target, force);
@@ -465,9 +482,17 @@ export function setupAssistant(options = {}) {
   const dryRun = Boolean(options.dryRun);
   const packageManager = detectPackageManager(cwd);
 
-  const install = runInstall(cwd, packageManager, { skipInstall: Boolean(options.skipInstall), dryRun });
+  const install = runInstall(cwd, packageManager, {
+    skipInstall: Boolean(options.skipInstall),
+    dryRun,
+  });
   const scaffold = runScaffold(cwd, { skipScaffold: Boolean(options.skipScaffold), dryRun });
-  const guard = runAssistantGuard(cwd, packageJsonPath, { ...options, assistant, dryRun }, assistantConfig);
+  const guard = runAssistantGuard(
+    cwd,
+    packageJsonPath,
+    { ...options, assistant, dryRun },
+    assistantConfig
+  );
   const generate = runGenerate({ skipGenerate: Boolean(options.skipGenerate), dryRun });
 
   const summary = {
@@ -497,5 +522,47 @@ export function setupAssistant(options = {}) {
   };
 
   console.log(JSON.stringify(summary, null, 2));
+
+  // セットアップ後のリマインダー。AI の会話履歴にも残るよう stderr に出す。
+  // en: Post-setup reminder. Written to stderr so it stays in the AI transcript
+  // without polluting the JSON stdout payload that tooling parses.
+  printPostSetupReminder(guard.target, packageManager);
+
   return summary;
 }
+
+// 検出した package manager に応じて `lint:sparkle` を呼び出すコマンドを返す。
+// en: Returns the shell invocation for the `lint:sparkle` script based on the
+// detected package manager.
+function buildLintCommand(packageManager) {
+  switch (packageManager) {
+    case 'pnpm':
+      return 'pnpm lint:sparkle';
+    case 'yarn':
+      return 'yarn lint:sparkle';
+    case 'bun':
+      return 'bun run lint:sparkle';
+    case 'npm':
+    default:
+      return 'npm run lint:sparkle';
+  }
+}
+
+function printPostSetupReminder(target, packageManager) {
+  const lintTarget = target || 'src';
+  const lintCmd = buildLintCommand(packageManager);
+  const lines = [
+    '',
+    '📝 次のステップ / Next steps:',
+    '  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.',
+    '  3. AI でレビューする場合は `lint:sparkle:json` を使い、`findings` に加えて `manualReviewReminders` の各項目まで必ず確認してください。',
+    '     For AI review, use `lint:sparkle:json` and inspect every entry of both `findings` and `manualReviewReminders`.',
+    '',
+  ];
+  for (const line of lines) {
+    console.error(line);
+  }
+}

package/package.json

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