@design-llm/qoder-cli

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

快速开始

步骤 1：添加组件

在项目根目录执行：

npx @design-llm/qoder-cli add button

添加多个组件时在命令后追加组件名，例如：npx @design-llm/qoder-cli add button tooltip dropdown-menu。

步骤 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：使用组件

import { Button } from '@/components/qoder/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-cli add button | 添加 button 到 src/components/qoder/，并自动创建缺失的 config、token 文件、utils | | npx @design-llm/qoder-cli add button tooltip dropdown-menu | 一次添加多个组件 | | npx @design-llm/qoder-cli init | 先做一次「完整初始化」再按需 add（token 会写进你现有的 CSS 入口，不用再单独 import） | | npx @design-llm/qoder-cli list | 列出所有可添加的组件名 | | npx @design-llm/qoder-cli diff button | 对比本地 button 和最新模板的差异 | | npx @design-llm/qoder-cli add button --overwrite | 覆盖已有组件文件 |

init 与 add 的选用

• 直接 add（推荐）：执行 npx @design-llm/qoder-cli add button 会生成 src/qoder-tokens.css，按步骤 2 在入口添加 import './qoder-tokens.css' 即可。
• 先 init 再 add：执行 npx @design-llm/qoder-cli init 可配置布局风格与依赖，并将 token 写入现有 globals.css / index.css，之后执行 add 时无需再单独引入 token 文件。

两种方式择一使用即可。

生成文件说明

| 文件 | 何时出现 | 说明 | |------|----------|------| | components.json | add 或 init | 配置（风格、路径别名），通常无需修改 | | src/qoder-tokens.css | 直接 add 且项目中尚无 token 时 | 设计变量文件，在入口引入一次即可 | | src/lib/utils.ts | add 或 init 且不存在时 | 工具函数 cn()，供组件使用 | | src/components/qoder/button.tsx 等 | add 对应组件时 | 组件源码，可按需修改 |

依赖

组件会用到：class-variance-authority、clsx（以及部分组件需要 tailwind-merge、@radix-ui/* 等）。
若执行 npx @design-llm/qoder-cli add button 后出现依赖缺失，请在项目根目录执行：

npm install class-variance-authority clsx tailwind-merge

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

为什么这个包这么小？

CLI 为代码生成器：仅包含命令与组件模板，不打包完整组件库。
执行 npx @design-llm/qoder-cli add button 时，会将 button.tsx 的模板复制到当前项目，源码归属项目仓库，故本包体积较小。完整设计系统见 @design-llm/qoder-design，若需通过 import 直接引用组件，请安装该包。

相关链接

• 设计系统主包：@design-llm/qoder-design
• 方案与扩展说明：主仓库 docs/CLI按需引入方案.md