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

适用对象: 所有接入 @koko/ui 的工作台项目及其 agent。维护公共库本身见 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. 接入步骤

项目根目录 .npmrc(可提交,不含 token):

@koko:registry=https://git.colinx.one/api/packages/koko/npm/

npm i @koko/ui。宿主需自备 react>=19、react-dom>=19、tailwindcss>=4。项目直接用到 recharts、sonner、lucide-react 时单独安装。
全局 CSS 入口:
```
@import "tailwindcss";
@import "@koko/ui/styles.css";
@source "../node_modules/@koko/ui/src";
```
@source 不可省,缺了包内类名被 purge,样式全丢。路径按 CSS 文件到 node_modules 的相对位置调整。
暗色模式: <html> 加/去 .dark 类。
使用: import { Button, Card, DatePicker, ChartContainer } from "@koko/ui"。
框架注意:
- 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`

4.4 KiB Raw Blame History