Shadcn UI & Blocks

Shadcn UI 与 ShadcnBlocks 集成

此技能可使用 shadcn/ui 组件和高级 ShadcnBlocks 模板，构建精致的前端。其主要能力是智能推荐适合任何 UI 需求的最佳区块或组件——不仅匹配正确的类别，还要匹配该类别中的正确变体——然后处理设置和安装。

使用时机

在以下情况下启用此技能：

• 创建新的前端、落地页、营销网站或应用 UI
• 项目使用或应使用搭配 Tailwind CSS 的 React/Next.js
• 预构建的 UI 区块（主视觉、定价、功能、用户评价等）可以加快开发
• 用户需要特定的 UI 元素（表单、图表、对话框、导航等）
• 用户提到 shadcn、shadcn/ui、shadcnblocks 或基于 Tailwind 的 UI 组件

区块与组件

	区块	组件
内容	完整的页面区块	可复用的 UI 元素
大小	主视觉、定价、页脚等	按钮、输入框、对话框等
数量	71 个类别，共 1,338 个	60 多个分组，共 1,189 个
访问权限	高级（需要 API 密钥）	免费
安装	@shadcnblocks/<name><number>	@shadcnblocks/<type>-<style>-<number>

使用区块，通过预构建的区块组合出完整的页面布局。 使用组件，在自定义代码中实现独立的 UI 元素。

---

智能选择区块

最多提问 0–2 个问题

推荐区块时，请遵循以下渐进式信息收集流程：

• 0 个问题：用户的需求足够具体，可以直接匹配（例如，“添加一个带邮件收集表单的主视觉” → 根据 cta_pattern: form_capture 匹配）
• 1 个问题：区块明确，但风格或布局不明确（例如，“添加一个功能区块” → 询问布局偏好）
• 最多 2 个问题：区块和风格都不明确（例如，“添加一个展示我们产品的区块” → 先询问区块类型，再询问风格）

提问绝不超过 2 个。 如果仍不明确，就选出最合适的 2–3 个选项并说明取舍。

决策流程：推断 → 提问 → 筛选

步骤 1 — 从需求中推断（始终先执行此步骤）

提问前尽可能提取约束条件：

• 区块类型：hero、feature、pricing、testimonial、cta、faq、navbar、footer、contact、stats
• 目标关键词：“注册” → 转化/收集潜在客户，“信任” → 信任，“比较方案” → 比较
• 布局提示：“网格” → grid_cards，“并排” → split，“手风琴” → 手风琴交互
• 语气提示：“简洁” → 极简，“醒目” → 醒目，“专业” → 企业级
• 媒体提示：“带截图” → 截图媒体，“视频” → 视频媒体
• 密度提示：“简单” → 极简密度，“详细” → 丰富密度

步骤 2 — 提出有针对性的问题（仅在需要时）

使用 AskUserQuestion 通过结构化的多选题进行细化。请参考 references/block-index.md → selection_prompts，查看每种区块预定义的问题和选项。

预定义提示的问题区块： hero、feature、pricing、testimonial、cta、faq、navbar、footer、contact、stats。

功能区块需求示例：

AskUserQuestion:
  question: "How do you want to showcase your features?"
  options:
    - "Card grid (3-4 columns with icons)" — Classic feature grid with icon + description per card
    - "Alternating image + text rows" — Deep-dive with large visuals, great for product tours
    - "Bento / asymmetric grid" — Modern editorial layout with mixed-size cards
    - "Simple icon list or checklist" — Compact, scannable benefit list

如果无法使用 AskUserQuestion，请直接列出带编号的选项，询问相同的问题。

步骤 3 — 匹配标签并返回 2–3 个最佳选项

将用户的回答映射到标签筛选条件，然后与 references/block-index.md 中的条目进行匹配。请严格按照以下格式返回 2–3 条推荐：

Here are the best matches for your [section type]:

1. **[block-id]** — [1-line "why this one"]
   Layout: [layout] · Tone: [tone] · [key differentiator]

2. **[block-id]** — [1-line "why this one"]
   Layout: [layout] · Tone: [tone] · [key differentiator]

3. **[block-id]** — [1-line "why this one"]
   Layout: [layout] · Tone: [tone] · [key differentiator]

Which one works best? I'll install it and set it up.

用户选定后，提供安装命令并将其组合到页面中。

用于匹配的标签维度

以下是 references/block-index.md 中用于区分区块的关键维度：

维度	说明	示例值
layout	视觉布局	居中、右侧分屏媒体、卡片网格、Bento、交替排列
tone	美学风格	极简、现代、大胆、企业风、优雅、活泼
goal	业务目的	提升认知、说明、建立信任、转化、获取潜在客户、比较
cta_pattern	行动类型	单一主要操作、主要操作加次要操作、表单收集、多项操作
media	视觉内容	截图、插图、视频、图标、头像、标志
interaction	动态行为	静态、手风琴、标签页、轮播、切换、悬停
items_count	显示的项目数量	少量、适中、大量
content_density	内容量	极少、标准、丰富
complexity	实现难度	低、中、高

何时使用哪种参考资料

场景	使用
推荐最合适的区块（默认）	references/block-index.md — 带有选择提示的标签推荐
用户想要特定编号的变体	references/block-catalog.md — 包含所有变体编号的完整目录
区块未列入 block-index（例如博客、图库）	references/block-catalog.md — 使用类别默认选项
用户想浏览所有选项	前往 https://shadcnblocks.com/explorer/blocks
需要单个 UI 元素	references/component-catalog.md — 免费组件

---

快速类别参考

对于尚未列入 block-index.md 的区块，请使用以下默认选项：

内容与博客

需求	类别	从以下选项开始
博客列表	blog（22 个变体）	blog1
博客文章页面	blogpost（7 个变体）	blogpost1
更新日志	changelog（7 个变体）	changelog1
代码片段	code-example（5 个变体）	code-example1

关于与团队

需求	类别	从以下选项开始
关于版块	about（17 个变体）	about1
团队页面	team（14 个变体）	team1
公司发展时间线	timeline（15 个变体）	timeline1
职位列表	careers（9 个变体）	careers1

电商

需求	类别	从以下选项开始
商品卡片	product-card（10 个变体）	product-card1
商品列表	product-list（10 个变体）	product-list1
商品详情	product-detail（10 个变体）	product-detail1
购物车	shopping-cart（11 个变体）	shopping-cart1
结账	checkout（6 个变体）	checkout1
订单历史	order-history（5 个变体）	order-history1

应用与仪表板

需求	类别	从以下选项开始
仪表板图表	chart-card（27 个变体）	chart-card10
数据表格	data-table（32 个变体）	data-table1
应用侧边栏	sidebar（21 个变体）	sidebar1
应用外壳布局	application-shell（14 个变体）	application-shell1
用户资料	user-profile（12 个变体）	user-profile1

###作品集

需求	类别	从以下选项开始
图片图库	gallery（48 个变体）	gallery1
项目列表	projects（25 个变体）	projects1
项目详情	project（33 个变体）	project1
案例研究	case-studies（6 个变体）	case-studies1

视觉与装饰

需求	类别	从以下选项开始
背景图案	background-pattern（40 个变体）	background-pattern1
动画着色器	shader（10 个变体）	shader1
Bento 网格布局	bento（8 个变体）	bento1

导航与其他

需求	类别	从这里开始
公告栏	banner（7 个变体）	banner1
促销栏	promo-banner（7 个变体）	promo-banner1
合作伙伴徽标	logos（13 个变体）	logos1
对比	compare（10 个变体）	compare1

---

选择合适的组件

查看 references/component-catalog.md 获取完整目录。主要分组：

需求	组件组	示例
表单布局	表单（86）	form-signin-1
带标签的输入框	字段（38）	field-standard-1
带附加项的输入框	输入组（39）	input-group-standard-1
可搜索的选择框	组合框（42）	combobox-standard-1
文件上传	文件上传（44）	file-upload-standard-1
日期选择器	日期选择器（8）	date-picker-standard-1
警告消息	警告（25）	alert-error-1
确认对话框	警告对话框（39）	alert-dialog-standard-1
加载骨架屏	骨架屏（30）	skeleton-standard-1
Toast 通知	Sonner（24）	sonner-standard-1
空状态	空状态（22）	empty-standard-1
模态对话框	对话框（17）	dialog-standard-1
侧边面板	Sheet（29）/ Drawer（22）	sheet-standard-1
折叠面板	Accordion（21）	accordion-standard-1
数据图表	图表（70）	chart-standard-1
命令面板	命令（21）	command-standard-1
下拉菜单	下拉菜单（30）	dropdown-menu-standard-1
键盘快捷键	KBD（39）	kbd-standard-1

---

核心工作流

1. 确保项目基础配置

确认项目已初始化 shadcn/ui。如果尚未初始化：

npx shadcn@latest init

这会在项目根目录创建 components.json。

2. 配置 ShadcnBlocks 注册表

检查 components.json 中是否已有 @shadcnblocks 注册表。如果没有，请运行：

bash "${CLAUDE_PLUGIN_ROOT}/skills/shadcn-ui/scripts/setup-shadcnblocks.sh" .

这会将 @shadcnblocks 注册表添加到 components.json，并在 .env 中设置 SHADCNBLOCKS_API_KEY。

如果脚本无法运行（例如，缺少 jq），请手动配置：

1. 添加到 .env：SHADCNBLOCKS_API_KEY=<key>
2. 将注册表添加到 components.json：

{
  "registries": {
    "@shadcnblocks": {
      "url": "https://shadcnblocks.com/r/{name}",
      "headers": {
        "Authorization": "Bearer ${SHADCNBLOCKS_API_KEY}"
      }
    }
  }
}

3. 选择并安装区块

使用智能选择流程（见上文）推荐合适的区块，然后安装：

# Blocks (full page sections)
npx shadcn add @shadcnblocks/hero125
npx shadcn add @shadcnblocks/pricing3

# Components (UI elements)
npx shadcn add @shadcnblocks/accordion-standard-1
npx shadcn add @shadcnblocks/file-upload-standard-1

4. 组合页面

在页面布局中导入并组合区块：

import { Navbar1 } from "@/components/navbar1";
import { Hero125 } from "@/components/hero125";
import { Feature3 } from "@/components/feature3";
import { Footer1 } from "@/components/footer1";

export default function LandingPage() {
  return (
    <>
      <Navbar1 />
      <Hero125 />
      <Feature3 />
      <Footer1 />
    </>
  );
}

区块是完全可编辑的源代码，而非锁定的依赖项。安装后可自定义属性和内容。

着陆页组装模式

对于典型的营销着陆页，可使用智能选择流程为每个版块进行选择。常见的组装方式：

npx shadcn add @shadcnblocks/navbar1      # Simple nav with CTA
npx shadcn add @shadcnblocks/hero125      # Modern centered hero
npx shadcn add @shadcnblocks/logos1        # Trust logos strip
npx shadcn add @shadcnblocks/feature3     # 3-column feature cards
npx shadcn add @shadcnblocks/stats1       # Metrics bar
npx shadcn add @shadcnblocks/testimonial1 # Social proof grid
npx shadcn add @shadcnblocks/pricing3     # 3-tier pricing cards
npx shadcn add @shadcnblocks/faq1         # Accordion FAQ
npx shadcn add @shadcnblocks/cta1         # Final call to action
npx shadcn add @shadcnblocks/footer1      # Multi-column footer

这些区块均针对“现代 SaaS”风格进行选择。对于不同的风格（企业级、极简、醒目、活泼），选择流程会推荐不同的变体。

API 密钥管理

ShadcnBlocks API 密钥可通过多种方式提供（按以下顺序检查）：

1. 环境变量（最简单）：在 shell 或 .env 文件中设置 SHADCNBLOCKS_API_KEY
2. 1Password CLI：辅助脚本使用 op read 获取密钥。将 OP_SHADCNBLOCKS_REF 设置为 1Password 引用路径；否则默认使用 op://Platform Infra/ShadcnBlocks API Key/credential

使用辅助脚本获取密钥：

bash "${CLAUDE_PLUGIN_ROOT}/skills/shadcn-ui/scripts/get-api-key.sh"

**安全性：**切勿将 API 密钥硬编码到源文件中。始终在 .env 中使用 SHADCNBLOCKS_API_KEY，并确保 .env 已列入 .gitignore。

故障排除

问题	解决方法
安装时出现身份验证错误	确认 .env 中已设置有效的 SHADCNBLOCKS_API_KEY
找不到注册表	检查 components.json 中是否存在 registries 键
缺少 components.json	运行 npx shadcn@latest init
1Password 访问	运行 op signin；使用 op vault list 验证保管库
找不到区块	在 https://shadcnblocks.com 检查区块名称

参考文件

• references/block-index.md — 带标签的精选区块及其选择提示，可用于智能推荐区块（主要来源）
• references/block-catalog.md — 1,338 个区块的完整目录，涵盖 71 个类别，并包含变体编号和安装命令
• references/component-catalog.md — 1,189 个组件的完整目录，涵盖 60 多个分组，并包含安装语法
• references/setup-guide.md — 详细的分步设置指南及故障排除说明

脚本

• scripts/setup-shadcnblocks.sh — 自动设置项目（获取密钥并配置注册表）
• scripts/get-api-key.sh — 获取 API 密钥（通过环境变量或 1Password）