@design-llm/qoder

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

当前版本：0.1.6 · 设计系统主包：@design-llm/qoder-design

快速开始

步骤 1：添加组件

在项目根目录执行：

npx @design-llm/qoder add button

添加多个组件时在命令后追加组件名，例如：npx @design-llm/qoder 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，组件样式依赖其中的设计变量。请在应用入口引入一次：

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">），不设置则使用默认值。

命令说明

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

支持的组件

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

权威列表请运行：

npx @design-llm/qoder list

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

npx @design-llm/qoder add button select dropdown-menu tooltip
npx @design-llm/qoder add chat-input response markdown

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

init 与 add 的选用

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

两种方式择一使用即可。

生成文件说明

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

依赖

组件会用到：class-variance-authority、clsx（以及部分组件需要 tailwind-merge、@radix-ui/* 等）。
若执行 npx @design-llm/qoder 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 配置说明。