docs: 使用规范与维护规范(含自研组件 2 项目准入门槛)

docs/USAGE.md

@@ -0,0 +1,90 @@
+# @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` |