zhixing-system/.trellis/tasks/archive/2026-08/08-07-home-market-overview/research/shadcn-ui.md

shadcn/ui 组件研究

来源

• Context7 library: /shadcn-ui/ui
• 当前官方文档通过 Context7 返回的来源包括：
  • https://github.com/shadcn-ui/ui/blob/main/apps/v4/content/docs/(root)/cli.mdx
  • https://github.com/shadcn-ui/ui/blob/main/apps/v4/content/docs/components/aria/scroll-area.mdx
  • https://github.com/shadcn-ui/ui/blob/main/apps/v4/content/docs/components/radix/skeleton.mdx
  • https://github.com/shadcn-ui/ui/blob/main/apps/v4/content/docs/installation/vite.mdx

结论

• 当前仓库的 components.json 已配置为 base-nova、Tailwind CSS 4、Lucide 图标，并将 @/shared/ui 作为 UI alias；新增组件应落在 zhixing-web/src/shared/ui/。
• 官方推荐通过 npx shadcn@latest add [component-name] 添加组件。若当前 CLI 与仓库版本不兼容，则保留相同 shadcn 组件边界和可访问性契约，在本地按生成结果最小化实现。
• Home 需要的基础能力包括 Avatar、Dialog、Input、Progress、ScrollArea、Separator 和 Skeleton；Card、Badge、Button 已存在，应先复用并只补足实际缺失的 variant/API。
• Skeleton 使用 Tailwind class 控制尺寸；Dialog、ScrollArea 等交互组件必须保留标准键盘与可访问行为，页面测试应从 role、name 和用户可见文本验证。

对本任务的约束

• 不在 Home feature 内重新实现 modal、滚动容器、头像或 loading primitive。
• 不把 shadcn primitive 变成数据感知组件；数据请求和业务分支留在 feature/page 层。
• 若执行 CLI 添加组件，检查其依赖、生成文件和 pnpm-lock.yaml，再运行格式、lint、类型和测试门禁。