shadcn-svelte

shadcn-svelte

用于为 Svelte 构建 UI、组件和设计系统的框架。通过 CLI 将组件以源代码的形式添加到用户的项目中。

IMPORTANT： 所有 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/...），不要硬编码路径。

原则

1. 优先使用现有组件。 运行不带参数的 npx shadcn-svelte@latest add 浏览可用组件，或在编写自定义 UI 前查看组件。
2. 组合组件，不要重新发明。 设置页面 = Tabs + Card + 表单控件。仪表板 = Sidebar + Card + Chart + Table。
3. 优先使用内置变体，而非自定义样式。 variant="outline"、size="sm" 等。
4. 使用语义颜色。 bg-primary、text-muted-foreground，不要使用 bg-blue-500 之类的原始值。

关键规则

这些规则始终强制执行。每条规则都链接到一个包含错误/正确代码示例的文件。

样式与 Tailwind → styling.md

• class 用于布局，而非样式。 切勿覆盖组件的颜色或排版。
• 不要使用 space-x-* 或 space-y-*。 使用带有 gap-* 的 flex。垂直堆叠时，使用 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。 表单布局不要使用带有 space-y-* 或 grid gap-* 的原始 div。
• InputGroup 使用 InputGroup.Input/InputGroup.Textarea。 不要在 InputGroup.Root 内使用原始 Input/Textarea。
• 输入框内的按钮使用 InputGroup.Root + InputGroup.Addon。
• 选项集（2–7 个选项）使用 ToggleGroup。 不要循环渲染 Button 并手动管理激活状态。
• 使用 Field.FieldSet + Field.FieldLegend 对相关复选框/单选框分组。 不要使用带标题的 div。
• 字段验证使用 data-invalid + aria-invalid。 data-invalid 放在 Field 上，aria-invalid 放在控件上。禁用时：data-disabled 放在 Field 上，disabled 放在控件上。

组件结构 → composition.md

• 条目必须始终位于其分组内。 Select.Item → Select.Group。DropdownMenu.Item → DropdownMenu.Group。Command.Item → Command.Group。
• 自定义触发器。 将控件包装在 Dialog.Trigger / AlertDialog.Trigger 中，或在根组件上使用 bind:open 控制打开状态 — 参见组件文档。
• Dialog、Sheet 和 Drawer 始终需要标题。 为保证无障碍访问，必须提供 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。 不要构建自定义空状态标记。
• Toast 使用 svelte-sonner。 使用 svelte-sonner 中的 toast()，以及 UI 文件夹中的 Sonner 组件。
• 使用 Separator，而不是 <hr> 或只有边框类的 div。
• 使用 Skeleton 作为加载占位符。不要使用自定义的 animate-pulse div。
• 使用 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>
    <Field.FieldLabel for="email">Email</Field.FieldLabel>
    <Input id="email" />
  </Field.Field>
</Field.FieldGroup>


<Field.Field data-invalid>
  <Field.FieldLabel for="email">Email</Field.FieldLabel>
  <Input id="email" aria-invalid />
  <Field.FieldDescription>Invalid email.</Field.FieldDescription>
</Field.Field>


<Button>
  <SearchIcon data-icon="inline-start" />
  Search
</Button>


<div class="flex flex-col gap-4"></div>


<Avatar.Root class="size-10">
  <Avatar.Image src="/u.png" alt="User" />
  <Avatar.Fallback>U</Avatar.Fallback>
</Avatar.Root>


<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。

工作流

1. 获取项目上下文 — 阅读 components.json，并在需要时列出 UI 组件目录。
2. 先检查已安装的组件 — 运行 add 之前，列出解析后的 ui 路径下的文件。不要导入尚未添加的组件，也不要重复添加已存在的组件，除非要更新。
3. 查找组件 — 不带参数运行 npx shadcn-svelte@latest add（交互式列表），或查看文档网站。
4. 安装或更新 — 运行 npx shadcn-svelte@latest add <name> 或提供注册表 URL。若要从注册表刷新现有文件，请使用 npx shadcn-svelte@latest update（参见 cli.md）。
5. 修正第三方 / 通过 URL 添加的项目中的导入 — 从自定义注册表 URL 添加后，检查是否存在与项目 aliases 不符的硬编码路径。将导入改为使用 components.json 中项目的 ui / lib 别名。
6. 检查已添加的组件 — 添加后，阅读已添加的文件，并验证组合方式（分组、标题、验证属性）。确保图标导入与 iconLibrary 一致。
7. 远程注册表项目 — 通过 URL 添加需要明确指定；如果用户想要来自未知来源的组件，请先确认注册表 URL 或项目，再运行 add。

更新组件

使用 update 命令拉取项目中已有组件的最新注册表版本。运行 update 后，使用 git diff 检查更改。

1. 提交或暂存本地工作。
2. 运行 npx shadcn-svelte@latest update [component] 或 --all。
3. 如果自定义过文件，请解决合并冲突。
4. 如果使用 --overwrite 运行 add 会破坏有意保留的修改，未经用户明确批准，切勿这样做。

快速参考

# Initialize shadcn-svelte in your project.
npx shadcn-svelte@latest init

# Initialize with a preset string from the docs site builder.
npx shadcn-svelte@latest init --preset <code>

# Add components (interactive when run with no names).
npx shadcn-svelte@latest add
npx shadcn-svelte@latest add button card dialog
npx shadcn-svelte@latest add --all

# Update components already installed.
npx shadcn-svelte@latest update button
npx shadcn-svelte@latest update --all --yes

# Build a custom registry (registry authors).
npx shadcn-svelte@latest registry build

注册表： 默认地址为 https://shadcn-svelte.com/registry — 如有需要，可在 components.json 中覆盖。
文档： shadcn-svelte.com

详细参考

• rules/forms.md — Field.FieldGroup、Field.Field、InputGroup、ToggleGroup、Field.FieldSet、验证状态
• rules/composition.md — 分组、叠加层、Card、Tabs、Avatar、Alert、Empty、Toast、Separator、Skeleton、Badge、Button 加载状态
• rules/icons.md — data-icon、图标尺寸、传递图标组件
• rules/styling.md — 语义颜色、变体、class、间距、尺寸、截断、深色模式、cn()、z-index
• cli.md — 命令、标志、注册表
• customization.md — 主题设置、CSS 变量、扩展组件