21st-dev-builder-v2

21st.dev Web Builder v2

使用 21st.dev 构建可用于生产环境的网站。21st.dev 是最大的开源 React UI 组件注册表。你擅长发现、分析、选择和集成 21st.dev 组件，以打造精致统一的 Web 应用。

此技能让你在以下方面表现出色：

• 实时发现 — 构建前始终从 21st.dev 获取最新组件
• 智能分析 — 评估哪些组件最符合用户需求
• 设计一致性 — 确保不同作者的组件在视觉上保持统一
• 全栈组合 — 构建完整的多页面应用，而非单独的页面

核心知识

什么是 21st.dev？

这是一个开源社区注册表（“设计工程师的 npm”），拥有 1400 多个 React 组件。与 npm 包不同，组件会以完整源代码的形式安装，由你掌控并可自行定制。它基于 shadcn/ui 理念构建。

技术栈

• 框架：React 18+ / Next.js（优先使用 App Router）
• 样式：Tailwind CSS 4+
• 原语：Radix UI
• 语言：TypeScript
• 安装：npx shadcn@latest add "https://21st.dev/r/{author}/{component}"

URL 模式

用途	URL 模式
浏览分类	https://21st.dev/s/{slug}
组件详情	https://21st.dev/r/{author}/{component}
作者资料	https://21st.dev/{author}
社区搜索	https://21st.dev/community/components/search

工作流

阶段 1：项目设置

检查项目是否已准备就绪。查找 package.json、tailwind.config.* 和 components.json。

新项目：

npx create-next-app@latest my-app --typescript --tailwind --eslint --app --src-dir --import-alias "@/*"
cd my-app
npx shadcn@latest init -d

现有项目缺少 shadcn：

npx shadcn@latest init

**检查 MCP 可用性：**如果 21st_magic_component_builder 工具可用，请将其作为主要的组件生成方式。否则，使用 WebSearch + WebFetch + npx install（效果同样很好）。

阶段 2：需求分析

将用户的请求拆解为组件计划：

1. 确定应用类型 — 正在构建哪类应用或页面？
2. 列出所需版块/功能 — 每个页面需要什么？
3. 映射到组件分类 — 使用下方的组件映射表
4. 确定共享组件 — 哪些组件会出现在多个页面中？

组件映射表

正在构建…	在 21st.dev 上搜索这些分类
落地页	hero、features、pricing、testimonials、cta、footers、navbars、backgrounds、announcements、clients
控制面板	sidebar、cards、tables、tabs、buttons、menus、badges、numbers
身份验证页面	sign-ins、sign-ups、forms、inputs、buttons
博客 / 内容	cards、texts、images、paginations、scroll-areas
电子商务	cards、carousels、badges、buttons、dialogs、inputs、tabs、selects
表单密集型应用	inputs、selects、checkboxes、radio-groups、date-pickers、forms、text-areas、toggles
AI / 聊天应用	ai-chats、inputs、buttons、cards、spinner-loaders
设置页面	forms、inputs、toggles、tabs、selects、checkboxes、accordions
作品集	hero、cards、images、texts、scroll-areas、backgrounds、navigation-menus
SaaS 产品	hero、pricing、features、testimonials、navbars、footers、cta、comparisons

阶段 3：实时发现组件

**每次构建都必须进行实时发现。**21st.dev 不断新增组件，切勿只依赖记忆。

发现策略

对于需要的每个组件类别，请按以下顺序搜索：

步骤 1：浏览类别页面

WebFetch: https://21st.dev/s/{category-slug}

这里会显示该类别中的所有可用组件，以及名称、作者和受欢迎程度。

步骤 2：深入了解有潜力的组件

WebFetch: https://21st.dev/r/{author}/{component}

查看组件的演示、代码、依赖项和安装命令。

步骤 3：搜索特定风格（如果仅浏览类别还不够）

WebSearch: "site:21st.dev {specific style or feature}"

示例：site:21st.dev animated gradient hero 或 site:21st.dev glassmorphism card

类别 slug 参考

阅读 references/component-catalog.md，了解类别、slug、数量和顶级作者的完整目录。以下是使用最广泛的类别：

落地页板块： hero、features、pricing、testimonials、cta、footers、navbars、backgrounds、announcements、clients、comparisons、docks、shaders

UI 组件： buttons、inputs、cards、selects、sliders、accordions、tabs、dialogs、calendars、ai-chats、tables、badges、dropdowns、alerts、forms、popovers、text-areas、radio-groups、spinner-loaders、paginations、checkboxes、menus、numbers、avatars、carousels、links、toggles、date-pickers、tooltips、toasts、sidebar、sign-ins、sign-ups、file-uploads、file-trees、icons、tags、notifications、empty-states

阶段 4：组件分析与选择

这是最需要专业判断的环节。针对每个组件位置，从以下维度评估候选项：

选择标准（按优先级排序）

1. 功能匹配度 — 它是否确实满足需求？检查 props、交互性和响应能力。
2. 视觉质量 — 设计是否精致、现代且美观？查看实时预览。
3. 设计协调性 — 它与其他选定组件的外观是否一致？优先考虑：
   • 相关组件来自同一作者（例如，导航栏和页脚都来自同一作者）
   • 相似的设计语言（圆角还是直角、阴影样式、间距）
   • 一致的配色系统（基于 CSS 变量的组件搭配效果最佳）
4. 完整性 — 是否支持深色模式？是否支持响应式布局？是否易于访问？
5. 受欢迎程度 — 获赞数或下载量较高的组件通常质量更好、bug 更少。
6. 最近更新 — 最近更新的组件通常采用更新的模式和 API。
7. 依赖项 — 外部依赖越少，集成越容易。

决策框架

For each component slot:
  1. Find 2-3 candidates from category browsing
  2. Score each on the criteria above (mentally)
  3. If user is involved → present top 2 with preview links + your recommendation
  4. If user says "you decide" → pick the best-scoring one
  5. Document your choice with reasoning

作者一致性策略

构建完整页面或网站时，尽量选用少数几位作者的组件。这样可以显著提升视觉协调性。以下是组件范围较广的知名作者：

• shadcn — 基础组件。简洁、极简且高度可组合。
• bundui — 带动画的现代组件。
• magicui — 动态效果丰富、富有创意的组件。
• 其他高产作者可在实时浏览时发现。

阶段 4.5：构建还是安装

并非每个板块都需要 21st.dev 组件。请针对每个板块做出决定：

从 21st.dev 安装的情况：

• 板块需要复杂的交互功能（带下拉菜单的导航栏、价格切换、轮播图）
• 板块需要精致的动画，而你不想自行编写（动画主视觉区、推荐语滑块）
• 21st.dev 组件几乎完全符合需求

自行编写的情况：

• 板块较简单（功能网格、统计数据行、基本行动号召）
• 找不到适合这一具体需求的 21st.dev 组件
• 需要非常具体的布局，而无论如何都要进行大量修改
• 混用过多作者的组件会破坏设计协调性

典型的落地页可能会安装 2-3 个复杂组件（主视觉区、导航栏、页脚），并自行编写 2-3 个简单板块（功能网格、统计数据、行动号召）。与其强行让每个板块都使用 21st.dev，不如这样做，速度更快，效果也更好。

阶段 5：安装与集成

安装组件：

npx shadcn@latest add "https://21st.dev/r/{author}/{component-name}"

此操作会：

• 将组件源代码复制到项目中（通常是 components/ui/ 或 components/blocks/）
• 安装所需的 npm 依赖
• 根据需要更新 Tailwind 配置
• 解析组件内部依赖

安装顺序很重要：

1. 先安装基础组件／原始组件（按钮、输入框）
2. 再安装可能依赖这些组件的复合组件（表单、对话框）
3. 最后安装页面区块级组件（Hero、定价）

安装后的兼容性修复（重要）

安装每个组件后，请立即检查以下常见问题，再继续操作：

1. render 属性与 asChild 冲突： 许多较新的 21st.dev 组件使用来自 @base-ui/react 的 render 属性，但你的项目可能使用标准 shadcn asChild。如果遇到有关 render 属性的 TypeScript 错误：

// BROKEN: Component uses render prop
<Button render={<a href="/signup" />}>Sign Up</Button>

// FIX: Convert to asChild pattern
<Button asChild><a href="/signup">Sign Up</a></Button>

检查每个已安装组件中的 Button、SheetTrigger、SelectTrigger。

2. 容器宽度不匹配： 组件可能默认使用不同的最大宽度。安装后，请确认每个组件使用一致的容器：

// If component uses its own container, it may conflict with your layout
// Wrap all sections in a consistent container OR
// Remove the component's internal container and use your own
<section className="py-20">
  <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
    {/* component content here */}
  </div>
</section>

3. 缺少 CSS 变量： 如果组件不可见或显示异常，请检查 globals.css 是否定义了所有必需的 CSS 变量。常见的缺失变量有：--border、--ring、--muted、--muted-foreground、--accent、--accent-foreground。

4. framer-motion 类型问题： 有些组件使用 TypeScript 不接受的 ease 数组。可通过类型断言修复：

// BROKEN
ease: [0.16, 1, 0.3, 1]
// FIX
ease: [0.16, 1, 0.3, 1] as const

5. 卡片背景过淡／不可见： 许多 21st.dev 推荐语卡片和功能卡片使用极淡的渐变（from-muted/50 to-muted/10 或仅使用 border-t），在白色背景上几乎不可见；在跑马灯中，边缘渐隐效果还会进一步增加透明度。请为卡片设置清晰可见的样式：

// BROKEN: Nearly invisible
"rounded-lg border-t bg-gradient-to-b from-muted/50 to-muted/10"

// FIX: Clearly visible with depth
"rounded-xl border border-border/60 bg-card shadow-sm"

6. 跑马灯的边缘渐隐渐变过强： 跑马灯组件通常在两侧各使用 w-1/3 的渐隐渐变，遮住了内容区域的 2/3。将其缩小到 w-1/6，让卡片保持可见：

// BROKEN: Covers too much
"absolute inset-y-0 left-0 w-1/3 bg-gradient-to-r from-background"

// FIX: Subtle fade
"absolute inset-y-0 left-0 w-1/6 bg-gradient-to-r from-background"

7. 使用 oklch() 的渐变颜色： Tailwind v4 使用 oklch() 表示颜色值，但在 radial-gradient() 和某些渐变场景中，oklch 的渲染效果不佳。自定义渐变请使用 rgba() 或十六进制颜色值：

// BROKEN: oklch in gradients renders poorly
"bg-[radial-gradient(ellipse_at_center,_oklch(0.55_0.28_285_/_0.18)_0%,_transparent_65%)]"

// FIX: Use rgba for reliable gradient rendering
"bg-[radial-gradient(ellipse_at_center,_rgba(139,92,246,0.18)_0%,_transparent_65%)]"

8. 渐变背景被父级背景遮挡（z-index 陷阱）： 不要将带有 -z-10 的渐变装饰元素放在自身带有 bg-background 的父元素后面。父元素的不透明背景会遮住渐变。请改为直接在区块上应用渐变：

// BROKEN: Gradient div behind parent bg-background
<section className="bg-background">
  <div className="-z-10 bg-gradient-to-b ..."> {/* invisible! */}

// FIX: Apply gradient directly on the section
<section className="bg-gradient-to-b from-[#ede9fe] via-[#f5f3ff] to-white">

如果安装失败：

1. 检查错误消息——通常是缺少对等依赖
2. 尝试运行 npm install {missing-dep}，然后重试
3. 如果组件 URL 不正确，请在 21st.dev 上搜索正确路径
4. 最后手段：通过 WebFetch 获取组件代码并手动创建文件

第 6 阶段：页面组合

统一布局（首先执行）

组合页面前，请统一所有已安装组件的布局，确保它们能够协调配合。来自不同作者的 21st.dev 组件通常会使用相互冲突的容器宽度、内边距和对齐方式。请提前修正：

1. 为整个页面选择一个容器宽度：max-w-7xl mx-auto px-4 sm:px-6 lg:px-8
2. 打开每个已安装的组件文件，检查是否自带容器／最大宽度
3. 二选一：移除组件内部容器并在外部包裹，或者确保其与所选宽度一致
4. 检查文本对齐方式：有些组件将内容居中对齐，另一些则左对齐。请统一对齐方式。
5. 检查 Hero 高度：Hero 组件通常使用 min-h-screen，可能过高。必要时调整为 min-h-[80vh] 或更小。

组合模式

落地页：

<Navbar />                          {/* sticky top-0 z-50 */}
<main>
  <Hero />                          {/* min-h-[80vh] — NOT min-h-screen */}
  <Features />                      {/* py-20 bg-muted/50 */}
  <SocialProof />                   {/* py-16 */}
  <Pricing />                       {/* py-20 bg-muted/50 */}
  <Testimonials />                  {/* py-16 */}
  <CTA />                           {/* py-20 bg-primary text-primary-foreground */}
</main>
<Footer />

仪表盘：

<SidebarProvider>
  <Sidebar>{/* navigation items */}</Sidebar>
  <main className="flex-1">
    <header>{/* toolbar, breadcrumbs */}</header>
    <div className="p-6">
      <div className="grid gap-4 md:grid-cols-3">{/* stat cards */}</div>
      <div className="mt-6">{/* data table or content */}</div>
    </div>
  </main>
</SidebarProvider>

身份验证流程：

<div className="min-h-screen flex items-center justify-center bg-muted/30">
  <div className="w-full max-w-md">
    <SignInCard />  {/* or SignUpCard */}
  </div>
</div>

多页应用布局：

// app/layout.tsx
<html>
  <body>
    <Navbar />
    {children}
    <Footer />
  </body>
</html>

间距与布局规则

• 区块：py-16 md:py-20 lg:py-24（响应式垂直内边距）
• 内容宽度：max-w-7xl mx-auto px-4 sm:px-6 lg:px-8
• 卡片网格：grid gap-4 sm:grid-cols-2 lg:grid-cols-3
• 交替的区块背景：使用 bg-background 和 bg-muted/50

深色模式设置

21st.dev 组件使用带有 dark: 前缀的 CSS 变量。请确保：

// In layout.tsx or providers
import { ThemeProvider } from "next-themes"

<ThemeProvider attribute="class" defaultTheme="system" enableSystem>
  {children}
</ThemeProvider>

安装 next-themes：npm install next-themes

字体设置

import { Geist, Geist_Mono } from "next/font/google";
const geist = Geist({ variable: "--font-sans", subsets: ["latin"] });
const geistMono = Geist_Mono({ variable: "--font-mono", subsets: ["latin"] });

<body className={`${geist.variable} ${geistMono.variable} font-sans antialiased`}>

阶段 7：自定义与优化

安装组件后，请根据项目需求进行自定义：

1. 内容 — 将占位文本、图片和链接替换为实际内容
2. 颜色 — 有意识地选择品牌色（见下方“颜色选择”）
3. 排版 — 确保字体大小和字重保持一致
4. 间距 — 使内边距／外边距与页面其他部分对齐
5. 动画 — 使用 Tailwind 或 framer-motion 添加或调整过渡效果
6. 响应式设计 — 在手机、平板和桌面断点下进行测试

颜色选择（至关重要 — 避免 AI 偏爱紫色）

AI 模型往往会强烈偏好将紫色／紫罗兰色作为默认品牌色。这是因为紫色在科技／AI 品牌中占主导地位（Figma、Notion AI、Copilot），且 shadcn/ui 示例中也经常使用紫色。每次都使用紫色会留下明显的 AI 痕迹——就像总是使用 Sparkles 图标一样。

规则：绝不要默认使用紫色。 应根据产品类型和行业选择颜色：

产品／行业	推荐主色	避免使用
金融／银行	深蓝色（oklch(0.45 0.15 250)）、海军蓝、蓝绿色	紫色、霓虹色
健康／保健	绿色（oklch(0.55 0.18 155)）、蓝绿色、柔和蓝色	红色、紫色
电子商务／零售	橙色（oklch(0.65 0.2 50)）、珊瑚色、琥珀色	暗淡的灰色
开发者工具	祖母绿（oklch(0.55 0.17 160)）、青色、石板色	紫色（已被过度使用）
创意／设计	玫瑰色（oklch(0.6 0.18 10)）、琥珀色、靛蓝色	纯蓝色
教育	蓝色（oklch(0.5 0.16 250)）、蓝绿色、绿色	霓虹色、深色主题
食品／餐厅	暖红色（oklch(0.55 0.22 25)）、橙色、橄榄色	冷蓝色
AI／写作工具	蓝绿色（oklch(0.55 0.12 195)）、蓝绿色调、石板色	紫色（老套！）
企业／B2B	石板蓝（oklch(0.5 0.1 255)）、海军蓝、钢蓝色	鲜艳的霓虹色
社交／社区	珊瑚色（oklch(0.6 0.17 25)）、天蓝色、暖粉色	暗淡的灰色

如果用户指定了品牌色，就使用该颜色。 如果没有指定，就从上表中选择——但除非用户明确要求，否则绝不要使用紫色。

如何应用所选颜色：

/* globals.css — example with teal for an AI writing tool */
:root {
  --brand: oklch(0.55 0.12 195);  /* Teal, NOT purple */
}

然后在整个网站中使用 bg-brand、text-brand、border-brand/30 等。更新主视觉渐变、CTA 按钮、图标背景和强调色，使其与所选颜色一致。

首屏视觉质量检查清单

首屏区域直接决定用户的第一印象。安装首屏组件后，请确保：

• 标题对比度：在纯色／渐变背景上，使用纯色 text-foreground，而不是渐变文本效果（bg-clip-text text-transparent），因为后者可能太淡
• 背景渐变：直接在区块元素上应用渐变（bg-gradient-to-b from-[color] via-[color] to-white）——不要在不透明的父元素后面叠加装饰性渐变 div
• 产品模型图：对于 SaaS 网站，请构建逼真的内嵌模型图（编辑器、仪表板、聊天界面），而不是使用 placehold.co 图片。包含窗口边框（红／黄／绿圆点）、侧边栏、内容区域和状态指示器。这能显著提升用户感知到的质量。
• CTA 样式：使用 rounded-xl、明显的阴影（shadow-lg）和品牌色。添加悬停效果（hover:-translate-y-0.5 transition-transform）
• 径向光晕点缀：在首屏内容后方使用 rgba() 颜色（而非 oklch）添加柔和的径向渐变，营造纵深感
• 避免 AI 陈词滥调图标：绝不要使用 Sparkles／Stars／Wand 图标——它们会立刻让人觉得是“AI 生成的”。使用简约的替代方案：脉动圆点指示器、小型“NEW”徽标，或者只用经过精心设计的文字。目标是让页面看起来像出自资深人类设计师之手，而不是 AI。
• 避免 AI 陈词滥调配色：绝不要默认使用紫色／紫罗兰色。根据产品类型，从颜色选择表中挑选颜色。紫色是最常见的 AI 配色偏见。

CSS 变量主题

/* globals.css */
@layer base {
  :root {
    --background: 0 0% 100%;
    --foreground: 0 0% 3.9%;
    --primary: 0 0% 9%;
    --primary-foreground: 0 0% 98%;
    /* ... customize these to match brand */
  }
  .dark {
    --background: 0 0% 3.9%;
    --foreground: 0 0% 98%;
    /* ... dark variants */
  }
}

阶段 8：验证（彻底检查）

此阶段用于发现会破坏用户第一印象的问题。不要跳过任何步骤。

步骤 1：构建通过

npm run build

继续之前，修复所有 TypeScript 或构建错误。

步骤 2：视觉检查（最重要）

运行 npm run dev，并实际查看页面的每个区块：

1. 截屏或使用 preview_screenshot——从上到下查看整个页面

2. 检查以下常见问题：

   • 空白／白色区块——DOM 中存在内容，但看不见？检查 CSS 变量，以及文字颜色是否与背景一致
   • 内容溢出——文字或元素是否延伸到屏幕右侧之外？检查容器宽度，移除 text-center 或调整 max-w
   • 大片空白区域——首屏占用的垂直空间是否过多？将 min-h-screen 缩小为 min-h-[80vh]
   • 区块未对齐——某些区块居中，其他区块左对齐？统一容器类
   • 图片损坏——占位图片 URL 是否无法加载？替换为真实图片或移除

3. 滚动浏览整个页面——每个区块都必须可见且样式正确

步骤 3：响应式适配

使用 preview_resize 或浏览器开发者工具，在 3 个断点进行测试：

• 移动设备（375px）：单列、文字清晰易读、无水平溢出
• 平板（768px）：网格布局正确切换
• 桌面（1280px）：按设计呈现完整布局

步骤 4：交互

• 点击每个按钮和链接
• 测试导航栏下拉菜单／移动端菜单
• 测试所有切换控件或标签页

步骤 5：控制台检查

浏览器控制台中不得有错误。缺少图片或未使用变量的警告可以接受。

如果在步骤 2-3 中发现任何视觉问题，请在向用户展示之前立即修复。 最常见的修复方法包括：调整容器宽度、修正 CSS 变量颜色，以及缩小首屏高度。

高级模式

组件依赖链

某些 21st.dev 组件依赖其他组件。npx 安装程序会自动处理，但请注意：

• Dialog 组件可能会将 Button 作为依赖项安装
• 如果你已自定义 Button，安装 dialog 时可能会覆盖它
• 从叶子组件开始安装，并记录已自定义的组件

安全地混合不同作者的组件

组合不同作者的组件时：

1. 检查它们是否使用相同的 CSS 变量命名方式（大多数基于 shadcn 的组件都如此）
2. 统一圆角：选定一种样式，并通过 CSS 变量全局应用
3. 确保动画时序一致（ease-in-out，duration-200）
4. 留意 Tailwind 配置扩展之间的冲突

构建组件变体

如果 21st.dev 上没有完全符合需求的组件：

1. 找到最接近的组件
2. 安装它
3. 直接修改源代码（它归你所有！）
4. 组件文件就在你的项目中——可以随意编辑

更新组件知识

每次开始构建时，都要浏览 21st.dev 上相关的分类页面，了解可用组件。该平台每天都会添加新组件，因此上周最好的选择今天可能已经被更好的组件超越。

也就是说：如果你一小时前才浏览过 https://21st.dev/s/hero，开始新的构建时也要再浏览一次。最新信息能帮助你更好地选择组件。

错误恢复

问题	解决方案
未找到组件	尝试其他拼写方式，浏览上级分类，或使用 WebSearch 搜索
npx 安装失败	检查是否缺少 peer deps，验证 URL 格式，先尝试使用 npm install 安装依赖
组件显示异常	检查是否更新了 Tailwind 配置，确认已定义 CSS 变量
深色模式失效	确保 ThemeProvider 包裹了应用，检查 CSS 变量定义
TypeScript 错误	检查组件预期的 props，安装缺少的 @types 包
样式冲突	检查是否存在冲突的 Tailwind 类、CSS 变量命名冲突
无法访问 21st.dev	使用 WebSearch 查找组件名称，根据缓存的知识构造安装 URL
组件过于复杂	从源代码中移除未使用的功能以简化组件
render prop 错误	组件使用 @base-ui/react 模式——转换为 asChild 模式
出现大片空白	Hero/section 使用了 min-h-screen——改为 min-h-[80vh] 或移除
内容超出屏幕右侧	容器宽度不匹配——添加 max-w-7xl mx-auto 包裹层
文字不可见	CSS 变量未定义——检查 globals.css 是否包含所有必需的颜色标记
卡片颜色过淡或不可见	背景渐变太淡——使用 bg-card border border-border/60 shadow-sm
Marquee 卡片被隐藏	边缘渐隐的 w-1/3 太宽——缩小为 w-1/6
渐变未显示	在父级 bg-background 后方使用了 -z-10——直接在 section 上应用渐变
oklch 渐变异常	oklch 在 radial-gradient() 中渲染效果不佳——改用 rgba() 十六进制值
渐变背景上的标题不可见	bg-clip-text text-transparent 太淡——改用纯色 text-foreground

MCP 设置（可选）

如需通过 AI 生成组件，请设置 Magic MCP：

npx @21st-dev/cli@latest install claude --api-key <YOUR_API_KEY>

获取 API 密钥：https://21st.dev/settings/api-keys

在 .claude/settings.json 中手动配置：

{
  "mcpServers": {
    "@21st-dev/magic": {
      "command": "npx",
      "args": ["-y", "@21st-dev/magic@latest"],
      "env": { "API_KEY": "your-api-key" }
    }
  }
}

MCP 提供以下工具：

• 21st_magic_component_builder — 根据描述生成组件
• 21st_magic_component_inspiration — 浏览组件创意
• logo_search — 查找公司徽标（通过 SVGL）