用途
shadcn-svelte 指南用于在 Svelte 5 与 Tailwind v4.1 环境下使用 shadcn-svelte 组件、集成 TanStack Table，并排查那些官方文档通常不会提及的反应性缺陷与迁移问题。它假设读者已经知道如何运行 npx shadcn-svelte@latest add，因此内容集中在“文档不会告诉你的事”。
主要能力
- 列出若干“绝不要做”的规则：不要在模块层解构 Bits UI builder（如 const { trigger } = Dialog），因为 builder 是反应式对象，解构会捕获过期引用，应改用 asChild let:builder 模式；不要把 data: myData 直接传给 createSvelteTable，Svelte 5 runes 需要 getter 访问器，否则数据永不更新；不要在 Tailwind v4.1 中使用 @tailwind base/components/utilities，这些指令会静默失效，应使用 @import "tailwindcss"；不要指望 npm update 修补 shadcn 组件，它们已被 fork 进你的代码库，维护由你负责；不要为简单展示表格一开始就用 TanStack Table，其复杂度攀升陡峭（每增加一个功能约增加 100–200 行）。
- 提供库选型决策树：需要自己掌控代码、深度定制选 shadcn-svelte（内置 TanStack 集成、可复制粘贴修改）；想快速交付、之后再定制选 Skeleton UI（预置主题、npm 包自动更新）；无障碍优先、自带样式选 Melt UI（仅无头原语）；都不合适则基于 Bits UI 原语自行构建。关键权衡是 shadcn 并非库，而是把组件 fork 到 $lib/components/ui/，安全补丁、缺陷修复与升级永久由你负责。
- 给出数据表格复杂度参考：简单表格约 50 行；加排序 +100 行；加过滤 +150 行；加选择 +200 行；加可见性 +100 行。建议先用 <table>，需要 2 个以上功能再升级到 TanStack。
- 列出关键反模式及修正：Bits UI 早期 builder 解构会导致组件渲染但点击处理器静默失败；TanStack Table 缺少 get 访问器会导致表格渲染正常、分页 UI 可用，但排序/过滤点击无效，且每个 onXChange 处理器都必须同时处理函数与值（typeof updater === "function" ? updater(old) : updater）；Tailwind v4.1 静默迁移失败会导致开发环境样式正常（缓存）而生产构建零 Tailwind 类且无报错，vite.config.ts 中 tailwindcss() 插件需排在 sveltekit() 之前；superforms 在 bind 之前解构会使 formData 变成过期引用、校验失效，应使用 bind: 连接 store。
- 提供专家模式：Tailwind v4.1 的 CSS 变量主题需使用空格分隔的 HSL 格式（而非 hsl(H,S,L)），才能让 /alpha 语法生效；表单字段模式使用 Form.Field、Form.Control let:attrs、Form.Label、Input 与 Form.FieldErrors，let:attrs 自动展开 aria 属性，Form.FieldErrors 自动接入校验状态。
- 提供调试清单：表格不更新时检查是否用了 get data() 访问器、所有状态是否用 get 包裹、每个 onXChange 是否有 typeof updater === "function" 守卫；builder 未定义时检查 Trigger 上是否有 asChild let:builder、是否传入 builders={[builder]} 数组、是否存在模块层解构；Tailwind 类缺失时检查是否用 @import "tailwindcss"、vite.config 是否含 @tailwindcss/vite 插件、插件是否排在 sveltekit() 之前、是否清除了 .svelte-kit/ 与 node_modules/.vite/ 缓存。
- 说明参考文档加载时机：实现 3 个以上表格功能（排序+过滤+选择）、TanStack 报错涉及 columnDef 或 getCoreRowModel、跨分页数据的复选框行选择时，加载 references/datatable-tanstack-svelte5.md；多步向导表单校验、跨字段依赖或异步校验、Zod + superforms 后端集成时，加载 references/form-patterns.md；库选择、反模式调试或 Tailwind 迁移则无需加载参考文档。
使用方式
该指南以规则、决策树、代码示例与调试清单的形式组织，读者按需查阅对应章节即可。涉及安装命令时使用 npx shadcn-svelte@latest add。
适用场景
适用于使用 shadcn-svelte 组件、在 Svelte 5 中集成 TanStack Table、从旧版 Tailwind 迁移到 v4.1、使用 superforms 处理表单，以及需要在多个 Svelte UI 库之间做选型权衡的开发者。
限制
该指南假设读者已掌握 shadcn-svelte 组件的基本添加方式；其内容聚焦于特定版本（Svelte 5、Tailwind v4.1）下的行为与陷阱。关于收费、价格、平台支持范围等信息，资料中暂未提供。