OpenClaw shadcn/ui 技能指南

OpenClaw shadcn/ui 技能概述

shadcn/ui 技能將 OpenClaw 連接到 shadcn/ui 元件庫，讓您的代理能夠在專案中新增、設定和組合可存取的 React 元件。安裝後，您可以使用自然語言描述來建立完整的 UI 功能——表單、資料表格、導覽列、對話框等。

與傳統以 npm 套件形式發佈的元件庫不同，shadcn/ui 會將元件原始碼直接複製到您的專案中。這意味著您擁有每一行程式碼的完全控制權，可以自由自訂元件而無需對抗函式庫的抽象層。OpenClaw shadcn/ui 技能透過對話方式處理元件選擇、安裝、組合和樣式設定，讓這個工作流程更加快速。

典型工作流程：

1. 要求 OpenClaw 新增一個帶有排序和分頁功能的資料表格。
2. 代理執行 npx shadcn@latest add table 及相關元件，然後根據您指定的欄位生成表格實作。
3. 一個功能完整、符合無障礙標準的資料表格出現在您的專案中——隨時可以自訂。

此技能專為使用 Tailwind CSS 的 React 和 Next.js 專案而設計。它與 Frontend Design 技能天然搭配，提供版面配置和使用者體驗指導，也能與任何設計系統工作流程良好協作。

shadcn/ui 技能安裝前的準備

在安裝 shadcn/ui 技能之前，請確保您已具備：

• 已安裝並運行的 OpenClaw（v1.0+）
• 已設定 Tailwind CSS 的 React 或 Next.js 專案
• Node.js v18+ 及套件管理器（npm、pnpm 或 bun）
• 已安裝用於技能管理的 clawhub CLI

驗證您的環境設定：

# 檢查 OpenClaw 版本
openclaw --version

# 檢查 Node.js 版本
node --version

# 確認 Tailwind CSS 已設定
npx tailwindcss --help

如果您正在建立新專案，代理可以協助您使用 npx shadcn@latest init 初始化一個預先設定好 shadcn/ui 的 Next.js 專案。

如何安裝 shadcn/ui 技能

透過單一指令安裝 shadcn/ui 技能：

npx clawhub@latest install shadcn-ui

驗證安裝是否成功：

clawhub list

您應該會在已安裝的技能清單中看到 shadcn-ui。

shadcn/ui 技能設定指南

shadcn/ui 技能不需要 API 金鑰或外部驗證。它直接使用您的本地專案檔案和 shadcn CLI。

專案初始化

如果您的專案尚未設定 shadcn/ui，代理可以為您初始化：

# 在您的專案中初始化 shadcn/ui
npx shadcn@latest init

這會在專案根目錄建立一個 components.json 設定檔，包含以下設定：

| 設定項 | 說明 | |---------|-------------| | style | 元件樣式變體（default 或 new-york） | | tailwind.baseColor | 主題基礎色（slate、gray、zinc 等） | | tailwind.cssVariables | 是否使用 CSS 變數進行主題設定 | | aliases.components | 元件的匯入路徑別名 | | aliases.utils | 工具函式的匯入路徑別名 |

主題自訂

透過編輯 CSS 變數或要求代理調整色彩來自訂預設主題：

/* 範例：在 globals.css 中自訂主題變數 */
@layer base {
  :root {
    --primary: 222.2 47.4% 11.2%;
    --primary-foreground: 210 40% 98%;
    --secondary: 210 40% 96.1%;
    --secondary-foreground: 222.2 47.4% 11.2%;
  }
}

重要提示： shadcn/ui 元件會複製到您的專案原始碼中。您對每個元件擁有完全控制權——沒有隱藏的依賴關係或鎖定的抽象層。

shadcn/ui 技能使用範例

1. 新增完整表單

你：「建立一個使用者註冊表單，包含姓名、電子郵件、密碼欄位和條款同意核取方塊。使用 zod 進行驗證。」

代理使用 npx shadcn@latest add 安裝所需的元件（form、input、checkbox、button、label），然後生成一個完整的表單元件，包含 zod 結構驗證、錯誤訊息和無障礙標籤。表單遵循 React Hook Form 模式，可直接連接到您的 API。

2. 建構資料表格

你：「新增一個用於顯示使用者的資料表格，包含姓名、電子郵件、角色和狀態欄位。包含排序、篩選和分頁功能。」

代理新增 table 元件，並使用 @tanstack/react-table 建構功能完整的資料表格。它會生成欄位定義、篩選控制項、排序處理器和分頁功能——全部具備正確的 TypeScript 型別和無障礙屬性。

3. 建立儀表板版面配置

你：「設定一個儀表板版面配置，包含可收合的側邊欄、頂部導覽列、麵包屑導覽和主要內容區域。」

代理安裝 sidebar、navigation-menu、breadcrumb 和 separator 元件，然後將它們組合成響應式版面配置，包含適合行動裝置的側邊欄切換和正確的語意 HTML 結構。

4. 新增命令面板

你：「新增一個類似 VS Code 的命令面板，使用 Ctrl+K 快捷鍵讓使用者搜尋頁面和操作。」

代理安裝 command 和 dialog 元件，設定鍵盤快捷鍵監聽器，並建立可搜尋的命令選單，包含分組項目、圖示和導覽處理器。

5. 組合設定頁面

你：「建構一個設定頁面，包含個人資料、帳戶、通知和外觀標籤頁。在每個標籤頁中使用卡片將相關選項分組。」

代理安裝 tabs、card、switch、select 和 separator 元件，然後建構完整的設定介面，包含表單欄位、切換開關和下拉選擇器，按邏輯分組到各個標籤頁中。

安全與最佳實踐

使用 shadcn/ui 技能時，請遵循以下指引：

• 審查生成的程式碼。 代理會直接在您的專案中生成元件程式碼。在提交之前，務必審查新檔案和變更，尤其是表單處理器和 API 整合部分。
• 驗證使用者輸入。 shadcn/ui 提供的是 UI 元件，而非輸入驗證。務必使用 zod 或 yup 等函式庫為表單搭配伺服器端驗證，並在處理前對輸入進行消毒。
• 保持依賴項更新。 shadcn/ui 元件依賴 Radix UI 基礎元件和其他套件。定期執行 npm audit 並更新有漏洞的依賴項。
• 使用語意化 HTML。 代理預設會生成符合無障礙標準的標記，但請確認自訂修改保留了 ARIA 屬性和鍵盤導覽功能。
• 遵循元件模式。 將 shadcn/ui 元件保存在指定的元件目錄中（例如 components/ui/）。避免內聯修改——改為透過組合方式擴展。請參閱安全檢查清單了解一般性的 OpenClaw 指引。

常見錯誤與故障排除

「components.json not found」

您的專案尚未初始化 shadcn/ui。

# 在您的專案中初始化 shadcn/ui
npx shadcn@latest init

按照提示選擇您的樣式、基礎色和匯入別名。代理也可以為您執行此操作。

「Module not found: Can't resolve '@/components/ui/button'」

匯入路徑別名與您的專案設定不符。

1. 檢查您的 components.json 中設定的別名路徑。
2. 確認您的 tsconfig.json 有匹配的路徑別名：

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

3. 如果使用 Next.js，在修改 tsconfig.json 後重新啟動開發伺服器。

「Tailwind CSS classes not applying」

Tailwind 未處理元件檔案目錄。

1. 確認您的 tailwind.config.js 包含元件路徑：

module.exports = {
  content: [
    "./src/components/**/*.{js,ts,jsx,tsx}",
  ],
}

2. 確保 globals.css 匯入了 Tailwind 指令（@tailwind base; @tailwind components; @tailwind utilities;）。
3. 重新啟動開發伺服器。