From 75cb4e543fa327d2161963c263ada172bc9c8db1 Mon Sep 17 00:00:00 2001 From: koko Date: Sun, 25 Oct 2026 13:51:08 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20=E4=BD=BF=E7=94=A8=E8=A7=84=E8=8C=83?= =?UTF-8?q?=E4=B8=8E=E7=BB=B4=E6=8A=A4=E8=A7=84=E8=8C=83(=E5=90=AB?= =?UTF-8?q?=E8=87=AA=E7=A0=94=E7=BB=84=E4=BB=B6=202=20=E9=A1=B9=E7=9B=AE?= =?UTF-8?q?=E5=87=86=E5=85=A5=E9=97=A8=E6=A7=9B)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 4 ++ docs/MAINTAINING.md | 115 ++++++++++++++++++++++++++++++++++++++++++++ docs/USAGE.md | 90 ++++++++++++++++++++++++++++++++++ 3 files changed, 209 insertions(+) create mode 100644 docs/MAINTAINING.md create mode 100644 docs/USAGE.md diff --git a/README.md b/README.md index 5974f53..589b112 100644 --- a/README.md +++ b/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 个项目在用**、发版护栏) diff --git a/docs/MAINTAINING.md b/docs/MAINTAINING.md new file mode 100644 index 0000000..cbe24cf --- /dev/null +++ b/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/`。 +- 发版后用不带 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「设置 → 应用」吊销并重新生成。 diff --git a/docs/USAGE.md b/docs/USAGE.md new file mode 100644 index 0000000..0bd176c --- /dev/null +++ b/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. 暗色模式: `` 加/去 `.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={