shadcn-component-discovery

shadcn 组件发现

在投入精力自定义实现之前，先从整个 shadcn 生态系统（包括用户尚未配置的注册表）中发现现有组件。

如何与官方 shadcn 技能互补

官方 shadcn 技能（随 CLI v4 发布）会搜索用户在 components.json 中声明的注册表。用户确定要使用哪些注册表后，这就是合适的工具。

此技能弥补了上游空缺：让用户了解整个生态系统。它帮助用户发现并选择可能尚未配置的注册表——例如，用于动画的 Magic UI、用于主视觉区域的 Aceternity、用于聊天界面的 AI Elements、用于语音组件的 ElevenLabs UI 等。遇到“有哪些现成方案”这类问题时，使用此技能；遇到“安装这个我已经了解的组件”这类需求时，则交由官方技能处理。

两种技能都适用时，先运行此技能（发现），再由官方技能接手安装和项目相关工作。

核心原则

先搜索，再构建。shadcn 生态系统已经解决了大多数 UI 需求。检查注册表花费 10 秒，几乎总比从头自定义实现已有组件更划算。

触发时机

主动触发（编写任何组件代码之前）：

• 用户要求构建表格、表单、模态框、侧边栏、仪表板、身份验证页面、着陆页区域、动画、轮播图、图表或任何常见 UI 模式
• 用户描述的功能隐含了 UI 需求（例如，“添加用户账户管理” → 表格；“让用户选择日期范围” → 日期选择器）
• 用户提到要构建“像 X 一样”的东西，且 X 是常见模式

明确触发（用户直接要求搜索）：

• “找一个……组件”
• “shadcn 有……组件吗？”
• “搜索注册表，查找……”
• “有哪些……？”
• “有什么好的[类别]组件吗？”
• 直接提及特定注册表（@animate-ui、Magic UI、Aceternity、Tailark 等）

工作流

步骤 1：明确需求

搜索之前，先确认：

• 功能：它必须实现什么？（例如，可排序、可筛选、带分页的表格）
• 样式：动画、简约、优先考虑无障碍、紧凑还是粗野主义？
• 约束：必须支持键盘导航吗？拖放呢？优先适配移动设备吗？需要 SSR 吗？

用两句话澄清需求，胜过用错误的查询搜索五次。

步骤 2：搜索

根据工具的可用情况选择三种路径。用户有 shadcn 项目时，官方 shadcn MCP 是首选——它会返回真实搜索结果和代码示例。

路径 A：官方 shadcn MCP（首选）

如果 shadcn MCP 服务正在运行（通过 npx shadcn@latest mcp init 或同等方式配置），直接使用其工具：

1. mcp__shadcn__search_items_in_registries
   - registries: ["@shadcn", "@blocks", "@animate-ui", "@reui", "@diceui"]
   - query: "<search term>"
   - limit: 10

2. For promising results, get full details:
   mcp__shadcn__view_items_in_registries
   - items: ["@registry/component-name", "@registry/other"]

3. For implementation examples:
   mcp__shadcn__get_item_examples_from_registries
   - query: "<component>-demo"

4. For the install command:
   mcp__shadcn__get_add_command_for_items
   - items: ["@registry/chosen-component"]

MCP 只会搜索用户在 components.json 中配置的注册表。如果用户要找的是专用组件，建议先将相关注册表添加到 components.json——推荐内容和配置片段请参阅 references/registries.md。

路径 B：shadcn CLI（无 MCP，但有 shadcn 项目）

如果存在 components.json，但未配置 MCP，请使用 CLI v3 随附的命令：

# Search across configured registries
npx shadcn@latest search "<term>"

# Preview a component before installing
npx shadcn@latest view @registry/component-name

# List everything available in a registry
npx shadcn@latest list @registry

建议添加 MCP，以便更好地与 Agent 集成：npx shadcn@latest mcp init。

路径 C：没有项目上下文

如果还没有 shadcn 项目，或者用户只是在探索：

• 根据用户描述的需求，推荐 references/registries.md 中的注册表
• 直接链接到注册表网站，方便用户浏览
• 用户选定方向后，主动协助搭建 shadcn 项目（npx shadcn@latest init）

步骤 3：呈现发现结果

根据上下文调整回复格式。内容要便于快速浏览——用户马上要做决定，而不是要读一篇长文。

主动检查（构建过程中）

当用户没有明确要求搜索，但你仍进行了搜索时：

Before building custom, I found existing options:

1. **@registry/component-name** — [one-line description]
2. **@registry/alternative** — [one-line description]

Want me to install one, or build custom?

控制在五行以内。用户正在推进工作；不要打断节奏。

明确搜索（用户提出请求）

## Results for "<query>"

**Top matches:**

### @registry/component-name ⭐
[What it does in one sentence]
- Fits because: [specific to their need]
- Install: `npx shadcn@latest add @registry/component-name`

### @registry/alternative
[What it does in one sentence]
- Fits because: [specific to their need]
- Install: `npx shadcn@latest add @registry/alternative`

---
Install [1] or [2], see more results, view code example, or build custom?

比较（有多个优质选项，选择很重要）

当有 3 个或更多确实可行、且各有取舍的选项时，使用简短表格。随后给出推荐选项及其安装命令。不要把所有内容都做成表格——表格比普通段落更繁复，只有在确有必要时才使用。

第 4 步：执行选择

• 安装所选项：运行 add 命令，然后根据需要通过 props / 组合进行自定义
• 查看更多：返回其他匹配项，继续翻页
• 查看代码：通过 get_item_examples_from_registries 或注册表的演示 URL 获取示例
• 构建自定义项：继续操作，但请参考最接近的现有组件，了解组合模式（CVA、cn()、data-slot、语义化令牌）

搜索策略

有效的查询词

简短、具体的名词效果最好。查询词保持在 1–3 个词。

查找内容……	尝试搜索……
数据展示	table、data-grid、list
用户输入	form、input、field、select、combobox
导航	sidebar、nav、menu、tabs、breadcrumb
反馈	toast、sonner、alert、notification
覆盖层	dialog、modal、sheet、popover、drawer
媒体	carousel、gallery、image
动画	animate、motion、transition
布局	card、section、hero、grid、stack
日期/时间	calendar、date-picker、date-range

注册表专长（快速选择）

需求	优先查看
核心 UI 基元	@shadcn
页面区块、预构建模块	@blocks、Tailark、HextaUI
数据网格、高级表格	@reui
动画组件	@animate-ui、Magic UI、Aceternity UI
AI / 聊天界面	AI Elements、assistant-ui
无障碍优先（React Aria）	@diceui、JollyUI、Intent UI
语音 / 音频	ElevenLabs UI
营销 / 落地页	Tailark、Eldora UI
风格变体（粗野主义、复古、玻璃质感）	查看 references/registries.md

完整目录（包括 URL、配置片段和注册表专长）请参阅 references/registries.md。

回复要求

每条发现结果回复都应展示：

1. 搜索内容 — 使用的查询词
2. 前 2–3 个推荐选项 — 带注册表名称的选项名、一句话描述、适用原因
3. 安装命令 — 可直接复制
4. 推荐意见 — 在有明确适用选项时，说明应选择哪一个
5. 后续选项 — 安装、查看代码、查看更多、自定义构建

除非用户提出要求，否则不要提供其他内容。简洁有助于保持交流顺畅。

示例

主动检查

用户：“添加一个用于展示用户账户并支持排序的表格”

回复：

在自定义构建之前，我找到了现有选项：

1. @reui/data-grid-table — 功能全面的网格，支持排序、筛选和分页
2. @shadcn/table — 无样式的基元（可搭配 TanStack Table 实现排序）

@reui/data-grid-table 看起来很合适——要安装它吗？

明确搜索

用户：“帮我找一个带动画的手风琴组件”

回复：

“animated accordion”的搜索结果

@animate-ui/components-base-accordion ⭐

基于 Motion 构建的手风琴组件，具有流畅的进入/退出过渡效果。

• 适用原因：内置动画、支持无障碍访问，并包含键盘导航
• 安装：npx shadcn@latest add @animate-ui/components-base-accordion

@shadcn/accordion

基于 Radix 的标准手风琴组件，默认不带动画。

• 适用原因：依赖更轻量；可自行添加动效
• 安装：npx shadcn@latest add @shadcn/accordion

---

安装带动画的 [1]、安装普通版 [2]，还是查看更多？

没有合适的匹配项

用户：“查找用于可视化 Git 提交谱系的组件”

回复：

“git commit lineage”的搜索结果

shadcn 生态系统中没有直接匹配的组件。较为接近的选项：

• @reui/tree — 树形可视化（可进行改造）
• @shadcn/chart — 通用图表库（基于 Recharts）

这需要自定义构建。你希望我以其中一个为基础构思实现方案，还是查看 @gitgraph/react 等非 shadcn 库？

最佳实践

建议：

• 编写组件代码前先搜索——务必如此
• 提供 2–3 个选项，而不是 10 个
• 说明每个选项为何适合具体需求
• 附上安装命令，而不只是名称
• 在选择明确时给出推荐

不建议：

• 因为“自己构建更快”而跳过搜索（通常并非如此）
• 罗列完整的搜索结果——应筛选整理
• 推荐用户尚未配置的注册表，却不提及 components.json 步骤
• 推荐无人维护或已弃用的注册表（查看 references/registries.md 了解当前状态）

资源

• 注册表目录：references/registries.md
• shadcn 官方文档：https://ui.shadcn.com
• shadcn 官方 MCP 文档：https://ui.shadcn.com/docs/mcp
• 注册表浏览器：https://registry.directory
• 组件索引：https://shadcnregistry.com