Skill: setup-sparkle-design
プロジェクトに sparkle-design を npm パッケージとして導入し、コンポーネントを利用できる状態にするためのスキル。
社内版との違い: 社内版 @goodpatch/sparkle-design-internal を導入する場合は install-sparkle-design スキルを使ってください。こちらは公開版 sparkle-design 用です。
<!-- ========== AI アシスタント向け指示（ユーザーにそのまま見せない） ========== -->
AI アシスタントへの指示
実行方針
-
プロジェクト状態を確認する
- パッケージマネージャを特定（
package.json や lockfile から）
sparkle.config.json の有無を確認- Tailwind エントリ CSS（
globals.css / index.css 等）の場所と内容を確認
-
不足しているステップのみ案内する
- 既に完了しているステップは省略してよい
- エラーが出たときはトラブルシューティングセクションを参照
参照ドキュメント
| ドキュメント | いつ参照するか |
|---|
| この SKILL.md | 導入・基本設定（常に利用可能） |
references/config-reference.md | primary/radius の選択肢確認・複数テーマ運用の相談時 |
references/update-workflow.md | アップデートが求められたとき |
references/component-catalog.md | コンポーネント選択の相談時 |
references/component-selection.md | コンポーネント置き換え・統一の依頼時 |
references/troubleshooting.md | 導入エラー発生時 |
<!-- ========== ここからユーザーに案内するコンテンツ ========== -->
バージョンの選び方
| プロジェクトの React | 使うバージョン | インストール |
|---|
| 19 | 2.x（現行。現在は beta で、latest はまだ 1.x） | npm install sparkle-design@beta（CLI も npx --yes sparkle-design-cli@beta） |
| 18 | 1.x（非推奨のメンテナンスライン） | npm install sparkle-design@1 |
2.x は ref を通常の props として受け取る React 19 の方式のため、React 18 では ref や Radix の asChild 経由の組み合わせが正しく動かない（npm では peer 依存の衝突で止まる）。詳細は README の「バージョンと React・CLI の対応」を参照。
Quick Start（1 コマンド）
npx --yes sparkle-design-cli setup --assistant claude
2.x（React 19）を beta で使う間は、この SKILL.md に出てくる sparkle-design-cli をすべて sparkle-design-cli@beta に読み替える（setup / generate / check とも）。タグなしは 1.x 向けの安定版 CLI を解決し、2.x と噛み合わないトークンを生成する。
このコマンド 1 つで以下が全て実行される:
- パッケージマネージャー検出 -- pnpm / yarn / bun / npm を lockfile から自動判定
- パッケージインストール --
sparkle-design を dependencies、tailwindcss + @tailwindcss/postcss を devDependencies に追加（既に入っていればスキップ）
- 初期ファイル生成 --
sparkle.config.json / postcss.config.mjs / Tailwind エントリ CSS（Next.js: globals.css、Vite: index.css）が無ければ作成（既存ファイルは保持）
- AI ガード設定 --
CLAUDE.md に Sparkle Design Guard ブロックと lint:sparkle スクリプトを追加（既存 AGENTS.md があれば併用書き込み）
- Stop hook 自動設定 --
--assistant に応じて .claude/settings.json / .cursor/hooks.json / .codex/hooks.json に lint:sparkle --strict || exit 2 の Stop hook を投入。findings があれば応答終了をブロックする
generate 実行 -- sparkle-design.css と SparkleHead.tsx を生成（Vite プロジェクトは index.html の <head> に font <link> の managed block も自動注入）
--assistant は claude / cursor / codex / generic から選択可能。部分的に実行したい場合は --skip-install / --skip-scaffold / --skip-generate を使う。CI では --strict を付けて silent failure を exit 1 に昇格できる。
実行前後の確認
- 実行前に
--dry-run を付けて変更予定を確認する（既存プロジェクトでは特に）
- 実行後に
git status --short で新規作成されたファイル（sparkle.config.json・生成 CSS など）を、git diff で既存ファイル（package.json・CLAUDE.md・.claude/settings.json など）の変更を確認し、ユーザーに要約して伝える
lint:sparkle を 1 回実行し、通ることを確かめる
生成されるファイル
sparkle.config.json -- デザインテーマ設定（初期値: blue / BIZ UDPGothic / BIZ UDGothic / md）postcss.config.mjs -- PostCSS 設定（@tailwindcss/postcss プラグインを有効化）src/app/globals.css / src/globals.css / src/index.css -- Tailwind エントリ CSS（プロジェクト構成から自動判定。@import "tailwindcss"; 不在時は canonical な import を自動 prepend）src/app/sparkle-design.css -- デザイントークン（プリミティブ :root + セマンティック :root + @theme inline）src/app/SparkleHead.tsx -- フォント読み込み用 React コンポーネント（Next.js 等のレイアウト用）index.html（Vite のみ） -- <head> 内に <!-- sparkle-design-cli:fonts:start --> ... end --> の managed block で font <link> を upsertCLAUDE.md / AGENTS.md（後者は既存があるときのみ） -- AI ガードブロック（<!-- sparkle-design-cli:setup:start --> で囲まれた部分）.claude/settings.json / .cursor/hooks.json / .codex/hooks.json -- assistant 別の Stop hook（--assistant claude / cursor / codex 時にそれぞれ生成）
SparkleHead の配置
生成された SparkleHead をルートレイアウトの <head> 内に配置する:
import { SparkleHead } from "./SparkleHead";
export default function RootLayout({ children }) {
return (
<html>
<head>
<SparkleHead />
</head>
<body>{children}</body>
</html>
);
}
TailwindCSS v4 との互換性: CLI が Tailwind エントリ CSS に @source ディレクティブを自動挿入するため、TailwindCSS v4 でも node_modules 内のクラスが正しく検出されます。追加パッケージがある場合は extend.source-packages 配列に追加してください。
Tailwind エントリ CSS がアプリのエントリで import されていることを確認する（Next.js: src/app/layout.tsx や _app.tsx、Vite: src/main.tsx 等）。
初期導入時にテーマを決める
初期導入の流れの中で sparkle.config.json を編集した場合は、再生成する。導入済みプロジェクトでテーマを変える場合は change-sparkle-config スキルを使う。
npx --yes sparkle-design-cli generate
拡張設定（extend）
フォントのウェイト個別指定やカスタム CSS トークンの読み込みが可能。
{
"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": [],
"custom-css": "./src/app/custom-tokens.css"
}
}
| フィールド | 説明 |
|---|
extend.fonts.pro / extend.fonts.mono | フォントファミリーごとにウェイトを指定。font-pro / font-mono より優先 |
extend.source-packages | @source で追加スキャンする npm パッケージ名の配列 |
extend.custom-css | プロジェクト固有のカスタムトークン CSS ファイルパス |
extend にはファイルパスも指定可能（例: "extend": "./sparkle.extend.json"）。
コンポーネントを使う
import { Button, Card, Input } from "sparkle-design";
export function MyPage() {
return (
<Card>
<Input placeholder="名前を入力" />
<Button>送信</Button>
</Card>
);
}
どのコンポーネントを使うか迷ったら references/component-catalog.md を参照。
sparkle.config.json リファレンス
primary / radius の選択肢一覧・必須および型検証の挙動・複数テーマ運用したい場合の案内は references/config-reference.md を参照。
設定ファイルは Sparkle Design Theme Settings Figma プラグインからも書き出せる。
部分的な setup 実行
フルセットアップではなく特定のステップだけ実行したい場合:
# 既存プロジェクトに AI ガードだけ追加する（パッケージ導入・ファイル生成・generate をスキップ）
npx --yes sparkle-design-cli setup --assistant claude --skip-install --skip-scaffold --skip-generate
# パッケージは別途インストール済みで、scaffold と generate だけやりたい
npx --yes sparkle-design-cli setup --assistant claude --skip-install
# Cursor の rules ファイルだけ追加
npx --yes sparkle-design-cli setup --assistant cursor --skip-install --skip-scaffold --skip-generate
--dry-run で変更内容のプレビュー、--target <path> で lint 対象ディレクトリの明示指定が可能。
アンチパターン検査
# テキスト出力
npx --yes sparkle-design-cli check src
# 厳格モード（違反があれば exit 1、CI 向け）
npx --yes sparkle-design-cli check src --strict
# JSON 出力（AI 連携向け、manualReviewReminders も含む）
npx --yes sparkle-design-cli check src --format json
検出ルールの一覧は CLI の help で確認する（件数やルール名をここに書き写さない）。lint:sparkle があるプロジェクトでは、個別ルールを毎回列挙するより先にコマンドを回す。
トラブルシューティング
| エラー | 原因 | 対処 |
|---|
| CSS が反映されない | globals.css が import されていない | ルートレイアウトで import "./globals.css" を確認 |
| CSS 再生成でデザインが崩れる | sparkle-design.css にカスタムトークンを直接追加していた | カスタムトークンは別ファイルに移動し、sparkle.config.json の extend.custom-css で指定する |
| フォントウェイトが足りない | デフォルトでは [400, 700] のみ | sparkle.config.json の extend.fonts でフォントごとにウェイトを指定する |
createContext is not a function | barrel export で client boundary が崩れる | "use client" 付きの re-export file を作る（references/troubleshooting.md 参照） |
詳細は references/troubleshooting.md を参照。
<!-- ========== AI アシスタント向け補足（ユーザーにそのまま見せない） ========== -->
AI アシスタント補足
AI ガード（Sparkle Design Guard）の浸透
setup を使った場合は、CLI が CLAUDE.md（既存の AGENTS.md があれば併記）に Guard ブロックを自動で入れるので、手動の追記は不要。setup を使わずに導入した場合に限り、同じ規則で CLAUDE.md（既存の AGENTS.md があれば併記）へ最低限以下を追記する:
## Sparkle Design Guard
- Sparkle Design を触った PR では `lint:sparkle` を実行する
- `lint:sparkle` が未設定なら `npx --yes sparkle-design-cli check src --strict` を script 化する。AI が直接確認する場合は `npx --yes sparkle-design-cli check src --format json` を優先する
- 機械検出できない使い分けは Sparkle Design の docs / JSDoc を参照する
個別ルールの説明を毎回複製するより、まず lint:sparkle を回す。Badge/Tag の意味的な使い分けや CardDescription の typography など、機械検出できないものだけ docs で補う。
Progressive Disclosure
Load references as needed:
- Always available: This SKILL.md (core workflow)
- Load on error:
references/troubleshooting.md
- Load for component selection:
references/component-catalog.md, references/component-selection.md
- Load for update:
references/update-workflow.md
- Load for config field details / multi-theme setups:
references/config-reference.md