sparkle-design-cli/README.md

Sparkle Design CSS Generator - デザインシステムCSSを設定ファイルから生成するツール

# Sparkle Design CLI

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

## インストール

```bash
npm install -g sparkle-design-cli
```

## 使用方法

### 基本的な使用方法

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

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

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

```bash
npx sparkle-design-cli
```

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

```bash
sparkle-design-cli
```

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

### コマンドオプション

```bash
# ヘルプを表示
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 など）

## 出力

- デフォルト出力先: `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 と組み合わせた場合、この順序が正しくないとビルド時に警告が発生します。

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

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

### 動作条件

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

### 出力例

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

## 開発

### セットアップ

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

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

### 開発用コマンド

```bash
# テスト実行
npm test

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

# Lint実行
npm run lint

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

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

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

### CLI実行テスト

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

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

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

## ライセンス

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