Skip to content

README.en.md

Latest commit

 

History

History
206 lines (149 loc) · 9.25 KB

README.en.md

File metadata and controls

206 lines (149 loc) · 9.25 KB
Raw

Sparkle Design

Sparkle Design for React

English | 日本語

npm version Sparkle Design ci License: Apache-2.0

This is a component library built with React.js and TypeScript.
It implements Goodpatch's "Sparkle Design" system on top of shadcn/ui.

Features

  • 🔧 Flexibility ... Because it is based on shadcn/ui and compatible with the shadcn/ui registry, you can introduce components one by one. It is also published as an npm package, so you can integrate it in the way that best fits each project.
  • ♿️ Accessibility ... Sparkle Design is engineered with accessibility as a primary consideration.
  • 🎨 Customizability ... A dedicated CLI tool lets you apply the same customizations found in the Figma files. This makes it easy to spin up code for design systems built on Sparkle Design.
  • 🤖 AI Friendly ... Ships with skills and guard configurations for Claude Code, Cursor, and Codex. Maintain design system quality even during AI-assisted coding.

Quick Start

1. Set up

In an existing Next.js / Vite project, a single command completes the integration:

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

This automatically:

  1. Detects your package manager (pnpm / npm / yarn / bun)
  2. Adds sparkle-design to dependencies and tailwindcss + @tailwindcss/postcss to devDependencies
  3. Generates sparkle.config.json / postcss.config.mjs / Tailwind entry CSS (Next.js: globals.css, Vite: index.css) if missing
  4. Writes the Sparkle Design guard block + lint:sparkle script to CLAUDE.md (and to AGENTS.md too when one already exists)
  5. Installs an assistant-specific Stop hook into .claude/settings.json / .cursor/hooks.json / .codex/hooks.json (lint:sparkle --strict || exit 2) so findings block the agent from finishing the turn
  6. Generates sparkle-design.css and SparkleHead.tsx (and for Vite projects, also injects a managed font <link> block into index.html's <head>)

--assistant accepts claude / cursor / codex / generic. Existing files are never overwritten.

Once the setup is complete, place the generated SparkleHead in the <head> of your root layout.

import { SparkleHead } from "./SparkleHead";

export default function RootLayout({ children }) {
  return (
    <html>
      <head>
        <SparkleHead />
      </head>
      <body>{children}</body>
    </html>
  );
}

@next/next/no-head-element in Next.js App Router: If your project extends next/core-web-vitals, placing a <head> element directly in layout.tsx may trigger a lint error. Add // eslint-disable-next-line @next/next/no-head-element to suppress it, or consider using next/font as an alternative.

Customize primary color, fonts, border radius, and more via sparkle.config.json. To tweak settings inside Figma, the Sparkle Design Theme Settings plugin is available. See sparkle-design-cli generate --help for details.

⚠️ Note for TailwindCSS v4 when using sparkle-design as an npm package: TailwindCSS v4 does not automatically scan utility classes inside node_modules. When consuming sparkle-design as an npm package, your entry CSS needs an @source directive like the one below:

@import "tailwindcss";
@source "../../node_modules/sparkle-design/dist";
@import "./sparkle-design.css";

sparkle-design-cli auto-scans your package.json (dependencies / devDependencies) on generate / setup and automatically inserts the matching @source directive when it detects sparkle-design. No manual config is required. If you want to include additional design system packages, add them to extend.source-packages in sparkle.config.json; the detected packages and your explicit list will be merged. When an existing entry CSS lacks @import "tailwindcss"; (e.g. straight from create-vite), the CLI auto-prepends the canonical import before continuing the patch, and the order of @import / @source is normalized to comply with the CSS spec, so both Vite and Next.js layouts reach a fully working state in a single setup run.

Installing as an AI Agent Skill (optional)

If you use an AI agent such as Claude Code, GitHub Copilot, Cursor, Codex, Gemini CLI, or Antigravity, you can install the Sparkle Design skills through the official gh skill command (requires gh CLI v2.90+), which lets the agent guide you through setup.

# Install only the setup-sparkle-design skill (recommended)
gh skill install goodpatch/sparkle-design setup-sparkle-design --agent claude-code

# Interactively pick multiple skills (setup / add-component / accessibility-checker / change-sparkle-config)
gh skill install goodpatch/sparkle-design --agent claude-code

# Inspect a skill before installing
gh skill preview goodpatch/sparkle-design setup-sparkle-design

After installation, asking the agent to "install Sparkle Design" triggers the setup-sparkle-design skill, which inspects the project and guides you through only the missing steps. Use --agent claude-code / --agent github-copilot / --agent cursor / --agent codex / --agent gemini / --agent antigravity to target a specific agent (the default for non-interactive runs is github-copilot).

Fallback if gh CLI is not available: The same skills are also published via Vercel's skills CLI:

npx skills add goodpatch/sparkle-design -s setup-sparkle-design
npx skills add goodpatch/sparkle-design --all

2. Use components

import React from "react";
import { Button, Badge, Card } from "sparkle-design";

function App() {
  return (
    <div>
      <Card>
        <h1>Example using Sparkle Design</h1>
        <Badge variant="primary">New feature</Badge>
        <Button variant="primary" size="md">
          Click the button
        </Button>
      </Card>
    </div>
  );
}

export default App;

Using with Server Components: For components that contain "use client", use subpath imports. Each component's README includes Server Component / Client Component information.

import { Button } from "sparkle-design/button";

3. Update settings and check for anti-patterns

After editing sparkle.config.json, regenerate the CSS:

npx sparkle-design-cli generate

After making Sparkle Design-related code changes, check for anti-patterns:

npx sparkle-design-cli check src

Manual installation (advanced)

If you prefer a step-by-step installation without CLI setup, run npx --yes sparkle-design-cli --help / npx --yes sparkle-design-cli generate --help / npx --yes sparkle-design-cli setup --help to see the usage of each subcommand. See also the sparkle-design-cli page on npm.

Install individual components

Sparkle Design works with the shadcn/ui registry. You can copy the registry URL from Storybook.
Refer to the official documentation for details on the shadcn/ui registry.

pnpm dlx shadcn@latest add [registry URL]

You can also specify namespaces in components.json to install components by name.

{
  "registries": {
    "@sparkle-design": "https://sparkle-design.goodpatch.com/r/{name}.json"
  }
}
pnpm dlx shadcn@latest add @sparkle-design/button

Development Guide

For environment setup, component creation, testing, and contribution guidelines, see CONTRIBUTING.md.

Directory structure

├─ src/
│  ├─ app/            # Sparkle Design pages and style files
│  ├─ components/     # React components
│  └─ lib/            # Shared utilities
├─ scripts/           # Various scripts
├─ docs/
│  └─ ai-instructions/ # Development, testing, and AI guidelines (source)
└─ .github/           # GitHub configuration

Sparkle Design badge

The Sparkle Design badge indicates that a component uses Sparkle Design. Add the following snippet to your README:

[![Sparkle Design](https://img.shields.io/badge/made%20with-Sparkle%20Design-0969DA)](https://sparkle-design.goodpatch.com/)

Component status

Please refer to the table on README.md for the current implementation status of components.

License

Apache License 2.0

Copyright 2026 Goodpatch Inc.