Setup sparkle design

Skill: setup-sparkle-design

プロジェクトに sparkle-design を npm パッケージとして導入し、コンポーネントを利用できる状態にするためのスキル。

社内版との違い: 社内版 @goodpatch/sparkle-design-internal を導入する場合は install-sparkle-design スキルを使ってください。こちらは公開版 sparkle-design 用です。

---

<!-- ========== AI アシスタント向け指示（ユーザーにそのまま見せない） ========== -->

AI アシスタントへの指示

実行方針

1. プロジェクト状態を確認する

   • パッケージマネージャを特定（package.json や lockfile から）
   • sparkle.config.json の有無を確認
   • Tailwind エントリ CSS（globals.css / index.css 等）の場所と内容を確認

2. 不足しているステップのみ案内する

   • 既に完了しているステップは省略してよい
   • エラーが出たときはトラブルシューティングセクションを参照

参照ドキュメント

ドキュメント	いつ参照するか
この SKILL.md	導入・基本設定（常に利用可能）
references/config-reference.md	primary/radius の選択肢確認・複数テーマ運用の相談時
references/update-workflow.md	アップデートが求められたとき
references/component-catalog.md	コンポーネント選択の相談時
references/component-selection.md	コンポーネント置き換え・統一の依頼時
references/troubleshooting.md	導入エラー発生時

<!-- ========== ここからユーザーに案内するコンテンツ ========== -->

---

Quick Start（1 コマンド）

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

このコマンド 1 つで以下が全て実行される:

1. パッケージマネージャー検出 -- pnpm / yarn / bun / npm を lockfile から自動判定
2. パッケージインストール -- sparkle-design を dependencies、tailwindcss + @tailwindcss/postcss を devDependencies に追加（既に入っていればスキップ）
3. 初期ファイル生成 -- sparkle.config.json / postcss.config.mjs / Tailwind エントリ CSS（Next.js: globals.css、Vite: index.css）が無ければ作成（既存ファイルは保持）
4. AI ガード設定 -- CLAUDE.md に Sparkle Design Guard ブロックと lint:sparkle スクリプトを追加（既存 AGENTS.md があれば併用書き込み）
5. Stop hook 自動設定 -- --assistant に応じて .claude/settings.json / .cursor/hooks.json / .codex/hooks.json に lint:sparkle --strict || exit 2 の Stop hook を投入。findings があれば応答終了をブロックする
6. 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 に昇格できる。

生成されるファイル

• 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> を upsert
• CLAUDE.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 がルートレイアウト（src/app/layout.tsx や _app.tsx）で import されていることを確認する。

テーマをカスタマイズする

sparkle.config.json を編集した後、再生成する:

npx 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"）。

Step 3: コンポーネントを使う

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

13 種類のアンチパターンを自動検出する。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 アシスタント補足

Anti-pattern ガードの浸透

初回セットアップ時に、利用プロジェクトの CODING-RULES.md や CLAUDE.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

---

Last Updated: 2026-03-31