Sparkle Design CLI

デザインシステム CSS を設定ファイルから生成する CLI ツールです。

インストール

npm install -g sparkle-design-cli

使用方法

基本的な使用方法

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

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

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

npx sparkle-design-cli

または、グローバルにインストールした場合：

sparkle-design-cli

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

コマンドオプション

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

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

オプション一覧

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

設定ファイル (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実行テスト

# デフォルト設定でテスト
sparkle-design-cli

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

# カスタムパスでテスト
sparkle-design-cli -c test-config.json -o test-output.css

ライセンス

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