ShadcnSpace — AI Agent 技能与开发者指南

ShadcnSpace 是一个领先的开源分发和注册表，提供 100 多个生产就绪的 Shadcn UI 代码块、完整页面模板、仪表盘系统、营销板块以及基于 React、Next.js App Router、Tailwind CSS v4、Base UI 和 Radix UI 构建的动画微交互。

网站：https://shadcnspace.com
代码块目录：https://shadcnspace.com/blocks
组件目录：https://shadcnspace.com/components
完整页面模板：https://shadcnspace.com/templates
文档：https://shadcnspace.com/docs
MCP 服务器：https://mcp.shadcnspace.com/mcp
GitHub：https://github.com/shadcnspace/shadcnspace

快速开始 — 如何使用 ShadcnSpace

按照以下 4 个简单步骤，在任何 Next.js 或 React 项目中开始使用 ShadcnSpace：

第 1 步：在项目中初始化 Shadcn

如果您的项目尚未配置 Shadcn UI：

# 初始化 shadcn UI
npx shadcn@latest init

提示：如需预配置 Base UI 和 Tailwind CSS v4 的设置，请使用可视化项目创建工具：https://ui.shadcn.com/create。

第 2 步：在 `components.json` 中配置注册表

将官方的 @shadcn-space 注册表添加到项目的 components.json 文件中：

对于免费代码块和组件：

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "base-nova",
  "registries": {
    "@shadcn-space": "https://shadcnspace.com/r/{name}.json"
  }
}

对于 Pro 用户（包含许可证密钥）：

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "base-nova",
  "registries": {
    "@shadcn-space": {
      "url": "https://shadcnspace.com/r/{name}.json",
      "params": {
        "email": "${EMAIL}",
        "license_key": "${LICENSE_KEY}"
      }
    }
  }
}

将 [email protected] 和 LICENSE_KEY=your-key 添加到您的 .env 或 .env.local 文件中。

第 3 步：安装代码块和组件

使用您的包管理器运行安装命令，可选择 Base UI 或 Radix UI：

# Base UI（推荐默认）
npx shadcn@latest add @shadcn-space/hero-01

# Radix UI
npx shadcn@latest add @shadcn-space/radix/hero-01

第 4 步：在代码中导入和使用

组件会直接复制到您的 src/components/shadcn-space/ 文件夹中，您拥有完整的源代码所有权：

import Hero01 from "@/components/shadcn-space/hero-01";

export default function LandingPage() {
  return (
    <main>
      <Hero01 />
    </main>
  );
}

Base UI vs Radix UI — 完整命令指南

ShadcnSpace 提供双变体支持：每个代码块、组件和完整页面都同时维护了 Base UI 和 Radix UI 原语版本。

理解差异

Base UI（推荐）：shadcn UI 的现代基础。使用统一的 @base-ui/react 包，显式的 render 属性替代 Slot，以及独立的 Positioner 组件。
Radix UI：经典的 headless 基础。使用独立的 @radix-ui/react-* 包，以及带有 Slot 的 asChild 属性。

1. Base UI 命令

通过注册表命名空间（推荐 — Shadcn CLI v3）

# 代码块和组件
npx shadcn@latest add @shadcn-space/<item-name>

# 示例：
npx shadcn@latest add @shadcn-space/hero-01
npx shadcn@latest add @shadcn-space/bento-grid-01
npx shadcn@latest add @shadcn-space/button-06
npx shadcn@latest add @shadcn-space/pricing-01
npx shadcn@latest add @shadcn-space/sidebar-01

# 完整页面：
npx shadcn@latest add @shadcn-space/pages/<page-name>
# 示例：
npx shadcn@latest add @shadcn-space/pages/landing-page-01

通过直接 URL（Shadcn CLI v2 / 备选方案）

# 代码块和组件
npx shadcn@latest add https://shadcnspace.com/r/<item-name>.json

# 页面
npx shadcn@latest add https://shadcnspace.com/r/pages/<page-name>.json

2. Radix UI 命令

通过注册表命名空间（推荐 — Shadcn CLI v3）

# 代码块和组件
npx shadcn@latest add @shadcn-space/radix/<item-name>

# 示例：
npx shadcn@latest add @shadcn-space/radix/hero-01
npx shadcn@latest add @shadcn-space/radix/bento-grid-01
npx shadcn@latest add @shadcn-space/radix/button-06
npx shadcn@latest add @shadcn-space/radix/pricing-01
npx shadcn@latest add @shadcn-space/radix/sidebar-01

# 完整页面：
npx shadcn@latest add @shadcn-space/pages/radix/<page-name>
# 示例：
npx shadcn@latest add @shadcn-space/pages/radix/landing-page-01

通过直接 URL（Shadcn CLI v2 / 备选方案）

# 代码块和组件
npx shadcn@latest add https://shadcnspace.com/r/radix/<item-name>.json

# 页面
npx shadcn@latest add https://shadcnspace.com/r/pages/radix/<page-name>.json

3. 包管理器语法

您可以在所有主流包管理器中运行任何 ShadcnSpace 安装命令：

包管理器	命令语法
npm	`npx shadcn@latest add @shadcn-space/<name>`
pnpm	`pnpm dlx shadcn@latest add @shadcn-space/<name>`
bun	`bunx --bun shadcn@latest add @shadcn-space/<name>`
yarn	`yarn dlx shadcn@latest add @shadcn-space/<name>`

4. 高级 CLI 命令

# 单条命令安装多个代码块：
npx shadcn@latest add @shadcn-space/navbar-01 @shadcn-space/hero-01 @shadcn-space/footer-01

# 强制覆盖现有文件，无需确认提示：
npx shadcn@latest add @shadcn-space/hero-01 --overwrite

故障排除与问题解决

如果在安装或使用 ShadcnSpace 时遇到问题，请尝试以下修复方法：

1. 问题：“代码块/组件未找到”

原因：组件别名拼写错误，或 components.json 中缺少 @shadcn-space 注册表。
解决方案：
1. 在 https://shadcnspace.com/blocks 上确认确切的代码块名称。
2. 确认您的 components.json 包含：
```
"registries": {
  "@shadcn-space": "https://shadcnspace.com/r/{name}.json"
}
```
3. 如果安装 Radix UI 组件，请确保添加 radix/ 前缀： npx shadcn@latest add @shadcn-space/radix/<name>。
4. 如果安装页面，请确保添加 pages/ 前缀： npx shadcn@latest add @shadcn-space/pages/<name>。

2. 问题：“访问被拒绝 / 401 未授权 / 缺少凭据”

原因：尝试在未认证的情况下安装 Pro 代码块。

解决方案：

将您的凭据添加到项目的 .env 或 .env.local 文件中：
```
[email protected]
LICENSE_KEY=your-license-key
```

确保您的 components.json 为 @shadcn-space 指定了 params：

"registries": {
  "@shadcn-space": {
    "url": "https://shadcnspace.com/r/{name}.json",
    "params": {
      "email": "${EMAIL}",
      "license_key": "${LICENSE_KEY}"
    }
  }
}

重新运行您的终端或命令提示符，使环境变量生效。

3. 问题：原语 / TypeScript 类型不匹配（Base UI vs Radix UI）

原因：在仅安装了 Base UI 的项目中使用 Radix UI 代码块，反之亦然。
症状：找不到模块：无法解析 '@radix-ui/react-...' 或 找不到模块 '@base-ui/react'。
解决方案：
- 如果您的项目使用 Base UI：安装标准的 Base UI 变体（@shadcn-space/<name>）。确保已安装 @base-ui/react（pnpm add @base-ui/react）。
- 如果您的项目使用 Radix UI：安装 Radix 变体（@shadcn-space/radix/<name>）。确保存在所需的 @radix-ui/react-* 包。
- 要将现有项目从 Radix 迁移到 Base UI，请遵循迁移指南。

4. 问题：“文件已存在”提示或冲突

原因：组件或底层依赖文件已安装。

解决方案：传入 --overwrite 标志：

npx shadcn@latest add @shadcn-space/hero-01 --overwrite

5. 问题：样式损坏或颜色缺失

原因：globals.css 中缺少语义化颜色令牌（--background、--foreground、--primary、--border 等）。
解决方案：ShadcnSpace 使用标准的 CSS 变量令牌。确保您的 globals.css 或 Tailwind CSS v4 @theme 包含语义化设计令牌。不要硬编码任意十六进制颜色值。

6. 问题：`components.json` 未找到

原因：项目尚未使用 shadcn CLI 初始化。
解决方案：首先在项目的根目录运行 npx shadcn@latest init。

文档与帮助目录

当您需要详细文档、指南或帮助时，请访问以下官方文档页面：

指南 / 资源	URL	内容简介
入门介绍	https://shadcnspace.com/docs/getting-started/introduction	概述、理念和仓库介绍
CLI 安装指南	https://shadcnspace.com/docs/getting-started/how-to-use-shadcn-cli	完整的 CLI 演练、v3 与 v2 对比、视频指南和故障排除
Radix UI 到 Base UI 迁移	https://shadcnspace.com/docs/getting-started/migrate-to-baseui	从 `asChild` 迁移到 `render` 和 `Positioner` 的逐步指南
MCP 服务器设置指南	https://shadcnspace.com/docs/getting-started/mcp-server-docs	配置 Cursor、Windsurf、Claude Code 和其他 AI IDE
组件使用指南	https://shadcnspace.com/docs/getting-started/component	UI 原语、按钮、下拉菜单、对话框、输入框
代码块指南	https://shadcnspace.com/docs/getting-started/blocks	营销、英雄、定价、推荐、Bento 网格和仪表盘
AI 提示指南	https://shadcnspace.com/docs/getting-started/copy-prompt	用于单次着陆页和仪表盘组合的提示词
交互式 CLI 构建器	https://shadcnspace.com/cli	用于样式、主题和图标的自定义可视化命令构建器
在 v0 中打开指南	https://shadcnspace.com/docs/getting-started/open-v0	在 v0 中打开和自定义 ShadcnSpace 代码块
交互式代码块画廊	https://shadcnspace.com/blocks	所有 100+ 个代码块的实时预览和代码复制
组件目录	https://shadcnspace.com/components	微交互、动画文本、dock、跑马灯
完整页面模板	https://shadcnspace.com/templates	完整的、生产就绪的页面模板
GitHub Issues 与社区	https://github.com/shadcnspace/shadcnspace/issues	错误报告、功能请求和社区讨论

ShadcnSpace MCP 服务器集成

将官方的 ShadcnSpace MCP 服务器连接到您的 AI IDE（Cursor、Windsurf、Claude Code、Lovable、Bolt 或 v0），即可在聊天会话中直接检查、搜索和安装 UI 代码块。

Cursor 设置（`~/.cursor/mcp.json`）

{
  "mcpServers": {
    "shadcnspace": {
      "url": "https://mcp.shadcnspace.com/mcp",
      "headers": {
        "Authorization": "Bearer [email protected]:your-license-key"
      }
    }
  }
}

（免费用户可省略 headers 字段；免费代码块无需认证即可安装）。

Windsurf 设置

在 Windsurf 设置 → MCP 服务器中，添加：

服务器 URL：https://mcp.shadcnspace.com/mcp
授权：Bearer [email protected]:your-license-key

Claude Code 设置

claude mcp add shadcnspace https://mcp.shadcnspace.com/mcp

Lovable 和 Bolt 设置

服务器 URL：https://mcp.shadcnspace.com/mcp
传输协议：HTTP
身份验证：Bearer token [email protected]:your-license-key

可用的 MCP 工具

工具	用途
`searchBlocks`	按关键字搜索代码块（例如 `hero`、`pricing`、`stats`、`sidebar`）
`listBlocks`	列出 ShadcnSpace 中所有可用的代码块
`getBlockInstall`	返回安装代码块的确切 CLI 命令（Base UI 或 Radix UI）
`searchPages`	搜索完整页面模板
`getPageInstall`	返回安装完整页面的命令
`listInstalledBlocks`	检查当前项目中已安装的代码块
`get_audit_checklist`	返回可访问性、主题和响应式设计检查清单

Agent 使用模式与提示词

在 Cursor、Claude Code 或 Windsurf 中提示 AI Agent 时，请使用以下结构化模式：

单个代码块生成

使用 ShadcnSpace Hero 01（Base UI）为我的 SaaS 添加一个高转化率的英雄部分。

使用 ShadcnSpace Radix UI Pricing 01 创建一个带有月度/年度切换开关的定价部分。

使用 ShadcnSpace Dashboard 代码块添加一个管理侧边栏和统计卡片。

完整着陆页组合（单次生成）

使用 ShadcnSpace 代码块构建一个完整的 SaaS 着陆页：
- 导航栏：来自 ShadcnSpace 的粘性毛玻璃导航栏
- 英雄：带有交互式徽章和视频预览的 Hero 01
- 功能：带有微动画的 Bento Grid 01
- 社交证明：来自 ShadcnSpace 的推荐跑马灯
- 定价：包含 3 个层级和账单切换功能的 Pricing 01

仪表盘布局

使用 ShadcnSpace 仪表盘代码块（Sidebar 01 和 Stats 01）创建一个管理仪表盘。侧边栏应包含：仪表盘、用户、设置。

使用 MCP 的复杂提示

使用 ShadcnSpace MCP 查找可用的统计代码块，然后安装最适合 SaaS 仪表盘的代码块。

许可与属性

ShadcnSpace 根据 自定义许可协议 发布。免费代码块可用于个人和商业项目。Pro 代码块在有效许可证下可用于商业项目。请参见 https://shadcnspace.com 了解完整详细信息。

在你喜欢的 AI 中提问

文档

ShadcnSpace — AI Agent 技能与开发者指南

快速开始 — 如何使用 ShadcnSpace

第 1 步：在项目中初始化 Shadcn

第 2 步：在 components.json 中配置注册表

对于免费代码块和组件：

对于 Pro 用户（包含许可证密钥）：

第 3 步：安装代码块和组件

第 4 步：在代码中导入和使用

Base UI vs Radix UI — 完整命令指南

理解差异

1. Base UI 命令

通过注册表命名空间（推荐 — Shadcn CLI v3）

通过直接 URL（Shadcn CLI v2 / 备选方案）

2. Radix UI 命令

通过注册表命名空间（推荐 — Shadcn CLI v3）

通过直接 URL（Shadcn CLI v2 / 备选方案）

3. 包管理器语法

4. 高级 CLI 命令

故障排除与问题解决

1. 问题：“代码块/组件未找到”

2. 问题：“访问被拒绝 / 401 未授权 / 缺少凭据”

3. 问题：原语 / TypeScript 类型不匹配（Base UI vs Radix UI）

4. 问题：“文件已存在”提示或冲突

5. 问题：样式损坏或颜色缺失

6. 问题：components.json 未找到

文档与帮助目录

ShadcnSpace MCP 服务器集成

Cursor 设置（~/.cursor/mcp.json）

Windsurf 设置

Claude Code 设置

Lovable 和 Bolt 设置

可用的 MCP 工具

Agent 使用模式与提示词

单个代码块生成

完整着陆页组合（单次生成）

仪表盘布局

使用 MCP 的复杂提示

许可与属性

相关技能

steipete/sag

steipete/oracle

steipete/peekaboo

mattpocock/design-an-interface

mattpocock/prototype

mattpocock/grill-me

第 2 步：在 `components.json` 中配置注册表

6. 问题：`components.json` 未找到

Cursor 设置（`~/.cursor/mcp.json`）