sparkle-design-cli 1.3.8 → 1.3.9

package/README.md

@@ -1,6 +1,6 @@
 # Sparkle Design CLI
 
-デザインシステム CSS を設定ファイルから生成する CLI ツールです。
+デザインシステム CSS の生成と、Sparkle Design のアンチパターン検査を行う CLI ツールです。
 
 ## インストール
 
@@ -10,7 +10,22 @@ npm install -g sparkle-design-cli
 
 ## 使用方法
 
-### 基本的な使用方法
+### サブコマンド
+
+```bash
+# CSS を生成
+npx sparkle-design-cli generate
+
+# アンチパターンを検査
+npx sparkle-design-cli check src --strict
+```
+
+### 後方互換モード
+
+既存の `npx sparkle-design-cli` も引き続き動作し、内部的には `generate` として扱われます。
+ただし後方互換のための動作なので、新規利用やドキュメント上の案内では `sparkle-design-cli generate` を使用してください。
+
+### generate: 基本的な使用方法
 
 1. プロジェクトのルートディレクトリに `sparkle.config.json` ファイルを作成または配置します：
 
@@ -26,39 +41,77 @@ npm install -g sparkle-design-cli
 2. CLI ツールを実行します：
 
 ```bash
-npx sparkle-design-cli
+npx sparkle-design-cli generate
 ```
 
-または、グローバルにインストールした場合：
+既存プロジェクトでサブコマンドなしの呼び出しを使っている場合も、後方互換として次の実行方法を継続利用できます:
 
 ```bash
-sparkle-design-cli
+npx sparkle-design-cli
 ```
 
 3. `src/app/sparkle-design.css` に CSS ファイルが生成されます。
 
-### コマンドオプション
+### generate: コマンドオプション
 
 ```bash
 # ヘルプを表示
-sparkle-design-cli --help
+sparkle-design-cli generate --help
 
 # カスタム設定ファイルを指定
-sparkle-design-cli --config ./config/design.json
+sparkle-design-cli generate --config ./config/design.json
 
 # カスタム出力先を指定
-sparkle-design-cli --output ./styles/design.css
+sparkle-design-cli generate --output ./styles/design.css
 
 # 設定ファイルと出力先を両方指定
-sparkle-design-cli -c ./config/custom.json -o ./dist/styles.css
+sparkle-design-cli generate -c ./config/custom.json -o ./dist/styles.css
 ```
 
-#### オプション一覧
+#### generate オプション一覧
 
 - `-h, --help`: ヘルプメッセージを表示
 - `-c, --config <パス>`: 設定ファイルのパス（デフォルト: `./sparkle.config.json`）
 - `-o, --output <パス>`: 出力ファイルのパス（デフォルト: `./src/app/sparkle-design.css`）
 
+### check: アンチパターン検査
+
+`sparkle-design-cli check` は、導入先プロジェクトで発生しやすい Sparkle Design のアンチパターンを検出します。
+
+```bash
+# src を検査
+sparkle-design-cli check
+
+# 特定ディレクトリを strict モードで検査
+sparkle-design-cli check src/components src/features --strict
+
+# check のヘルプを表示
+sparkle-design-cli check --help
+```
+
+#### check オプション一覧
+
+- `-h, --help`: ヘルプメッセージを表示
+- `--strict`: 違反が見つかった場合に exit code 1 で終了
+
+#### 現在検出するルール
+
+- フォーム入力に Dialog を使わない
+- DialogCancel/DialogAction を Button で二重ラップしない
+- shadcn/ui 既定 token を Sparkle Design 内へ持ち込まない
+
+#### 導入先での推奨設定
+
+```json
+{
+  "scripts": {
+    "lint:sparkle": "sparkle-design-cli check src --strict"
+  }
+}
+```
+
+AI エージェントや CI からこの `lint:sparkle` を呼ぶ運用にすると、ガイドラインの注意書きだけに頼らず機械的に検査できます。
+
 ## 設定ファイル (sparkle.config.json)
 
 ### 設定ファイルの作成
@@ -105,12 +158,12 @@ sparkle-design-cli -c ./config/custom.json -o ./dist/styles.css
 生成される `globals.css`:
 
 ```css
-@import "tailwindcss";
+@import 'tailwindcss';
 /* npm パッケージのコンテンツスキャン（Tailwind がクラスを検出するために必要） */
 @source "../node_modules/@goodpatch/sparkle-design/dist";
 @source "../node_modules/@scope/my-extension-design/dist";
 /* Sparkle Design のカスタム定義（Tailwindの後にインポート） */
-@import "./sparkle-design.css";
+@import './sparkle-design.css';
 ```
 
 > **注意**: `source-packages` を指定しない場合、`@source` ディレクティブは生成されません。
@@ -192,14 +245,17 @@ npm run format:check
 ### CLI実行テスト
 
 ```bash
-# デフォルト設定でテスト
+# CSS生成
+sparkle-design-cli generate
+
+# 既存呼び出しの後方互換モード
 sparkle-design-cli
 
 # ヘルプ表示
-sparkle-design-cli --help
+sparkle-design-cli generate --help
 
-# カスタムパスでテスト
-sparkle-design-cli -c test-config.json -o test-output.css
+# 検査
+sparkle-design-cli check src --strict
 ```
 
 ## ライセンス

package/bin/sparkle-design.js

@@ -1,93 +1,176 @@
 #!/usr/bin/env node
 
 import { generateCSS } from '../lib/generate-css.js';
+import { checkProject } from '../lib/check.js';
 
-// コマンドライン引数を解析
-function parseArguments() {
-  const args = process.argv.slice(2);
+const SUBCOMMANDS = new Set(['generate', 'check']);
+
+function requireOptionValue(args, index, flags) {
+  const value = args[index + 1];
+  if (!value || value.startsWith('-')) {
+    throw new Error(`Missing value for ${flags}`);
+  }
+  return value;
+}
+
+function parseGenerateOptions(args) {
   const options = {
     configPath: null,
     outputPath: null,
     help: false,
   };
 
-  for (let i = 0; i < args.length; i++) {
+  for (let i = 0; i < args.length; i += 1) {
     const arg = args[i];
 
     if (arg === '-h' || arg === '--help') {
       options.help = true;
     } else if (arg === '-c' || arg === '--config') {
-      options.configPath = args[i + 1];
-      i++; // 次の引数をスキップ
+      options.configPath = requireOptionValue(args, i, '-c/--config');
+      i += 1;
     } else if (arg === '-o' || arg === '--output') {
-      options.outputPath = args[i + 1];
-      i++; // 次の引数をスキップ
+      options.outputPath = requireOptionValue(args, i, '-o/--output');
+      i += 1;
+    } else {
+      throw new Error(`Unknown option for generate: ${arg}`);
+    }
+  }
+
+  return options;
+}
+
+function parseCheckOptions(args) {
+  const options = {
+    targets: [],
+    strict: false,
+    help: false,
+  };
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+
+    if (arg === '-h' || arg === '--help') {
+      options.help = true;
+    } else if (arg === '--strict') {
+      options.strict = true;
+    } else if (arg.startsWith('-')) {
+      throw new Error(`Unknown option for check: ${arg}`);
+    } else {
+      options.targets.push(arg);
     }
   }
 
   return options;
 }
 
-// ヘルプメッセージを表示
 function showHelp() {
   console.log(`
-Sparkle Design CLI - デザインシステム CSS 生成ツール
+Sparkle Design CLI
 
 使用方法:
-  sparkle-design-cli [オプション]
+  sparkle-design-cli <command> [options]
+
+Commands:
+  generate   sparkle.config.json から CSS を生成
+  check      Sparkle Design のアンチパターンを検査
+
+後方互換:
+  sparkle-design-cli [generate options]
+  サブコマンドなしの実行は現在も generate として動作しますが、
+  正式リリース時に削除予定です。今後は sparkle-design-cli generate を使ってください。
 
-基本的な使用方法:
-  1. プロジェクトのルートディレクトリに sparkle.config.json ファイルを作成または配置
-  2. CLI ツールを実行: sparkle-design-cli
-  3. src/app/sparkle-design.css に CSS ファイルが生成されます
+Generate:
+  sparkle-design-cli generate
+  sparkle-design-cli generate --config ./config/design.json
+  sparkle-design-cli generate --output ./styles/design.css
+  sparkle-design-cli generate -c ./config/custom.json -o ./dist/styles.css
 
-オプション:
+Check:
+  sparkle-design-cli check
+  sparkle-design-cli check src --strict
+  sparkle-design-cli check src/components src/features
+
+Generate options:
   -h, --help                 このヘルプメッセージを表示
-  -c, --config <パス>        設定ファイルのパス (デフォルト: ./sparkle.config.json)
-  -o, --output <パス>        出力ファイルのパス (デフォルト: ./src/app/sparkle-design.css)
-
-使用例:
-  sparkle-design-cli
-  sparkle-design-cli --config ./config/design.json
-  sparkle-design-cli --output ./styles/design.css
-  sparkle-design-cli -c ./config/custom.json -o ./dist/styles.css
-
-設定ファイル (sparkle.config.json):
-  設定ファイルは専用のプラグインから自動生成することを推奨します。
-  プロジェクトのルートディレクトリに配置してください。
-
-  設定例:
-  {
-    "primary": "blue",
-    "font-pro": "BIZ UDPGothic",
-    "font-mono": "BIZ UDGothic",
-    "radius": "md"
-  }
+  -c, --config <path>        設定ファイルのパス (default: ./sparkle.config.json)
+  -o, --output <path>        出力ファイルのパス (default: ./src/app/sparkle-design.css)
 
-  設定オプション:
-  - primary: プライマリカラー (blue, red, orange など)
-  - font-pro: プロポーショナルフォント (Google Fonts の名前)
-  - font-mono: モノスペースフォント (Google Fonts の名前)
-  - radius: 角丸設定 (sm, md, lg など)
+Check options:
+  -h, --help                 このヘルプメッセージを表示
+  --strict                   違反があれば exit code 1 で終了
 
-出力:
-  - デフォルト出力先: src/app/sparkle-design.css
-  - カスタム出力先: -o オプションで指定可能
-  - 実行場所を基準として相対パスで処理されます
+Check で検出する主なパターン:
+  - フォーム入力に Dialog を使っている
+  - DialogCancel / DialogAction を <Button> で二重ラップしている
+  - text-muted-foreground / bg-background / border-border を持ち込んでいる
 `);
 }
 
-// メイン処理
-function main() {
-  const options = parseArguments();
+function showGenerateDeprecationNotice() {
+  console.warn(
+    '[sparkle-design-cli] Running without a subcommand defaults to `generate`. ' +
+      'Use `sparkle-design-cli generate` instead. This compatibility mode will be removed at the formal release.'
+  );
+}
 
-  if (options.help) {
-    showHelp();
-    process.exit(0);
-  }
+function main() {
+  const args = process.argv.slice(2);
+  const command = args[0];
 
   try {
-    generateCSS(options.configPath, options.outputPath);
+    if (args.length === 0) {
+      showGenerateDeprecationNotice();
+      generateCSS();
+      return;
+    }
+
+    if (command === '-h' || command === '--help') {
+      showHelp();
+      process.exit(0);
+    }
+    if (command === 'generate') {
+      const options = parseGenerateOptions(args.slice(1));
+
+      if (options.help) {
+        showHelp();
+        process.exit(0);
+      }
+
+      generateCSS(options.configPath, options.outputPath);
+      return;
+    }
+
+    if (command === 'check') {
+      const options = parseCheckOptions(args.slice(1));
+
+      if (options.help) {
+        showHelp();
+        process.exit(0);
+      }
+
+      const hasFindings = checkProject(options.targets, { strict: options.strict });
+      if (hasFindings && options.strict) {
+        process.exit(1);
+      }
+      return;
+    }
+
+    if (!SUBCOMMANDS.has(command) && command.startsWith('-')) {
+      showGenerateDeprecationNotice();
+      const options = parseGenerateOptions(args);
+
+      if (options.help) {
+        showHelp();
+        process.exit(0);
+      }
+
+      generateCSS(options.configPath, options.outputPath);
+      return;
+    }
+
+    if (!SUBCOMMANDS.has(command)) {
+      throw new Error(`Unknown command: ${command}`);
+    }
   } catch (error) {
     console.error('❌ エラーが発生しました:', error.message);
     process.exit(1);

package/lib/anti-pattern-rules.js

@@ -0,0 +1,698 @@
+const COMMON_INTRO =
+  '以下は頻繁に発生する誤用パターンです。コンポーネントが提供する専用 props・サブコンポーネントを使ってください。';
+
+function lines(values) {
+  return values.join('\n');
+}
+
+function renderJSDocSection(section) {
+  const output = ['**アンチパターン / Anti-patterns**', ''];
+
+  for (const bullet of section.bullets) {
+    output.push(`- ${bullet.ja}`);
+    output.push(`  en: ${bullet.en}`);
+  }
+
+  if (section.example) {
+    output.push('');
+    output.push('```tsx');
+    output.push(...section.example.split('\n'));
+    output.push('```');
+  }
+
+  return output.map((line) => (line ? ` * ${line}` : ' *')).join('\n');
+}
+
+const ANTI_PATTERN_GROUPS = [
+  {
+    id: 'card-description',
+    featureSection: lines([
+      '### CardTitle の補足テキストには CardDescription を使う',
+      '',
+      '```tsx',
+      '// ✅ Correct',
+      '<CardHeader>',
+      '  <CardTitle>',
+      '    プロジェクト一覧',
+      '    <CardDescription className="character-3-regular-pro text-text-low">',
+      '      全 12 件',
+      '    </CardDescription>',
+      '  </CardTitle>',
+      '</CardHeader>',
+      '',
+      '// ❌ Wrong — CardTitle 内に span で補足を入れない',
+      '<CardHeader>',
+      '  <CardTitle>',
+      '    プロジェクト一覧',
+      '    <span className="text-sm text-neutral-500">(12件)</span>',
+      '  </CardTitle>',
+      '</CardHeader>',
+      '```',
+      '',
+      'CardTitle 内の補足情報や件数は CardDescription を使い、必要な typography / color token は className で明示する。',
+    ]),
+    jsdocTargets: [],
+  },
+  {
+    id: 'size-alignment',
+    featureSection: lines([
+      '### Input / Select と横並びの Button はサイズを揃える',
+      '',
+      '```tsx',
+      '// ✅ Correct — 同じサイズで統一',
+      '<div className="flex gap-2">',
+      '  <Input placeholder="検索..." />',
+      '  <Button size="md">検索</Button>',
+      '</div>',
+      '',
+      '// ❌ Wrong — サイズ不一致で高さが揃わない',
+      '<div className="flex gap-2">',
+      '  <Input placeholder="検索..." />',
+      '  <Button size="sm">検索</Button>',
+      '</div>',
+      '```',
+      '',
+      'Input / Select / Textarea のデフォルトサイズは md。横並びの Button も原則 md に合わせる。テーブル内アクションなど独立した Button は sm でよい。',
+    ]),
+    jsdocTargets: [
+      {
+        file: 'src/components/ui/input/index.tsx',
+        targetName: 'Input',
+        section: {
+          bullets: [
+            {
+              ja: 'Input の横にアイコンボタンを手動で配置しないでください。`isTrigger` / `triggerIcon` props を使用してください。',
+              en: 'Do not manually place an IconButton next to Input. Use `isTrigger` / `triggerIcon` props instead.',
+            },
+            {
+              ja: 'Input と横並びの Button は原則同じサイズにしてください。デフォルトの Input に対しては `Button size="md"` を使ってください。',
+              en: 'Keep Button size aligned when placing it next to Input. Use `Button size="md"` with the default Input size.',
+            },
+          ],
+          example: lines([
+            '// ✅ Correct',
+            '<>',
+            '  <Input',
+            '    isTrigger',
+            '    triggerIcon="search"',
+            '    triggerAriaLabel="検索"',
+            '    onIconButtonClick={() => {}}',
+            '  />',
+            '  <div className="flex gap-2">',
+            '    <Input placeholder="検索..." />',
+            '    <Button size="md">検索</Button>',
+            '  </div>',
+            '</>',
+            '',
+            '// ❌ Wrong - 手動配置',
+            '<div className="flex">',
+            '  <Input />',
+            '  <IconButton icon="search" aria-label="検索" />',
+            '</div>',
+            '',
+            '// ❌ Wrong - サイズ不一致',
+            '<div className="flex gap-2">',
+            '  <Input placeholder="検索..." />',
+            '  <Button size="sm">検索</Button>',
+            '</div>',
+          ]),
+        },
+      },
+      {
+        file: 'src/components/ui/select/index.tsx',
+        targetName: 'Select',
+        section: {
+          bullets: [
+            {
+              ja: '`SelectTrigger` と横並びの Button は原則同じサイズにしてください。デフォルトの `SelectTrigger` に対しては `Button size="md"` を使ってください。',
+              en: 'Keep Button size aligned when placing it next to `SelectTrigger`. Use `Button size="md"` with the default `SelectTrigger` size.',
+            },
+          ],
+          example: lines([
+            '// ✅ Correct',
+            '<div className="flex gap-2">',
+            '  <Select>',
+            '    <SelectTrigger size="md" className="w-60">',
+            '      <SelectValue placeholder="選択してください" />',
+            '    </SelectTrigger>',
+            '  </Select>',
+            '  <Button size="md">追加</Button>',
+            '</div>',
+            '',
+            '// ❌ Wrong - 高さが揃わないサイズ不一致',
+            '<div className="flex gap-2">',
+            '  <Select>',
+            '    <SelectTrigger size="md" className="w-60">',
+            '      <SelectValue placeholder="選択してください" />',
+            '    </SelectTrigger>',
+            '  </Select>',
+            '  <Button size="sm">追加</Button>',
+            '</div>',
+          ]),
+        },
+      },
+    ],
+  },
+  {
+    id: 'badge-tag',
+    featureSection: lines([
+      '### Badge と Tag を用途で使い分ける',
+      '',
+      '| コンポーネント | 用途 | 例 |',
+      '| --- | --- | --- |',
+      '| **Badge** | 特定の要素に**数値情報**を付与 | `<Badge>3</Badge>` |',
+      '| **Tag** | 情報の**ラベリング / ステータス付与** | `<Tag status="success">完了</Tag>` |',
+      '',
+      '```tsx',
+      '// ✅ Correct — ステータス表示には Tag を使う',
+      '<Tag variant="outline" status="warning">未紐付け</Tag>',
+      '',
+      '// ❌ Wrong — Badge をステータスラベルに使わない',
+      '<Badge>未紐付け</Badge>',
+      '```',
+    ]),
+    jsdocTargets: [
+      {
+        file: 'src/components/ui/badge/index.tsx',
+        targetName: 'Badge',
+        section: {
+          bullets: [
+            {
+              ja: 'ステータス表示や分類ラベルには `Badge` を使わず、`Tag` を使ってください。',
+              en: 'Do not use `Badge` for status display or category labels. Use `Tag` instead.',
+            },
+          ],
+          example: lines([
+            '// ✅ Correct',
+            '<>',
+            '  <Badge>3</Badge>',
+            '  <Tag status="warning" variant="outline">未紐付け</Tag>',
+            '</>',
+            '',
+            '// ❌ Wrong - ステータスラベルに Badge を使わない',
+            '<Badge>未紐付け</Badge>',
+          ]),
+        },
+      },
+      {
+        file: 'src/components/ui/tag/index.tsx',
+        targetName: 'Tag',
+        section: {
+          bullets: [
+            {
+              ja: '通知数や件数などの数値情報には `Tag` を使わず、`Badge` を使ってください。',
+              en: 'Do not use `Tag` for numeric information such as notification counts. Use `Badge` instead.',
+            },
+          ],
+          example: lines([
+            '// ✅ Correct',
+            '<>',
+            '  <Tag status="success">完了</Tag>',
+            '  <Badge>3</Badge>',
+            '</>',
+            '',
+            '// ❌ Wrong - 件数表示に Tag を使わない',
+            '<Tag status="info">3件</Tag>',
+          ]),
+        },
+      },
+    ],
+  },
+  {
+    id: 'shadcn-token',
+    check: {
+      description: 'shadcn/ui 既定 token を Sparkle Design 内へ持ち込まない',
+      recommendation:
+        'text-muted-foreground / bg-background / border-border などは Sparkle Design token に置き換えてください。',
+      pattern: /\b(text-muted-foreground|bg-background|border-border)\b/g,
+    },
+    featureSection: lines([
+      '### shadcn/ui 由来の class / token をそのまま使わない',
+      '',
+      '```tsx',
+      '// ✅ Correct — Sparkle Design の typography / color token を使う',
+      '<CardDescription className="character-3-regular-pro text-text-low">',
+      '  全 12 件',
+      '</CardDescription>',
+      '',
+      '// ❌ Wrong — shadcn/ui の既定 token や素の font utility を持ち込まない',
+      '<CardDescription className="text-sm text-muted-foreground">',
+      '  全 12 件',
+      '</CardDescription>',
+      '<CardDescription className="font-medium text-slate-500">',
+      '  全 12 件',
+      '</CardDescription>',
+      '```',
+      '',
+      'shadcn/ui と混在するプロジェクトでも、Sparkle Design のコンポーネント内では `character-*` / `text-text-*` / Sparkle の color token を優先する。',
+    ]),
+    jsdocTargets: [],
+  },
+  {
+    id: 'button-icons',
+    featureSection: lines([
+      '### Button: prefixIcon / suffixIcon を使う',
+      '',
+      '```tsx',
+      '// ✅ Correct',
+      '<Button prefixIcon="check">確定</Button>',
+      '<Button suffixIcon="arrow_forward">次へ</Button>',
+      '',
+      '// ❌ Wrong - Icon を children に入れない（レイアウト崩れ・ローディング時に非表示にならない）',
+      '<Button><Icon icon="check" /> 確定</Button>',
+      '',
+      '// ❌ Wrong - アイコンのみのボタンは IconButton を使う',
+      '<Button><Icon icon="edit" /></Button>',
+      '// ✅ Correct',
+      '<IconButton icon="edit" aria-label="編集" />',
+      '```',
+      '',
+      '> Button は size に応じてアイコンサイズを自動設定する（sm→4, md→5, lg→6）。isLoading 時にアイコンを自動で非表示にする。',
+    ]),
+    jsdocTargets: [
+      {
+        file: 'src/components/ui/button/index.tsx',
+        targetName: 'Button',
+        section: {
+          bullets: [
+            {
+              ja: '`<Icon>` を children として渡さないでください。`prefixIcon` / `suffixIcon` props を使用してください。',
+              en: 'Do not pass `<Icon>` as children. Use `prefixIcon` / `suffixIcon` props instead.',
+            },
+            {
+              ja: 'アイコンのみのボタンには `IconButton` を使用してください。',
+              en: 'Use `IconButton` for icon-only buttons.',
+            },
+          ],
+          example: lines([
+            '// ✅ Correct',
+            '<Button prefixIcon="check">確定</Button>',
+            '',
+            '// ❌ Wrong - Icon を children に入れない',
+            '<Button><Icon icon="check" /> 確定</Button>',
+            '',
+            '// ❌ Wrong - アイコンのみは IconButton を使う',
+            '<Button><Icon icon="edit" /></Button>',
+            '// ✅ Correct',
+            '<IconButton icon="edit" aria-label="編集" />',
+          ]),
+        },
+      },
+    ],
+  },
+  {
+    id: 'card-control',
+    featureSection: lines([
+      '### CardHeader: CardControl を使う',
+      '',
+      '```tsx',
+      '// ✅ Correct',
+      '<CardHeader>',
+      '  <CardTitle>タイトル</CardTitle>',
+      '  <CardControl>',
+      '    <Button>アクション</Button>',
+      '  </CardControl>',
+      '</CardHeader>',
+      '',
+      '// ❌ Wrong - 手動 flex を使わない（CardHeader は内部で flex justify-between を適用済み）',
+      '<CardHeader>',
+      '  <div className="flex justify-between">',
+      '    <CardTitle>タイトル</CardTitle>',
+      '    <Button>アクション</Button>',
+      '  </div>',
+      '</CardHeader>',
+      '```',
+    ]),
+    jsdocTargets: [
+      {
+        file: 'src/components/ui/card/index.tsx',
+        targetName: 'CardHeader',
+        section: {
+          bullets: [
+            {
+              ja: 'CardHeader 内で手動の flex レイアウト（`<div className="flex justify-between">`）を使わないでください。CardHeader は内部で flex レイアウトを適用済みです。アクションボタンは `CardControl` で囲んでください。',
+              en: 'Do not use manual flex layout inside CardHeader. CardHeader already applies flex layout internally. Wrap action buttons with `CardControl`.',
+            },
+            {
+              ja: 'CardTitle の補足情報や件数は、`span` などを直書きせず `CardDescription` を使ってください。',
+              en: 'For supporting text or counts inside CardTitle, do not inline a `span`; use `CardDescription`.',
+            },
+          ],
+          example: lines([
+            '// ✅ Correct',
+            '<CardHeader>',
+            '  <CardTitle>',
+            '    タイトル',
+            '    <CardDescription className="character-3-regular-pro text-text-low">',
+            '      全 12 件',
+            '    </CardDescription>',
+            '  </CardTitle>',
+            '  <CardControl>',
+            '    <Button>アクション</Button>',
+            '  </CardControl>',
+            '</CardHeader>',
+            '',
+            '// ❌ Wrong - 手動 flex を使わない',
+            '<CardHeader>',
+            '  <div className="flex justify-between">',
+            '    <CardTitle>タイトル</CardTitle>',
+            '    <Button>アクション</Button>',
+            '  </div>',
+            '</CardHeader>',
+            '',
+            '// ❌ Wrong - CardTitle 内に補足を入れない',
+            '<CardHeader>',
+            '  <CardTitle>',
+            '    タイトル',
+            '    <span className="text-sm text-neutral-500">全 12 件</span>',
+            '  </CardTitle>',
+            '</CardHeader>',
+          ]),
+        },
+      },
+    ],
+  },
+  {
+    id: 'icon-scale',
+    featureSection: lines([
+      '### Icon / Spinner: スケール値（1-12）を使う',
+      '',
+      '```tsx',
+      '// ✅ Correct - スケール値',
+      '<Icon icon="settings" size={6} />   // 24px 相当',
+      '',
+      '// ❌ Wrong - ピクセル値は受け付けない',
+      '<Icon icon="settings" size={24} />',
+      '```',
+      '',
+      '> スケール対応表は上記「Icon Size Scale」セクション参照。',
+    ]),
+    jsdocTargets: [
+      {
+        file: 'src/components/ui/icon/index.tsx',
+        targetName: 'Icon',
+        section: {
+          bullets: [
+            {
+              ja: '`size` にピクセル値（24, 32 など）を渡さないでください。スケール値（1-12）を使用してください。',
+              en: 'Do not pass pixel values to `size`. Use scale values (1-12) instead.',
+            },
+          ],
+          example: lines([
+            '// ✅ Correct - スケール値',
+            '<Icon icon="settings" size={6} />   // 24px 相当',
+            '',
+            '// ❌ Wrong - ピクセル値',
+            '<Icon icon="settings" size={24} />',
+          ]),
+        },
+      },
+      {
+        file: 'src/components/ui/spinner/index.tsx',
+        targetName: 'Spinner',
+        section: {
+          bullets: [
+            {
+              ja: '`size` にピクセル値（24, 32 など）を渡さないでください。スケール値（1-12）を使用してください。',
+              en: 'Do not pass pixel values to `size`. Use scale values (1-12) instead.',
+            },
+          ],
+          example: lines([
+            '// ✅ Correct - スケール値',
+            '<Spinner size={6} />',
+            '',
+            '// ❌ Wrong - ピクセル値',
+            '<Spinner size={24} />',
+          ]),
+        },
+      },
+    ],
+  },
+  {
+    id: 'dialog-button-wrap',
+    check: {
+      description: 'DialogCancel/DialogAction を Button で二重ラップしない',
+      recommendation:
+        'DialogCancel と DialogAction は内部で Button を描画するので、children に Button を入れないでください。',
+      pattern: /<(DialogCancel|DialogAction)\b[^>]*>\s*<Button\b/g,
+    },
+    featureSection: lines([
+      '### DialogCancel / DialogAction: Button で二重ラップしない',
+      '',
+      '```tsx',
+      '// ✅ Correct - 文字列を渡すだけ（内部で Button を描画）',
+      '<DialogCancel>キャンセル</DialogCancel>',
+      '<DialogAction>確定</DialogAction>',
+      '',
+      '// ❌ Wrong - 二重ラップ',
+      '<DialogCancel><Button>キャンセル</Button></DialogCancel>',
+      '```',
+    ]),
+    jsdocTargets: [
+      {
+        file: 'src/components/ui/dialog/index.tsx',
+        targetName: 'DialogCancel',
+        section: {
+          bullets: [
+            {
+              ja: '`DialogCancel` の children に `<Button>` を渡さないでください。内部で Button を描画します。',
+              en: 'Do not pass `<Button>` as children. DialogCancel renders a Button internally.',
+            },
+          ],
+          example: lines([
+            '// ✅ Correct',
+            '<DialogCancel>キャンセル</DialogCancel>',
+            '',
+            '// ❌ Wrong - 二重ラップ',
+            '<DialogCancel><Button>キャンセル</Button></DialogCancel>',
+          ]),
+        },
+      },
+      {
+        file: 'src/components/ui/dialog/index.tsx',
+        targetName: 'DialogAction',
+        section: {
+          bullets: [
+            {
+              ja: '`DialogAction` の children に `<Button>` を渡さないでください。内部で Button を描画します。',
+              en: 'Do not pass `<Button>` as children. DialogAction renders a Button internally.',
+            },
+          ],
+          example: lines([
+            '// ✅ Correct',
+            '<DialogAction>確定</DialogAction>',
+            '',
+            '// ❌ Wrong - 二重ラップ',
+            '<DialogAction><Button>確定</Button></DialogAction>',
+          ]),
+        },
+      },
+    ],
+  },
+  {
+    id: 'dialog-form',
+    check: {
+      description: 'フォーム入力に Dialog を使わない',
+      recommendation: '確認ダイアログは Dialog、フォーム入力や詳細表示は Modal を使ってください。',
+      pattern:
+        /<Dialog(?:\s|>)[\s\S]*?<(Input|Select|Textarea|Checkbox|Radio|Switch|Form|FormField|FormItem)\b[\s\S]*?<\/Dialog>/g,
+    },
+    featureSection: lines([
+      '### Dialog / Modal: 用途を混ぜない',
+      '',
+      '| コンポーネント | ベース | 用途 | 例 |',
+      '| --- | --- | --- | --- |',
+      '| **Dialog** | `AlertDialog` | アクション確認 | 削除確認、再試行確認、保存前の警告 |',
+      '| **Modal** | `Dialog` | フォーム入力・情報表示 | 作成/編集フォーム、詳細表示 |',
+      '',
+      '```tsx',
+      '// ✅ Correct - フォーム入力には Modal を使う',
+      '<Modal>',
+      '  <ModalContent size="md">',
+      '    <ModalHeader>',
+      '      <ModalTitle>ユーザー作成</ModalTitle>',
+      '      <ModalClose />',
+      '    </ModalHeader>',
+      '    <ModalBody isSpace>',
+      '      <Input />',
+      '      <Select />',
+      '    </ModalBody>',
+      '    <ModalFooter>',
+      '      <Button variant="ghost">キャンセル</Button>',
+      '      <Button>作成</Button>',
+      '    </ModalFooter>',
+      '  </ModalContent>',
+      '</Modal>',
+      '',
+      '// ❌ Wrong - フォーム入力に Dialog を使わない',
+      '<Dialog>',
+      '  <DialogContent>',
+      '    <DialogHeader>',
+      '      <DialogTitle>ユーザー作成</DialogTitle>',
+      '    </DialogHeader>',
+      '    <Input />',
+      '    <Select />',
+      '    <DialogFooter>',
+      '      <DialogCancel>キャンセル</DialogCancel>',
+      '      <DialogAction>作成</DialogAction>',
+      '    </DialogFooter>',
+      '  </DialogContent>',
+      '</Dialog>',
+      '```',
+    ]),
+    jsdocTargets: [
+      {
+        file: 'src/components/ui/dialog/index.tsx',
+        targetName: 'Dialog',
+        section: {
+          bullets: [
+            {
+              ja: 'フォーム入力や詳細表示には使わず、削除確認や再試行確認などのアクション確認に使ってください。',
+              en: 'Do not use Dialog for forms or detail views. Use it for action confirmations such as delete and retry flows.',
+            },
+          ],
+          example: lines([
+            '// ✅ Correct',
+            '<Dialog>',
+            '  <DialogContent>',
+            '    <DialogHeader>',
+            '      <DialogTitle>削除確認</DialogTitle>',
+            '      <DialogDescription>本当に削除しますか？</DialogDescription>',
+            '    </DialogHeader>',
+            '    <DialogFooter>',
+            '      <DialogCancel>キャンセル</DialogCancel>',
+            '      <DialogAction>削除</DialogAction>',
+            '    </DialogFooter>',
+            '  </DialogContent>',
+            '</Dialog>',
+            '',
+            '// ❌ Wrong - フォーム入力に Dialog を使わない',
+            '<Dialog>',
+            '  <DialogContent>',
+            '    <Input />',
+            '    <Select />',
+            '  </DialogContent>',
+            '</Dialog>',
+          ]),
+        },
+      },
+      {
+        file: 'src/components/ui/modal/index.tsx',
+        targetName: 'Modal',
+        section: {
+          bullets: [
+            {
+              ja: '作成/編集フォームや詳細表示など、確認だけではない情報入力・閲覧に使ってください。',
+              en: 'Use Modal for forms and detail views such as create and edit flows, not for simple action confirmation.',
+            },
+          ],
+          example: lines([
+            '// ✅ Correct',
+            '<Modal>',
+            '  <ModalContent size="md">',
+            '    <ModalHeader>',
+            '      <ModalTitle>ユーザー作成</ModalTitle>',
+            '      <ModalClose />',
+            '    </ModalHeader>',
+            '    <ModalBody isSpace>',
+            '      <Input />',
+            '      <Select />',
+            '    </ModalBody>',
+            '    <ModalFooter>',
+            '      <Button>作成</Button>',
+            '    </ModalFooter>',
+            '  </ModalContent>',
+            '</Modal>',
+          ]),
+        },
+      },
+    ],
+  },
+  {
+    id: 'input-trigger',
+    featureSection: lines([
+      '### Input: 組み込みトリガーを使う',
+      '',
+      '```tsx',
+      '// ✅ Correct',
+      '<Input isTrigger triggerIcon="search" triggerAriaLabel="検索" onIconButtonClick={handleSearch} />',
+      '',
+      '// ❌ Wrong - 手動で IconButton を配置しない',
+      '<div className="flex">',
+      '  <Input />',
+      '  <IconButton icon="search" aria-label="検索" />',
+      '</div>',
+      '```',
+    ]),
+    jsdocTargets: [],
+  },
+  {
+    id: 'link-open-in-new',
+    featureSection: lines([
+      '### Link: isOpenInNew を使う',
+      '',
+      '```tsx',
+      '// ✅ Correct - 自動で open_in_new アイコンが表示される',
+      '<Link href="https://example.com" isOpenInNew>外部リンク</Link>',
+      '',
+      '// ❌ Wrong - 手動でアイコンを追加しない',
+      '<Link href="https://example.com">外部リンク <Icon icon="open_in_new" /></Link>',
+      '```',
+    ]),
+    jsdocTargets: [
+      {
+        file: 'src/components/ui/link/index.tsx',
+        targetName: 'Link',
+        section: {
+          bullets: [
+            {
+              ja: '外部リンクアイコンを手動で追加しないでください。`isOpenInNew` prop が自動で `open_in_new` アイコンを表示します。',
+              en: 'Do not manually add external link icons. The `isOpenInNew` prop automatically displays the `open_in_new` icon.',
+            },
+          ],
+          example: lines([
+            '// ✅ Correct',
+            '<Link href="https://example.com" isOpenInNew>外部リンク</Link>',
+            '',
+            '// ❌ Wrong - 手動アイコン',
+            '<Link href="https://example.com">外部リンク <Icon icon="open_in_new" /></Link>',
+          ]),
+        },
+      },
+    ],
+  },
+];
+
+function getCheckRules() {
+  const order = ['dialog-form', 'dialog-button-wrap', 'shadcn-token'];
+
+  return ANTI_PATTERN_GROUPS.filter((group) => group.check)
+    .map((group) => ({
+      id: group.id,
+      ...group.check,
+    }))
+    .sort((left, right) => {
+      const leftIndex = order.indexOf(left.id);
+      const rightIndex = order.indexOf(right.id);
+      const normalizedLeftIndex = leftIndex === -1 ? Number.MAX_SAFE_INTEGER : leftIndex;
+      const normalizedRightIndex = rightIndex === -1 ? Number.MAX_SAFE_INTEGER : rightIndex;
+      return normalizedLeftIndex - normalizedRightIndex;
+    });
+}
+
+function getAllJSDocTargets() {
+  return ANTI_PATTERN_GROUPS.flatMap((group) => group.jsdocTargets);
+}
+
+function renderFeatureSections() {
+  return ANTI_PATTERN_GROUPS.map((group) => group.featureSection).join('\n\n');
+}
+
+export {
+  ANTI_PATTERN_GROUPS,
+  COMMON_INTRO,
+  getAllJSDocTargets,
+  getCheckRules,
+  renderFeatureSections,
+  renderJSDocSection,
+};

package/lib/check.js

@@ -0,0 +1,104 @@
+import fs from 'fs';
+import path from 'path';
+
+import { getCheckRules } from './anti-pattern-rules.js';
+
+const DEFAULT_TARGET = 'src';
+const TEXT_EXTENSIONS = new Set(['.js', '.jsx', '.ts', '.tsx']);
+const RULES = getCheckRules();
+
+function collectFiles(targetPath, files, visited) {
+  if (!fs.existsSync(targetPath)) {
+    throw new Error(`Target path does not exist: ${targetPath}`);
+  }
+
+  const realPath = fs.realpathSync(targetPath);
+  if (visited.has(realPath)) {
+    return;
+  }
+  visited.add(realPath);
+
+  const stat = fs.statSync(realPath);
+
+  if (stat.isFile()) {
+    if (TEXT_EXTENSIONS.has(path.extname(realPath))) {
+      files.add(realPath);
+    }
+    return;
+  }
+
+  if (!stat.isDirectory()) {
+    return;
+  }
+
+  for (const entry of fs.readdirSync(realPath, { withFileTypes: true })) {
+    if (entry.name === 'node_modules' || entry.name === '.git') {
+      continue;
+    }
+
+    collectFiles(path.join(realPath, entry.name), files, visited);
+  }
+}
+
+function getLineNumber(content, index) {
+  return content.slice(0, index).split(/\r?\n/).length;
+}
+
+function formatMatch(match) {
+  return match[0].replace(/\s+/g, ' ').trim().slice(0, 120);
+}
+
+function collectFindings(filePath) {
+  const content = fs.readFileSync(filePath, 'utf8');
+  const findings = [];
+
+  for (const rule of RULES) {
+    for (const match of content.matchAll(rule.pattern)) {
+      findings.push({
+        filePath,
+        id: rule.id,
+        description: rule.description,
+        recommendation: rule.recommendation,
+        line: getLineNumber(content, match.index ?? 0),
+        snippet: formatMatch(match),
+      });
+    }
+  }
+
+  return findings;
+}
+
+export function checkProject(targets = [], options = {}) {
+  const resolvedTargets = targets.length > 0 ? targets : [DEFAULT_TARGET];
+  const files = new Set();
+  const visited = new Set();
+
+  for (const target of resolvedTargets) {
+    collectFiles(path.resolve(process.cwd(), target), files, visited);
+  }
+
+  const findings = [...files].flatMap(collectFindings);
+
+  if (findings.length === 0) {
+    console.log('sparkle-design-cli check: no findings');
+    return false;
+  }
+
+  console.log(`sparkle-design-cli check: ${findings.length} finding(s)\n`);
+
+  for (const finding of findings) {
+    const relativePath = path.relative(process.cwd(), finding.filePath);
+    console.log(`${relativePath}:${finding.line} [${finding.id}] ${finding.description}`);
+    console.log(`  Recommendation: ${finding.recommendation}`);
+    console.log(`  Snippet: ${finding.snippet}`);
+    console.log('');
+  }
+
+  if (options.strict) {
+    console.error('sparkle-design-cli check: failed because --strict was specified');
+  }
+
+  return true;
+}
+
+export { RULES, collectFindings };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sparkle-design-cli",
-  "version": "1.3.8",
+  "version": "1.3.9",
   "description": "Sparkle Design CSS Generator - デザインシステムCSSを設定ファイルから生成するツール",
   "main": "lib/generate-css.js",
   "type": "module",
@@ -13,7 +13,8 @@
     "lint": "eslint bin/ lib/ test/",
     "lint:fix": "eslint bin/ lib/ test/ --fix",
     "format": "prettier --write bin/ lib/ test/ *.md *.json",
-    "format:check": "prettier --check bin/ lib/ test/ *.md *.json"
+    "format:check": "prettier --check bin/ lib/ test/ *.md *.json",
+    "sync:anti-pattern-docs": "node scripts/sync-anti-pattern-docs.mjs"
   },
   "keywords": [
     "css",