shadcn-first 是做什麼的？
在你之後，會有人維護這段程式碼。每一行手寫的 div 搭配自訂 class、每一個 style={{}}，都是他們必須持續維護的包袱。手刻 UI 也會不知不覺遺漏函式庫免費提供的工藝：焦點環、懸停與啟用狀態、鍵盤導航、骨架載入、空狀態、ARIA 無障礙標記。
順序。永遠不要跳過任何步驟。
- 區塊。
ui.shadcn.com/blocks提供完整的側邊欄、儀表板、登入頁、資料表格。直接安裝區塊。 - 元件。 如果沒有適合的區塊，就從元件註冊表中安裝元件。
- 組合。 組合兩到三個元件。
- 自行手寫。 只有在前面三步都不適用時才手寫，並且 commit message 必須註明你評估了哪個區塊或元件，以及為何它不適用。
讓設計配合元件，而不是讓元件配合設計。品牌與視覺語言應透過單一佈景主題變數來達成，永遠不要在元件旁邊撰寫每個畫面專屬的 CSS。
工具，以及何時使用
已設定兩個 MCP 伺服器。它們負責不同的工作。
shadcn-official (npx shadcn@latest mcp) 能感知專案：它會讀取儲存庫中的 components.json。請用它來處理實際工作。
| 工具 | 用途 |
|---|---|
get_project_registries | 確認專案是否已初始化 |
search_items_in_registries | 模糊搜尋適合任務的元件 |
list_items_in_registries | 列出所有可用的元件 |
view_items_in_registries | 查看元件的實際原始碼與相依套件 |
get_item_examples_from_registries | 複製真實使用範例，避免猜測 API |
get_add_command_for_items | 取得精確的 npx shadcn add … 指令，然後執行它 |
get_audit_checklist | 在撰寫程式碼後執行。這是閘門。 |
shadcn (@jpisnice/shadcn-ui-mcp-server) 涵蓋整個註冊表，並支援區塊與佈景主題：list_blocks、get_block、list_themes、get_theme、get_component_demo。請在步驟 1 與主題設定時使用它。
如果專案沒有 components.json，官方工具會回報錯誤。請先執行 npx shadcn@latest init，然後再繼續。
針對 AI 對話介面，請使用 prompt-kit (prompt-kit.com，與 shadcn 相容)：chat-container、message、prompt-input、scroll-button、markdown、code-block、loader。同樣規則：安裝，而非重造。
開發者經常手寫而非安裝的元件
sidebar（可收合，附底部使用者選單）、command（Cmd+K 指令面板）、table + TanStack 資料表格區塊、tabs、sheet、dialog、alert-dialog、popover、tooltip、skeleton、sonner（提示訊息）、form（react-hook-form + zod）、breadcrumb、resizable、scroll-area、avatar、badge、separator、dropdown-menu、select、collapsible、chart。
如果你發現自己在手刻以上任何元件，請停止並直接安裝。
鍵盤快速鍵
Cmd+K 開啟指令面板，這是 cmdk 慣例，也是 command 元件內建的功能。Cmd+L 被瀏覽器保留給網址列，在 Chrome 中無法可靠攔截。如果有人要求 Cmd+L，請綁定 Cmd+K，並有機會時才額外綁定 Cmd+L，同時說明原因。
完成 = 可量化，而非口頭宣稱
在回報完成之前，請執行 get_audit_checklist 並回報數字：
- 移除的手寫 UI 行數
- 安裝的區塊與元件數量
- 剩餘的
style={{}}出現次數（grep -rc 'style={{' src/） - 每個畫面：來自
components/ui/的元素 vs 手寫元素
任何仍然手寫的部分都必須明確標示原因，而非被忽略。螢幕截圖是畫面正常呈現的證明；計數則是規則被遵守的證明。兩者都必須具備，否則不算完成。
禁止事項
- UI 中不要使用表情符號。使用真實 SVG 圖示（Lucide 已隨 shadcn 提供）。
- 品牌 Logo 不要放在圓形文字內。請使用真實 SVG 路徑：SimpleIcons > svgl.app > gilbarbara/logos > favicon。
- 最多使用一或兩種強調色。卡片上不要有彩色左邊框。不要在每個元素上都使用漸層。
- 不要為了改變顏色而 fork 元件。請修改主題變數。