sparkle-design
v1.0.4
Published
Sparkle DesignのReactコンポーネントライブラリ
Maintainers
goodpatch-sparkleReadme
Sparkle Design for React
English | 日本語
React.js + TypeScript を用いたコンポーネントライブラリです。 shadcn/ui をベースに、グッドパッチのデザインシステム「Sparkle Design」を実装しています。
特徴
- 🔧 柔軟性 ... shadcn/ui をベースに shadcn/ui registry に対応しているため、1コンポーネントから導入が可能です。npm パッケージとしても公開しているため、プロジェクトごとに適した方法で導入していただくことが出来ます。
- ♿️ アクセシビリティ ... Sparkle Design はアクセシビリティを重視して設計されています。
- 🎨 カスタマイズ性 ... 専用CLIツールを利用し、Figmaファイルと同等のカスタマイズを適用することが出来ます。これによりSparkle Designをベースとしたデザインシステムのコードを素早く用意することが出来ます。
- 🤖 AI フレンドリー ... Claude Code / Cursor / Codex 向けのスキルとガード設定を同梱。AI コーディングでもデザインシステムの品質を維持できます。
クイックスタート
1. セットアップ
既存の Next.js / Vite プロジェクトで次の 1 コマンドを実行するだけで導入が完了します。
npx --yes sparkle-design-cli setup --assistant claudeこれで以下が自動で行われます:
- パッケージマネージャー（pnpm / npm / yarn / bun）を自動検出
sparkle-designを dependencies、tailwindcss+@tailwindcss/postcssを devDependencies に追加sparkle.config.json/postcss.config.mjs/ Tailwind エントリ CSS（Next.js:globals.css、Vite:index.css）を必要に応じて生成CLAUDE.md/AGENTS.md（既存があれば併用書き込み）に Sparkle Design ガードブロックとlint:sparkleスクリプトを追加--assistantに応じて.claude/settings.json/.cursor/hooks.json/.codex/hooks.jsonの Stop hook を自動設定（lint:sparkle --strict || exit 2で findings があれば応答終了をブロック）sparkle-design.cssとSparkleHead.tsxを生成（Vite プロジェクトではindex.htmlの<head>内に font<link>の managed block も自動注入）
--assistant は claude / cursor / codex / generic から選択できます。既存ファイルは上書きされません。
セットアップが完了したら、生成された SparkleHead をルートレイアウトの <head> に配置してください。
import { SparkleHead } from "./SparkleHead";
export default function RootLayout({ children }) {
return (
<html>
<head>
<SparkleHead />
</head>
<body>{children}</body>
</html>
);
}Next.js App Router で
@next/next/no-head-elementが出る場合:next/core-web-vitalsを使用しているプロジェクトでは、layout.tsxに<head>を直接書くと lint エラーになることがあります。該当行に// eslint-disable-next-line @next/next/no-head-elementを追加するか、next/fontによる代替方法を検討してください。
sparkle.config.json でプライマリカラー・フォント・角丸などをカスタマイズできます。Figma 上で設定を調整したい場合は Sparkle Design Theme Settings プラグインを利用できます。詳細は sparkle-design-cli generate --help を参照してください。
⚠️ TailwindCSS v4 で npm package として使う場合の注意: TailwindCSS v4 は
node_modules内のユーティリティクラスを自動スキャンしないため、sparkle-designを npm package として使うときはエントリ CSS に以下のような@sourceディレクティブが必要です。@import "tailwindcss"; @source "../../node_modules/sparkle-design/dist"; @import "./sparkle-design.css";
sparkle-design-cliはgenerate/setup実行時にpackage.jsonの dependencies / devDependencies を自動スキャン し、sparkle-designが含まれていれば該当する@sourceを自動挿入します。sparkle.config.json側で何も設定しなくても動きます。独自のデザインシステムパッケージを併用したい場合のみextend.source-packagesに追記すると、自動検出分と合算されます。@import "tailwindcss";が無い既存プロジェクト（create-vite直後など）には canonical な@importを自動 prepend し、@importと@sourceの順序も CSS 仕様に従って整列するため、Vite / Next.js のどちらのレイアウトでもセットアップ 1 回で動く状態に到達できます。
AI エージェントに Skill として導入する場合（任意）
Claude Code / GitHub Copilot / Cursor / Codex / Gemini CLI / Antigravity などの AI エージェントを使っている場合は、GitHub 公式の gh skill コマンド（gh CLI v2.90 以上）経由で Sparkle Design のスキルセットを導入しておくと、会話から誘導してもらえます。
# setup-sparkle-design スキルだけを導入（推奨）
gh skill install goodpatch/sparkle-design setup-sparkle-design --agent claude-code
# 対話モードで複数スキルをまとめて選択（setup / add-component / accessibility-checker / change-sparkle-config）
gh skill install goodpatch/sparkle-design --agent claude-code
# インストール前に内容を検査したい場合
gh skill preview goodpatch/sparkle-design setup-sparkle-design導入後に「Sparkle Design を導入して」と依頼すると setup-sparkle-design スキルが発動し、プロジェクト状態に合わせて不足ステップだけ案内してくれます。--agent には claude-code / github-copilot / cursor / codex / gemini / antigravity などを指定できます（非対話実行のデフォルトは github-copilot）。
gh CLI が手元に無い場合の fallback: Vercel の skills CLI でも同じスキルを配布しています:
npx skills add goodpatch/sparkle-design -s setup-sparkle-design npx skills add goodpatch/sparkle-design --all
2. コンポーネントの使用
import React from "react";
import { Button, Badge, Card } from "sparkle-design";
function App() {
return (
<div>
<Card>
<h1>Sparkle Design を使った例</h1>
<Badge variant="primary">新機能</Badge>
<Button variant="primary" size="md">
ボタンをクリック
</Button>
</Card>
</div>
);
}
export default App;Server Component で使う場合:
"use client"を含むコンポーネントは個別 import を推奨します。各コンポーネントの README に Server Component / Client Component の情報が記載されています。import { Button } from "sparkle-design/button";
3. 設定の更新とアンチパターンの検査
sparkle.config.json を編集した後は以下で CSS を再生成できます。
npx sparkle-design-cli generateSparkle Design に関するコード変更後は、アンチパターンを検出できます。
npx sparkle-design-cli check src手動インストール（高度な利用）
CLI setup を使わずに段階的に導入したい場合は、npx --yes sparkle-design-cli --help / npx --yes sparkle-design-cli generate --help / npx --yes sparkle-design-cli setup --help で各サブコマンドの使い方を確認できます。npm ページは sparkle-design-cli on npm を参照してください。
個別コンポーネントの導入
Sparkle Design は shadcn/ui registry に対応しています。レジストリの URL は Storybook からコピーすることができます。 shadcn/ui registry の詳細な情報は 公式ドキュメント を参照してください。
pnpm dlx shadcn@latest add [registry URL]またNamespacesをcomponents.jsonに指定することで、コンポーネント名でのインストールも可能になります。
{
"registries": {
"@sparkle-design": "https://sparkle-design.goodpatch.com/r/{name}.json"
}
}pnpm dlx shadcn@latest add @sparkle-design/button開発ガイド
開発環境のセットアップ・コンポーネントの作成・テスト・コントリビューション方法は CONTRIBUTING.md を参照してください。
ディレクトリ構成
├─ src/
│ ├─ app/ # Sparkle Designのページとスタイルファイル
│ ├─ components/ # React コンポーネント
│ └─ lib/ # 共有ユーティリティ
├─ scripts/ # 各種スクリプト
├─ docs/
│ └─ ai-instructions/ # 開発・テスト・AI向けガイドライン（ソース）
└─ .github/ # GitHub関連の設定ファイルSparkle Design バッジ
Sparkle Design のバッジは、コンポーネントが Sparkle Design を使用していることを示します。README に次のように追加してください。
[](https://sparkle-design.goodpatch.com/)コンポーネント公開状況
現在公開されているコンポーネントの一覧です。 ✅ 公開中 ❌ 非公開・開発前
| コンポーネント | 実装 | Storybook | レジストリ | Figma Code Connect | A11y チェック | | ----------------- | ---- | --------- | ---------- | ------------------ | ------------- | | Avatar | ❌ | ❌ | ❌ | ❌ | ❌ | | Badge | ✅ | ✅ | ✅ | ✅ | ✅ | | Breadcrumb | ✅ | ✅ | ✅ | ✅ | ✅ | | Button | ✅ | ✅ | ✅ | ✅ | ✅ | | Calendar | ❌ | ❌ | ❌ | ❌ | ❌ | | Card | ✅ | ✅ | ✅ | ✅ | ✅ | | Checkbox | ✅ | ✅ | ✅ | ✅ | ✅ | | Dialog | ✅ | ✅ | ✅ | ✅ | ✅ | | Divider | ✅ | ✅ | ✅ | ✅ | ✅ | | Filter Chip | ❌ | ❌ | ❌ | ❌ | ❌ | | Form | ✅ | ✅ | ✅ | ✅ | ✅ | | Icon | ✅ | ✅ | ✅ | ✅ | ✅ | | Icon Button | ✅ | ✅ | ✅ | ✅ | ✅ | | Image | ❌ | ❌ | ❌ | ❌ | ❌ | | Inline Message | ✅ | ✅ | ✅ | ✅ | ✅ | | Input | ✅ | ✅ | ✅ | ✅ | ✅ | | Input Chip | ❌ | ❌ | ❌ | ❌ | ❌ | | Input Date | ❌ | ❌ | ❌ | ❌ | ❌ | | Input File | ❌ | ❌ | ❌ | ❌ | ❌ | | Input Number | ❌ | ❌ | ❌ | ❌ | ❌ | | Input Password | ✅ | ✅ | ✅ | ✅ | ✅ | | Input Search | ❌ | ❌ | ❌ | ❌ | ❌ | | Input Time | ❌ | ❌ | ❌ | ❌ | ❌ | | Link | ✅ | ✅ | ✅ | ✅ | ✅ | | List | ❌ | ❌ | ❌ | ❌ | ❌ | | Menu | ❌ | ❌ | ❌ | ❌ | ❌ | | Modal | ✅ | ✅ | ✅ | ✅ | ✅ | | Overlay | ✅ | ✅ | ✅ | ✅ | ✅ | | Pagination | ❌ | ❌ | ❌ | ❌ | ❌ | | Popover | ❌ | ❌ | ❌ | ❌ | ❌ | | Radio | ✅ | ✅ | ✅ | ✅ | ✅ | | Segmented Control | ❌ | ❌ | ❌ | ❌ | ❌ | | Select | ✅ | ✅ | ✅ | ✅ | ✅ | | Side Navigation | ❌ | ❌ | ❌ | ❌ | ❌ | | Skeleton | ✅ | ✅ | ✅ | ✅ | ✅ | | Slider | ✅ | ✅ | ✅ | ✅ | ✅ | | Slot | ❌ | ❌ | ❌ | ❌ | ❌ | | Spinner | ✅ | ✅ | ✅ | ✅ | ✅ | | Stack | ❌ | ❌ | ❌ | ❌ | ❌ | | Stepper | ❌ | ❌ | ❌ | ❌ | ❌ | | Switch | ✅ | ✅ | ✅ | ✅ | ✅ | | Table | ❌ | ❌ | ❌ | ❌ | ❌ | | Tabs | ✅ | ✅ | ✅ | ✅ | ✅ | | Tag | ✅ | ✅ | ✅ | ✅ | ✅ | | Textarea | ✅ | ✅ | ✅ | ✅ | ✅ | | Toast | ✅ | ✅ | ✅ | ✅ | ✅ | | Tooltip | ✅ | ✅ | ✅ | ✅ | ✅ | | Vertical Tabs | ❌ | ❌ | ❌ | ❌ | ❌ |
ライセンス
Copyright 2026 Goodpatch Inc.