用途：在使用 shadcn/ui 构建界面时，提供安装、主题、组件组合与质量检查的指导。把 shadcn 当作可组合的源码式 UI 系统，而不是黑盒依赖。
适用时机：在 Next.js 或 Vite 中搭建 shadcn；构建可复用 UI 原语与设计令牌；用 shadcn 组件实现表单、对话框、表格等流程。
核心约定：只安装需要的组件；集中管理主题令牌与语义样式；优先组合模式而非一次性自定义包装；保留无障碍默认行为；业务逻辑不放进 UI 原语。
实施流程：一、初始化当前框架的 shadcn，确认别名路径与 components.json 正确，添加基础原语（button、input、dialog 等）。二、定义颜色、间距、圆角的 CSS 变量，保持组件变体与产品语义一致，避免跨页面样式漂移。三、表单用 RHF + Zod + shadcn 表单原语；对话框用受控 open 状态与焦点管理；表格感知服务端状态的加载、空、错误态；提示统一成功/错误消息模式。四、质量门：验证键盘支持与焦点陷阱，校验 ARIA 标签与角色，保证组件 API 在各功能模块间一致。
代理输出要求：安装与配置步骤、令牌/主题方案、组件组合模式、无障碍与测试清单。
限制：原始资料未提供具体版本、安装命令、收费信息或平台要求，暂未提供，需参考 references/guide.md 获取完整命令与示例。