Geruyang/agent-skills-library

shadcn/ui

您是 shadcn/ui 的專家——這是一個基於 Radix UI 原語與 Tailwind CSS 的美觀、可存取且可自訂的 React 元件集合。元件會以原始碼形式直接加入您的程式碼庫，而非作為依賴套件安裝。

核心概念

shadcn/ui 在傳統意義上並非一個元件庫。您不會將其作為套件安裝。相反地，CLI 會將元件原始碼複製到您的專案中，賦予您完整的擁有權與自訂能力。

CLI 指令

初始化 (非互動式 — 一律使用此方式)

重要提示：shadcn init 預設為互動式。請務必使用 -d (預設值) 進行非互動式初始化：

# 使用預設值進行非互動式初始化 — 請使用此方式
npx shadcn@latest init -d

# 使用預設集進行非互動式初始化 (建議用於一致的設計系統)
npx shadcn@latest init --preset <code> -f

# 明確選擇基底函式庫的非互動式初始化
npx shadcn@latest init -d --base radix
npx shadcn@latest init -d --base base-ui

# 創建完整專案模板 (CLI v4)

AI Elements 相容性：當專案使用或可能使用 AI Elements 時，請一律使用 --base radix (預設值)。AI Elements 元件依賴 Radix API，若使用 Base UI 會產生型別錯誤。

npx shadcn@latest init --template next -d
npx shadcn@latest init --template vite -d

選項：

• -d, --defaults — 使用預設配置，跳過所有互動式提示 (CI/代理使用時必填)
• -y, --yes — 跳過確認提示 (不會跳過函式庫選擇 — 請改用 -d)
• -f, --force — 強制覆寫現有配置
• -t, --template — 創建完整專案模板 (next, vite, react-router, astro, laravel, tanstack-start)
• --preset — 將設計系統預設集 (顏色、主題、圖示、字型、圓角) 作為單一可分享的 code 套用
• --base — 選擇原語函式庫：radix (預設) 或 base-ui
• --monorepo — 設定 monorepo 結構

警告：-y/--yes 單獨使用無法使 init 完全非互動——它仍會提示選擇元件函式庫。請務必使用 -d 以跳過所有提示。

CLI v4 中已棄用：--style、--base-color、--src-dir、--no-base-style 和 --css-variables 旗標已被移除，使用時會報錯。registry:build 和 registry:mcp 註冊表類型也已棄用。請改用 registry:base 和 registry:font。

init 指令會：

1. 偵測您的框架 (Next.js, Vite, React Router, Astro, Laravel, TanStack Start)
2. 安裝必要的依賴套件 (Radix UI, tailwind-merge, class-variance-authority)
3. 建立 components.json 配置
4. 設定 cn() 輔助函式
5. 配置用於主題設定的 CSS 變數

新增元件

# 新增特定元件
npx shadcn@latest add button dialog card

# 新增所有可用元件
npx shadcn@latest add --all

# 從自訂註冊表新增
npx shadcn@latest add @v0/dashboard
npx shadcn@latest add @acme/custom-button

# 從 AI Elements 註冊表新增
npx shadcn@latest add https://elements.ai-sdk.dev/api/registry/all.json

選項：

• -o, --overwrite — 覆寫現有檔案
• -p, --path — 自訂安裝路徑
• -a, --all — 安裝所有元件
• --dry-run — 預覽將新增的內容，但不實際寫入檔案
• --diff — 更新現有元件時顯示差異
• --view — 內嵌顯示註冊表項目的原始碼

搜尋與列表

npx shadcn@latest search button
npx shadcn@latest list @v0

建置 (自訂註冊表)

npx shadcn@latest build
npx shadcn@latest build ./registry.json -o ./public/r

檢視、資訊與文件 (CLI v4)

# 在安裝前檢視註冊表項目的原始碼
npx shadcn@latest view button

# 顯示專案診斷資訊 — 配置、已安裝元件、依賴套件
npx shadcn@latest info

# 取得任何元件的文件、程式碼與範例 (對代理友善的輸出)
npx shadcn@latest docs button
npx shadcn@latest docs dialog

shadcn docs 提供編碼代理正確使用原語所需的上下文——內嵌回傳程式碼範例、API 參考與使用模式。

遷移

npx shadcn@latest migrate rtl    # RTL 支援遷移
npx shadcn@latest migrate radix  # 遷移至統一的 radix-ui 套件
npx shadcn@latest migrate icons  # 圖示庫變更

# 遷移位於預設 ui 目錄之外的元件
npx shadcn@latest migrate radix src/components/custom

shadcn/skills (CLI v4)

shadcn/skills 賦予編碼代理正確使用元件與註冊表所需的上下文。它涵蓋了 Radix 和 Base UI 原語、更新的 API、元件模式以及註冊表工作流程。此技能知道如何使用 CLI、何時呼叫它以及傳遞哪些旗標——因此代理產生的程式碼會與您的設計系統匹配。

安裝指令：pnpm dlx skills add shadcn/ui

統一的 Radix UI 套件 (2026 年 2 月)

new-york 風格現在使用單一的 radix-ui 套件，取代了原本的個別 @radix-ui/react-* 套件：

// 舊版 — 個別套件
import * as DialogPrimitive from "@radix-ui/react-dialog"

// 新版 — 統一套件
import { Dialog as DialogPrimitive } from "radix-ui"

若要遷移現有專案：npx shadcn@latest migrate radix。遷移後，請從 package.json 中移除未使用的 @radix-ui/react-* 套件。

Base UI 支援 (2026 年 1 月)

shadcn/ui 現在支援 Base UI 作為 Radix UI 的替代底層原語函式庫。無論您選擇哪個函式庫，元件的外觀和行為都相同——僅改變底層的實作方式。

在初始化時選擇：npx shadcn@latest init --base base-ui

CLI 會根據您的專案配置自動拉取正確的元件變體。

配置 (components.json)

components.json 檔案配置 shadcn/ui 在您的專案中如何運作：

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "tailwind.config.ts",
    "css": "src/app/globals.css",
    "baseColor": "zinc",  // 選項：gray, neutral, slate, stone, zinc, mauve, olive, mist, taupe
    "cssVariables": true
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  },
  "registries": {
    "v0": {
      "url": "https://v0.dev/chat/api/registry"
    },
    "ai-elements": {
      "url": "https://elements.ai-sdk.dev/api/registry"
    }
  }
}

命名空間註冊表

為您的專案配置多個註冊表：

{
  "registries": {
    "acme": {
      "url": "https://acme.com/registry/{name}.json"
    },
    "private": {
      "url": "https://internal.company.com/registry/{name}.json",
      "headers": {
        "Authorization": "Bearer ${REGISTRY_TOKEN}"
      }
    }
  }
}

使用命名空間語法安裝：

npx shadcn@latest add @acme/header @private/auth-form

主題設定

CSS 變數

shadcn/ui 使用 CSS 自訂屬性進行主題設定，定義在 globals.css 中：

@theme inline {
  --color-background: oklch(0.145 0 0);
  --color-foreground: oklch(0.985 0 0);
  --color-card: oklch(0.205 0 0);
  --color-card-foreground: oklch(0.985 0 0);
  --color-primary: oklch(0.488 0.243 264.376);
  --color-primary-foreground: oklch(0.985 0 0);
  --color-secondary: oklch(0.269 0 0);
  --color-secondary-foreground: oklch(0.985 0 0);
  --color-muted: oklch(0.269 0 0);
  --color-muted-foreground: oklch(0.708 0 0);
  --color-accent: oklch(0.269 0 0);
  --color-accent-foreground: oklch(0.985 0 0);
  --color-destructive: oklch(0.396 0.141 25.723);
  --color-border: oklch(0.269 0 0);
  --color-input: oklch(0.269 0 0);
  --color-ring: oklch(0.488 0.243 264.376);
  --radius: 0.625rem;
  /* CLI v4: radius tokens use multiplicative calc instead of additive */
  --radius-xs: calc(var(--radius) * 0.5);
  --radius-sm: calc(var(--radius) * 0.75);
  --radius-md: calc(var(--radius) * 0.875);
  --radius-lg: var(--radius);
  --radius-xl: calc(var(--radius) * 1.5);
}

暗色模式

如需暗色模式，請在 <html> 上使用 dark 類別：

// app/layout.tsx
<html lang="en" className="dark">

或使用 next-themes 來切換：

import { ThemeProvider } from 'next-themes'

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

自訂顏色

將應用程式特定顏色與 shadcn 預設值一同加入：

@theme inline {
  /* 上方為 shadcn 預設值... */

  /* 自訂應用程式顏色 */
  --color-priority-urgent: oklch(0.637 0.237 15.163);
  --color-priority-high: oklch(0.705 0.213 47.604);
  --color-status-done: oklch(0.723 0.219 149.579);
}

在元件中使用：

<span className="text-[var(--color-priority-urgent)]">緊急</span>
// 或搭配 Tailwind v4 theme()：
<span className="text-priority-urgent">緊急</span>

最常見元件

元件	使用情境
button	動作、表單提交
card	內容容器
dialog	模態框、確認提示
input / textarea	表單欄位
select	下拉選單
table	資料顯示
tabs	檢視切換
command	指令面板 (Cmd+K)
dropdown-menu	上下文選單
popover	浮動內容
tooltip	懸浮提示
badge	狀態指示器
avatar	使用者個人資料圖片
scroll-area	可捲動容器
separator	視覺分隔線
label	表單標籤
sheet	滑出式面板
skeleton	載入佔位符

Vercel 上 shadcn 的設計方向

shadcn/ui 不僅僅是一個元件原始碼產生器。在 Vercel 技術棧中，它是預設的介面語言。請不要停留在「元件能運作就好」。組合出感覺經過深思熟慮、信號明確且一致的頁面。

產品 UI 的預設美學

• 偏好使用 new-york 風格於產品、儀表板、AI 及管理後台介面。
• 儀表板、AI 應用、內部工具、設定頁及開發者導向產品，預設使用暗色模式。僅在產品明顯是內容優先或編輯性質時使用亮色模式。
• 介面文字使用 Geist Sans，程式碼、指標、ID、時間戳記、指令使用 Geist Mono。
• 首選 zinc、neutral 或 slate 作為基礎色板。透過 --color-primary 使用一個強調色。
• 使用 token 建構核心表面：bg-background、bg-card、text-foreground、text-muted-foreground、border-border、ring-ring。避免使用臨時十六進位值。
• 保持圓角一致。預設的 --radius: 0.625rem 是一個很好的基線。
• 每頁使用一個密度系統：寬鬆 (gap-6 / p-6 / text-sm) 或緊湊 (gap-4 / p-4 / text-sm)。
• 圖示保持簡潔一致。使用 Lucide 圖示，尺寸為 h-4 w-4 或 h-5 w-5。

優先考慮這些

使用情境	優先考慮此方案	原因
設定頁	Tabs + Card + Form	清晰的資訊分組，搭配可預測的儲存流程
資料儀表板	Card + Badge + Table + DropdownMenu	無需自訂外殼即可涵蓋摘要、狀態、密集資料和列操作
CRUD 表格	Table + DropdownMenu + Sheet + AlertDialog	在標準模式中支援瀏覽、操作、編輯和破壞性確認
驗證畫面	Card + Label + Input + Button + Alert	保持進入流程專注，並為錯誤提供適當的處理
全域搜尋	Command + Dialog	快速的鍵盤優先探索，具有成熟的互動模型
行動導航	Sheet + Button + Separator	提供一個能乾淨適應小螢幕的緊湊導航外殼
詳細資料頁	header + Badge + Separator + Card	平衡層級結構、元資料和支援性內容，避免過度巢狀
篩選器	Card 側邊欄 + Sheet + Select	適用於桌上型電腦的持久性篩選器和可折疊的行動控制項
空/載入/錯誤狀態	Card + Skeleton + Alert	為非正常路徑提供設計過的表面，而非取代文字

組合配方

• 設定頁：Tabs + 每組一個 Card + Separator + 儲存動作
• 管理儀表板：摘要 Cards + 篩選列 + Table
• 實體詳細資料：header + 狀態 Badge + 主要 Card + 側邊 Card + 用於破壞性操作的 AlertDialog
• 搜尋密集型：快速查詢用 Command，選擇器用 Popover，行動篩選用 Sheet
• 驗證/入職：置中 Card + 社交 Separator + 用於錯誤的內聯 Alert
• 破壞性流程：使用 AlertDialog (而非 Dialog) 進行確認

避免的反模式

• 當 shadcn 原語存在時，使用原始的 button / input / select / div
• 重複使用 div rounded-xl border p-6 而非 Tabs / Table / Sheet / Dialog
• 多個強調色互相衝突
• 在 Card 裡面再巢狀 Card，層層疊疊
• 在每個表面上使用大型漸層背景和玻璃態效果
• 混合使用隨意的間距和圓角值
• 使用 Dialog 進行破壞性確認而非 AlertDialog
• 未經設計處理就交付空/載入/錯誤狀態
• 使用臨時 Tailwind 色板類別來處理基礎表面，而非主題 token