shadcn

shadcn skill 概覽

shadcn skill 是做什麼用的

shadcn skill 的用途，是讓 AI 助理能在真實的 shadcn/ui 專案裡正確工作：找到現有元件、用正確的 CLI 安裝、以既有 primitives 組出畫面，並避開不同 preset 與元件家族之間常見的 API 誤用。當你的需求不只是「幫我生一個 button」，而是希望輸出能真正符合 components.json、已安裝的 registry 項目、目前使用的 template，以及 base 與 radix 的差異時，這個 shadcn skill 就特別有價值。

哪些人適合使用這個 shadcn skill

最適合的讀者包括：

• 已經在使用 shadcn/ui 的開發者
• 正在導入 preset 或 registry 驅動 UI 工作流的團隊
• 會請 AI 協助新增或重構表單、對話框、設定頁、dashboard 或主題樣式的人
• 希望助理在寫 JSX 前先檢查專案上下文的使用者

如果你的專案沒有用 shadcn/ui、components.json 或 shadcn CLI，這個 skill 多半就太專門了。

真正要解決的工作

使用者要的通常不只是 repo 摘要，而是希望助理能：

1. 判斷專案目前的 shadcn 設定，
2. 優先選用現有元件，而不是先發明新元件，
3. 使用正確的 CLI 指令與官方支援的 flags，
4. 依照這個函式庫偏好的模式來組 UI，
5. 避免一些不容易第一眼看出的壞掉情況，例如錯誤的 trigger composition、漏掉必要的 group wrapper，或 form validation wiring 接錯。

這正是 shadcn skill 相較一般 UI prompt 更有價值的地方。

shadcn 和一般 prompt 有什麼不同

shadcn 的關鍵差異，主要都很務實：

• 它會先從 npx shadcn@latest info --json 的專案上下文開始
• 它強調先做 search、view、docs，再考慮自訂實作
• 它把 rules/composition.md、rules/forms.md、rules/styling.md、rules/base-vs-radix.md 這些檔案中的專案規則納入流程
• 它不只處理元件片段，也涵蓋 theme 與 preset 切換
• 它也包含透過 MCP 進行 registry 搜尋與安裝工作流的指引

簡單說，shadcn skill 的重點不是「寫 React」，而是「針對這個 shadcn 設定寫出正確的 React」。

導入前要先知道的限制

在你真的依賴這個 skill 之前，先注意幾個限制：

• 它預設專案可以透過封包執行器使用 shadcn CLI：npx、pnpm dlx 或 bunx --bun
• 它受限於官方文件支援的 CLI flags；這個 skill 會明確避免亂猜 flags
• 很多高品質輸出都建立在有效的 components.json 上
• API 細節會因 preset 以及 base／radix 而不同，所以直接照抄範例常常會出錯

如何使用 shadcn skill

shadcn skill 的安裝與使用前提

先依照目錄的標準安裝流程，把這個 skill 加進你的 AI 環境，接著在實際已經有、或預計要有 shadcn 設定的 repo 中使用它。實務上，比起 skill 本身怎麼安裝，更重要的是 repository 端的條件：助理需要能讀到你的專案檔案，也最好能執行 shadcn CLI 指令。

在目標專案裡，常用的執行指令是：

• npx shadcn@latest info --json
• npx shadcn@latest search <query>
• npx shadcn@latest view <item>
• npx shadcn@latest docs <component>
• npx shadcn@latest add <component>

如果你的專案是用別的 package manager，就改成 pnpm dlx shadcn@latest 或 bunx --bun shadcn@latest。

要求輸出前，先讀這些檔案

想要更快、也更準地使用 shadcn，建議大致依照這個順序先檢查：

1. SKILL.md
2. cli.md
3. rules/composition.md
4. rules/base-vs-radix.md
5. rules/forms.md
6. rules/styling.md
7. customization.md
8. mcp.md

這個順序之所以有效，是因為：

• SKILL.md 定義了觸發條件與工作流程
• cli.md 可以避免助理亂猜指令與 flags
• rules/ 底下的檔案，正好涵蓋一般 codegen 最容易犯的錯
• customization.md 在你需要 theme-safe 的 styling，而不是直接硬寫 Tailwind 顏色時特別重要
• mcp.md 則是在你的助理可透過 MCP 瀏覽 registry，而不是只靠 shell 指令時很關鍵

每個 shadcn 任務都先做專案探查

最值得優先做的第一步就是：

npx shadcn@latest info --json

這個指令會告訴助理目前專案已經設定了什麼，包括元件與專案層級的上下文。它特別適合用來：

• 確認是否存在 components.json
• 盤點已安裝的元件
• 辨識會影響合法程式碼選擇的設定細節
• 確認 package runner，避免舉出錯誤的指令範例

如果你跳過這一步，shadcn skill 就會變得更像一般的 prompt，而不是專案感知型工具。

把模糊需求變成有效的 shadcn prompt

弱的 prompt：

Build me a profile dialog with shadcn.

更好的 prompt：

In this existing shadcn/ui app, inspect components.json and run npx shadcn@latest info --json first. We use the radix setup and lucide-react. Create a profile edit dialog using existing shadcn components only where possible. Include avatar, name, bio, Save/Cancel actions, accessible title, semantic tokens, and no raw color classes. If a component is missing, tell me the exact shadcn add command before generating code.

為什麼這種寫法更強：

• 它強制先做專案探查
• 它明確指定了會影響實作的 preset 行為
• 它把 icon 與 styling 限制講清楚
• 它要求在缺少依賴時，先提供安裝步驟

先 search 和 docs，再寫自訂程式碼

高品質的 shadcn 工作流通常是：

1. 先搜尋 registry 裡是否已有現成元件，
2. 再看 docs 與 examples，
3. 補上缺少的項目，
4. 最後再組出畫面。

實用指令如下：

npx shadcn@latest search dialog
npx shadcn@latest docs dialog
npx shadcn@latest view @shadcn/dialog

這點對 forms、overlays、navigation、empty states 特別重要，因為這個 shadcn skill 的規則本來就偏向優先採用函式庫既有模式，而不是臨時用 div 結構手刻。

用現有 building blocks 來組畫面

當你要求的是「組合」，而不是一次做一大坨客製 UI，shadcn skill 的表現會最好。比較好的任務 framing 例如：

• 「settings page = Tabs + Card + form controls」
• 「dashboard = Sidebar + Card + Chart + Table」
• 「empty state = Empty component，不要自己做一個置中的 div」
• 「callout = Alert，不要手工刻 border box」

這跟這個 skill 偏好的流程一致：先用現有元件，再視需要微調 variants 與 wrappers。

注意 base 與 radix 的差異

導入 shadcn 時最常卡住的一點，就是誤以為所有 shadcn 範例都能互換。其實不行。

這個 shadcn skill 對 base 與 radix 有明確指引，包括：

• asChild 與 render 的差異
• trigger composition 的差異
• 特定僅限 base 情境下的 nativeButton={false}
• 像 Select、ToggleGroup、Slider、Accordion 這些元件的 API 差異

如果你的 prompt 沒有講清楚目前是哪種 setup，至少要要求助理從 npx shadcn@latest info 自行判斷。

採用能撐住主題切換的 styling 規則

在 shadcn for UI Design 的情境下，使用 semantic tokens 與 CSS variable 驅動的 theming，通常比硬寫 Tailwind 顏色更可靠。

建議優先用：

• bg-background
• text-foreground
• text-muted-foreground
• text-destructive

避免預設就寫成：

• bg-red-500
• text-gray-400
• 大量手動 dark: 覆寫

這件事很重要，因為 customization.md 有說明元件樣式是繼承自 CSS variables。若助理改用 semantic tokens，你的設計在 light/dark theme 與不同 preset 間都會更容易擴充，也更一致。

用 shadcn 的方式處理表單

從 evals 與 rules 可以看出，form 品質是這個 skill 很重視的一塊。要讓 shadcn 的表單輸出更到位，通常代表：

• 使用提供好的 field layout patterns，而不是直接堆疊原始 div
• 以 data-invalid 和 aria-invalid 標記無效狀態
• 獨立開關型偏好設定使用 Switch
• 當規則有要求時，優先用 gap-* 而不是 space-y-*

如果你的任務包含 validation，務必要明講。否則很多助理都只會生出「看起來像表單」但其實不符合函式庫慣例的實作。

編輯器支援 MCP 時就善用它

如果你的環境支援 MCP，shadcn skill 在處理 registry 相關操作時會更可靠。mcp.md 有記錄可用工具，包括：

• 列出專案 registries
• 搜尋 registry 項目
• 查看 item 詳細資訊與檔案內容
• 取得 examples
• 安裝項目

當你希望助理以對話方式瀏覽 registry，而不是只依賴 CLI 輸出時，這會很好用。但它不能取代 info --json 在專案設定探查上的角色。

實用的 shadcn 使用 prompt 範本

如果你想拿到品質更高的輸出，可以直接套用這個範本：

Use the shadcn skill for this task. First inspect the project with `npx shadcn@latest info --json` and read `components.json` if present. Confirm whether this project uses `base` or `radix`. Search for existing components before building custom UI. If something is missing, give the exact documented `shadcn add` command. Then generate the component using semantic tokens, correct composition rules, and the project’s icon library.

Goal: [what you want to build]
Screen context: [page/dialog/form/dashboard/etc.]
Existing components: [if known]
Framework/template: [Next.js/Vite/Astro/etc.]
Constraints: [icons, validation, dark mode, accessibility, no raw colors, no guessed APIs]
Output needed: [component code, install commands, explanation, refactor diff]

shadcn skill 常見問題

這個 shadcn skill 只是拿來安裝元件嗎？

不是。shadcn install 類型的任務只是其中一部分，這個 skill 涵蓋的範圍更廣：專案檢查、registry 搜尋、元件組合、theming、除錯、preset 切換，以及 API 正確的重構都在範圍內。

shadcn skill 對新手友善嗎？

算友善，但前提是你已經對 React 和 package manager 有基本熟悉度。這個 skill 會透過正確的指令與規則，降低助理亂猜的空間。若你需要的是從零開始完整學 React、Tailwind 或 design system，它就沒那麼適合新手。

什麼情況下 shadcn 比一般 prompt 更適合？

當正確性高度依賴專案上下文時，就該用 shadcn skill：

• 現有的 components.json
• 需要對齊已安裝元件
• base 與 radix 的行為差異
• 只能使用官方支援的 CLI flags
• 要保留 theme tokens 與函式庫的 composition 規則

一般 prompt 也許能產出看起來合理的 JSX，但更容易漏掉安裝步驟，或把元件 API 用錯。

什麼時候不該用 shadcn skill？

以下情況就可以跳過：

• 你的專案沒有使用 shadcn/ui
• 你只需要一般 HTML/CSS mockup
• 你想要的是不綁定特定 design system 的答案
• 助理沒辦法檢查檔案或執行指令，而你也無法手動補足必要上下文

這些情況下，改用更通用的 frontend skill 會比較合適。

這個 skill 能協助 shadcn for UI Design 的設計決策嗎？

可以，尤其是在 composition 與 theming 上。它會引導助理優先使用可重用 primitives、semantic color tokens、正確的 overlay patterns，以及比一次性手刻版型更容易維護的元件結構。

AI 輸出在 shadcn 使用上最常壞在哪裡？

常見失敗點包括：

• 亂造不支援的 CLI flags
• 在 base 與 radix 間用錯 trigger composition
• 明明有現成 registry 元件，卻硬做自訂 UI
• 用 raw colors 寫樣式，跟 theme system 打架
• 漏掉必要的 subcomponents，例如 titles、groups 或 fallbacks

而這些正是這個 skill 想要幫你收斂、降低風險的地方。

如何提升 shadcn skill 的使用效果

一開始就把 shadcn skill 缺的上下文補齊

最有槓桿的改善方式，通常是給更完整的輸入。建議至少補上：

• framework 或 template（next、vite、astro 等）
• 是否存在 components.json
• 若已知，是 base 還是 radix
• 目前使用的 icon set
• 目標元件或畫面
• 這次任務是 install、refactor 還是 bugfix

哪怕只多一兩句具體上下文，都可能避免助理選錯 API。

元件可能沒裝時，先要指令再要程式碼

如果你不確定專案裡是否已有需要的元件，可以這樣下 prompt：

Before writing code, check whether the required shadcn components are already present. If not, give me the exact add command and wait.

這樣做會改善輸出品質，因為它把環境變更和實作拆開處理，讓結果更容易信任，也更容易直接套用。

對脆弱元件類型，強制要求遵守規則

像 forms、dialogs、dropdowns、sheets、drawers、selects 這些類型，特別建議明講要助理依規則檔處理。例如：

Follow the shadcn rules for composition, forms, and base-vs-radix differences. Do not simplify structure if it changes the component API.

這點很重要，因為很多低品質輸出表面上看起來沒問題，實際上卻破壞了可及性或 composition contract。

用設計限制來提升 shadcn 輸出品質

好的 UI prompt 不該只寫「做得現代一點」。你應該補上更具體的限制，例如：

• 只能使用 semantic tokens
• 不要用 raw palette utilities
• dark mode 必須在不手動覆寫的情況下正常運作
• 先用現有 variants，再考慮自訂 classes
• 優先使用函式庫既有的 empty states、alerts、separators、badges、skeletons

這些細節對 shadcn for UI Design 類任務的首輪品質有非常實際的影響。

用精準修正迭代，不要整份重寫

拿到第一版輸出後，不要只說「再試一次」。更好的方式是直接指出：

• 「把這段改成只使用已安裝的 shadcn 元件。」
• 「這裡要改成符合 base，不是 radix。」
• 「把 raw color classes 換成 semantic tokens。」
• 「補上 shadcn 要求的 title/fallback/group wrappers。」
• 「凡是有假設的地方，都列出確切的 shadcn add 指令。」

這樣能保留已經做對的部分，只修正最容易出錯的位置。

對照 repo 最有力的訊號來驗證

如果想提高可信度，就把輸出拿去對照：

• cli.md：檢查指令與 flags
• rules/composition.md：檢查結構
• rules/base-vs-radix.md：檢查 API 正確性
• rules/forms.md：檢查驗證與版面模式
• rules/styling.md 和 customization.md：檢查 theme-safe styling
• evals/evals.json：看實務上什麼才算「好」

這是最快判斷 shadcn skill 產出的內容，究竟有沒有對齊 repository 規則，而不只是一般 UI 程式碼的方式。