# @design-llm/qoder-cli

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

---

## 快速开始

### 步骤 1：添加组件

在项目根目录执行：

```bash
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`）顶部添加：

```ts
import './qoder-tokens.css'
```

**Next.js（App Router）：**

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

```ts
import '../qoder-tokens.css'
```

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

### 步骤 3：使用组件

```tsx
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` 后出现依赖缺失，请在项目根目录执行：

```bash
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](https://www.npmjs.com/package/@design-llm/qoder-design)，若需通过 `import` 直接引用组件，请安装该包。

---

## 相关链接

- 设计系统主包：[@design-llm/qoder-design](https://www.npmjs.com/package/@design-llm/qoder-design)
- 方案与扩展说明：主仓库 [docs/CLI按需引入方案.md](https://github.com/spark-qoder/spark-qoder-design/blob/master/docs/CLI按需引入方案.md)