ShadcnSpace — AI 代理程式技能與開發者指南

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 與 Radix UI — 完整命令指南

ShadcnSpace 提供雙變體支援：每個區塊、元件與完整頁面都同時維護 Base UI 與 Radix UI 兩種基礎元件的版本。

了解差異

Base UI（建議）：shadcn UI 的現代基礎。使用統一的 @base-ui/react 套件，使用明確的 render props 而非 Slot，並使用獨立的 Positioner 元件。
Radix UI：經典的無頭元件基礎。使用個別的 @radix-ui/react-* 套件以及 asChild prop 搭配 Slot。

1. Base UI 命令

透過註冊中心命名空間（建議 — Shadcn CLI v3）

# 區塊與元件
npx shadcn@latest add @shadcn-space/<項目名稱>

# 範例：
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/<頁面名稱>
# 範例：
npx shadcn@latest add @shadcn-space/pages/landing-page-01

透過直接 URL（Shadcn CLI v2 / 備援）

# 區塊與元件
npx shadcn@latest add https://shadcnspace.com/r/<項目名稱>.json

# 頁面
npx shadcn@latest add https://shadcnspace.com/r/pages/<頁面名稱>.json

2. Radix UI 命令

透過註冊中心命名空間（建議 — Shadcn CLI v3）

# 區塊與元件
npx shadcn@latest add @shadcn-space/radix/<項目名稱>

# 範例：
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/<頁面名稱>
# 範例：
npx shadcn@latest add @shadcn-space/pages/radix/landing-page-01

透過直接 URL（Shadcn CLI v2 / 備援）

# 區塊與元件
npx shadcn@latest add https://shadcnspace.com/r/radix/<項目名稱>.json

# 頁面
npx shadcn@latest add https://shadcnspace.com/r/pages/radix/<頁面名稱>.json

3. 套件管理器語法

您可以在所有主要的套件執行器上執行任何 ShadcnSpace 安裝命令：

套件管理器	命令語法
npm	`npx shadcn@latest add @shadcn-space/<名稱>`
pnpm	`pnpm dlx shadcn@latest add @shadcn-space/<名稱>`
bun	`bunx --bun shadcn@latest add @shadcn-space/<名稱>`
yarn	`yarn dlx shadcn@latest add @shadcn-space/<名稱>`

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/<名稱>。
4. 如果安裝頁面，請確保前綴為 pages/： npx shadcn@latest add @shadcn-space/pages/<名稱>。

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 與 Radix UI）

原因：在僅安裝 Base UI 的專案中使用 Radix UI 區塊，反之亦然。
症狀：Module not found: Can't resolve '@radix-ui/react-...' 或 Cannot find module '@base-ui/react'。
解決方案：
- 如果您的專案使用 Base UI：請安裝標準的 Base UI 變體（@shadcn-space/<名稱>）。確保已安裝 @base-ui/react（pnpm add @base-ui/react）。
- 如果您的專案使用 Radix UI：請安裝 Radix 變體（@shadcn-space/radix/<名稱>）。確保所需的 @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 議題與社群	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`	傳回無障礙性、主題與響應式設計檢查清單

代理程式使用模式與提示

在 Cursor、Claude Code 或 Windsurf 中對 AI 代理程式下提示時，請使用下列結構化模式：

單一區塊生成

使用 ShadcnSpace Hero 01（Base UI）為我的 SaaS 新增一個高轉換率的英雄區塊。

使用 ShadcnSpace Radix UI Pricing 01 建立一個包含月/年切換功能的定價區塊。

使用 ShadcnSpace 儀表板區塊新增一個管理側邊欄和統計卡片。

完整落地頁面組合（單次傳遞）

使用 ShadcnSpace 區塊建立一個完整的 SaaS 落地頁面：
- 導覽列：ShadcnSpace 的黏性毛玻璃導覽列
- 英雄區塊：Hero 01，附互動徽章與影片預覽
- 功能區塊：Bento Grid 01，附微動畫
- 社交證明：ShadcnSpace 的推薦跑馬燈
- 定價區塊：Pricing 01，3 個方案與帳單切換
- 頁尾：ShadcnSpace 的 Footer 01
只安裝我要求的區塊，不要安裝任何未明確指定的區塊。

授權與貢獻

ShadcnSpace 在 MIT 授權下發布。鼓勵社群貢獻。請造訪 GitHub 儲存庫提交拉取請求、回報問題或請求新功能。

此技能文件旨在協助開發者與 AI 代理程式有效率地使用 ShadcnSpace。如需即時更新，請務必參閱官方文件。

在你喜歡的 AI 中提問

說明文件

ShadcnSpace — AI 代理程式技能與開發者指南

快速開始 — 如何使用 ShadcnSpace

步驟 1：在專案中初始化 Shadcn

步驟 2：在 components.json 中設定註冊中心

免費區塊與元件：

Pro 使用者（含授權金鑰）：

步驟 3：安裝區塊與元件

步驟 4：在程式碼中匯入並使用

Base UI 與 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 與 Radix UI）

4. 問題：「檔案已存在」提示或衝突

5. 問題：樣式損壞或缺少顏色

6. 問題：找不到 components.json

文件與協助目錄

ShadcnSpace MCP 伺服器整合

Cursor 設定（~/.cursor/mcp.json）

Windsurf 設定

Claude Code 設定

Lovable & Bolt 設定

可用的 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`）