sparkle-design-cli 1.5.0 → 1.6.0

package/README.md

@@ -111,6 +111,14 @@ 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 を上書きしない
+- CardControl に Button / IconButton 以外を入れない
+- CardHeader / CardContent の padding を上書きしない
+- asChild と prefixIcon / suffixIcon / isLoading を併用しない
+- disabled を isDisabled の代わりに使わない
+- Button の prefixIcon に JSX を渡さない
+- Icon の children にテキストを渡さない
 
 #### Manual Review Reminders
 
@@ -119,6 +127,7 @@ sparkle-design-cli check --help
 - Badge と Tag の意味的な使い分け
 - CardDescription の typography / color token 明示
 - Dialog と Modal の UX 上の使い分け
+- 手書き span が Tag で置き換え可能か
 
 #### 導入先での推奨設定
 
@@ -181,8 +190,8 @@ npx --yes sparkle-design-cli setup --assistant generic
 #### Core（プラグインが出力）
 
 - `primary`: プライマリカラー（blue, red, orange など）
-- `font-pro`: プロポーショナルフォント（文字列または配列。配列の場合はフォールバックチェーンになる）
-- `font-mono`: モノスペースフォント（文字列または配列）
+- `font-pro`: プロポーショナルフォント（[Google Fonts](https://fonts.google.com/) の名前）
+- `font-mono`: モノスペースフォント（[Google Fonts](https://fonts.google.com/) の名前）
 - `radius`: 角丸設定（sm, md, lg など）
 
 ### extend セクション（拡張設定）

package/bin/sparkle-design.js

@@ -76,6 +76,7 @@ function parseSetupOptions(args) {
   const options = {
     assistant: 'generic',
     target: null,
+    instructionsPath: null,
     dryRun: false,
     forceScriptUpdate: false,
     help: false,
@@ -92,6 +93,9 @@ function parseSetupOptions(args) {
     } else if (arg === '--target') {
       options.target = requireOptionValue(args, i, '--target');
       i += 1;
+    } else if (arg === '--instructions-path') {
+      options.instructionsPath = requireOptionValue(args, i, '--instructions-path');
+      i += 1;
     } else if (arg === '--dry-run') {
       options.dryRun = true;
     } else if (arg === '--force-script-update') {
@@ -138,6 +142,7 @@ Setup:
   sparkle-design-cli setup --assistant codex --target src
   sparkle-design-cli setup --assistant cursor --dry-run
   sparkle-design-cli setup --assistant claude --force-script-update
+  sparkle-design-cli setup --assistant claude --instructions-path app/admin/CLAUDE.md
 
 Generate options:
   -h, --help                 このヘルプメッセージを表示
@@ -179,6 +184,7 @@ Setup options:
   --assistant <name>         claude / codex / cursor / generic (default: generic)
   --target <path>            lint 対象パス (default: auto-detect)
   --dry-run                  ファイルを変更せず結果だけ表示
+  --instructions-path <path> AI 指示ファイルの出力先パス (default: アシスタント別のデフォルト)
   --force-script-update      既存の lint:sparkle 系 script も上書きする
 
 Check で検出する主なパターン:
@@ -186,9 +192,23 @@ Check で検出する主なパターン:
   - DialogCancel / DialogAction を <Button> で二重ラップしている
   - children なしの Button に prefixIcon / suffixIcon を使っている
   - Material Symbols を className 直書きしている
-  - text-muted-foreground / bg-background / border-border を持ち込んでいる
+  - shadcn/ui 既定 token（text-muted-foreground 等）を持ち込んでいる
+  - Tailwind デフォルト typography（text-sm, font-medium 等）を使っている
+  - CardTitle に typography を上書きしている
+  - CardControl に Button / IconButton 以外を入れている
+  - CardHeader / CardContent の padding を上書きしている
+  - asChild と prefixIcon / suffixIcon / isLoading を併用している
+  - disabled を isDisabled の代わりに使っている
+  - Button の prefixIcon に JSX を渡している
+  - Icon の children にテキストを渡している
+  - globals.css にフォント @import が残っている（SparkleHead への移行が必要）
+  - CSP ヘッダーで Google Fonts がブロックされている可能性
 
 JSON 出力では manualReviewReminders も返すため、AI から実行する場合は --format json を推奨
+
+generate で生成されるファイル:
+  sparkle-design.css         デザイントークン CSS
+  SparkleHead.tsx            フォント読み込み用 React コンポーネント（layout.tsx の <head> に配置）
 `);
 }
 

package/lib/anti-pattern-rules.js

@@ -40,6 +40,11 @@ const MANUAL_REVIEW_REMINDERS = [
     message:
       'Dialog が確認用途、Modal が入力・詳細表示用途になっているか確認してください。文脈判断が必要なケースは機械検出されません。',
   },
+  {
+    id: 'tag-vs-handwritten-span',
+    message:
+      'ステータスバッジ風の手書き span（bg-*-100 text-*-700 rounded-full 等）が Tag コンポーネントで置き換え可能か確認してください。',
+  },
 ];
 
 const ANTI_PATTERN_GROUPS = [
@@ -859,10 +864,220 @@ const ANTI_PATTERN_GROUPS = [
       },
     ],
   },
+  {
+    id: 'tailwind-typography',
+    check: {
+      description: 'Tailwind デフォルト typography を Sparkle Design コンポーネント内で使わない',
+      recommendation:
+        'text-sm / text-xs / text-base / font-medium / font-semibold / font-bold は character-* utility に置き換えてください。',
+      pattern: /\b(text-(?:xs|sm|base|lg|xl|2xl)|font-(?:medium|semibold|bold|normal|light))\b/g,
+    },
+    featureSection: lines([
+      '### Tailwind デフォルト typography を使わない',
+      '',
+      '```tsx',
+      '// ✅ Correct — character-* utility を使う',
+      '<span className="character-3-regular-pro">テキスト</span>',
+      '',
+      '// ❌ Wrong — Tailwind デフォルトの typography を使わない',
+      '<span className="text-sm font-medium">テキスト</span>',
+      '```',
+      '',
+      'Sparkle Design コンポーネント内では `character-*-pro` / `character-*-mono` を使用する。Tailwind の `text-sm` / `font-medium` 等は使わない。',
+    ]),
+    jsdocTargets: [],
+  },
+  {
+    id: 'card-title-typography',
+    check: {
+      description: 'CardTitle に typography 系クラスを付与しない',
+      recommendation:
+        'CardTitle は character-4-bold-pro を内蔵しています。className で typography を上書きしないでください。',
+      pattern: /<CardTitle\b[^>]*\bclassName\s*=\s*(?:"[^"]*\bcharacter-[^"]*"|'[^']*\bcharacter-[^']*'|\{[^}]*\bcharacter-[^}]*\})[^>]*>/g,
+    },
+    featureSection: lines([
+      '### CardTitle に typography を上書きしない',
+      '',
+      '```tsx',
+      '// ✅ Correct — CardTitle はデフォルトで character-4-bold-pro が適用される',
+      '<CardTitle>タイトル</CardTitle>',
+      '',
+      '// ❌ Wrong — typography を上書きしない',
+      '<CardTitle className="character-2-bold-pro">タイトル</CardTitle>',
+      '```',
+    ]),
+    jsdocTargets: [],
+  },
+  {
+    id: 'card-control-non-button',
+    check: {
+      description: 'CardControl に Button / IconButton 以外を入れない',
+      recommendation:
+        'CardControl はアクションボタン用です。ステータス表示には CardDescription を使ってください。',
+      pattern: /<CardControl\b[^>]*>[\s\S]*?<(?!Button\b|IconButton\b|\/CardControl)\w+/g,
+    },
+    featureSection: lines([
+      '### CardControl にはアクションボタンのみを入れる',
+      '',
+      '```tsx',
+      '// ✅ Correct — Button / IconButton を CardControl に入れる',
+      '<CardControl>',
+      '  <Button>保存</Button>',
+      '</CardControl>',
+      '',
+      '// ❌ Wrong — ステータス表示を CardControl に入れない（CardDescription を使う）',
+      '<CardControl>',
+      '  <Tag status="negative">警告</Tag>',
+      '</CardControl>',
+      '```',
+    ]),
+    jsdocTargets: [
+      {
+        file: 'src/components/ui/card/index.tsx',
+        targetName: 'CardControl',
+        section: {
+          bullets: [
+            {
+              ja: 'CardControl にはアクション用の Button / IconButton のみを入れてください。ステータス表示（Tag 等）は CardDescription に入れてください。',
+              en: 'CardControl is for action buttons (Button / IconButton) only. Place status displays (Tag, etc.) in CardDescription.',
+            },
+          ],
+          example: lines([
+            '// ✅ Correct',
+            '<CardControl>',
+            '  <Button theme="neutral" variant="outline">キャンセル</Button>',
+            '  <Button>保存</Button>',
+            '</CardControl>',
+            '',
+            '// ❌ Wrong - ステータス表示を CardControl に入れない',
+            '<CardControl>',
+            '  <Tag status="negative">警告</Tag>',
+            '</CardControl>',
+          ]),
+        },
+      },
+    ],
+  },
+  {
+    id: 'card-padding-override',
+    check: {
+      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,
+    },
+    featureSection: lines([
+      '### Card 系コンポーネントの padding を上書きしない',
+      '',
+      '```tsx',
+      '// ✅ Correct — デフォルトの padding をそのまま使う',
+      '<CardHeader>',
+      '  <CardTitle>タイトル</CardTitle>',
+      '</CardHeader>',
+      '',
+      '// ❌ Wrong — padding を安易に上書きしない',
+      '<CardHeader className="p-4 pb-2">',
+      '  <CardTitle>タイトル</CardTitle>',
+      '</CardHeader>',
+      '```',
+    ]),
+    jsdocTargets: [],
+  },
+  {
+    id: 'aschild-with-icon-props',
+    check: {
+      description: 'asChild 使用時に prefixIcon / suffixIcon / isLoading を使わない',
+      recommendation:
+        'asChild モードでは prefixIcon / suffixIcon / isLoading は無視されます。アイコン付きの Link が必要なら asChild を外してください。',
+      pattern: /<Button\b(?=[^>]*\basChild\b)(?=[^>]*\b(?:prefixIcon|suffixIcon|isLoading)\b)[^>]*>/g,
+    },
+    featureSection: lines([
+      '### asChild と prefixIcon / suffixIcon / isLoading を併用しない',
+      '',
+      '```tsx',
+      '// ✅ Correct',
+      '<Button asChild>',
+      '  <Link href="/items/new">新規作成</Link>',
+      '</Button>',
+      '',
+      '// ❌ Wrong — asChild では prefixIcon は反映されない',
+      '<Button asChild prefixIcon="add">',
+      '  <Link href="/items/new">新規作成</Link>',
+      '</Button>',
+      '```',
+    ]),
+    jsdocTargets: [],
+  },
+  {
+    id: 'disabled-vs-is-disabled',
+    check: {
+      description: 'Sparkle Design コンポーネントでは isDisabled を使う',
+      recommendation:
+        'Button / Input / Checkbox / IconButton では disabled ではなく isDisabled を使ってください。',
+      pattern: /<(Button|Input|Checkbox|IconButton)\b[^>]*\sdisabled(?!=\s*\{)\b/g,
+    },
+    featureSection: lines([
+      '### disabled ではなく isDisabled を使う',
+      '',
+      '```tsx',
+      '// ✅ Correct',
+      '<Button isDisabled>確定</Button>',
+      '<Input isDisabled placeholder="無効状態" />',
+      '',
+      '// ❌ Wrong — disabled 属性を直接使わない',
+      '<Button disabled>確定</Button>',
+      '```',
+      '',
+      'HTML 標準の `disabled` も互換のため受け付けますが、Sparkle Design のコードでは `isDisabled` に統一します。',
+    ]),
+    jsdocTargets: [],
+  },
+  {
+    id: 'button-prefixicon-jsx',
+    check: {
+      description: 'Button の prefixIcon / suffixIcon に JSX を渡さない',
+      recommendation:
+        'prefixIcon / suffixIcon には Material Symbols のアイコン名（文字列）を渡してください。JSX（<Icon ... />）は渡さないでください。',
+      pattern: /<Button\b[^>]*\b(?:prefixIcon|suffixIcon)\s*=\s*\{[^}]*</g,
+    },
+    featureSection: lines([
+      '### Button の prefixIcon / suffixIcon に JSX を渡さない',
+      '',
+      '```tsx',
+      '// ✅ Correct — 文字列でアイコン名を渡す',
+      '<Button prefixIcon="bolt">アクション</Button>',
+      '',
+      '// ❌ Wrong — JSX を渡さない',
+      '<Button prefixIcon={<Icon icon="bolt" size={4} />}>アクション</Button>',
+      '```',
+    ]),
+    jsdocTargets: [],
+  },
+  {
+    id: 'icon-children-text',
+    check: {
+      description: 'Icon の children にテキストを渡さない',
+      recommendation:
+        'Icon には icon prop でアイコン名を渡してください。children にテキストを渡すのは旧 Material Icons の書き方です。',
+      pattern: /<Icon\b(?:[^>]|\/(?!>))*>[^<]+<\/Icon>/g,
+    },
+    featureSection: lines([
+      '### Icon の children にテキストを渡さない',
+      '',
+      '```tsx',
+      '// ✅ Correct — icon prop を使う',
+      '<Icon icon="chevron_left" size={4} />',
+      '',
+      '// ❌ Wrong — children にテキストを渡さない',
+      '<Icon size={4}>chevron_left</Icon>',
+      '```',
+    ]),
+    jsdocTargets: [],
+  },
 ];
 
 function getCheckRules() {
-  const order = ['dialog-form', 'dialog-button-wrap', 'button-icon-only', 'material-symbols-direct', 'shadcn-token'];
+  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

@@ -2,17 +2,26 @@ import fs from 'fs';
 import path from 'path';
 
 import { getCheckRules, getManualReviewReminders } from './anti-pattern-rules.js';
+import { REGEX, FONT_DOMAINS } from './constants.js';
 
 const DEFAULT_TARGET = 'src';
 const TEXT_EXTENSIONS = new Set(['.js', '.jsx', '.ts', '.tsx']);
+const CSS_EXTENSIONS = new Set(['.css']);
 const RULES = getCheckRules();
-const MANUAL_REVIEW_REMINDERS = getManualReviewReminders();
+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'];
 
 function toRelativeReportPath(filePath) {
   return path.relative(process.cwd(), filePath).split(path.sep).join('/');
 }
 
-function collectFiles(targetPath, files, visited) {
+/**
+ * ディレクトリを1回だけ走査し、テキストファイルと CSS ファイルを同時に収集する
+ */
+function collectFiles(targetPath, textFiles, cssFiles, visited) {
   if (!fs.existsSync(targetPath)) {
     throw new Error(`Target path does not exist: ${targetPath}`);
   }
@@ -26,8 +35,11 @@ function collectFiles(targetPath, files, visited) {
   const stat = fs.statSync(realPath);
 
   if (stat.isFile()) {
-    if (TEXT_EXTENSIONS.has(path.extname(realPath))) {
-      files.add(realPath);
+    const ext = path.extname(realPath);
+    if (TEXT_EXTENSIONS.has(ext)) {
+      textFiles.add(realPath);
+    } else if (CSS_EXTENSIONS.has(ext)) {
+      cssFiles.add(realPath);
     }
     return;
   }
@@ -41,7 +53,7 @@ function collectFiles(targetPath, files, visited) {
       continue;
     }
 
-    collectFiles(path.join(realPath, entry.name), files, visited);
+    collectFiles(path.join(realPath, entry.name), textFiles, cssFiles, visited);
   }
 }
 
@@ -53,8 +65,7 @@ function formatMatch(match) {
   return match[0].replace(/\s+/g, ' ').trim().slice(0, 120);
 }
 
-function collectFindings(filePath) {
-  const content = fs.readFileSync(filePath, 'utf8');
+function collectFindings(filePath, content) {
   const findings = [];
 
   for (const rule of RULES) {
@@ -73,42 +84,137 @@ function collectFindings(filePath) {
   return findings;
 }
 
+/**
+ * CSS ファイルからフォント @import の残存を検出する
+ */
+function collectFontImportFindings(cssFiles) {
+  const findings = [];
+
+  for (const filePath of cssFiles) {
+    const content = fs.readFileSync(filePath, 'utf8');
+    for (const match of content.matchAll(REGEX.FONT_IMPORT)) {
+      findings.push({
+        filePath,
+        id: 'font-import-in-css',
+        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),
+      });
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * ソースコード内に <SparkleHead /> の JSX 使用があるか検出する
+ * SparkleHead.tsx 自体の定義は除外し、実際に JSX として使用している箇所のみ検出する
+ */
+function hasSparkleHeadUsage(fileContents) {
+  for (const [filePath, content] of fileContents) {
+    if (path.basename(filePath) === 'SparkleHead.tsx') continue;
+    if (SPARKLE_HEAD_JSX_PATTERN.test(content)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Next.js の CSP ヘッダー設定を検出し、Google Fonts ドメインの許可を確認する
+ */
+function collectNextjsCspFindings(cwd) {
+  const findings = [];
+
+  for (const candidate of NEXT_CONFIG_CANDIDATES) {
+    const configPath = path.resolve(cwd, candidate);
+
+    let content;
+    try {
+      content = fs.readFileSync(configPath, 'utf8');
+    } catch {
+      continue;
+    }
+
+    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://', '')) },
+    ].filter(({ pattern }) => !pattern.test(content));
+
+    if (missingDomains.length > 0) {
+      const missing = missingDomains.map(d => `${d.domain} (${d.directive})`).join(', ');
+      findings.push({
+        filePath: configPath,
+        id: 'csp-font-block',
+        description: `CSP ヘッダーが設定されていますが、${missing} が許可されていない可能性があります。`,
+        recommendation: `style-src に ${FONT_DOMAINS.GOOGLEAPIS} を、font-src に ${FONT_DOMAINS.GSTATIC} を追加してください。`,
+        line: 1,
+        snippet: `Content-Security-Policy detected, missing: ${missing}`,
+      });
+    }
+    break;
+  }
+
+  return findings;
+}
+
 function createCheckReport(targets = []) {
   const resolvedTargets = targets.length > 0 ? targets : [DEFAULT_TARGET];
-  const files = new Set();
+  const textFiles = new Set();
+  const cssFiles = new Set();
   const visited = new Set();
 
+  // 1回のディレクトリ走査でテキストファイルと CSS ファイルを同時に収集
   for (const target of resolvedTargets) {
-    collectFiles(path.resolve(process.cwd(), target), files, visited);
+    collectFiles(path.resolve(process.cwd(), target), textFiles, cssFiles, visited);
   }
 
-  const checkedFiles = [...files]
+  const checkedFiles = [...textFiles]
     .map((filePath) => toRelativeReportPath(filePath))
     .sort((left, right) => left.localeCompare(right));
-  const findings = [...files]
-    .flatMap(collectFindings)
+
+  // ファイル内容を1回だけ読み込んでキャッシュ（collectFindings + hasSparkleHeadUsage で再利用）
+  const fileContents = new Map();
+  for (const filePath of textFiles) {
+    fileContents.set(filePath, fs.readFileSync(filePath, 'utf8'));
+  }
+
+  const findings = [...fileContents.entries()]
+    .flatMap(([filePath, content]) => collectFindings(filePath, content))
     .map((finding) => ({
       ...finding,
       filePath: toRelativeReportPath(finding.filePath),
-    }))
-    .sort((left, right) => {
-      const fileComparison = left.filePath.localeCompare(right.filePath);
-      if (fileComparison !== 0) {
-        return fileComparison;
-      }
-
-      if (left.line !== right.line) {
-        return left.line - right.line;
-      }
-
-      return left.id.localeCompare(right.id);
+    }));
+
+  const fontFindings = collectFontImportFindings(cssFiles);
+  findings.push(...fontFindings.map((f) => ({ ...f, filePath: toRelativeReportPath(f.filePath) })));
+
+  const cspFindings = collectNextjsCspFindings(process.cwd());
+  findings.push(...cspFindings.map((f) => ({ ...f, filePath: toRelativeReportPath(f.filePath) })));
+
+  findings.sort((left, right) => {
+    const fileComparison = left.filePath.localeCompare(right.filePath);
+    if (fileComparison !== 0) return fileComparison;
+    if (left.line !== right.line) return left.line - right.line;
+    return left.id.localeCompare(right.id);
+  });
+
+  const manualReviewReminders = [...BASE_MANUAL_REVIEW_REMINDERS];
+  if (!hasSparkleHeadUsage(fileContents)) {
+    manualReviewReminders.push({
+      id: 'sparkle-head-missing',
+      message: 'SparkleHead がソースコード内に見つかりませんでした。ルートレイアウトの <head> 内に <SparkleHead /> を配置してフォントの早期読み込みを有効にしてください。',
     });
+  }
 
   return {
     targets: resolvedTargets,
     checkedFiles,
     findings,
-    manualReviewReminders: MANUAL_REVIEW_REMINDERS,
+    manualReviewReminders,
   };
 }
 
@@ -171,4 +277,4 @@ export function checkProject(targets = [], options = {}) {
   return report.findings.length > 0;
 }
 
-export { RULES, collectFindings, createCheckReport, MANUAL_REVIEW_REMINDERS };
+export { RULES, collectFindings, createCheckReport, BASE_MANUAL_REVIEW_REMINDERS as MANUAL_REVIEW_REMINDERS };

package/lib/constants.js

@@ -56,6 +56,12 @@ export const PLACEHOLDERS = {
   FONT_FAMILY_MONO: '{{FONT_FAMILY_MONO}}',
 };
 
+// Google Fonts ドメイン
+export const FONT_DOMAINS = {
+  GOOGLEAPIS: 'https://fonts.googleapis.com',
+  GSTATIC: 'https://fonts.gstatic.com',
+};
+
 // フォントのデフォルト設定
 export const FONT_DEFAULTS = {
   WEIGHTS: [400, 700],

package/lib/font-manager.js

@@ -172,19 +172,18 @@ function findTailwindImport(globalsContent) {
 
 /**
  * globals.css を再構築する
+ * フォント @import は SparkleHead.tsx に移行したため、globals.css には差し込まない
  * @param {string} globalsContent 元のglobals.cssの内容
- * @param {string} fontImportBlock フォントimportブロック
  * @param {string} sparkleImportBlock sparkle-design.css importブロック
  * @param {Object} tailwindInfo Tailwind importの情報
  * @returns {string} 再構築されたglobals.css
  */
-function reconstructGlobalsCss(globalsContent, fontImportBlock, sparkleImportBlock, tailwindInfo) {
+function reconstructGlobalsCss(globalsContent, sparkleImportBlock, tailwindInfo) {
   const beforeTailwind = globalsContent.substring(0, tailwindInfo.index);
   const afterTailwind = globalsContent.substring(tailwindInfo.afterIndex);
 
-  // フォントimport + Tailwind + sparkle-design.css + 残りのコンテンツ
+  // Tailwind + sparkle-design.css + 残りのコンテンツ（フォント @import なし）
   return (
-    fontImportBlock +
     beforeTailwind +
     tailwindInfo.match +
     sparkleImportBlock +
@@ -222,14 +221,12 @@ export function updateGlobalsWithFonts(fontImports, globalsPath, sourcePackages
       return false;
     }
 
-    // 4. importブロックを生成
-    const fontImportBlock = createFontImportBlock(fontImports);
+    // 4. importブロックを生成（フォント @import は SparkleHead に移行したため生成しない）
     const sparkleImportBlock = createSparkleImportBlock(sourcePackages, globalsPath, customCssPath);
 
-    // 5. globals.css を再構築
+    // 5. globals.css を再構築（フォント @import なし）
     const reconstructedContent = reconstructGlobalsCss(
       globalsContent,
-      fontImportBlock,
       sparkleImportBlock,
       tailwindInfo
     );

package/lib/generate-css.js

@@ -7,7 +7,7 @@
 
 import fs from 'fs';
 import path from 'path';
-import { REGEX, PATHS, MESSAGES, FONT_DEFAULTS } from './constants.js';
+import { REGEX, PATHS, MESSAGES, FONT_DEFAULTS, FONT_DOMAINS } from './constants.js';
 import {
   loadConfig,
   loadTemplate,
@@ -181,6 +181,80 @@ function generateFontImportsBlock(configOrResolved) {
   return imports.join('\n');
 }
 
+/**
+ * @import 文から Google Fonts の URL を抽出する
+ * @param {string} importLine @import 文
+ * @returns {string} URL
+ */
+function extractUrlFromImport(importLine) {
+  const match = importLine.match(/@import\s+['"]([^'"]+)['"]/);
+  return match ? match[1] : '';
+}
+
+/**
+ * SparkleHead.tsx の内容を生成する
+ * sparkle.config.json のフォント設定に基づき、preconnect + link タグを含む React コンポーネントを生成
+ * @param {Object} resolvedFonts resolveFontConfig の結果
+ * @returns {string} SparkleHead.tsx のファイル内容
+ */
+function generateSparkleHeadContent(resolvedFonts) {
+  const materialSymbolsUrl = extractUrlFromImport(FONT_DEFAULTS.MATERIAL_SYMBOLS_IMPORT);
+  const fontImportLines = generateMergedFontImports([...resolvedFonts.pro, ...resolvedFonts.mono]);
+  const fontUrls = fontImportLines.map(extractUrlFromImport).filter(Boolean);
+
+  const linkTags = [
+    `      <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}" />`),
+  ];
+
+  return `/**
+ * Copyright 2026 Goodpatch Inc.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * SparkleHead - フォント読み込みコンポーネント
+ *
+ * sparkle-design-cli generate により sparkle.config.json から自動生成されます。
+ * ルートレイアウトの <head> 内に配置してください。
+ *
+ * @example
+ * import { SparkleHead } from "./SparkleHead";
+ *
+ * export default function RootLayout({ children }) {
+ *   return (
+ *     <html>
+ *       <head>
+ *         <SparkleHead />
+ *       </head>
+ *       <body>{children}</body>
+ *     </html>
+ *   );
+ * }
+ */
+export function SparkleHead() {
+  return (
+    <>
+${linkTags.join('\n')}
+    </>
+  );
+}
+`;
+}
+
+/**
+ * SparkleHead.tsx を書き出す
+ * @param {string} content SparkleHead.tsx の内容
+ * @param {string} sparkleDesignCssPath sparkle-design.css の出力パス（同じディレクトリに配置）
+ */
+function writeSparkleHead(content, sparkleDesignCssPath) {
+  const outputPath = path.join(path.dirname(sparkleDesignCssPath), 'SparkleHead.tsx');
+  fs.writeFileSync(outputPath, content, 'utf8');
+  console.log(`✅ SparkleHead.tsx を生成しました: ${outputPath}`);
+  console.log('   → ルートレイアウトの <head> 内に <SparkleHead /> を追加してください');
+}
+
 /**
  * テンプレート変数を設定値で置換する
  * @param {string} template CSSテンプレート
@@ -212,7 +286,7 @@ function processTemplate(template, config, grayMapping, radiusMapping, colors) {
   processedCSS = processedCSS.replace(/\{\{FONT_FAMILY_PRO\}\}/g, proFamilyValue);
   processedCSS = processedCSS.replace(/\{\{FONT_FAMILY_MONO\}\}/g, monoFamilyValue);
 
-  // 5. 基本的な設定値による置換（font-pro / font-mono の配列以外）
+  // 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') {
@@ -250,7 +324,7 @@ function processTemplate(template, config, grayMapping, radiusMapping, colors) {
   processedCSS = dedupeFontImports(processedCSS);
 
   console.log(MESSAGES.TEMPLATE_PROCESSED);
-  return processedCSS;
+  return { css: processedCSS, resolvedFonts };
 }
 
 /**
@@ -304,8 +378,8 @@ export function generateCSS(configPath = null, outputPath = null) {
   const grayMapping = loadGrayMapping();
   const radiusMapping = loadRadiusMapping();
 
-  // 5. テンプレートを設定値で処理
-  const processedCSS = processTemplate(template, config, grayMapping, radiusMapping, colors);
+  // 5. テンプレートを設定値で処理（resolvedFonts も返す）
+  const { css: processedCSS, resolvedFonts } = processTemplate(template, config, grayMapping, radiusMapping, colors);
 
   // 6. CSSファイルを書き出し
   const defaultOutputPath = path.resolve(
@@ -316,7 +390,11 @@ export function generateCSS(configPath = null, outputPath = null) {
   const resolvedOutputPath = outputPath ? path.resolve(outputPath) : defaultOutputPath;
   writeCSS(processedCSS, outputPath);
 
-  // 7. フォント管理の自動処理を実行
+  // 7. SparkleHead.tsx を生成（processTemplate で解決済みの resolvedFonts を再利用）
+  const sparkleHeadContent = generateSparkleHeadContent(resolvedFonts);
+  writeSparkleHead(sparkleHeadContent, resolvedOutputPath);
+
+  // 8. フォント管理の自動処理を実行（globals.css にはフォント @import を差し込まない）
   console.log(MESSAGES.FONT_MANAGEMENT_START);
   const sourcePackages = 'source-packages' in config ? (config['source-packages'] || []) : null;
   const customCssPath = config['custom-css'] || null;

package/lib/setup.js

@@ -43,36 +43,49 @@ function writeJson(filePath, value) {
   fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
 }
 
-function normalizeTarget(cwd, target, sourceLabel) {
-  const trimmed = target.trim();
+/**
+ * 相対パスのバリデーションと正規化
+ * @param {string} cwd プロジェクトルート
+ * @param {string} inputPath 入力パス
+ * @param {string} label エラーメッセージ用ラベル
+ * @param {{ checkParentOnly?: boolean }} options
+ *   checkParentOnly: true の場合、パス自体ではなく親ディレクトリの存在をチェック（新規ファイル作成用）
+ */
+function normalizePath(cwd, inputPath, label, { checkParentOnly = false } = {}) {
+  const trimmed = inputPath.trim();
 
   if (!trimmed) {
-    throw new Error(`Target path is empty (${sourceLabel})`);
+    throw new Error(`${label} is empty`);
   }
 
   if (path.isAbsolute(trimmed)) {
-    throw new Error(`Target path must be relative to the project root: ${trimmed}`);
+    throw new Error(`${label} must be relative to the project root: ${trimmed}`);
   }
 
   if (UNSAFE_TARGET_PATTERN.test(trimmed)) {
     throw new Error(
-      `Target path contains unsupported characters: ${trimmed}. Use a simple relative path without spaces or shell metacharacters.`
+      `${label} contains unsupported characters: ${trimmed}. Use a simple relative path.`
     );
   }
 
   const normalized = path.posix.normalize(trimmed.replace(/\\/g, '/'));
 
-  if (normalized === '.' || normalized === '') {
-    throw new Error(`Target path is empty (${sourceLabel})`);
+  if (!checkParentOnly && (normalized === '.' || normalized === '')) {
+    throw new Error(`${label} is empty`);
   }
 
   if (normalized.startsWith('../')) {
-    throw new Error(`Target path must stay inside the project root: ${trimmed}`);
+    throw new Error(`${label} must stay inside the project root: ${trimmed}`);
   }
 
-  const absolutePath = path.resolve(cwd, normalized);
-  if (!fs.existsSync(absolutePath)) {
-    throw new Error(`Target path does not exist: ${normalized}`);
+  const checkPath = checkParentOnly
+    ? path.resolve(cwd, path.dirname(normalized))
+    : path.resolve(cwd, normalized);
+
+  if (!fs.existsSync(checkPath)) {
+    const desc = checkParentOnly ? 'Parent directory' : 'Path';
+    const displayPath = checkParentOnly ? path.dirname(normalized) : normalized;
+    throw new Error(`${desc} does not exist: ${displayPath}`);
   }
 
   return normalized;
@@ -221,15 +234,17 @@ export function setupAssistant(options = {}) {
 
   const targetSource = options.target ? 'explicit' : 'auto';
   const target = options.target
-    ? normalizeTarget(cwd, options.target, 'explicit')
-    : normalizeTarget(cwd, detectTarget(cwd), 'auto');
+    ? normalizePath(cwd, options.target, 'Target path')
+    : normalizePath(cwd, detectTarget(cwd), 'Target path');
 
   const packageJsonPath = path.resolve(cwd, 'package.json');
   if (!fs.existsSync(packageJsonPath)) {
     throw new Error(`package.json not found in ${cwd}`);
   }
 
-  const instructionPath = path.resolve(cwd, assistantConfig.path);
+  const instructionPath = options.instructionsPath
+    ? path.resolve(cwd, normalizePath(cwd, options.instructionsPath, 'Instructions path', { checkParentOnly: true }))
+    : path.resolve(cwd, assistantConfig.path);
   const packageResult = updatePackageJson(packageJsonPath, target, force);
   const instructionBlock = buildInstructionBlock(target, assistant);
   const instructionResult = updateInstructionFile(instructionPath, instructionBlock);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sparkle-design-cli",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Sparkle Design CSS Generator - デザインシステムCSSを設定ファイルから生成するツール",
   "main": "lib/generate-css.js",
   "type": "module",