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

README.md

@@ -36,3 +36,7 @@ npm version patch|minor      # 改版本
 GITEA_NPM_TOKEN=... npm publish   # prepublishOnly 自动跑护栏
 ```
 同名同版本不可重发。护栏: `scripts/prepublish-check.mjs`(白名单/敏感信息/体积)。
+
+## 文档
+- [docs/USAGE.md](docs/USAGE.md) 使用方规范(接入、可改/不可改、验证)
+- [docs/MAINTAINING.md](docs/MAINTAINING.md) 维护规范(同步上游、**自研组件准入: 至少 2 个项目在用**、发版护栏)

docs/MAINTAINING.md

@@ -0,0 +1,115 @@
+# @koko/ui 维护与开发规范(维护者)
+
+适用对象: 在本仓库改动、发版的人与 agent。使用方规范见 [USAGE.md](./USAGE.md)。
+
+## 1. 仓库结构
+
+```
+src/components/ui/      官方 shadcn base-nova 组件(由 sync 脚本生成,不要手改)
+src/components/extra/   自研/封装组件(如 DatePicker),须满足准入门槛
+src/hooks/  src/lib/    官方依赖的 hooks、cn 工具
+src/tokens.css          基准主题变量(Light Green, oklch)
+src/shadcn-tailwind.css 内置的官方 shadcn Tailwind 基础样式
+src/styles.css          总体样式入口
+src/index.ts            统一导出
+src/UPSTREAM.json       上游 shadcn 版本/样式记录
+scripts/sync-shadcn.py  上游同步
+scripts/prepublish-check.mjs  发版护栏
+docs/                   本规范
+```
+
+核心边界: 本包只含「主要组件 + 总体样式」。业务逻辑、项目专属样式一律不收。
+
+## 2. 日常改动类型
+
+| 类型 | 做法 | 版本 |
+|---|---|---|
+| 修 bug / 小调整 | 改 `extra/` 或 `tokens.css` | patch |
+| 风格调整(圆角、字体、阴影) | 改 `tokens.css` | minor(视觉有变化) |
+| 同步上游 shadcn | 见 §3 | minor,破坏性变更为 major |
+| 新增自研组件 | 先过 §4 准入,再实现 | minor |
+| 删除/改名导出 | 先标记弃用一个版本再删 | major |
+
+`src/components/ui/` 下文件由脚本覆盖,**手改会在下次同步丢失**。需要定制官方组件时: 优先改 `tokens.css`;确需改结构,在 `extra/` 做封装,不改 `ui/`。
+
+## 3. 同步上游 shadcn
+
+1. `npm run sync`(脚本在临时脚手架里跑官方 CLI,展开样式标记、替换图标为 lucide,再拷入 `ui/`,并更新 `UPSTREAM.json`)。
+2. `git diff` 审查: 重点看 import 变化、新增依赖、被删除的导出。
+3. 同步新增的依赖到 `package.json`。
+4. `npm run check`(tsc)必须通过。
+5. 重新生成 `src/index.ts` 导出,检查命名冲突。
+6. 在预览站验证(§6)。
+7. 发版(§5)。
+
+建议节奏: 每月或遇到安全/重要修复时同步一次。上游更新不会自动流入,不同步就会落后。
+
+## 4. 新增自研组件的准入门槛
+
+**硬性条件: 该组件已被至少两个不同项目实际使用,才可以考虑放入公共库。**
+
+流程:
+
+1. 第一个项目需要时,在**该项目内**实现(`src/components/local/`),不进公共库。
+2. 第二个项目出现同样需求,两边实现趋同后,才提出收录。
+3. 收录前逐项确认:
+   - [ ] 两个项目都已有在用实现,并能指出具体文件位置。「预计以后会用」「看起来通用」不算。
+   - [ ] 官方 shadcn 没有现成等价组件(有则直接用官方)。
+   - [ ] 与业务无关: 无项目名、无数据请求、无业务文案、无硬编码接口。
+   - [ ] 由现有公共组件和 token 组合而成,样式只用 token 类,不写死颜色/像素。
+   - [ ] API 以两个项目的共同需求为准,不为想象中的第三方场景加参数。
+   - [ ] 新增依赖尽量为零;若必须新增,单独说明体积与理由。
+4. 收录后:
+   - 放 `src/components/extra/`,在 `index.ts` 导出。
+   - 预览站补一个示例。
+   - 两个来源项目随即改为使用公共版本并删除本地实现,避免两份并存。
+   - 在 CHANGELOG 记录来源项目。
+
+不满足门槛的诉求一律留在项目内。门槛对 agent 同样有效,不得绕过。
+
+## 5. 发版
+
+```
+cd /opt/data/workspace/koko-ui
+npm run check
+npm version patch|minor|major --no-git-tag-version
+node scripts/prepublish-check.mjs
+npm pack --dry-run        # 肉眼看文件清单
+npm publish               # token 由环境注入,见下
+git add -A && git commit -m "release x.y.z" && git push origin main
+```
+
+- token 在 `/opt/data/git/gitea_token.json`(需 `write:package`),只通过临时 userconfig 注入,发完删除。禁止写进仓库、聊天或日志。
+- 同名同版本不可重发。撤回: `DELETE /api/v1/packages/koko/npm/%40koko%2Fui/<ver>`。
+- 发版后用不带 token 的环境 `npm view @koko/ui version` 验证。
+
+### 发版安全护栏(必须)
+
+包发布后匿名可读,发布前必须保证无敏感信息、体积合理。
+
+- `prepublishOnly` 自动跑 `scripts/prepublish-check.mjs`,检查:
+  - 文件白名单: `package.json`、`README.md`、`src/**/*.{ts,tsx,css}`、`src/UPSTREAM.json`。
+  - 敏感信息: 私钥、各类 token 格式、`_authToken` 明文、硬编码凭证、JWT、URL 内嵌密码。
+  - 体积上限: 打包 ≤150KB、解压 ≤600KB、文件 ≤80。
+- 当前基线(0.2.0): 60 文件 / 打包 39.8KB / 解压 210KB。明显偏离(如翻倍)先查原因,不要直接调高阈值。
+- 禁止进入包的内容: `.env`、截图、`node_modules`、业务数据、`docs/`、`scripts/`。
+- 护栏拦截时先判断是误报还是真问题,不得为通过而绕过检查。
+
+## 6. 验证
+
+- `npm run check` 通过。
+- 预览站: `/opt/data/workspace/koko-ui-preview`(Astro),用 `npm pack` 的 tgz 安装本包后构建。
+- 部署到 Netlify koko-preview,在 mac-C 浏览器验证: 控制台无报错,图表有 SVG 输出,弹窗/日期选择可用,亮/暗色各看。
+- 不要在 Hermes 主机启动浏览器。
+- 禁用 `file:` / `npm link`(React 双实例)。
+
+## 7. 通知使用方
+
+- 发版后各项目按需执行 `npm i @koko/ui@latest`,构建验证后部署。
+- major 版本或有破坏性变更时,在 CHANGELOG 写迁移说明。
+- 项目提出的风格诉求、缺陷汇总到本仓库处理,不接受「在项目里先打补丁」。
+
+## 8. 凭据卫生
+
+- 本仓库公开,任何文档与提交不得包含 token。
+- 发现 token 曾在聊天或日志出现,到 Gitea「设置 → 应用」吊销并重新生成。

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` |