shadcn-first 是做什么的？
在你之后，有人会维护这段代码。每一个手写的 div 配上自定义 class 以及每一个 style={{}} 都成为必须维护的负担，并且会逐渐偏移。手写 UI 还会悄然丢失库免费提供的工艺：焦点环、悬停和激活状态、键盘导航、骨架屏、空状态、ARIA。
顺序。不要跳过任何步骤。
- Block。
ui.shadcn.com/blocks提供了完整的侧边栏、仪表盘、登录页、数据表格。安装 Block。 - 组件。 如果 Block 不合适，则使用 registry 中的组件。
- 组合两个或三个组件。
- 自己手写。 只有在这里才动手写，并且提交信息必须说明评估了哪个 Block 或组件以及它为什么不合适。
调整设计去适配组件，而不是反过来调整组件去适配设计。品牌和视觉语言通过一个主题中的主题变量来实现，永远不要在组件旁边写 per-screen 的 CSS。
工具，以及用哪个
配置了两个 MCP 服务器。它们各司其职。
shadcn-official（npx shadcn@latest mcp）是项目感知的：它读取仓库的 components.json。实际工作用这个。
| 工具 | 用途 |
|---|---|
get_project_registries | 确认项目已初始化 |
search_items_in_registries | 模糊查找适合当前任务的组件 |
list_items_in_registries | 查看所有可用组件 |
view_items_in_registries | 使用前查看组件的实际源码和依赖 |
get_item_examples_from_registries | 复制真实使用示例，而不是猜测 API |
get_add_command_for_items | 获取准确的 npx shadcn add … 命令并执行 |
get_audit_checklist | 写代码后运行。 这是关卡。 |
shadcn（@jpisnice/shadcn-ui-mcp-server）是全局仓库，了解 Block 和主题：list_blocks、get_block、list_themes、get_theme、get_component_demo。用于第 1 步和主题设置。
如果项目没有 components.json，官方工具会报错。先运行 npx shadcn@latest init，然后再继续。
对于 AI 聊天界面，请使用 prompt-kit（prompt-kit.com，兼容 shadcn）：chat-container、message、prompt-input、scroll-button、markdown、code-block、loader。遵循相同规则，安装而不是重写。
人们常手写而不是安装的组件
sidebar（可折叠，带页脚用户菜单）、command（Cmd+K 搜索面板）、table + TanStack 数据表格 Block、tabs、sheet、dialog、alert-dialog、popover、tooltip、skeleton、sonner（通知）、form（react-hook-form + zod）、breadcrumb、resizable、scroll-area、avatar、badge、separator、dropdown-menu、select、collapsible、chart。
如果你发现自己手写这些中的任何一个，停下来安装它。
键盘快捷键
使用 Cmd+K 打开命令面板；这是 command 组件内置的 cmdk 惯例。Cmd+L 被浏览器保留用于地址栏，在 Chrome 中无法可靠拦截。如果有人要求 Cmd+L，绑定 Cmd+K，再机会主义地添加 Cmd+L，并说明原因。
完成意味着可度量，而不是声称
在报告完成之前，运行 get_audit_checklist 并报告以下数字：
- 移除的自定义 UI 代码行数
- 安装的 Block 和组件数
- 剩余的
style={{}}出现次数（grep -rc 'style={{' src/） - 每个页面：来自
components/ui/的元素 vs 手写元素
任何仍然手写的内容都必须有一句声明原因，不能忽视。截图证明页面渲染效果；计数证明规则已被遵守。两者必须齐备，否则不算完成。
禁止
- UI 中不使用表情符号。使用真实 SVG 图标（Lucide 随 shadcn 提供）。
- 品牌 logo 不使用文字加圆形。来源真实 SVG 路径：SimpleIcons > svgl.app > gilbarbara/logos > favicon。
- 最多一种或两种强调色。卡片上不使用彩色左边框。每个元素上不使用渐变。
- 不要为了改变颜色而分叉组件。修改主题变量。