shadcn-svelte 是做什麼的？
一個用於為 Svelte 建構 UI、元件及設計系統的框架。元件透過 CLI 以原始碼形式新增至使用者的專案。
重要事項： 所有 CLI 指令都應使用專案的套件執行器執行：
npx shadcn-svelte@latest、pnpm dlx shadcn-svelte@latest或bunx --bun shadcn-svelte@latest— 取決於專案的套件管理工具。下方範例使用npx shadcn-svelte@latest，但請替換為專案適用的正確執行器。
目前專案上下文
讀取專案根目錄下的 components.json，當你需要即時檔案結構時，列出 aliases.ui 路徑指向的目錄（解析規則與 CLI 相同）。
匯入（Svelte）
每個元件都有自己的資料夾，並包含一個 index.ts 匯出檔。請參照安裝文件：
- 多部分元件（dialog、select、card、field、tabs 等）：
import * as Dialog from "$lib/components/ui/dialog"然後使用Dialog.Content、Dialog.Title、Card.Root、Card.Header等 — 視匯出內容而定（短名稱和/或Root as …別名）。 - 單一元件匯出（資料夾中只有一個有意義的元件）：使用具名匯入 —
import { Button } from "$lib/components/ui/button"並以<Button>使用，而非import * as Button+Button.Root。{ Input }、{ Badge }、{ Spinner }、{ Checkbox }、{ Separator }、{ Skeleton }等也遵循相同模式。
import * as Dialog from "$lib/components/ui/dialog";
import { Button } from "$lib/components/ui/button";
import { Separator } from "$lib/components/ui/separator";
使用 components.json 中的實際別名（通常為 $lib/components/ui/...），而非硬編碼路徑。
原則
- 優先使用現有元件。 執行
npx shadcn-svelte@latest add不帶參數以瀏覽可用元件，或在撰寫自訂 UI 前先查閱元件庫。 - 組合，而非重新發明。 設定頁面 = Tabs + Card + 表單控制項。儀表板 = Sidebar + Card + Chart + Table。
- 優先使用內建變體，再使用自訂樣式。 例如
variant="outline"、size="sm"等。 - 使用語意顏色。 例如
bg-primary、text-muted-foreground— 絕不使用bg-blue-500這類原始數值。
關鍵規則
這些規則一律強制執行。每個規則都連接到一個包含錯誤/正確程式碼配對的檔案。
樣式與 Tailwind → styling.md
class用於佈局，而非樣式。 絕不覆寫元件的顏色或排版。- 不使用
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:顏色覆寫。 使用語意令牌（bg-background、text-muted-foreground）。 - 使用
cn()處理條件式類別。 不要撰寫手動的模板字串三元運算子。 - 重疊元件不使用手動
z-index。 Dialog、Sheet、Popover 等會自行處理堆疊順序。
表單與輸入 → forms.md
- 表單使用
Field.FieldGroup+Field.Field。 對於表單佈局，絕不使用原始div搭配space-y-*或grid gap-*。 InputGroup使用InputGroup.Input/InputGroup.Textarea。 在InputGroup.Root內絕不使用原始Input/Textarea。- 輸入內部的按鈕使用
InputGroup.Root+InputGroup.Addon。 - 選項集（2–7 個選項）使用
ToggleGroup。 不要使用手動 active 狀態的Button迴圈。 - 使用
Field.FieldSet+Field.FieldLegend來分組相關的核取方塊/單選按鈕。 不要使用帶有標題的div。 - 欄位驗證使用
data-invalid+aria-invalid。 在Field上使用data-invalid，在控制項上使用aria-invalid。禁用狀態：在Field上使用data-disabled，在控制項上使用disabled。
元件結構 → composition.md
- 項目永遠放在其群組內。
Select.Item→Select.Group。DropdownMenu.Item→DropdownMenu.Group。Command.Item→Command.Group。 - 自訂觸發器。 將控制項包裹在
Dialog.Trigger/AlertDialog.Trigger中，或使用根元件上的bind:open控制開啟狀態 — 請參閱元件文件。 - Dialog、Sheet 和 Drawer 永遠需要 Title。
Dialog.Title、Sheet.Title、Drawer.Title是無障礙性所必需的。若需視覺隱藏，請使用class="sr-only"。 - 使用完整的 Card 組合。
Card.Header/Card.Title/Card.Description/Card.Content/Card.Footer。不要將所有內容塞入Card.Content。 - Button 沒有
isPending/isLoading。 在Button內部組合Spinner加上disabled；在Spinner上使用data-icon="inline-start"/inline-end以獲得正確間距（import { Button }、import { Spinner }）。 Tabs.Trigger必須放在Tabs.List內部。 永遠不要直接在Tabs中渲染觸發器。Avatar永遠需要Avatar.Fallback。 用於圖片載入失敗的情況。
使用元件，而非自訂標記 → composition.md
- 在自訂標記之前優先使用現有元件。 在撰寫帶有樣式的
div之前，先檢查元件是否存在。 - 提示框使用
Alert。 不要建構自訂的樣式化 div。 - 空狀態使用
Empty。 不要建構自訂的空狀態標記。 - 使用
svelte-sonner顯示 Toast。 使用來自svelte-sonner的toast()函式和 UI 資料夾中的 Sonner 元件。 - 使用
Separator代替<hr>或僅帶有邊框類別的div。 - 載入佔位符使用
Skeleton。 不要使用自訂的animate-pulsediv。 - 使用
Badge代替自訂的樣式化 span。
圖示 → icons.md
<Button>中的圖示使用data-icon。 在圖示上使用data-icon="inline-start"或data-icon="inline-end"。- 元件內部的圖示不使用尺寸類別。 元件透過 CSS 處理圖示尺寸。不使用
size-4或w-4 h-4。 - 將圖示作為元件傳遞。 從設定的
iconLibrary（例如@lucide/svelte）匯入，而非字串鍵。
CLI
- 預設 — 從 shadcn-svelte.com 的設計系統建構器複製編碼後的字串，並傳遞給
npx shadcn-svelte@latest init --preset <code>。
關鍵模式
這些是區分正確 shadcn-svelte 程式碼最常見的模式。邊緣情況請參閱上面的規則檔案。
<script lang="ts">
import * as Field from "$lib/components/ui/field";
import { Input } from "$lib/components/ui/input";
import { Button } from "$lib/components/ui/button";
import SearchIcon from "@lucide/svelte/icons/search";
import { Badge } from "$lib/components/ui/badge";
import * as Avatar from "$lib/components/ui/avatar";
</script>
<!-- 表單佈局：Field.FieldGroup + Field.Field，而非 div + Label。 -->
<Field.FieldGroup>
<Field.Field>
<Field.FieldLabel for="email">電子郵件</Field.FieldLabel>
<Input id="email" />
</Field.Field>
</Field.FieldGroup>
<!-- 驗證：在 Field 上使用 data-invalid，在控制項上使用 aria-invalid。 -->
<Field.Field data-invalid>
<Field.FieldLabel for="email">電子郵件</Field.FieldLabel>
<Input id="email" aria-invalid />
<Field.FieldDescription>無效的電子郵件。</Field.FieldDescription>
</Field.Field>
<!-- 按鈕中的圖示：使用 data-icon，不使用尺寸類別。 -->
<Button>
<SearchIcon data-icon="inline-start" />
搜尋
</Button>
<!-- 間距：使用 gap-*，而非 space-y-*。 -->
<div class="flex flex-col gap-4"></div>
<!-- 相等尺寸：使用 size-*，而非 w-* h-*。 -->
<Avatar.Root class="size-10">
<Avatar.Image src="/u.png" alt="使用者" />
<Avatar.Fallback>U</Avatar.Fallback>
</Avatar.Root>
<!-- 狀態顏色：使用 Badge 變體或語意令牌，而非原始顏色。 -->
<Badge variant="secondary">+20.1%</Badge>
元件選擇
| 需求 | 使用 |
|---|---|
| 按鈕/動作 | Button 搭配適當的變體（import { Button }） |
| 表單輸入 | Input、Select、Combobox、Switch、Checkbox、RadioGroup、Textarea、InputOTP、Slider |
| 在 2–5 個選項之間切換 | ToggleGroup.Root + ToggleGroup.Item |
| 資料顯示 | Table、Card、Badge、Avatar |
| 導航 | Sidebar、NavigationMenu、Breadcrumb、Tabs、Pagination |
| 重疊層 | Dialog（模態框）、Sheet（側面板）、Drawer（底部面板）、AlertDialog（確認對話框） |
| 回饋 | svelte-sonner（toast）、Alert、Progress、Skeleton、Spinner |
| 命令面板 | Dialog 內的 Command |
| 圖表 | Chart（LayerChart） |
| 佈局 | Card、Separator、Resizable、ScrollArea、Accordion、Collapsible |
| 空狀態 | Empty |
| 選單 | DropdownMenu、ContextMenu、Menubar |
| 工具提示/資訊 | Tooltip、HoverCard、Popover |
關鍵欄位
使用 components.json 和檔案系統 — 而非單獨的 info 指令：
aliases→ 使用設定中的實際別名前綴（例如$lib/），永遠不要為不相關的專案硬編碼。tailwind.css→ 包含主題變數的全域 CSS 檔案。編輯此檔案以調整主題；除非使用者已使用其他全域檔案，否則不要新增第二個全域檔案。style→ 視覺處理（例如nova、vega等）和註冊表樣式路徑。iconLibrary→ 決定圖示套件（@lucide/svelte、@tabler/icons-svelte等）。永遠不要假設是@lucide/svelte。registry→ CLI 擷取元件的來源；預設官方註冊表位於shadcn-svelte.com。resolvedPaths（概念性）→ CLI 將aliases解析為絕對路徑；列出磁碟上的aliases.ui以查看已安裝的元件。
關於指令和旗標，請參閱 cli.md。
元件文件、範例與使用方式
開啟 https://shadcn-svelte.com/docs/components/<name>.md 以取得文件和範例。在建立、修復、除錯或使用元件時，請先閱讀官方頁面，以遵循已記錄的 API。
工作流程
- 取得專案上下文 — 讀取
components.json，並在需要時列出 UI 元件目錄。 - 先檢查已安裝的元件 — 在執行
add之前，列出已解析ui路徑下的檔案。不要匯入尚未新增的元件，也不要重新新增已存在的元件（除非是更新）。 - 探索元件 — 執行
npx shadcn-svelte@latest add不帶參數（互動式清單），或瀏覽文件網站。 - 安裝或更新 — 執行
npx shadcn-svelte@latest add <name>或註冊表 URL。若要從註冊表重新整理現有檔案，請使用npx shadcn-svelte@latest update（請參閱 cli.md）。 - 修復第三方/URL 新增項目的匯入 — 從自訂註冊表 URL 新增後，檢查是否有不符合專案
aliases的硬編碼路徑。重寫匯入以使用components.json中的專案ui/lib別名。 - 審查已新增的元件 — 新增後，讀取已新增的檔案並驗證組合（群組、標題、驗證屬性）。根據
iconLibrary調整圖示匯入。 - 遠端註冊表項目 — 透過 URL 新增是明確的；如果使用者想要從未知來源新增元件，請在執行
add之前確認註冊表 URL 或項目。
來自 DESIGN.md 的設計系統
當使用者要求從 DESIGN.md（或品牌規格）建立設計系統時，無論是否有預設，請端到端遵循 design-system.md：
- 對於新應用程式，使用
npx sv create <app>搭建 SvelteKit（或 Svelte + Vite，當要求時），然後使用npx shadcn-svelte@latest init --preset <code>初始化。如果沒有代碼，請選擇符合 DESIGN.md 的樣式並傳遞其名稱，例如init --preset luma；React 預設代碼和搭建旗標不適用。在現有應用程式中，保留本地自訂。 - 在新應用程式中使用
add --all --yes安裝所有元件；在現有應用程式中僅新增缺少的元件。 - 在編輯之前，閱讀 DESIGN.md 的前言、注意事項與已知差距。
- 將其令牌對應到
components.json中tailwind.css的變數。固定圓角縮放、陰影、字型和type-*工具類別。 - 重新設計已安裝的
tailwind-variants變體及相關的樣式 CSS。一起變更控制項高度。 - 根據 design-system-page.md 建構頁面：對比檢查的顏色角色、字型樣本、固定的狀態矩陣、邊緣情況、注意/避免配對、使用配方。使用
scripts/showcase-coverage.mjs檢查匯入，然後驗證每個元件的渲染。 - 在瀏覽器中驗證：
svelte-check、生產建置包含 SSR、無控制台錯誤、從頂部載入、無水平溢出、深色模式。
更新元件
使用 update 指令從註冊表拉取專案中已存在元件的最新版本。在 update 之後使用 git diff 審查變更。
- 提交或暫存本地工作。
- 執行
npx shadcn-svelte@latest update [component]或--all。 - 如果自訂過檔案，請解決合併衝突。
- 未經使用者明確同意，永遠不要在
add上使用--overwrite，因為這會破壞有意的編輯。
快速參考
# 在您的專案中初始化 shadcn-svelte
...
[為翻譯而截斷]