# @koko/ui 使用规范(使用方)

适用对象: 所有接入 `@koko/ui` 的工作台项目及其 agent。维护公共库本身见 [MAINTAINING.md](./MAINTAINING.md)。

## 1. 基本信息

| 项 | 值 |
|---|---|
| 包名 | `@koko/ui` |
| Registry | `https://git.colinx.one/api/packages/koko/npm/`(匿名可读,无需 token) |
| 源码 | https://git.colinx.one/koko/koko-ui |
| 预览站 | https://koko-preview.netlify.app |
| 技术底座 | shadcn/ui 官方 `base-nova`(Base UI,非 Radix)、Tailwind v4、React 19、lucide-react |
| Skill | `koko-ui-shared-package` |

## 2. 接入步骤

1. 项目根目录 `.npmrc`(可提交,不含 token):
   ```
   @koko:registry=https://git.colinx.one/api/packages/koko/npm/
   ```
2. `npm i @koko/ui`。宿主需自备 `react>=19`、`react-dom>=19`、`tailwindcss>=4`。项目直接用到 `recharts`、`sonner`、`lucide-react` 时单独安装。
3. 全局 CSS 入口:
   ```css
   @import "tailwindcss";
   @import "@koko/ui/styles.css";
   @source "../node_modules/@koko/ui/src";
   ```
   `@source` 不可省,缺了包内类名被 purge,样式全丢。路径按 CSS 文件到 `node_modules` 的相对位置调整。
4. 暗色模式: `<html>` 加/去 `.dark` 类。
5. 使用: `import { Button, Card, DatePicker, ChartContainer } from "@koko/ui"`。
6. 框架注意:
   - Astro: 交互组件加 `client:load` / `client:visible`。
   - Next.js: 配置 `transpilePackages: ["@koko/ui"]`(包发的是 TS 源码)。
   - Netlify / CI: 提交 lockfile 与 `.npmrc` 即可,不需要 `NPM_TOKEN`。

## 3. 必须遵守

### 3.1 能改什么 / 不能改什么

| 类别 | 在使用方仓库 | 在 koko-ui 仓库 |
|---|---|---|
| 品牌色变量 | 允许,仅限下表 | — |
| 圆角、字体、阴影、间距 | 禁止 | 改 `tokens.css` 发版 |
| 组件外观/行为、修 bug | 禁止 | 改后发版 |
| 新增通用组件 | 禁止直接复制进来当公共组件 | 须满足准入门槛(见 MAINTAINING §4) |
| 项目业务组件 | 允许,放项目自己的目录 | 不收 |

允许覆盖的变量(全局 CSS 的 `:root` / `.dark` 中):
`--primary --primary-foreground --ring --accent --accent-foreground --chart-1..5 --sidebar-primary --sidebar-primary-foreground --sidebar-ring`

当前阶段色调暂缓: **默认不覆盖任何变量**,沿用基准主题 Light Green。

### 3.2 编码约定

- 只从 `@koko/ui` 引入,不要深入引用 `node_modules/@koko/ui/src/...` 内部路径。
- 不要把 shadcn 组件源码复制进项目,不要在项目里运行 `npx shadcn add`。
- Base UI 用 `render={<Button />}` 代替 Radix 的 `asChild`。
- 样式用 token 类(`bg-primary`、`text-muted-foreground`、`rounded-lg` 等),不要写死颜色值或像素圆角。
- 项目自己的外壳变量使用独占前缀,不要在 `:root` 定义 `--muted`、`--card`、`--radius` 等同名变量,否则覆盖公共 token。
- 图标统一 `lucide-react`,不混用其他图标库。
- 项目内的业务组件由公共组件组合而成,放 `src/components/local/`(或项目等价目录),不要冒充公共组件。

### 3.3 版本管理

- 依赖写 `^x.y.z`,升级用 `npm i @koko/ui@latest`,升级后必须构建并过一遍关键页面再部署。
- 发现公共组件缺陷或风格诉求: 不要本地打补丁,记录诉求,到 koko-ui 仓库处理(见 MAINTAINING)。
- 禁止用 `file:` 或 `npm link` 安装本包验证。会出现两份 React,Recharts 图表静默空白。需要验证未发布改动时使用 `npm pack` 生成的 tgz。

### 3.4 安全

- `.npmrc` 只写 registry 一行,绝不写 `_authToken`。
- 不向 koko-ui 提交任何项目业务数据、域名内部信息、凭据(该包匿名可读)。

## 4. 验证清单(接入或升级后)

- [ ] `npm run build` 退出码 0。
- [ ] 产物 CSS 含 `--primary`,`bg-primary` 等类被生成。
- [ ] 在 mac-C 浏览器(不是 Hermes 主机)打开预览: 控制台无报错,弹窗、下拉、日期选择、图表正常,亮/暗色各看一遍。
- [ ] 无遗留旧 UI 库依赖与样式。

## 5. 常见问题

| 现象 | 原因 | 处理 |
|---|---|---|
| 组件无样式 | 缺 `@source` 或路径写错 | 补 `@source`,检查相对路径 |
| 图表空白、无报错 | React 双实例(`file:`/`npm link`) | 改装 npm pack 的 tgz |
| `E404` 找不到包 | 缺 `.npmrc` scope 配置 | 加 `@koko:registry=...` |
| 颜色/圆角被改乱 | 项目 `:root` 定义了同名变量 | 外壳变量改独占前缀 |
| `asChild` 无效 | Base UI 不支持 | 改用 `render` |