shadcn

# shadcn/ui 一个用于构建 UI、组件和设计系统的框架。组件通过 CLI 作为源代码添加到用户的项目中。 > **重要：** 使用项目的包运行器运行所有 CLI 命令：`npx shadcn@latest`、`pnpm dlx shadcn@latest` 或 `bunx --bun shadcn@latest` — 具体取决于项目的 `packageManager`。以下示例使用 `npx shadcn@latest`，请根据项目替换为正确的运行器。 ## 何时使用 - 当从 shadcn/ui 或社区注册表添加新组件时使用。 - 当样式化、组合或调试现有的 shadcn/ui 组件时使用。 - 当初始化新项目或切换设计系统预设时使用。 - 用于检索组件文档、示例和 API 参考。 ## 当前项目上下文 !`npx shadcn@latest info --json 2>/dev/null || echo '{"error": "未找到 shadcn 项目。请先运行 shadcn init。"}'` 上述 JSON 包含项目配置和已安装的组件。使用 `npx shadcn@latest docs ` 获取任何组件的文档和示例 URL。 ## 原则 1. **优先使用现有组件。** 在编写自定义 UI 之前，使用 `npx shadcn@latest search` 检查注册表。同时检查社区注册表。 2. **组合，不要重复造轮子。** 设置页面 = Tabs + Card + 表单控件。仪表板 = Sidebar + Card + Chart + Table。 3. **优先使用内置变体而非自定义样式。** `variant="outline"`, `size="sm"` 等。 4. **使用语义化颜色。** `bg-primary`, `text-muted-foreground` — 永远不要使用原始值，如 `bg-blue-500`。 ## 关键规则 这些规则是**强制执行的**。每一项都链接到一个包含错误/正确代码对的文件。 ### 样式与 Tailwind → [styling.md](./rules/styling.md) - **`className` 用于布局，而非样式。** 永远不要覆盖组件颜色或排版。 - **禁止使用 `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](./rules/forms.md) - **表单使用 `FieldGroup` + `Field`。** 永远不要使用带有 `spac` 的原始 `div`