sparkdesign

v0.4.8

Published

15 days ago

Modern React Design System with dual-dimension theme system

Downloads

426

0High
0Medium
0Low

cunyu666

react components design-system ui-library tailwind

Spark Design

现代化 React 设计系统，支持双维度主题（颜色 theme + 布局 scale），5 种内置布局风格，提供 Basic 基础组件与 Chat 对话流组件，可扩展颜色主题。

当前版本：0.4.6（CLI 快速上手 / NPM 快速上手）

🌟 纯新手？ 查看 CLI 快速上手指南，一步步带你跑起来！

以下为安装与使用说明；仓库结构、开发脚本与贡献方式见文末仓库与开发。

特性

双维度主题：data-theme（颜色）+ data-style（布局），独立切换
5 种布局风格：neutral / compact / soft / sharp / dense
官方起始 preset：Mint / Parchment
CSS 变量驱动：覆盖颜色和 scale token 即可定制
图标系统可替换：通过 IconsProvider 接 Lucide、Remix 或自定义图标库
Tailwind 友好：类名与设计 token 映射，无硬编码色值
组件分层：Basic 原子组件 + Chat 对话组件，开箱即用

两种使用方式

| 方式 | 适用场景 | 命令 | |------|----------|------| | npm 安装 | 直接引用、不改源码 | npm install sparkdesign | | CLI 按需引入 | 复制源码到项目、可自由修改 | npx sparkdesign init → npx sparkdesign add button |

发布模型：sparkdesign 是唯一发布到 npm 的包。CLI 不是第二个独立 npm 包，而是根包中的 bin 入口；因此用户侧既可以 npm install sparkdesign，也可以直接 npx sparkdesign@latest add button。

风格控制模型

不管你用哪种接入方式，真正决定项目风格的都是三层：

colors：颜色 token，决定品牌色、背景、边框、语义色
scale：布局 token，决定间距、圆角、字号和密度
icons：图标系统，决定视觉语言

mint / parchment 只是官方提供的两套 starter preset，更适合当起点和 showcase 示例，而不是长期绑定的唯一主题心智。

接入后你实际拿到什么

CLI 模式

components.json：记录默认 appearance / theme / style
src/sparkdesign-tokens.css 或注入后的 src/index.css：预设好的颜色和 scale token，可直接改
src/components/ui/...：复制出来的组件源码，可直接改
src/lib/utils.ts：组件依赖的工具函数

npm 安装模式

预编译样式：import 'sparkdesign/style'
token 入口：import 'sparkdesign/theme.css' / import 'sparkdesign/scale.css'
运行时入口：ThemeStyleProvider、IconsProvider

也就是说：

CLI 更适合“拿到文件后自己改”
npm 更适合“先跑起来，再通过 token 和 icon 覆盖”

安装（npm 包）

npm install sparkdesign

依赖：需自行安装 react、react-dom（>=18）。

按需引入（CLI，推荐）

若希望将组件源码复制到项目中并自由修改，可使用 CLI：

npx sparkdesign init                    # 初始化 components.json、tokens、utils
npx sparkdesign add button tooltip      # 添加组件到 src/components/ui/
npx sparkdesign list                    # 列出可用组件
npx sparkdesign diff button             # 对比本地与注册表差异

详见 docs/cli/on-demand-import.md。

快速开始

三步即可在项目中使用组件，无需配置 Tailwind：

// 1. 引入样式（必做）
import 'sparkdesign/style'

// 2. 按需引入组件与类型
import { Button } from 'sparkdesign'
import type { ButtonProps } from 'sparkdesign'

// 3. 在根节点设置主题与布局（可选，不设则使用默认 light + neutral）
function App() {
  return (
    <div data-theme="light" data-style="neutral">
      <Button variant="primary" size="md">点击</Button>
    </div>
  )
}

样式引入方式（三选一，推荐方式 A）：

| 方式 | 用法 | 说明 | |------|------|------| | A | import 'sparkdesign/style' | 推荐。预编译完整样式（Tailwind 工具类 + 设计 token），无需配置 Tailwind | | B | import 'sparkdesign/theme.css'import 'sparkdesign/scale.css' | 仅引入设计 token，适合已有 Tailwind 4 项目自行扫描组件并覆盖变量（需在消费者 CSS 中 @source 指向本包） | | C | 只引入组件、不引入样式 | 需在项目中自行提供与设计 token 同名的 CSS 变量，否则组件无样式 |

Markdown 数学公式：若使用 MarkdownBody 组件且需要渲染 KaTeX 数学公式，额外引入： import 'sparkdesign/katex.css'

自定义主题时，请先引入设计系统样式，再引入你的覆盖 CSS，变量覆盖才会生效。

设计系统用法

1. 引入样式（必做）

样式引入的三种方式见上方「快速开始」表格。

方式 A（推荐）：import 'sparkdesign/style' 包含预编译的 Tailwind 工具类 + theme/scale 设计 token，消费者项目不需要安装或配置 Tailwind。
方式 B（Tailwind 用户）：仅引入 token 文件，消费者需在自己的 CSS 中 @source 指向本包以扫描组件中使用的 Tailwind 类名：

/* 消费者 CSS（已有 Tailwind 4 的项目）*/
@import "tailwindcss";
@source "../node_modules/sparkdesign/dist";
@import "sparkdesign/theme.css";
@import "sparkdesign/scale.css";

约定：自定义主题时，先引入设计系统样式，再引入你的覆盖 CSS。

2. 颜色主题（theme）

通过 data-theme 切换颜色主题，作用于主色、背景、边框、语义色等。

| 主题 | 说明 | |--------|----------| | light | Mint 亮色（默认） | | dark | Mint 暗色 | | light-parchment | Parchment 亮色 | | dark-parchment | Parchment 暗色 |

// 在根节点或任意父节点设置
<div data-theme="dark">
  <Button variant="primary">按钮</Button>
</div>

<!-- 或直接挂在 body -->
<body data-theme="dark">

如果你使用 React，ThemeStyleProvider 还支持按三维组合主题：

appearance: light | dark
theme: mint | parchment | 自定义对象
style: neutral | compact | soft | sharp | dense

例如 appearance="dark" theme="parchment" style="soft" 会得到 data-theme="dark-parchment" 与 data-style="soft"。主题对应的 CSS 变量定义在 theme.css（如 --color-primary、--color-bg-container 等）。自定义主题见下文「自定义 theme / scale」。

3. 布局风格（scale）

通过 data-style 切换布局尺度，作用于间距、圆角、字号等。

| 风格 | 描述 | 特点 | |-----------|----------------|----------------| | neutral | 平衡的标准 | 默认，简洁直观 | | compact | 优化效率 | 更窄间距，紧凑 | | soft | 舒适至上 | 大圆角、宽松间距 | | sharp | 几何精度 | 直角、利落线条 | | dense | 信息密集 | 最小留白 |

<div data-style="soft">
  <Button>按钮</Button>
</div>

布局变量定义在 scale.css（如 --spacing-*、--radius-*、--font-size-*）。可组合使用：

<div data-theme="dark" data-style="soft">
  {/* 暗色 + 柔和布局 */}
</div>

4. 真正决定风格的三件事

颜色变量：决定品牌色、背景、边框、语义色
scale 变量：决定间距、圆角、字号和组件密度
图标系统：决定视觉语言和产品气质

官方 mint / parchment 只是两套 starter preset。无论你用整包还是 CLI，长期稳定的定制入口都应该是 token + icons，而不是依赖 preset 名称本身。

5. 自定义 theme / scale

在先引入设计系统样式之后，用你自己的 CSS 覆盖变量即可。

选择器约定：

:root — 覆盖默认
[data-theme="主题名"] — 颜色主题（自定义名称）
[data-style="风格名"] — 布局风格（自定义名称）

/* 自定义颜色主题 */
[data-theme="my-brand"] {
  --color-primary: #3B82F6;
  --color-primary-hover: #2563EB;
}

/* 自定义布局风格 */
[data-style="custom"] {
  --spacing-4: 20px;
  --radius-md: 8px;
}

完整变量说明见主题自定义指南（颜色 --color-*、间距 --spacing-*、圆角 --radius-*、字号 --font-size-* 等）。

6. Portal 浮层与主题一致

DropdownMenu、Tooltip 等会挂到 body，不会继承局部容器的 data-theme / data-style。两种做法：

做法 A：把 data-theme、data-style 设到 <html> 或 <body>，全局一致。
做法 B：用 ThemeStyleProvider 包裹应用，浮层会使用同一主题/风格：

import { ThemeStyleProvider, Button, DropdownMenu } from 'sparkdesign'

function App() {
  const appearance = 'dark'
  const theme = 'mint'
  const style = 'soft'
  return (
    <ThemeStyleProvider appearance={appearance} theme={theme} style={style}>
      <div data-theme="dark" data-style={style}>
        <Button>打开</Button>
        <DropdownMenu>...</DropdownMenu>
      </div>
    </ThemeStyleProvider>
  )
}

组件使用

组件与类型均从主入口按需引入，用法见上方「快速开始」。示例：

import 'sparkdesign/style'
import { Button } from 'sparkdesign'
import type { ButtonProps } from 'sparkdesign'

function App() {
  return (
    <div data-theme="light" data-style="neutral">
      <Button variant="primary" size="md">Click me</Button>
    </div>
  )
}

组件概览

| 分层 | 说明 | 示例 | |------|------|------| | Basic | 原子级 UI 组件 | Button, IconButton, Tooltip, Select, DropdownMenu, Tabs, Toast, Tag, Progress, Avatar, Table, Slider, Pagination, Collapse, Resizable, Scrollbar, Skeleton, Spinner, Kbd, EllipsisText, Switch, Toggle, ToggleGroup, RadioGroup, AlertDialog, OptionList … | | Chat | 对话流相关组件 | ChatInput, SendButton, Request, Response, FileCard, FileAttachment, ImageAttachment, FolderButton, ReasoningStep, ToolInvocationCard, PermissionCard, MarkdownBody, GenerationStatusBar, ThinkingIndicator, ImageGenerating, RelatedPrompts, SuggestionPart, SidebarMenu … |

完整导出见 src/components/index.ts。图标通过 IconsProvider / useIcon 注入，可替换为 Lucide、Remix 等，见图标自定义说明。

文档（仓库内）

| 文档 | 说明 | |------|------| | NPM 快速上手 | 整包引入、ThemeStyleProvider、Portal 主题继承 | | CLI 快速上手 | npx sparkdesign init / add 入门 | | 组件入库文档 | 组件与 Showcase 规范 | | 图标自定义说明 | IconsProvider / 替换为 Lucide 等 | | CLI 按需引入方案 | CLI 架构与按需引入说明 | | Component Lifecycle SOP | 组件从开发到发布的固定流程 | | Theme Lifecycle SOP | preset / token / ThemeStyleProvider 维护流程 | | Release Checklist | 发布前后检查单 |

仓库与开发

以下内容面向参与仓库开发的贡献者；仅使用本包时可忽略。

组件展示（Showcase）

本仓库内 apps/showcase 提供所有组件的演示与 Props 文档：

cd apps/showcase && npm install && npm run dev

项目脚本

| 脚本 | 说明 | |------|------| | npm run dev | 设计系统开发服务器 | | npm run build | 生产构建：Vite 输出 JS → @tailwindcss/cli 预编译 CSS → tsc 类型声明 | | npm run build:css | 仅重新生成预编译 CSS（dist/sparkdesign.css） | | npm run preview | 预览构建产物 | | cd apps/showcase && npm run dev | 组件展示站点 |

目录结构

src/
├── index.css       # dev 模式 CSS 入口
├── lib.css         # 库构建 CSS 入口（@tailwindcss/cli）
├── tokens/         # theme.css、scale.css
├── components/     # basic/、chat/
└── lib/            # 工具与 ThemeStyleProvider

技术栈与规范

React 19 + TypeScript + Vite 7；Tailwind CSS 4；Radix UI、Framer Motion
项目哲学与 GEB 协议：AGENTS.md

"Keep the map aligned with the terrain."