@design-llm/qoder-design

v0.2.5

Published

4 days ago

Modern React Design System with dual-dimension theme system

0High
0Medium
0Low

lucy.cl

cunyu666

react components design-system ui-library tailwind

Spark Qoder Design

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

当前版本：0.2.4（变更说明）

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

特性

双维度主题：data-theme（颜色）+ data-style（布局），独立切换
5 种布局风格：neutral / compact / soft / sharp / dense
内置颜色主题：light / dark
CSS 变量驱动：组件仅用 token，覆盖变量即可定制
Tailwind 友好：类名与设计 token 映射，无硬编码色值
组件分层：Foundation 原子组件 + Chat 对话组件，开箱即用

两种使用方式

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

安装（npm 包）

npm install @design-llm/qoder-design

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

按需引入（CLI）

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

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

详见 docs/CLI按需引入方案.md。

快速开始

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

// 1. 引入样式（必做）
import '@design-llm/qoder-design/style'

// 2. 按需引入组件与类型
import { Button } from '@design-llm/qoder-design'
import type { ButtonProps } from '@design-llm/qoder-design'

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

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

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

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

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

设计系统用法

1. 引入样式（必做）

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

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

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

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

2. 颜色主题（theme）

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

| 主题 | 说明 | |--------|----------| | light | 亮色模式（默认） | | dark | 暗色模式 |

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

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

主题对应的 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. 自定义 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;
}

完整变量清单见 NPM 发布指南（颜色 --color-*、间距 --spacing-*、圆角 --radius-*、字号 --font-size-* 等）。

5. Portal 浮层与主题一致

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

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

import { ThemeStyleProvider, Button, DropdownMenu } from '@design-llm/qoder-design'

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

组件使用

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

import '@design-llm/qoder-design/style'
import { Button } from '@design-llm/qoder-design'
import type { ButtonProps } from '@design-llm/qoder-design'

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

组件概览

| 分层 | 说明 | 示例 | |------|------|------| | Foundation | 原子级 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 发布指南 | 变量清单、主题覆盖、发布步骤 | | 组件入库文档 | 组件与 Showcase 规范 | | 图标自定义说明 | IconsProvider / 替换为 Lucide 等 | | CLI 按需引入方案 | npx @design-llm/qoder init / add 使用说明 |

仓库与开发

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

组件展示（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/qoder-design.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/     # foundation/、chat/
└── lib/            # 工具与 ThemeStyleProvider

技术栈与规范

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

"Keep the map aligned with the terrain."