安装与接入
通过 shadcn CLI 安装你能完整拥有的组件源码。
Kitseed 使用 shadcn Registry。先注册当前文档站的地址，再按名称安装；版本路径固定在 v0.3.0，不会因文档更新而改变已有项目的安装基线。
环境要求
| 项目 | 当前约定 |
|---|---|
| UI 运行时 | React 19、TypeScript |
| 样式 | Tailwind CSS 4、CSS 语义变量 |
| 交互基础 | Base UI，通过 Registry 声明依赖 |
| 安装工具 | 已初始化的 shadcn CLI 与 components.json |
| 应用框架 | Next.js 或 Vite；通用组件不依赖应用路由 |
如果项目尚未配置 shadcn，请先按官方安装说明完成初始化，并确认 components.json 中的组件、工具函数与 CSS 别名指向真实路径。
1. 注册当前版本
{
"registries": {
"@kitseed": "http://127.0.0.1:3040/r/v0.3.0/{name}.json"
}
}上面的地址使用当前站点 origin。部署到自己的域名后，复制出的命令会随地址变化；本地开发时，应保持文档服务可访问，供 CLI 获取 JSON。
2. 安装基础与组件
pnpm dlx shadcn@4.22.1 add http://127.0.0.1:3040/r/v0.3.0/button.json首次使用请先完成 Registry 与主题接入。
Registry 会根据条目声明安装依赖、工具和相应源码。后续组件使用相同流程；组件页提供专属安装命令，不需要一次安装整个目录。
3. 接入样式与 Provider
组件条目自动依赖 @kitseed/theme。基础样式需要在全局 CSS 中手动导入一次：
@import "tailwindcss";
@import "./lib/kitseed/theme.css";第二行路径相对于你的全局 CSS，以安装后 lib/kitseed/theme.css 的实际位置调整。保留语义变量、Tailwind 映射及主题规则，避免只复制 TSX 而遗漏 CSS。
KitseedProvider 统一配置 density 与 messages，默认密度为 compact；嵌套 Provider 继承未覆盖配置，messages 可局部覆盖文案与文案函数。它不读取应用翻译状态。Toast 需要 ToastProvider，Tooltip 使用 TooltipProvider 共享延迟。将 Provider 放在应用布局的稳定位置，避免路由切换时重复挂载和清空反馈。
Image Lightbox 的预览外观通过自带 CSS module 交付，不要求宿主为它导入全局主题；源码安装仍遵循 Registry 的依赖声明。
组件内部通过相对依赖组织源码。应用中使用安装后的组件别名；文档预览的源码使用默认 @/ 别名展示；CLI 根据宿主的 components.json 将路径写入对应目录。
4. 在真实容器中验证
- 在浅色、深色和窄容器中检查文字、边界、浮层和长内容。
- 用键盘完成一次任务，确认标签、焦点、Escape 和关闭后的焦点恢复。
- 对表单补上等待、错误与成功状态，对破坏性动作明确提供确认文案。
- 对选择器检查选项值、可见名称和提交值；业务验证仍由应用负责。
升级与维护
先查看版本记录，再在隔离分支比较 Registry 提供的源码与本地修改。存在业务定制时，以人工审查合并；不要用覆盖安装替代升级判断。
Kitseed 当前保持私有。提炼来源、原有依赖许可与字体许可应随源码保留；本版本没有额外授予公开发布或开源再分发许可。