JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 55
  • Score
    100M100P100Q115882F
  • 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 ツールです。

インストール

npm install -g sparkle-design-cli

使用方法

サブコマンド

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

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

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

# Claude / Codex / Cursor 向けの guard 設定を差し込む
npx --yes sparkle-design-cli setup --assistant claude

後方互換モード

既存の 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"
}
  1. CLI ツールを実行します：
npx sparkle-design-cli generate

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

npx sparkle-design-cli
  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 内へ持ち込まない

Manual Review Reminders

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

  • Badge と Tag の意味的な使い分け
  • CardDescription の typography / color token 明示
  • Dialog と Modal の UX 上の使い分け

導入先での推奨設定

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

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

setup: AI ガード設定の差し込み

sparkle-design-cli setup は、導入先プロジェクトの package.json と AI 向け指示ファイルに Sparkle Design guard を追加します。

# 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

# generic な Markdown を生成
npx --yes sparkle-design-cli setup --assistant generic

追加されるもの:

  • package.json の lint:sparkle
  • package.json の lint❇️json
  • assistant ごとの指示ファイルへの managed block

--target を省略した場合は src, src/components, src/features, app, components の順で自動検出します。既存の lint:sparkle* がすでに Sparkle Design 向け script なら再実行時に更新されます。独自 script は保持され、上書きしたい場合だけ --force-script-update を付けます。

利用できる assistant:

  • claude: CLAUDE.md
  • codex: AGENTS.md
  • cursor: .cursor/rules/sparkle-design-guard.mdc
  • generic: SPARKLE-DESIGN-AI.md

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

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

設定ファイルの作成

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

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

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

設定オプション

Core（プラグインが出力）

  • primary: プライマリカラー（blue, red, orange など）
  • font-pro: プロポーショナルフォント（文字列または配列。配列の場合はフォールバックチェーンになる）
  • font-mono: モノスペースフォント（文字列または配列）
  • radius: 角丸設定（sm, md, lg など）

Core Options

  • font-pro-weights: （オプション）プロポーショナルフォントのウェイト配列（デフォルト: [400, 700]）
  • font-mono-weights: （オプション）モノスペースフォントのウェイト配列（デフォルト: [400, 700]）
  • source-packages: （オプション）@source ディレクティブで追加スキャンする npm パッケージの配列

Custom Settings

  • custom-css: （オプション）プロジェクト固有のカスタムトークン CSS ファイルのパス。globals.css に @import が自動挿入される

フォントウェイトとフォールバック

font-pro-weights / font-mono-weights でフォントウェイトをカスタマイズできます。未指定時は [400, 700] がデフォルトです。

font-pro / font-mono に配列を指定すると、フォントフォールバックチェーンとして複数の Google Fonts import が生成されます。

{
  "primary": "blue",
  "font-pro": ["Montserrat", "Noto Sans JP"],
  "font-pro-weights": [400, 500, 600, 700],
  "font-mono": "Roboto Mono",
  "font-mono-weights": [400, 700],
  "radius": "md"
}

生成される CSS:

--font-family-pro: 'Montserrat', 'Noto Sans JP', sans-serif;
@import 'https://fonts.googleapis.com/css2?family=Montserrat:wght@400;500;600;700&display=swap';
@import 'https://fonts.googleapis.com/css2?family=Noto+Sans+JP:wght@400;500;600;700&display=swap';

custom-css オプション

プロジェクト固有のカスタムトークン（Display, Heading, Body 等のタイポグラフィトークン、追加のフォントウェイト、メディアクエリなど）を sparkle-design.css に直接追加するのは避けてください。generate 実行時に上書きされます。

代わりに、カスタムトークンを別の CSS ファイルに定義し、custom-css で指定してください：

{
  "custom-css": "./src/app/custom-tokens.css"
}

CLI が globals.css に @import を自動挿入します。CLI はファイルの中身を一切触りません。

/* globals.css に自動生成される構造 */
/* フォントのインポート */
@import '...google fonts...';
@import "tailwindcss";
/* Sparkle Design のカスタム定義 */
@import "./sparkle-design.css";
/* プロジェクト固有のカスタムトークン */
@import "./custom-tokens.css";

source-packages オプション

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

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

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

注意: 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 ファイルを参照してください。