shadcn-registry-first

优先使用 Shadcn 注册表

Darkmatter 付费使用 @shadcnblocks 区块注册表，并将它和免费的 @shadcn 注册表接入 shadcn MCP。这意味着，大多数常见的 UI 界面——主视觉区、导航栏、页脚、定价表、功能网格、仪表板、登录页、数据表格——都已有生产级、无障碍且可主题化的区块，只需一条命令即可安装。优先使用这些区块，比从空白文件编写 JSX 更快，产出也更好。

此技能要纠正的默认错误：Agent 悄悄手动编写注册表中已有的主视觉区或定价表，既浪费 token，产出也不够精致。在从头编写新组件之前，先检查注册表中是否已有合适的区块。

适用场景

• 构建新的营销／落地页区块：主视觉区、功能网格、CTA 横幅、用户评价、品牌 Logo 墙、页脚、定价区。
• 构建应用框架：导航栏、侧边栏、仪表板外壳、设置面板。
• 构建常见的交互界面：表单、身份验证页面、数据表格、命令面板、文件上传、日历、图表。
• 为现有组件重新设置样式或替换组件，且使用更简洁的注册表区块即可实现。
• 用户说“添加一个 X 区块”“构建一个 Y 页面”“我需要一个 Z 组件”，且 Z 是常见的 Web UI 模式。

不适用场景

• 组件确实与特定领域相关（例如流动性区间刻度图、特定协议的仓位卡片）——通用注册表中不会有这类组件，因此应自行构建，最好组合使用注册表中的基础组件。
• 项目不是 React 项目，或者没有配置注册表的 components.json。请先检查（见下文）；如果未配置任何内容，则此技能不适用。
• 微小的一次性元素（单个样式化按钮、标签），安装一个区块比编写一行代码更麻烦。
• 你要修改的是现有组件的内部实现，而不是添加新的界面。

工作流

1. 确认已配置注册表

使用 shadcn MCP 的 get_project_registries 工具（或读取 components.json）。你应能看到 @shadcnblocks 和／或 @shadcn。如果已配置 @shadcnblocks，但 API 密钥无法解析，请参阅下方的“注册表访问”；不要只因为缺少密钥就退回手动编写，应修复密钥。

2. 搜索并至少筛选出三个候选项

使用 search_items_in_registries，按所需模式搜索，并将范围限定为已配置的注册表。搜索具体内容，而非关键词：

• search_items_in_registries(registries=["@shadcnblocks"], query="hero dark")
• search_items_in_registries(registries=["@shadcnblocks"], query="pricing toggle")
• search_items_in_registries(registries=["@shadcnblocks"], query="dashboard analytics")

@shadcnblocks 规模很大（1000+ 个区块）；搜索“hero”会返回数百个结果。添加限定词缩小范围（“hero split”“hero video”“hero dark”），并浏览描述——描述经过精简，方便快速浏览，也会说明布局、分栏和显著特性。

从结果中挑选至少三个不同的候选项，每个都应有可能满足需求。优先选择真正多样的方案——布局、信息密度或视觉重点各不相同，而不是三个近乎相同的区块。这样做是为了让用户真正有选择，就像提供多种字体或配色方案，而不是默默替用户做决定。

搜索结果可能非常庞大。如果单次调用返回的列表被大量截断，不要把整份输出都读入自己的上下文；应交由 explore Agent 使用 Grep/Read 处理已保存的工具输出文件，或使用更精确的查询重新搜索。

3. 预览每个候选项

对于每个入围候选项，检查你准备引入的内容：

• get_item_examples_from_registries — 查找演示示例及其完整源码，以便了解实际标记和 props。
• view_items_in_registries — 查看该项的文件、依赖项和注册表依赖项（它引入的其他组件）。

确认每项都符合项目的设计系统（主题令牌、字体、圆角）。许多区块默认使用 shadcn 主题；如果项目覆盖了令牌（例如终端主题中的 --radius: 0），区块会适配这些令牌，但请检查是否存在需要协调的硬编码颜色或圆角。

4. 安装所有变体

使用 get_add_command_for_items 获取每个添加命令并运行（通常是 bunx shadcn@latest add @shadcnblocks/<name>）。这会将每个组件写入项目的 ui/components 别名目录并安装依赖项。请将各个变体彼此隔离——把它们安装到名称清晰的文件或临时目录中，这样替换或删除某个变体时就不会影响其他变体。

5. 构建对比界面

务必让用户能够并排查看已构建的各个变体，而不只是在聊天中看到名称。参照字体对比模式：在同一屏幕上呈现每个变体，为每个选项清晰标注，并使用相同的代表性内容，确保唯一的区别就是区块本身。

• 带路由的 Web 应用（TanStack Router、Next）：添加一个临时路由，例如 /compare/<feature>，导入并纵向排列所有变体，并为每个选项添加标题。明确标注这是一次性内容（添加 // TODO: remove after selection 注释），并确保绕过任何身份验证或启动门控，以便用户可以查看。
• 组件 / Storybook：创建一个以单行展示各个变体的画廊故事。
• 运行开发服务器，并向用户提供可正常访问的预览 URL（例如此环境中由 Tailscale 提供的开发 URL）。不要让他们凭空想象效果——让他们直接查看。

对比界面必须通过构建检查（lsp_diagnostics、check-types 和项目构建），之后才能展示给用户。

6. 让用户选择，然后调整胜出项

展示带有清晰标签的选项和预览 URL，并询问用户要保留哪一个。用户选定后：

• 将胜出项接入真实数据和路由，删除演示用占位文案，协调主题差异，并移除不需要的部分。
• 删除其他变体和临时对比界面，避免它们在代码库中逐渐过时。

目标是从精致、易访问的结构开始，让用户从真正构建完成的选项中做出选择，而不是直接交付找到的第一个区块，或遗留 Lorem ipsum 占位文本。

7. 审查

确定胜出项并删除其他内容后，运行 shadcn MCP 的 get_audit_checklist 并逐项检查（导入能正常解析、依赖项已安装、没有遗留演示数据或对比界面脚手架、类型检查通过）。然后运行项目自身的检查（lsp_diagnostics、check-types、构建）。

注册表访问

@shadcnblocks 注册表要求在 components.json 的 Authorization 标头中提供 API 密钥。在 darkmatter 仓库中，会按项目处理：

• components.json 被 Git 忽略，且包含解析后的密钥（或者 shadcn MCP 从环境变量 ${SHADCNBLOCKS_API_KEY} 中读取密钥）。
• components.json.template 已提交，其中包含 ${SHADCNBLOCKS_API_KEY} 占位符。
• 密钥存储在密钥库中（himitsu：himitsu read shadcnblocks-api-key，或 SOPS 加密的密钥）。小型脚本 scripts/setup-components-json.ts 会将密钥写入模板并生成文件。

运行任何 bunx shadcn 命令之前

必须确保渲染后的 components.json 存在且是最新的——上一次会话留下的旧文件可能包含已过期的密钥。请务必先完成以下两步：

1. 生成 components.json：在仓库根目录运行 bun scripts/setup-components-json.ts。此命令会从 himitsu 读取当前密钥，并写入被 git 忽略的 components.json。跳过这一步会导致 401 身份验证失败。
2. cd 到应用目录（例如 apps/web/），然后再运行 bunx shadcn@latest add ...。CLI 会从当前工作目录的 components.json 中解析注册表配置。从 monorepo 根目录运行会失败。
3. 使用 --overwrite 标志，跳过有关已有文件（utils.ts、button.tsx 等）的交互式提示；这些文件可能是该区块所依赖的，但已存在于项目中。

典型调用：

# From repo root:
bun scripts/setup-components-json.ts
cd apps/web
bunx shadcn@latest add @shadcnblocks/hero253 --overwrite

如果注册表调用因缺少环境变量或身份验证错误而失败，解决方法是从密钥存储中填入密钥，而不是放弃使用注册表并手动编写组件。有关加密配置以及预期的密钥处理模式，请参阅 sops-secret-access 技能。

将屏幕中稳定的部分迁移到仓库的共享 UI 包中（包名因仓库而异；请参阅 ADR-0013）。

与其他技能的关系

• sops-secret-access — 如何_访问_加密的注册表配置和密钥。本技能侧重于_优先使用注册表组件_；该技能则介绍如何连接到私有注册表。
• ui-ux-pro-max — 设计智能（样式、配色、布局、a11y）。用它来决定好的 UI 应该是什么样子；用本技能来_获取_实现这些设计的组件。两者可以结合使用：用 ui-ux-pro-max 选择美学风格，然后在注册表中搜索匹配的区块。
• vercel-react-best-practices — 为围绕已安装区块及其内部编写的 React 代码提供性能模式。