JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 55
  • Score
    100M100P100Q115894F
  • License MIT

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

Package Exports

  • sparkle-design-cli
  • sparkle-design-cli/lib/generate-css.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (sparkle-design-cli) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Sparkle Design CLI

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

クイックスタート

既存の Next.js / Vite プロジェクトに Sparkle Design を導入する場合、以下 1 コマンドで完了します：

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

setup は次を自動で行います:

  1. パッケージマネージャー（pnpm / npm / yarn / bun）を自動検出
  2. sparkle-design を dependencies、tailwindcss + @tailwindcss/postcss を devDependencies に追加
  3. 未作成の場合のみ初期ファイルを生成:
    • sparkle.config.json（デフォルトは blue / Inter / JetBrains Mono / md）
    • postcss.config.mjs
    • src/app/globals.css（または src/globals.css）
  4. AI 指示ファイル（CLAUDE.md / AGENTS.md / Cursor rules）に Sparkle Design Guard ブロックを追加
  5. sparkle-design-cli generate を実行し、sparkle-design.css と SparkleHead.tsx を生成

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

インストール

npm install -g sparkle-design-cli

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

使用方法

サブコマンド

# プロジェクト全体を一気にセットアップ（推奨・新規導入時）
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"
}
  1. CLI ツールを実行します：
npx sparkle-design-cli generate
  1. 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

# 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（text-sm, font-medium 等）を使わない
  • CardTitle に typography を上書きしない
  • CardControl に Button / IconButton 以外を入れない
  • CardHeader / CardContent の padding を上書きしない
  • asChild と prefixIcon / suffixIcon / isLoading を併用しない
  • disabled を isDisabled の代わりに使わない
  • Button の prefixIcon に JSX を渡さない
  • Icon の children にテキストを渡さない

Manual Review Reminders

--format json では、機械検出できない観点も manualReviewReminders として返します。現在は次を含みます。

  • Badge と Tag の意味的な使い分け
  • CardDescription の typography / color token 明示
  • Dialog と Modal の UX 上の使い分け
  • 手書き span が Tag で置き換え可能か

導入先での推奨設定

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

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

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 / globals.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.* / globals.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: .cursor/rules/sparkle-design-guard.mdc
  • 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 も上書き

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

設定ファイル (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 パッケージとして利用する場合に必須。globals.css に @source ディレクティブを自動挿入します。sparkle-design は常にデフォルトで含まれます。

extend.custom-css

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

出力

  • デフォルト出力先: 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 --help
sparkle-design-cli generate --help

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

ライセンス

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