Sparkle Design CLI

Sparkle Design のプロジェクト初期セットアップ、CSS 生成、導入先プロジェクト向けのアンチパターン検査、AI エージェント向け guard 設定を行う CLI ツールです。

クイックスタート

既存の Next.js / Vite プロジェクトで以下を実行するだけで導入完了します。詳細は setup セクション を参照してください。

npx --yes sparkle-design-cli setup --assistant claude

--assistant は claude / cursor / codex / generic から選べます。既存ファイルは上書きされません。

インストール

npm install -g sparkle-design-cli

npx --yes sparkle-design-cli ... で都度実行する運用を推奨します（常に最新版が利用されます）。

リリースチャネル

npm の dist-tag でチャネルを分けています。通常は latest を使い、RC や beta は先行試用時のみ指定してください。

| チャネル | dist-tag | バージョン形式 | 用途 | | ----------------- | -------- | -------------- | --------------------------- | | 安定版 | latest | X.Y.Z | 本番運用向け（デフォルト） | | Release Candidate | next | X.Y.Z-rc.N | GA 直前の検証、チーム展開前 | | Beta | beta | X.Y.Z-beta.N | 品質保証中の検証用 |

# latest を使う（デフォルト）
npx --yes sparkle-design-cli setup --assistant claude

# RC を使う
npx --yes sparkle-design-cli@next setup --assistant claude

# beta を使う
npx --yes sparkle-design-cli@beta setup --assistant claude

使用方法

サブコマンド

# プロジェクト全体を一気にセットアップ（推奨・新規導入時）
npx --yes sparkle-design-cli setup --assistant claude

# CSS を生成
npx sparkle-design-cli generate

# アンチパターンを検査
npx sparkle-design-cli check src --strict

# AI 向けに JSON で検査結果と手動確認項目を取得
npx sparkle-design-cli check src --format json

generate: 基本的な使用方法

1. プロジェクトのルートディレクトリに sparkle.config.json ファイルを作成または配置します：

{
  "primary": "blue",
  "font-mono": "BIZ UDGothic",
  "font-pro": "BIZ UDPGothic",
  "radius": "md"
}

2. CLI ツールを実行します：

npx sparkle-design-cli generate

3. src/app/sparkle-design.css に CSS ファイルが生成されます。

generate: コマンドオプション

# ヘルプを表示
sparkle-design-cli generate --help

# カスタム設定ファイルを指定
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

# Tailwind エントリ CSS を明示指定
sparkle-design-cli generate --globals-path src/styles/app.css

# CI 向け: @source 注入や Tailwind import 欠落などの失敗を exit 1 にする
sparkle-design-cli generate --strict

generate オプション一覧

• -h, --help: ヘルプメッセージを表示
• -c, --config <パス>: 設定ファイルのパス（デフォルト: ./sparkle.config.json）
• -o, --output <パス>: 出力ファイルのパス（デフォルト: ./src/app/sparkle-design.css）
• --globals-path <パス>: Tailwind エントリポイント CSS のパス（デフォルト: 自動検出）。 指定したパスが存在しない場合は --strict の有無に関わらず常に exit 1（sparkle.config.json の extend.globals-path も同様）
• --strict: 以下を warn ではなく exit 1 に昇格させる（CI 向け。既定は warn + 継続で後方互換を維持）:
  • デザインシステムパッケージが package.json に入っているのに Tailwind エントリ CSS が見つからない
  • エントリ CSS はあるが @import "tailwindcss"; が書かれていない（警告メッセージに追記すべき行まで actionable に表示）
  • エントリ CSS への書き込みに失敗した

check: アンチパターン検査

sparkle-design-cli check は、導入先プロジェクトで発生しやすい Sparkle Design のアンチパターンを検出します。

# src を検査
sparkle-design-cli check

# 特定ディレクトリを strict モードで検査
sparkle-design-cli check src/components src/features --strict

# AI 向けに JSON 出力
sparkle-design-cli check src --format json

# check のヘルプを表示
sparkle-design-cli check --help

check オプション一覧

• -h, --help: ヘルプメッセージを表示
• --strict: 違反が見つかった場合に exit code 1 で終了
• --format <text|json>: 出力形式。AI 連携では json を推奨

現在検出するルール

• フォーム入力に Dialog を使わない
• DialogCancel/DialogAction を Button で二重ラップしない
• children なしの Button に prefixIcon / suffixIcon を使わない
• Material Symbols を className 直書きで使わない
• shadcn/ui 既定 token を Sparkle Design 内へ持ち込まない
• Tailwind デフォルト typography を Sparkle Design コンポーネント内で使わない
• CardTitle に typography 系クラスを付与しない
• CardControl に Button / IconButton 以外を入れない
• Card 系コンポーネントのデフォルト padding を安易に上書きしない
• asChild 使用時に prefixIcon / suffixIcon / isLoading を使わない
• Sparkle Design コンポーネントでは isDisabled を使う
• Button の prefixIcon / suffixIcon に JSX を渡さない
• Icon の children にテキストを渡さない
• クリック可能な Card は ClickableCard を使う（button / a / role="button" でラップしない）

導入先での推奨設定

{
  "scripts": {
    "lint:sparkle": "npx --yes sparkle-design-cli check src --strict"
  }
}

AI エージェントや CI からこの lint:sparkle を呼ぶ運用にすると、ガイドラインの注意書きだけに頼らず機械的に検査できます。

アンチパターン検知の拡張（プラグイン）

他のコンポーネントライブラリ（社内拡張など）に固有のアンチパターン検知を、sparkle-design-cli 本体に変更を加えず追加できる拡張機構があります。

仕組み

プラグインを提供するパッケージは、自身の package.json に検知ルールのエントリを宣言します:

{
  "name": "@your-org/your-design-extensions",
  "sparkleCli": {
    "antiPatterns": "./anti-patterns/index.js"
  }
}

エントリファイルは defineAntiPatternPlugin を使ってプラグインを default export します:

import { defineAntiPatternPlugin } from 'sparkle-design-cli/plugin';

export default defineAntiPatternPlugin({
  groups: [
    {
      id: 'your-org-foocard-nesting',
      check: {
        description: 'FooCard を別の FooCard でラップしないでください。',
        recommendation: '入れ子表示が必要なら FooStack を使ってください。',
        pattern: /<FooCard[^>]*>[\s\S]*?<FooCard/g,
      },
    },
  ],
  manualReviewReminders: [
    {
      id: 'your-org-foocard-color',
      message: 'FooCard の color token が brand に揃っているか確認してください。',
    },
  ],
});

複雑な検出（match とヘルパー）

単純な正規表現では安全に書けない検出（accessible name の有無、prop の組み合わせ、JSX 式を意識した走査など）には、check.pattern の代わりに check.match を使います。match は (content, helpers) で呼ばれ、第 2 引数の helpers に JSX パースヘルパーが CLI から注入 されます。各パッケージがパース処理を再実装して同じ false-positive / negative を踏むのを防ぐ仕組みです。

// sparkle-design-cli を import しない（plain object を default export）
export default {
  groups: [
    {
      id: 'your-org-avatar-accessible-name',
      check: {
        description: 'Avatar に accessible name がありません。',
        recommendation: 'aria-label か alt を指定してください。',
        // helpers = { matchOpeningTags, hasProp, isMultipleTypeProp, findOpeningTagEnd }
        match: (content, { matchOpeningTags, hasProp }) =>
          matchOpeningTags(
            content,
            'Avatar',
            (props) =>
              !hasProp(props, 'src') &&
              !hasProp(props, 'aria-label') &&
              !hasProp(props, 'aria-labelledby')
          ),
      },
    },
  ],
};

注入されるヘルパー（check.match の第 2 引数）:

| ヘルパー | 用途 | | ----------------------------------------------- | ------------------------------------------------------------------------------------ | | matchOpeningTags(content, tagName, predicate) | <Tag ...> / <Tag ... /> を走査し predicate が真のものを { index, text } で返す | | hasProp(propsBlock, propName) | prop が指定されているかを厳密判定（aria-* / data-* を誤検出しない） | | isMultipleTypeProp(propsBlock) | type が静的に "multiple" か判定（動的式は false） | | findOpeningTagEnd(content, startIdx) | 低レベル: 開きタグの閉じ > のオフセット（文字列 / JSX 式を考慮）。無ければ -1 |

💡 match を使うプラグインは（上の pattern 例の defineAntiPatternPlugin import と違い）sparkle-design-cli を import せず plain object として default export してください。helpers はランタイムで CLI が注入するため import は不要で、生 JS のまま配布され npx 経由で実行される consumer 環境でも確実に解決されます。pattern と match は排他で、どちらか一方のみ指定します。

自動 discovery

sparkle-design-cli check 実行時、CLI は consumer プロジェクトの package.json の dependencies / devDependencies / peerDependencies / optionalDependencies を走査し、sparkleCli.antiPatterns を宣言しているパッケージを発見次第ロードしてビルトインのルールにマージします。

• プラグインパッケージが install されていなければ何も起きません
• ロードや評価で失敗したプラグインは warn を出してスキップし、残りのルールで check は継続されます
• ルール ID はビルトイン・他プラグインと名前空間を共有するため、your-org- のようなプレフィックスを付けて衝突を避けてください

⚠️ 信頼境界: プラグインのエントリファイルは import() で 任意の JavaScript を実行 します。これは Node.js の通常のパッケージ依存と同じ性質ですが、sparkle-design-cli check 実行時に走るコードが増えるという点で意識しておく必要があります。プラグインは信頼できる org / 著者のパッケージのみインストールしてください。

契約仕様の確認

最新の契約仕様は CLI から直接出力できます:

# 契約 shape のドキュメントを出力
npx --yes sparkle-design-cli plugin-spec

# 現在のプロジェクトで discover されたプラグインを一覧
npx --yes sparkle-design-cli plugin-spec --list

完全な型定義は node_modules/sparkle-design-cli/lib/plugin-api.js の JSDoc を参照してください。

setup: プロジェクトのフルセットアップ

sparkle-design-cli setup は、Sparkle Design の導入に必要な作業をまとめて行います：

1. パッケージマネージャーの検出（pnpm / yarn / bun / npm）
2. パッケージのインストール — sparkle-design（dependencies）、tailwindcss + @tailwindcss/postcss（devDependencies）
3. 初期ファイルの生成 — sparkle.config.json / postcss.config.mjs / Tailwind エントリ CSS（Next.js は src/app/globals.css、Vite は src/index.css）が無い場合のみ作成
4. AI ガード設定 — CLAUDE.md などに Sparkle Design Guard ブロックと lint:sparkle script を追加
5. generate の実行 — sparkle-design.css と SparkleHead.tsx を生成

# Claude Code 向けフルセットアップ
npx --yes sparkle-design-cli setup --assistant claude

# Codex / AGENTS.md 向け
npx --yes sparkle-design-cli setup --assistant codex

# Cursor rules 向け
npx --yes sparkle-design-cli setup --assistant cursor

# AI ガードだけ追加したい場合（パッケージインストール・scaffold・generate をスキップ）
npx --yes sparkle-design-cli setup --assistant claude --skip-install --skip-scaffold --skip-generate

既存ファイルは上書きされません:

• sparkle.config.json / postcss.config.* / Tailwind エントリ CSS が存在する場合はそのまま保持
• 既に依存関係に入っているパッケージはインストールをスキップ
• package.json の既存の lint:sparkle* 独自 script は保持（--force-script-update で上書き）

--target を省略した場合、lint 対象は src, src/components, src/features, app, components の順で自動検出されます。

利用できる assistant:

• claude: CLAUDE.md
• codex: AGENTS.md
• cursor: AGENTS.md（rc.4 から .cursor/rules/*.mdc を廃止。Cursor は AGENTS.md を always-load するため、条件付き読み込みで Guard が silent に skip される問題を解消）
• generic: SPARKLE-DESIGN-AI.md

setup オプション一覧

• --assistant <name>: claude / codex / cursor / generic (default: generic)
• --target <path>: lint 対象パス (default: auto-detect)
• --instructions-path <path>: AI 指示ファイルの出力先パス (default: アシスタント別のデフォルト)
• --skip-install: パッケージインストールをスキップ
• --skip-scaffold: 初期ファイル生成をスキップ
• --skip-generate: generate 実行をスキップ
• --dry-run: ファイルを変更せず結果だけ表示
• --force-script-update: 既存の lint:sparkle 系 script も上書き
• --strict: generate ステージの失敗を exit 1 に昇格（CI 向け）。 現状は generate の失敗のみ対象（install / scaffold / guard の失敗は従来どおり warn）。 --skip-generate / --dry-run と併用した場合は strict チェック対象が無くなるため警告を出します。

setup は通常実行時も JSON サマリーを stdout に表示します。--dry-run を付けると、その JSON を表示したままファイル変更だけを抑止します。

手動セットアップ（Next.js / Vite 以外のプロジェクト向け）

setup コマンドは Next.js App Router と Vite を前提に scaffold / entry CSS の配置を自動判定します。Remix / Astro / TanStack Start など他のフレームワークや、独自ディレクトリ構成のプロジェクトでは自動判定が外れるため、以下の手順で手動セットアップすることを推奨します。

手順

1. パッケージをインストール

# 本体
pnpm add sparkle-design        # or npm install / yarn add / bun add

# Tailwind v4
pnpm add -D tailwindcss @tailwindcss/postcss

2. sparkle.config.json をプロジェクトルートに作成

{
  "primary": "blue",
  "font-pro": "Inter",
  "font-mono": "JetBrains Mono",
  "radius": "md"
}

選択肢の詳細は本 README の「設定オプション」を参照してください。

3. postcss.config.mjs をプロジェクトルートに作成

export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
};

4. Tailwind エントリ CSS を自前で用意

既存プロジェクトに組み込む場合、@import "tailwindcss"; を含む CSS ファイル（例: src/styles/app.css）があればそれを使います。無ければ作成してアプリケーションのエントリから import します。

5. generate を実行

npx --yes sparkle-design-cli generate

これで sparkle-design.css が src/app/sparkle-design.css に生成され、SparkleHead.tsx も同じ場所に出ます。エントリ CSS の検出に失敗する場合は sparkle.config.json の extend.globals-path に明示指定してください。

{
  "primary": "blue",
  "extend": {
    "globals-path": "src/styles/app.css"
  }
}

6. フォントの <link> タグを手動で配置

Next.js / Vite 以外ではアプリケーションフレームワークごとに「<head> 相当」の配置方法が異なります。自動生成される SparkleHead.tsx はそのまま使えるはずですが、使えない場合は中身（preconnect + Google Fonts の <link> タグ群）を自前のレイアウトにコピーしてください。

たとえば Astro なら src/layouts/BaseLayout.astro の <head> に直接書きます:

<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link
  rel="stylesheet"
  href="https://fonts.googleapis.com/css2?family=Material+Symbols+Rounded:FILL,[email protected],500&display=block"
/>
<!-- sparkle.config.json の font-pro / font-mono に合わせた Google Fonts URL -->
<link
  rel="stylesheet"
  href="https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap"
/>
<link
  rel="stylesheet"
  href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;700&display=swap"
/>

7. アンチパターン検査を package.json に追加（任意）

{
  "scripts": {
    "lint:sparkle": "npx --yes sparkle-design-cli check src --strict",
    "lint:sparkle:json": "npx --yes sparkle-design-cli check src --format json"
  }
}

8. AI エージェントを使うなら Guard ブロックと hook を手動で配置

AI ガード（CLAUDE.md / AGENTS.md）と hook 設定（.claude/settings.json / .cursor/hooks.json / .codex/hooks.json）は setup に任せるのが最も楽です。Cursor 用 Guard は rc.4 から AGENTS.md に統一しました（.cursor/rules/*.mdc は条件付き読み込みのため）。

# ガード追加・hook 設定のみ（パッケージインストールや scaffold はスキップ）
npx --yes sparkle-design-cli setup --assistant claude --skip-install --skip-scaffold --skip-generate

この --skip-* 組み合わせは手動セットアップ済みのプロジェクトに対して Guard + hook だけ差し込むのに使えます。

既知の未対応ケース

• モノレポ（workspaces）: generate は実行した cwd からパッケージマネージャーを遡及検出しないため、サブパッケージで直接実行するのが確実です。
• CSS 以外のエントリ（CSS-in-JS / vanilla-extract 等）: Sparkle Design は Tailwind v4 の @source + CSS variable 前提で作られているため、ビルドパイプラインの外で CSS を扱うソリューションは対象外です。
• Tailwind v3: @source ディレクティブ依存のため v4 必須です。

Next.js / Vite 以外で導入したい方で困ったときは Issue で教えていただけると助かります。

設定ファイル (sparkle.config.json)

設定ファイルの作成

設定ファイルは専用のプラグインから自動生成することを推奨します。プラグインを使用すると、デザインシステムに基づいた適切な設定が自動で生成されます。

設定ファイルは以下の場所に配置してください：

• プロジェクトのルートディレクトリ（推奨）
• または -c オプションで指定した任意の場所

設定オプション

Core（プラグインが出力）

• primary: プライマリカラー（blue, red, orange など）
• font-pro: プロポーショナルフォント（Google Fonts の名前）
• font-mono: モノスペースフォント（Google Fonts の名前）
• radius: 角丸設定（sm, md, lg など）

extend セクション（拡張設定）

Figma プラグインが出力する基本4項目に加えて、プロジェクト固有の拡張を extend セクションにまとめます。extend はオブジェクト直書き（推奨）またはファイルパスを指定できます。

{
  "primary": "blue",
  "font-pro": "Montserrat",
  "font-mono": "Roboto Mono",
  "radius": "md",
  "extend": {
    "fonts": {
      "pro": [
        { "family": "Montserrat", "weights": [500, 600, 700] },
        { "family": "Noto Sans JP", "weights": [400, 500, 600, 700] }
      ],
      "mono": [{ "family": "Roboto Mono", "weights": [400, 700] }]
    },
    "source-packages": ["@goodpatch/sparkle-design-internal"],
    "custom-css": "./src/app/custom-tokens.css"
  }
}

ファイル参照も可能です：

{
  "primary": "blue",
  "font-pro": "Montserrat",
  "font-mono": "Roboto Mono",
  "radius": "md",
  "extend": "./sparkle.extend.json"
}

extend.fonts

フォントごとにウェイトを個別指定。extend.fonts がない場合は font-pro / font-mono + デフォルトウェイト [400, 700] が使われます。extend.fonts が存在しても fonts.pro / fonts.mono のどちらかが未指定なら、そのスロットのみ font-pro / font-mono にフォールバックします。同じフォントファミリーが pro と mono で重複する場合、ウェイトはマージされ import は 1 行に統合されます。

extend.source-packages

sparkle-design を npm パッケージとして利用する場合に必須。Tailwind エントリ CSS（自動検出）に @source ディレクティブを自動挿入します。sparkle-design は常にデフォルトで含まれます。

extend.custom-css

プロジェクト固有のカスタムトークンの CSS ファイルパス。Tailwind エントリ CSS に @import が自動挿入されます。sparkle-design.css に直接追加すると generate 実行時に上書きされるため、必ず別ファイルに分離してください。

出力

• デフォルト出力先: src/app/sparkle-design.css
• カスタム出力先: -o オプションで指定可能
• 実行場所を基準として相対パスで処理されます

フォントと entry CSS の自動管理

CLI は Tailwind エントリ CSS（@import "tailwindcss" を含む CSS ファイル） を自動検出し、以下を 1 回で揃えます:

• sparkle-design.css の @import
• @source "../node_modules/sparkle-design/dist"（v4 が node_modules のクラスを拾うのに必要）
• フォント <link> タグ（React 向けは SparkleHead.tsx、Vite 向けは index.html の managed block に自動注入）

CSS 仕様上 @import は他の at-rule より前に書く必要があるため、順序も適切に整えます。@import "tailwindcss" が欠けている場合は先頭に自動追記されます。

開発

セットアップ

# 依存関係をインストール
npm install

# パッケージをローカルでリンク
npm link

開発用コマンド

npm test              # Node.js test runner
npm run lint          # ESLint
npm run format        # Prettier

リリース手順（メンテナ向け）

publish は GitHub Actions の Publish to npm workflow 経由。ローカル npm publish は禁止。

1. package.json の version を更新（安定版: X.Y.Z / RC: X.Y.Z-rc.N / Beta: X.Y.Z-beta.N）
2. CHANGELOG.md に該当セクションを追加
3. PR をマージ後、Publish to npm workflow を channel: auto で実行

channel: auto は package.json の version 形式から dist-tag を自動判定します（-beta.N → beta / -rc.N → next / それ以外 → latest）。既存 RC / Beta を latest に昇格させる場合は、新しい X.Y.Z として改めて publish します（npm dist-tag add での手動付け替えも可能ですが、version 管理が明確になる前者を推奨）。

ライセンス

MIT License - 詳細は LICENSE ファイルを参照してください。