shadcn/ui

shadcn/ui 官方将自己定义为设计良好、可访问的组件集合与代码分发平台，并强调 Open Source、Open Code。它和传统从 NPM 导入封装组件的模式不同：通过 CLI 与 Registry 将组件源码加入项目，团队可以直接阅读、修改和组合，也要自行维护这些代码。

先理解“拥有组件代码”的含义

安装前对齐项目约定

先确定框架、TypeScript、样式方案、路径别名、CSS 变量和组件目录，再运行文档对应的初始化流程。不要在已有大型项目中未经检查直接接受默认配置；初始化产生的文件应进入版本控制，并由团队审查依赖和全局样式变化。

CLI 的任务是分发和写入

1. 初始化配置并确认生成位置。
2. 按需添加 Button、Dialog、Data Table 等组件。
3. 阅读新增源码与依赖，不把命令输出当黑盒。
4. 用项目令牌调整颜色、圆角和字体。
5. 补上业务状态、测试与文档后再复用。

组件目录很丰富，但不必一次性全部安装。

主题应从语义变量出发

颜色变量要表达 background、foreground、primary、muted、border 和 destructive 等角色，而不是只替换一组品牌 HEX。浅色与暗色分别验证文字、表面、焦点和禁用状态；字体、间距与圆角也要与产品的密度和平台习惯匹配。

可访问性基础仍需业务验收

组件提供可访问性起点，不代表组合后的产品自动合格。Dialog 的标题和焦点返回、表单的标签与错误信息、菜单的键盘操作、Data Table 的排序说明，都可能因你的封装和文案而改变。用键盘、屏幕阅读器和真实数据完成回归。

Registry 可以扩展为团队分发层

官方 Registry 文档包含 schema、CLI、命名空间、认证、GitHub Registries 和 MCP 等能力。团队可把内部组件、区块、样式与依赖封装为受控条目，在多个项目间分发；私有 Registry 还要规划访问控制、版本策略和来源审计。

升级要比较源码而非只改版本号

• 记录组件加入时的上游版本与本地改动；
• 关注 Changelog 和依赖安全更新；
• 升级前比较生成代码差异；
• 为关键交互保留视觉与行为测试；
• 避免在多个项目复制出无法同步的分叉。

开放代码带来自主性，也把维护责任明确交给使用团队。