sparkdesign

Spark Design 按需引入 CLI：将组件源码复制到当前项目，支持在项目内自由修改。

当前版本：0.1.6 · 设计系统主包：sparkdesign

快速开始

步骤 1：添加组件

在项目根目录执行：

npx sparkdesign add button

添加多个组件时在命令后追加组件名，例如：npx sparkdesign add button tooltip dropdown-menu。

输出目录由 components.json 的 aliases.ui 决定（默认 @/components/ui → src/components/ui/）。执行 add 时会在终端打印当前配置与目标目录，修改 components.json 后再次 add 即可生效。

• Foundation：<目标目录>/basic/*.tsx
• Chat：<目标目录>/chat/*.tsx
• 例如默认：src/components/ui/basic/button.tsx、src/components/ui/chat/chat-input/index.tsx

步骤 2：引入设计 token

CLI 会生成 src/qoder-tokens.css，组件样式依赖其中的设计变量。请在应用入口引入一次：

注意：组件样式需在 Tailwind CSS 4 环境下才能正确生效（token 使用 @theme 生成工具类）。请确保项目使用 Tailwind 4，并在同一份会被 Tailwind 处理的 CSS 入口中引入 token（详见下方「按需引入完整说明」）。

Vite / CRA（入口为 main.tsx 或 main.jsx）：

在 src/main.tsx（或 src/main.jsx）顶部添加：

import './qoder-tokens.css'

Next.js（App Router）：

在 src/app/layout.tsx 中与其他 import 一并添加：

import '../qoder-tokens.css'

（若 layout 位于 src/app/layout.tsx 使用 ../qoder-tokens.css，位于 app/layout.tsx 则使用 ./qoder-tokens.css。）

步骤 3：使用组件

默认会生成 src/components/ui/basic/<name>.tsx（Foundation）或 src/components/ui/chat/<name>/（Chat），因此导入路径在默认配置下为：

• Foundation：import { X } from '@/components/ui/basic/<组件名>'
• Chat：import { X } from '@/components/ui/chat/<组件名>'

（若你修改了 aliases.ui，把上面路径中的 @/components/ui 换成你的 alias 即可。）

// 默认 aliases.ui = @/components/ui 时：
import { Button } from '@/components/ui/basic/button'

function App() {
  return (
    <div>
      <Button variant="primary">点击</Button>
    </div>
  )
}

可选：在根节点设置 data-theme 与 data-style（如 <div data-theme="light" data-style="neutral">），不设置则使用默认值。

按需引入完整说明（与 Showcase 一致）

要让按需引入的组件样式与官方 Showcase 完全一致，需满足以下环境与配置。

环境要求

| 项目 | 要求 | |------|------| | Tailwind 版本 | 必须使用 Tailwind CSS 4。设计 token 使用 Tailwind 4 的 @theme 语法，将 CSS 变量映射为工具类（如 h-7、bg-primary、rounded-md）。使用 Tailwind 3 时这些类不会生成，组件样式会异常。 | | 安装 | npm install tailwindcss@^4 @tailwindcss/vite（Vite 项目）；或使用 @tailwindcss/cli 做预编译。 |

Token 引入的两种方式

| 方式 | 何时用 | Token 如何生效 | |------|--------|----------------| | 先 init | 希望 token 直接写进现有 CSS 入口、少一步手动 import 时 | 执行 npx sparkdesign init，CLI 会把 theme.css + scale.css 的内容注入到 src/app/globals.css 或 src/index.css，无需再单独引入 token 文件。 | | 直接 add | 不想改现有流程、先装组件再补样式时 | 执行 npx sparkdesign add button 会生成 src/qoder-tokens.css。须在应用入口（如 main.tsx、layout.tsx）添加一行：import './qoder-tokens.css'（路径按实际入口位置调整，如 Next.js 可为 import '../qoder-tokens.css'）。 |

无论哪种方式，token 必须处在「会被 Tailwind 处理的同一份 CSS 管线」中（即包含 @import "tailwindcss" 的那份 CSS 或其 import 链中），这样 @theme 才会被 Tailwind 4 读取并生成对应工具类。

CSS 入口配置（与 Showcase 一致）

1. 顺序：先 @import "tailwindcss"，再引入 token（或包含 token 的文件）。
2. 扫描组件目录：Showcase 会扫描组件所在目录以生成 h-7、w-9 等工具类。按需引入后组件在你项目里，需让 Tailwind 扫描到这些文件。在同一份 CSS 入口中增加 @source 指向组件目录（路径对应你当前的 aliases.ui）。

最小可用的入口 CSS 示例（Vite 项目，组件默认在 src/components/ui）：

@import "tailwindcss";
@source "../components/ui";
@import "./qoder-tokens.css";

若你已通过 init 把 token 写入了本文件，则无需再写 @import "./qoder-tokens.css"，只需保留 @import "tailwindcss" 和 @source "../components/ui" 即可。

主题与布局风格（可选）

与 Showcase 一样切换主题/风格时，在根节点设置：

• data-theme：颜色主题，如 light、dark。
• data-style：布局风格，如 neutral、compact、soft、sharp、dense。

示例：<div data-theme="light" data-style="neutral">。不设置则使用默认值。

命令说明

| 命令 | 说明 | |------|------| | npx sparkdesign add button | 添加 button 到 src/components/ui/（默认），并自动创建缺失的 config、token 文件、utils | | npx sparkdesign add button tooltip dropdown-menu | 一次添加多个组件 | | npx sparkdesign init | 先做一次「完整初始化」：选择布局风格、组件存放目录（相对 src，默认 components）、是否安装依赖；token 会写进现有 CSS 入口 | | npx sparkdesign list | 列出所有可添加的组件名 | | npx sparkdesign diff button | 对比本地 button 和最新模板的差异 | | npx sparkdesign add button --overwrite | 覆盖已有组件文件 |

支持的组件

支持的组件 = CLI 包内 registry/meta.json 的全部条目（覆盖当前 registry 的 Foundation + Chat 组件实现）。

权威列表请运行：

npx sparkdesign list

示例（Foundation + Chat 混合添加）：

npx sparkdesign add button select dropdown-menu tooltip
npx sparkdesign add chat-input response markdown

说明：tokens（registry/tokens/*.css）与 registry/lib/utils.ts 由 init 或首次 add 时的“初始化逻辑”处理，不作为单组件条目列出。

init 与 add 的选用

• 直接 add（推荐）：执行 npx sparkdesign add button 会生成 src/qoder-tokens.css，按步骤 2 在入口添加 import './qoder-tokens.css' 即可。
• 先 init 再 add：执行 npx sparkdesign init 时会询问组件存放目录（相对 src，如 components 或 ui），并写入 components.json 的 aliases.components 与 aliases.ui（默认 @/components/ui）。之后 add 会按该配置输出到对应目录（如 src/components/ui/），并将 token 写入现有 globals.css / index.css。

两种方式择一使用即可。若要与官方 Showcase 样式完全一致，请同时满足上文「按需引入完整说明」中的 Tailwind 4 与 CSS 入口配置（含 @source 扫描组件目录）。

生成文件说明

| 文件 | 何时出现 | 说明 | |------|----------|------| | components.json | add 或 init | 配置：style、aliases.components、aliases.utils、aliases.ui（组件安装目录，默认 @/components/ui）。修改 aliases.ui 可改变 add 的输出目录；再次 add 时终端会打印目标目录以确认生效。 | | src/qoder-tokens.css | 直接 add 且项目中尚无 token 时 | 设计 token 文件（theme + scale），须在与 Tailwind 同一管线的入口中引入一次，且项目需使用 Tailwind 4 | | src/lib/utils.ts | add 或 init 且不存在时 | 工具函数 cn()，供组件使用 | | src/<aliases.ui 解析路径>/basic/*.tsxsrc/<aliases.ui 解析路径>/chat/*.tsx | add 对应组件时 | 组件源码（路径由 aliases.ui 决定，默认 src/components/ui/），可按需修改 |

依赖

• 样式生效前提：组件样式依赖设计 token 与 Tailwind 工具类，项目须使用 Tailwind CSS 4（见上文「按需引入完整说明」）。若未使用 Tailwind 4，token 中的 @theme 不会生效，h-7、bg-primary 等类不会生成。
• 运行时依赖：组件会用到 class-variance-authority、clsx（以及部分组件需要 tailwind-merge、@radix-ui/* 等）。若执行 npx sparkdesign add button 后出现依赖缺失，请在项目根目录执行：

npm install class-variance-authority clsx tailwind-merge

使用 tooltip、dropdown-menu 等组件时，按提示安装 @radix-ui/react-tooltip、@radix-ui/react-dropdown-menu 等依赖。

安装目录配置

支持 aliases.ui 作为组件安装目录，默认 @/components/ui；未设置时使用 aliases.components + '/qoder' 以兼容旧配置。改安装位置只需改 aliases.ui，aliases.components 一般不必改。详见 CLI 配置说明。