shadcn

shadcn/ui

一個用於建構 UI、元件與設計系統的框架。元件會以原始碼形式透過 CLI 新增至使用者的專案中。

重要： 所有 CLI 指令請使用專案的套件執行器：npx shadcn@latest、pnpm dlx shadcn@latest 或 bunx --bun shadcn@latest — 依據專案的 packageManager 決定。以下範例使用 npx shadcn@latest，但請替換為專案適用的執行器。

目前專案上下文

!`npx shadcn@latest info --json`

上述 JSON 包含專案設定與已安裝的元件。使用 npx shadcn@latest docs <component> 可取得任何元件的文件與範例網址。

原則

1. 優先使用現有元件。 在撰寫自訂 UI 前，先使用 npx shadcn@latest search 檢查註冊表。也請檢查社群註冊表。
2. 組合，不要重新發明。 設定頁面 = Tabs + Card + 表單控制項。儀表板 = Sidebar + Card + Chart + Table。
3. 優先使用內建變體而非自訂樣式。 例如 variant="outline"、size="sm" 等。
4. 使用語意化顏色。 例如 bg-primary、text-muted-foreground — 絕不使用 bg-blue-500 這類原始值。

關鍵規則

這些規則一律強制執行。每個規則連結到一個包含錯誤/正確程式碼對應的檔案。

樣式與 Tailwind → styling.md

• className 用於佈局，而非樣式。 絕不覆寫元件的顏色或字體。
• 禁止使用 space-x-* 或 space-y-*。 使用 flex 搭配 gap-*。垂直堆疊請用 flex flex-col gap-*。
• 當寬高相等時使用 size-*。 使用 size-10 而非 w-10 h-10。
• 使用 truncate 簡寫。 而非 overflow-hidden text-ellipsis whitespace-nowrap。
• 禁止手動 dark: 顏色覆寫。 使用語意化 token（如 bg-background、text-muted-foreground）。
• 使用 cn() 處理條件式 class。 不要手寫模板字串三元運算式。
• 覆蓋層元件禁止手動設定 z-index。 Dialog、Sheet、Popover 等元件會自行處理堆疊順序。

表單與輸入 → forms.md

• 表單使用 FieldGroup + Field。 絕不使用原始 div 搭配 space-y-* 或 grid gap-* 進行表單佈局。
• InputGroup 使用 InputGroupInput/InputGroupTextarea。 絕不在 InputGroup 內使用原始 Input/Textarea。
• 輸入框內的按鈕使用 InputGroup + InputGroupAddon。
• 選項集合（2–7 個選項）使用 ToggleGroup。 不要用 Button 迴圈搭配手動 active 狀態。
• FieldSet + FieldLegend 用於分組相關的核取方塊/選項按鈕。 不要使用 div 搭配標題。
• 欄位驗證使用 data-invalid + aria-invalid。 data-invalid 放在 Field 上，aria-invalid 放在控制項上。停用時：data-disabled 放在 Field 上，disabled 放在控制項上。

元件結構 → composition.md

• 項目必須放在對應的 Group 內。 SelectItem → SelectGroup。DropdownMenuItem → DropdownMenuGroup。CommandItem → CommandGroup。
• 使用 asChild（radix）或 render（base）處理自訂觸發器。 從 npx shadcn@latest info 檢查 base 欄位。→ base-vs-radix.md
• Dialog、Sheet 和 Drawer 必須包含標題。 為符合無障礙需求，需使用 DialogTitle、SheetTitle、DrawerTitle。若視覺上隱藏，可使用 className="sr-only"。
• 使用完整的 Card 組合。 包含 CardHeader/CardTitle/CardDescription/CardContent/CardFooter。不要將所有內容塞進 CardContent。
• Button 沒有 isPending/isLoading。 請組合使用 Spinner + data-icon + disabled。
• TabsTrigger 必須放在 TabsList 內。 絕不直接在 Tabs 中渲染觸發器。
• Avatar 必須包含 AvatarFallback。 用於圖片載入失敗時的備用顯示。

使用元件，而非自訂標記 → composition.md

• 優先使用現有元件而非自訂標記。 在撰寫自訂樣式 div 前，先檢查是否有對應元件。
• 提示框使用 Alert。 不要建立自訂樣式 div。
• 空狀態使用 Empty。 不要建立自訂空狀態標記。
• Toast 使用 sonner。 從 sonner 匯入 toast()。
• 使用 Separator 取代 <hr> 或 <div className="border-t">。
• 使用 Skeleton 作為載入佔位符。不要使用自訂 animate-pulse div。
• 使用 Badge 取代自訂樣式 span。

圖示 → icons.md

• Button 內的圖示使用 data-icon。 在圖示上使用 data-icon="inline-start" 或 data-icon="inline-end"。
• 元件內的圖示禁止使用尺寸 class。 元件會透過 CSS 處理圖示尺寸。不要使用 size-4 或 w-4 h-4。
• 將圖示作為物件傳遞，而非字串鍵。 使用 icon={CheckIcon}，而非字串查詢。

CLI

• 絕不手動解碼預設集代碼或手動建立預設集網址。 使用 npx shadcn@latest preset decode <code>、preset url <code> 或 preset open <code>。如需專案感知的預設集偵測，使用 npx shadcn@latest preset resolve。
• 直接使用 CLI 套用預設集代碼。 對現有專案使用 npx shadcn@latest apply <code>，初始化時使用 npx shadcn@latest init --preset <code>。

關鍵模式

以下是區分正確 shadcn/ui 程式碼的最常見模式。邊緣案例請參閱上方連結的規則檔案。

// 表單佈局：FieldGroup + Field，而非 div + Label。
<FieldGroup>
  <Field>
    <FieldLabel htmlFor="email">Email</FieldLabel>
    <Input id="email" />
  </Field>
</FieldGroup>

// 驗證：data-invalid 在 Field 上，aria-invalid 在控制項上。
<Field data-invalid>
  <FieldLabel>Email</FieldLabel>
  <Input aria-invalid />
  <FieldDescription>無效的 Email。</FieldDescription>
</Field>

// 按鈕中的圖示：data-icon，無尺寸 class。
<Button>
  <SearchIcon data-icon="inline-start" />
  搜尋
</Button>

// 間距：gap-*，而非 space-y-*。
<div className="flex flex-col gap-4">  // 正確
<div className="space-y-4">           // 錯誤

// 等寬高：size-*，而非 w-* h-*。
<Avatar className="size-10">   // 正確
<Avatar className="w-10 h-10"> // 錯誤

// 狀態顏色：Badge 變體或語意化 token，而非原始顏色。
<Badge variant="secondary">+20.1%</Badge>    // 正確
<span className="text-emerald-600">+20.1%</span> // 錯誤

元件選擇

需求	使用
按鈕/動作	Button 搭配適當的 variant
表單輸入	Input、Select、Combobox、Switch、Checkbox、RadioGroup、Textarea、InputOTP、Slider
切換 2–5 個選項	ToggleGroup + ToggleGroupItem
資料顯示	Table、Card、Badge、Avatar
導航	Sidebar、NavigationMenu、Breadcrumb、Tabs、Pagination
覆蓋層	Dialog（模態）、Sheet（側邊面板）、Drawer（底部面板）、AlertDialog（確認對話框）
回饋	sonner（toast）、Alert、Progress、Skeleton、Spinner
指令面板	Command 放在 Dialog 內
圖表	Chart（包裝 Recharts）
佈局	Card、Separator、Resizable、ScrollArea、Accordion、Collapsible
空狀態	Empty
選單	DropdownMenu、ContextMenu、Menubar
工具提示/資訊	Tooltip、HoverCard、Popover

關鍵欄位

注入的專案上下文包含以下關鍵欄位：

• aliases → 使用實際的別名前綴進行匯入（例如 @/、~/），絕不硬編碼。
• isRSC → 當為 true 時，使用 useState、useEffect、事件處理器或瀏覽器 API 的元件需要在檔案頂部加上 "use client"。在建議此指令時務必參考此欄位。
• tailwindVersion → "v4" 使用 @theme inline 區塊；"v3" 使用 tailwind.config.js。
• tailwindCssFile → 定義自訂 CSS 變數的全域 CSS 檔案。務必編輯此檔案，不要建立新檔案。
• style → 元件視覺處理（例如 nova、vega）。
• base → 基礎元件庫（radix 或 base）。影響元件 API 與可用 props。
• iconLibrary → 決定圖示匯入方式。lucide 使用 lucide-react，tabler 使用 @tabler/icons-react 等。不要預設為 lucide-react。
• resolvedPaths → 元件、工具函式、hooks 等的確切檔案系統路徑。
• framework → 路由與檔案慣例（例如 Next.js App Router 與 Vite SPA）。
• packageManager → 用於任何非 shadcn 的相依套件安裝（例如 pnpm add date-fns 與 npm install date-fns）。
• preset → 目前專案的已解析預設集代碼與值。僅需預設集資訊時，使用 npx shadcn@latest preset resolve --json。

完整欄位參考請見 cli.md — info 指令。

元件文件、範例與用法

執行 npx shadcn@latest docs <component> 可取得元件的文件、範例與 API 參考網址。請擷取這些網址以取得實際內容。

npx shadcn@latest docs button dialog select

在建立、修復、除錯或使用元件時，務必先執行 npx shadcn@latest docs 並擷取網址。 這可確保您使用的是正確的 API 與使用模式，而非猜測。

工作流程

1. 取得專案上下文 — 已在上方注入。如需重新整理，請再次執行 npx shadcn@latest info。
2. 先檢查已安裝的元件 — 在執行 add 之前，務必從專案上下文檢查 components 列表，或列出 resolvedPaths.ui 目錄。不要匯入尚未新增的元件，也不要重新新增已安裝的元件。
3. 尋找元件 — npx shadcn@latest search。
4. 取得文件與範例 — 執行 npx shadcn@latest docs <component> 取得網址，然後擷取內容。使用 npx shadcn@latest view 瀏覽尚未安裝的註冊表項目。若要預覽已安裝元件的變更，使用 npx shadcn@latest add --diff。
5. 安裝或更新 — npx shadcn@latest add。更新現有元件時，先使用 --dry-run 和 --diff 預覽變更（請參閱下方更新元件）。
6. 修復第三方元件的匯入路徑 — 從社群註冊表（例如 @bundui、@magicui）新增元件後，檢查新增的非 UI 檔案中是否有硬編碼的匯入路徑，例如 @/components/ui/...。這些可能與專案的實際別名不符。使用 npx shadcn@latest info 取得正確的 ui 別名（例如 @workspace/ui/components）並重新撰寫匯入。CLI 會為自己的 UI 檔案重新撰寫匯入，但第三方註冊表元件可能使用不符合專案的預設路徑。
7. 審查新增的元件 — 從任何註冊表新增元件或區塊後，務必閱讀新增的檔案並確認其正確性。檢查是否有遺漏的子元件（例如 SelectItem 沒有 SelectGroup）、遺漏的匯入、不正確的組合，或違反關鍵規則的情況。同時將任何圖示匯入替換為專案上下文中的 iconLibrary（例如，如果註冊表項目使用 lucide-react 但專案使用 hugeicons，請相應地切換匯入與圖示名稱）。在繼續之前修復所有問題。
8. 註冊表必須明確指定 — 當使用者要求新增區塊或元件時，不要猜測註冊表。如果未指定註冊表（例如使用者說「新增一個登入區塊」但未指定 @shadcn、@tailark、owner/repo 等），請詢問要使用哪個註冊表。絕不代使用者預設註冊表。
9. 切換預設集 — 先詢問使用者：覆寫、部分、合併或跳過？
   • 檢查目前預設集：npx shadcn@latest preset resolve。需要結構化值時使用 --json。
   • 檢查新預設集：npx shadcn@latest preset decode <code>。使用 preset url <code> 或 preset open <code> 分享或開啟預設集建構器。
   • 覆寫：npx shadcn@latest apply <code>。覆寫偵測到的元件、字型與 CSS 變數。
   • 部分：npx shadcn@latest apply <code> --only theme,font。僅更新選取的預設集部分，不重新安裝 UI 元件。支援的值為 theme 和 font；可逗號分隔組合。icon 刻意不支援，因為圖示變更可能需要完整元件重新安裝與轉換。
   • 合併：npx shadcn@latest init --preset <code> --force --no-reinstall，然後執行 npx shadcn@latest info 列出已安裝元件，接著對每個已安裝元件使用 --dry-run 和 --diff 進行智慧合併。
   • 跳過：npx shadcn@latest init --preset <code> --force --no-reinstall。僅更新設定與 CSS，保留元件不變。
   • 重要：務必在使用者的專案目錄內執行預設集指令。apply 僅在已有 components.json 檔案的現有專案中運作。CLI 會自動保留 components.json 中的目前基礎（base 與 radix）。如果必須使用暫存/臨時目錄（例如用於 --dry-run 比較），請明確傳遞 --base <current-base> — 預設集代碼不包含基礎資訊。

更新元件

當使用者要求從上游更新元件但保留本地變更時，使用 --dry-run 和 --diff 進行智慧合併。絕不手動從 GitHub 擷取原始檔案 — 一律使用 CLI。

1. 執行 npx shadcn@latest add <component> --dry-run 查看所有受影響的檔案。
2. 對每個檔案，執行 npx shadcn@latest add <component> --diff <file> 查看上游與本地的差異。
3. 根據差異逐檔案決定：
   • 無本地變更 → 可安全覆寫。
   • 有本地變更 → 讀取本地檔案，分析差異，並在保留本地修改的同時套用上游更新。
   • 使用者說「全部更新」 → 使用 --overwrite，但先確認。
4. 未經使用者明確同意，絕不使用 --overwrite。

快速參考

# 建立新專案。
npx shadcn@latest init --name my-app --preset base-nova
npx shadcn@latest init --name my-app --preset a2r6bw --template vite

# 建立 monorepo 專案。
npx shadcn@latest init --name my-app --preset base-nova --monorepo
npx shadcn@latest init --name my-app --preset base-nova --template next --monorepo

# 初始化現有專案。
npx shadcn@latest init --preset base-nova
npx shadcn@latest init --defaults  # 快捷方式：--template=next --preset=nova（基礎樣式隱含）

# 對現有專案套用預設集。
npx shadcn@latest apply a2r6bw
npx shadcn@latest apply a2r6bw --only theme
npx shadcn@latest apply a2r6bw --only font
npx shadcn@latest apply a2r6bw --only theme,font

# 檢查預設集代碼與專案預設集狀態。
npx shadcn@latest preset decode a2r6bw
npx shadcn@latest preset url a2r6bw
npx shadcn@latest preset open a2r6bw
npx shadcn@latest preset resolve
npx shadcn@latest preset resolve --json

# 新增元件。
npx shadcn@latest add button card dialog
npx shadcn@latest add @magicui/shimmer-button
npx shadcn@latest add owner/repo/item
npx shadcn@latest add --all

# 在新增/更新前預覽變更。
npx shadcn@latest add button --dry-run
npx shadcn@latest add button --diff button.tsx
npx shadcn@latest add @acme/form --view button.tsx
npx shadcn@latest add owner/repo/item --dry-run

# 搜尋註冊表。
npx shadcn@latest search @shadcn -q "sidebar"
npx shadcn@latest search @tailark -q "stats"
npx shadcn@latest search owner/repo -q "login"
npx shadcn@latest search                          # 所有已設定的註冊表
npx shadcn@latest search @shadcn -q "menu" -t ui  # 依項目類型篩選

# 取得元件文件與範例網址。
npx shadcn@latest docs button dialog select

# 檢視註冊表項目詳細資訊（適用於尚未安裝的項目）。
npx shadcn@latest view @shadcn/button
npx shadcn@latest view owner/repo/item

命名預設集： nova、vega、maia、lyra、mira、luma
範本： next、vite、start、react-router、astro（全部支援 --monorepo）與 laravel（不支援 monorepo）
預設集代碼： 版本前綴的 base62 字串（例如 a2r6bw 或 b0），來自 ui.shadcn.com。

詳細參考

• rules/forms.md — FieldGroup、Field、InputGroup、ToggleGroup、FieldSet、驗證狀態
• rules/composition.md — Groups、覆蓋層、Card、Tabs、Avatar、Alert、Empty、Toast、Separator、Skeleton、Badge、Button 載入
• rules/icons.md — data-icon、圖示尺寸、將圖示作為物件傳遞
• rules/styling.md — 語意化顏色、變體、className、間距、尺寸、truncate、深色模式、cn()、z-index
• rules/base-vs-radix.md — asChild 與 render、Select、ToggleGroup、Slider、Accordion
• cli.md — 指令、旗標、預設集、範本
• registry.md — 編寫來源註冊表、include、項目定義、相依性、GitHub 註冊表規則
• customization.md — 主題設定、CSS 變數、擴充元件