Sparkle Design CLI

デザインシステム CSS の生成と、Sparkle Design のアンチパターン検査を行う CLI ツールです。

インストール

npm install -g sparkle-design-cli

使用方法

サブコマンド

# 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 ファイルを作成または配置します：

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

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

npx sparkle-design-cli generate

既存プロジェクトでサブコマンドなしの呼び出しを使っている場合も、後方互換として次の実行方法を継続利用できます:

npx sparkle-design-cli

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

generate オプション一覧

• -h, --help: ヘルプメッセージを表示
• -c, --config <パス>: 設定ファイルのパス（デフォルト: ./sparkle.config.json）
• -o, --output <パス>: 出力ファイルのパス（デフォルト: ./src/app/sparkle-design.css）

check: アンチパターン検査

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

# 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 内へ持ち込まない

導入先での推奨設定

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

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

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

設定ファイルの作成

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

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

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

設定オプション

• primary: プライマリカラー（blue, red, orange など）
• font-pro: プロポーショナルフォント（Google Fonts の名前）
• font-mono: モノスペースフォント（Google Fonts の名前）
• radius: 角丸設定（sm, md, lg など）
• source-packages: （オプション）@source ディレクティブで追加スキャンする npm パッケージの配列

source-packages オプション

@goodpatch/sparkle-design を npm パッケージとして利用するプロジェクトでは、TailwindCSS v4 がパッケージ内のユーティリティクラスを検出できるように @source ディレクティブが必要です。

source-packages を設定すると、CLI が globals.css に @source ディレクティブを自動挿入します。@goodpatch/sparkle-design は常にデフォルトで含まれます。

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

追加の npm パッケージ（拡張リポジトリなど）をスキャン対象にする場合：

{
  "source-packages": ["@scope/my-extension-design"]
}

生成される globals.css:

@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';

注意: source-packages を指定しない場合、@source ディレクティブは生成されません。

出力

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

自動フォント管理

v1.2.0 以降の新機能

CLI は自動的にフォント管理を行います：

1. フォント検出: sparkle-design.css から Google Fonts の @import 文を検出
2. globals.css への移動: フォントの @import を globals.css の先頭に移動
3. sparkle-design.css から削除: 元のファイルからフォント @import を削除

なぜこの処理が必要なのか？

CSS の仕様では、@import 文は @charset と @layer 以外のすべてのルールより前に記述する必要があります。Tailwind CSS v4 と組み合わせた場合、この順序が正しくないとビルド時に警告が発生します。

この機能により、以下の警告が自動的に解決されます：

⚠️ @import rules must precede all rules aside from @charset and @layer statements

動作条件

• globals.css が sparkle-design.css と同じディレクトリに存在する場合のみ実行されます
• globals.css が存在しない場合は、フォント管理処理はスキップされます

出力例

📦 フォント管理処理を開始します...
📝 3個のフォントimportを検出しました
✅ globals.css にフォントimportを追加しました
✅ sparkle-design.css からフォントimportを削除しました

開発

セットアップ

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

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

開発用コマンド

# テスト実行
npm test

# テスト監視モード
npm run test:watch

# Lint実行
npm run lint

# Lintエラーを自動修正
npm run lint:fix

# コードフォーマット
npm run format

# フォーマットチェック
npm run format:check

CLI実行テスト

# CSS生成
sparkle-design-cli generate

# 既存呼び出しの後方互換モード
sparkle-design-cli

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

# 検査
sparkle-design-cli check src --strict

ライセンス

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