@koko/ui 维护与开发规范(维护者)

适用对象: 在本仓库改动、发版的人与 agent。使用方规范见 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

npm run sync(脚本在临时脚手架里跑官方 CLI,展开样式标记、替换图标为 lucide,再拷入 ui/,并更新 UPSTREAM.json)。
git diff 审查: 重点看 import 变化、新增依赖、被删除的导出。
同步新增的依赖到 package.json。
npm run check(tsc)必须通过。
重新生成 src/index.ts 导出,检查命名冲突。
在预览站验证(§6)。
发版(§5)。

建议节奏: 每月或遇到安全/重要修复时同步一次。上游更新不会自动流入,不同步就会落后。

4. 新增自研组件的准入门槛

硬性条件: 该组件已被至少两个不同项目实际使用,才可以考虑放入公共库。

流程:

第一个项目需要时,在该项目内实现(src/components/local/),不进公共库。
第二个项目出现同样需求,两边实现趋同后,才提出收录。
收录前逐项确认:
- 两个项目都已有在用实现,并能指出具体文件位置。「预计以后会用」「看起来通用」不算。
- 官方 shadcn 没有现成等价组件(有则直接用官方)。
- 与业务无关: 无项目名、无数据请求、无业务文案、无硬编码接口。
- 由现有公共组件和 token 组合而成,样式只用 token 类,不写死颜色/像素。
- API 以两个项目的共同需求为准,不为想象中的第三方场景加参数。
- 新增依赖尽量为零;若必须新增,单独说明体积与理由。
收录后:
- 放 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「设置 → 应用」吊销并重新生成。

5.5 KiB Raw Blame History