shadcn/ui 框架：React 组件库与 UI 设计系统，Tailwind CSS 最佳实践

shadcn by shadcn/ui

45,300 周安装量

110,800 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/shadcn/ui --skill shadcn

开发设计

🇨🇳中文介绍

包含 Shell 命令

此技能包含可能执行系统命令的 shell 命令指令（!命令``）。安装前请仔细审查。

shadcn/ui

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

重要提示： 使用项目的包运行器运行所有 CLI 命令：npx shadcn@latest、pnpm dlx shadcn@latest 或 bunx --bun shadcn@latest —— 具体取决于项目的 packageManager。下面的示例使用 npx shadcn@latest，但请根据项目替换正确的运行器。

当前项目上下文

!`npx shadcn@latest info --json`

上面的 JSON 包含项目配置和已安装的组件。使用 npx shadcn@latest docs <组件名> 获取任何组件的文档和示例 URL。

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

样式与 Tailwind → 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

表单使用 FieldGroup + Field。 永远不要使用原始的 div 配合 space-y-* 或 grid gap-* 进行表单布局。
InputGroup 使用 InputGroupInput/InputGroupTextarea。 永远不要在 InputGroup 内使用原始的 Input/Textarea。
输入框内的按钮使用 InputGroup + InputGroupAddon。
选项集（2–7 个选项）使用 ToggleGroup。 不要用 Button 循环并手动管理激活状态。
分组相关的复选框/单选按钮使用 FieldSet + FieldLegend。 不要使用带标题的 div。
字段验证使用 data-invalid + aria-invalid。 data-invalid 放在 Field 上，aria-invalid 放在控件上。对于禁用状态：data-disabled 放在 Field 上，disabled 放在控件上。

组件结构 → composition.md

项目始终在其组内。 SelectItem → SelectGroup。DropdownMenuItem → DropdownMenuGroup。CommandItem → CommandGroup。
自定义触发器使用 asChild (radix) 或 render (base)。 检查 npx shadcn@latest info 中的 base 字段。→ base-vs-radix.md
Dialog、Sheet 和 Drawer 始终需要一个 Title。 为了可访问性，必须包含 DialogTitle、SheetTitle、DrawerTitle。如果视觉上隐藏，使用 className="sr-only"。
使用完整的 Card 组合。 CardHeader/CardTitle/CardDescription/CardContent/CardFooter。不要把所有东西都塞进 CardContent。
Button 没有 isPending/isLoading。 使用 Spinner + data-icon + disabled 进行组合。
TabsTrigger 必须在 TabsList 内部。 永远不要直接在 Tabs 中渲染触发器。
Avatar 始终需要 AvatarFallback。 用于图片加载失败时。

使用组件，而非自定义标记 → composition.md

在自定义标记之前优先使用现有组件。 在编写带样式的 div 之前，检查是否存在相应的组件。
提示信息使用 Alert。 不要构建自定义样式的 div。
空状态使用 Empty。 不要构建自定义的空状态标记。
Toast 通过 sonner。 使用 sonner 中的 toast()。
使用 Separator 而不是 <hr> 或 <div className="border-t">。
使用 Skeleton 作为加载占位符。不要使用自定义的 animate-pulse div。
使用 Badge 而不是自定义样式的 span。

Button 中的图标使用 data-icon。 在图标上设置 data-icon="inline-start" 或 data-icon="inline-end"。
组件内的图标不要使用尺寸类。 组件通过 CSS 处理图标尺寸。不要使用 size-4 或 w-4 h-4。
将图标作为对象传递，而非字符串键。 使用 icon={CheckIcon}，而不是字符串查找。

永远不要手动解码或获取预设代码。 直接将它们传递给 npx shadcn@latest init --preset <code>。

这些是区分正确的 shadcn/ui 代码的最常见模式。对于边缘情况，请参阅上面链接的规则文件。

// 表单布局：FieldGroup + Field，而不是 div + Label。
<FieldGroup>
  <Field>
    <FieldLabel htmlFor="email">邮箱</FieldLabel>
    <Input id="email" />
  </Field>
</FieldGroup>

// 验证：data-invalid 在 Field 上，aria-invalid 在控件上。
<Field data-invalid>
  <FieldLabel>邮箱</FieldLabel>
  <Input aria-invalid />
  <FieldDescription>邮箱无效。</FieldDescription>
</Field>

// 按钮中的图标：data-icon，无尺寸类。
<Button>
  <SearchIcon data-icon="inline-start" />
  搜索
</Button>

// 间距：gap-*，而不是 space-y-*。
<div className="flex flex-col gap-4">  // 正确
<div className="space-y-4">           // 错误

// 等尺寸：size-*，而不是 w-* h-*。
<Avatar className="size-10">   // 正确
<Avatar className="w-10 h-10"> // 错误

// 状态颜色：Badge 变体或语义化标记，而非原始颜色。
<Badge variant="secondary">+20.1%</Badge>    // 正确
<span className="text-emerald-600">+20.1%</span> // 错误

需求	使用
按钮/操作	具有适当变体的 `Button`
表单输入	`Input`、`Select`、`Combobox`、`Switch`、`Checkbox`、`RadioGroup`、`Textarea`、`InputOTP`、`Slider`
在 2–5 个选项之间切换	`ToggleGroup` + `ToggleGroupItem`
数据显示	`Table`、`Card`、`Badge`、`Avatar`
导航	`Sidebar`、`NavigationMenu`、`Breadcrumb`、`Tabs`、`Pagination`
覆盖层	`Dialog` (模态框)、`Sheet` (侧边面板)、`Drawer` (底部面板)、`AlertDialog` (确认对话框)
反馈	`sonner` (toast)、`Alert`、`Progress`、`Skeleton`、`Spinner`
命令面板	`Dialog` 内的 `Command`
图表	`Chart` (包装 Recharts)
布局	`Card`、`Separator`、`Resizable`、`ScrollArea`、`Accordion`、`Collapsible`
空状态	`Empty`
菜单	`DropdownMenu`、`ContextMenu`、`Menubar`
工具提示/信息	`Tooltip`、`HoverCard`、`Popover`

注入的项目上下文包含以下关键字段：

aliases → 使用导入的实际别名前缀（例如 @/、~/），永远不要硬编码。
isRSC → 当为 true 时，使用 useState、useEffect、事件处理程序或浏览器 API 的组件需要在文件顶部添加 "use client"。在建议该指令时始终引用此字段。
tailwindVersion → "v4" 使用 @theme inline 块；"v3" 使用 tailwind.config.js。
tailwindCssFile → 定义自定义 CSS 变量的全局 CSS 文件。始终编辑此文件，不要创建新文件。
style → 组件视觉风格（例如 nova、vega）。
base → 基础库（radix 或 base）。影响组件 API 和可用属性。
iconLibrary → 决定图标导入。对于 lucide 使用 lucide-react，对于 tabler 使用 @tabler/icons-react 等。永远不要假设是 lucide-react。
resolvedPaths → 组件、工具函数、钩子等的确切文件系统路径。
framework → 路由和文件约定（例如 Next.js App Router 与 Vite SPA）。
packageManager → 用于任何非 shadcn 依赖安装（例如 pnpm add date-fns 与 npm install date-fns）。

完整字段参考请参见 cli.md — info 命令。

组件文档、示例和用法

运行 npx shadcn@latest docs <组件名> 获取组件的文档、示例和 API 参考的 URL。获取这些 URL 以获取实际内容。

npx shadcn@latest docs button dialog select

在创建、修复、调试或使用组件时，务必先运行 npx shadcn@latest docs 并获取 URL。 这确保您使用的是正确的 API 和使用模式，而不是猜测。

获取项目上下文 —— 已注入上方。如果需要刷新，请再次运行 npx shadcn@latest info。
首先检查已安装的组件 —— 在运行 add 之前，始终检查项目上下文中的 components 列表或列出 resolvedPaths.ui 目录。不要导入尚未添加的组件，也不要重新添加已安装的组件。
查找组件 —— npx shadcn@latest search。
获取文档和示例 —— 运行 npx shadcn@latest docs <组件名> 获取 URL，然后获取它们。使用 npx shadcn@latest view 浏览尚未安装的注册表项。要预览对已安装组件的更改，请使用 npx shadcn@latest add --diff。
安装或更新 —— npx shadcn@latest add。更新现有组件时，先使用 --dry-run 和 --diff 预览更改（见下文“更新组件”）。
修复第三方组件中的导入 —— 从社区注册表（例如 @bundui、@magicui）添加组件后，检查添加的非 UI 文件中是否存在硬编码的导入路径，如 @/components/ui/...。这些路径可能与项目的实际别名不匹配。使用 npx shadcn@latest info 获取正确的 ui 别名（例如 @workspace/ui/components），并相应地重写导入。CLI 会重写其自身 UI 文件的导入，但第三方注册表组件可能使用与项目不匹配的默认路径。
审查添加的组件 —— 从任何注册表添加组件或区块后，务必阅读添加的文件并验证其正确性。检查是否缺少子组件（例如 SelectItem 没有 SelectGroup）、缺少导入、组合不正确或违反关键规则。同时，将任何图标导入替换为项目上下文中的 iconLibrary（例如，如果注册表项使用 lucide-react 但项目使用 hugeicons，则相应地交换导入和图标名称）。在继续之前修复所有问题。
注册表必须明确 —— 当用户要求添加区块或组件时，不要猜测注册表。如果未指定注册表（例如，用户说“添加登录区块”而未指定 @shadcn、@tailark 等），请询问使用哪个注册表。永远不要代表用户默认选择注册表。
切换预设 —— 先询问用户：重新安装、合并还是跳过？ * 重新安装：npx shadcn@latest init --preset <code> --force --reinstall。覆盖所有组件。 * 合并：npx shadcn@latest init --preset <code> --force --no-reinstall，然后运行 npx shadcn@latest info 列出已安装的组件，接着对每个已安装的组件使用 --dry-run 和 --diff 进行智能合并。 * 跳过：npx shadcn@latest init --preset <code> --force --no-reinstall。仅更新配置和 CSS，保持组件不变。 * 重要提示：始终在用户的项目目录内运行预设命令。CLI 会自动保留 components.json 中的当前基础库（base 与）。如果必须使用临时/临时目录（例如用于比较），请显式传递 —— 预设代码不编码基础库。

当用户要求从上游更新组件同时保留其本地更改时，使用 --dry-run 和 --diff 进行智能合并。永远不要手动从 GitHub 获取原始文件 —— 始终使用 CLI。

运行 npx shadcn@latest add <组件名> --dry-run 查看所有将受影响的文件。
对于每个文件，运行 npx shadcn@latest add <组件名> --diff <文件名> 查看上游与本地之间的差异。
根据差异决定每个文件：
- 无本地更改 → 可以安全覆盖。
- 有本地更改 → 阅读本地文件，分析差异，在保留本地修改的同时应用上游更新。
- 用户说“直接更新所有内容” → 使用 --overwrite，但需先确认。
未经用户明确批准，切勿使用 --overwrite。

# 创建新项目。
npx shadcn@latest init --name my-app --preset base-nova
npx shadcn@latest init --name my-app --preset a2r6bw --template vite

# 创建 monorepo 项目。
npx shadcn@latest init --name my-app --preset base-nova --monorepo
npx shadcn@latest init --name my-app --preset base-nova --template next --monorepo

# 初始化现有项目。
npx shadcn@latest init --preset base-nova
npx shadcn@latest init --defaults  # 快捷方式：--template=next --preset=base-nova

# 添加组件。
npx shadcn@latest add button card dialog
npx shadcn@latest add @magicui/shimmer-button
npx shadcn@latest add --all

# 在添加/更新前预览更改。
npx shadcn@latest add button --dry-run
npx shadcn@latest add button --diff button.tsx
npx shadcn@latest add @acme/form --view button.tsx

# 搜索注册表。
npx shadcn@latest search @shadcn -q "sidebar"
npx shadcn@latest search @tailark -q "stats"

# 获取组件文档和示例 URL。
npx shadcn@latest docs button dialog select

# 查看注册表项详情（针对尚未安装的项）。
npx shadcn@latest view @shadcn/button

命名预设： base-nova、radix-nova 模板： next、vite、start、react-router、astro（均支持 --monorepo）和 laravel（不支持 monorepo） 预设代码： 以 a 开头的 Base62 字符串（例如 a2r6bw），来自 ui.shadcn.com。

rules/forms.md — FieldGroup、Field、InputGroup、ToggleGroup、FieldSet、验证状态
rules/composition.md — 组、覆盖层、Card、Tabs、Avatar、Alert、Empty、Toast、Separator、Skeleton、Badge、Button 加载状态
rules/icons.md — data-icon、图标尺寸、将图标作为对象传递
rules/styling.md — 语义化颜色、变体、className、间距、尺寸、truncate、暗色模式、cn()、z-index
rules/base-vs-radix.md — asChild 与 render、Select、ToggleGroup、Slider、Accordion
cli.md — 命令、标志、预设、模板
customization.md — 主题化、CSS 变量、扩展组件

🇺🇸English

Contains Shell Commands

This skill contains shell command directives (!command``) that may execute system commands. Review carefully before installing.

shadcn/ui

A framework for building ui, components and design systems. Components are added as source code to the user's project via the CLI.

IMPORTANT: Run all CLI commands using the project's package runner: npx shadcn@latest, pnpm dlx shadcn@latest, or bunx --bun shadcn@latest — based on the project's packageManager. Examples below use npx shadcn@latest but substitute the correct runner for the project.

Current Project Context

!`npx shadcn@latest info --json`

The JSON above contains the project config and installed components. Use npx shadcn@latest docs <component> to get documentation and example URLs for any component.

Principles

Use existing components first. Use npx shadcn@latest search to check registries before writing custom UI. Check community registries too.
Compose, don't reinvent. Settings page = Tabs + Card + form controls. Dashboard = Sidebar + Card + Chart + Table.
Use built-in variants before custom styles. variant="outline", size="sm", etc.
Use semantic colors. bg-primary, text-muted-foreground — never raw values like bg-blue-500.

Critical Rules

These rules are always enforced. Each links to a file with Incorrect/Correct code pairs.

Styling & Tailwind → styling.md

className for layout, not styling. Never override component colors or typography.
Nospace-x-* or space-y-*. Use flex with gap-*. For vertical stacks, flex flex-col gap-*.
Usesize-* when width and height are equal. size-10 not w-10 h-10.
Usetruncate shorthand. Not .

Forms & Inputs → forms.md

Forms useFieldGroup + Field. Never use raw div with space-y-* or grid gap-* for form layout.
InputGroup uses InputGroupInput/InputGroupTextarea. Never raw Input/Textarea inside InputGroup.

Component Structure → composition.md

Items always inside their Group. SelectItem → SelectGroup. DropdownMenuItem → DropdownMenuGroup. CommandItem → CommandGroup.
UseasChild (radix) or render (base) for custom triggers. Check base field from npx shadcn@latest info. → base-vs-radix.md

Use Components, Not Custom Markup → composition.md

Use existing components before custom markup. Check if a component exists before writing a styled div.
Callouts useAlert. Don't build custom styled divs.
Empty states useEmpty. Don't build custom empty state markup.
Toast viasonner. Use toast() from sonner.
UseSeparator instead of <hr> or <div className="border-t">.

Icons → icons.md

Icons inButton use data-icon. data-icon="inline-start" or data-icon="inline-end" on the icon.
No sizing classes on icons inside components. Components handle icon sizing via CSS. No size-4 or w-4 h-4.
Pass icons as objects, not string keys. icon={CheckIcon}, not a string lookup.

CLI

Never decode or fetch preset codes manually. Pass them directly to npx shadcn@latest init --preset <code>.

Key Patterns

These are the most common patterns that differentiate correct shadcn/ui code. For edge cases, see the linked rule files above.

// Form layout: FieldGroup + Field, not div + Label.
<FieldGroup>
  <Field>
    <FieldLabel htmlFor="email">Email</FieldLabel>
    <Input id="email" />
  </Field>
</FieldGroup>

// Validation: data-invalid on Field, aria-invalid on the control.
<Field data-invalid>
  <FieldLabel>Email</FieldLabel>
  <Input aria-invalid />
  <FieldDescription>Invalid email.</FieldDescription>
</Field>

// Icons in buttons: data-icon, no sizing classes.
<Button>
  <SearchIcon data-icon="inline-start" />
  Search
</Button>

// Spacing: gap-*, not space-y-*.
<div className="flex flex-col gap-4">  // correct
<div className="space-y-4">           // wrong

// Equal dimensions: size-*, not w-* h-*.
<Avatar className="size-10">   // correct
<Avatar className="w-10 h-10"> // wrong

// Status colors: Badge variants or semantic tokens, not raw colors.
<Badge variant="secondary">+20.1%</Badge>    // correct
<span className="text-emerald-600">+20.1%</span> // wrong

Component Selection

Need	Use
Button/action	`Button` with appropriate variant
Form inputs	`Input`, `Select`, `Combobox`, `Switch`, `Checkbox`, `RadioGroup`, `Textarea`, `InputOTP`,

Key Fields

The injected project context contains these key fields:

aliases → use the actual alias prefix for imports (e.g. @/, ~/), never hardcode.
isRSC → when true, components using useState, useEffect, event handlers, or browser APIs need "use client" at the top of the file. Always reference this field when advising on the directive.
tailwindVersion → "v4" uses blocks; uses .

See cli.md — info command for the full field reference.

Component Docs, Examples, and Usage

Run npx shadcn@latest docs <component> to get the URLs for a component's documentation, examples, and API reference. Fetch these URLs to get the actual content.

npx shadcn@latest docs button dialog select

When creating, fixing, debugging, or using a component, always runnpx shadcn@latest docs and fetch the URLs first. This ensures you're working with the correct API and usage patterns rather than guessing.

Workflow

Get project context — already injected above. Run npx shadcn@latest info again if you need to refresh.
Check installed components first — before running add, always check the components list from project context or list the resolvedPaths.ui directory. Don't import components that haven't been added, and don't re-add ones already installed.
Find components — npx shadcn@latest search.
Get docs and examples — run npx shadcn@latest docs <component> to get URLs, then fetch them. Use npx shadcn@latest view to browse registry items you haven't installed. To preview changes to installed components, use npx shadcn@latest add --diff.

Updating Components

When the user asks to update a component from upstream while keeping their local changes, use --dry-run and --diff to intelligently merge. NEVER fetch raw files from GitHub manually — always use the CLI.

Run npx shadcn@latest add <component> --dry-run to see all files that would be affected.
For each file, run npx shadcn@latest add <component> --diff <file> to see what changed upstream vs local.
Decide per file based on the diff:
- No local changes → safe to overwrite.
- Has local changes → read the local file, analyze the diff, and apply upstream updates while preserving local modifications.
- User says "just update everything" → use --overwrite, but confirm first.
Never use--overwrite without the user's explicit approval.

Quick Reference

# Create a new project.
npx shadcn@latest init --name my-app --preset base-nova
npx shadcn@latest init --name my-app --preset a2r6bw --template vite

# Create a monorepo project.
npx shadcn@latest init --name my-app --preset base-nova --monorepo
npx shadcn@latest init --name my-app --preset base-nova --template next --monorepo

# Initialize existing project.
npx shadcn@latest init --preset base-nova
npx shadcn@latest init --defaults  # shortcut: --template=next --preset=base-nova

# Add components.
npx shadcn@latest add button card dialog
npx shadcn@latest add @magicui/shimmer-button
npx shadcn@latest add --all

# Preview changes before adding/updating.
npx shadcn@latest add button --dry-run
npx shadcn@latest add button --diff button.tsx
npx shadcn@latest add @acme/form --view button.tsx

# Search registries.
npx shadcn@latest search @shadcn -q "sidebar"
npx shadcn@latest search @tailark -q "stats"

# Get component docs and example URLs.
npx shadcn@latest docs button dialog select

# View registry item details (for items not yet installed).
npx shadcn@latest view @shadcn/button

Named presets: base-nova, radix-nova Templates: next, vite, start, react-router, astro (all support --monorepo) and laravel (not supported for monorepo) Preset codes: Base62 strings starting with a (e.g. a2r6bw), from .

Detailed References

rules/forms.md — FieldGroup, Field, InputGroup, ToggleGroup, FieldSet, validation states
rules/composition.md — Groups, overlays, Card, Tabs, Avatar, Alert, Empty, Toast, Separator, Skeleton, Badge, Button loading
rules/icons.md — data-icon, icon sizing, passing icons as objects
rules/styling.md — Semantic colors, variants, className, spacing, size, truncate, dark mode, cn(), z-index
rules/base-vs-radix.md — asChild vs render, Select, ToggleGroup, Slider, Accordion
cli.md — Commands, flags, presets, templates
customization.md — Theming, CSS variables, extending components

Weekly Installs

40.8K

Repository

shadcn/ui

GitHub Stars

110.5K

First Seen

Mar 6, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

codex39.4K

cursor39.4K

github-copilot39.3K

opencode39.2K

gemini-cli38.9K

amp38.7K

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

102,200 周安装

--base <current-base>

overflow-hidden text-ellipsis whitespace-nowrap

No manualdark: color overrides. Use semantic tokens (bg-background, text-muted-foreground).

Usecn() for conditional classes. Don't write manual template literal ternaries.

No manualz-index on overlay components. Dialog, Sheet, Popover, etc. handle their own stacking.

Buttons inside inputs useInputGroup + InputGroupAddon.

Option sets (2–7 choices) useToggleGroup. Don't loop Button with manual active state.

FieldSet + FieldLegend for grouping related checkboxes/radios. Don't use a div with a heading.

Field validation usesdata-invalid + aria-invalid. data-invalid on Field, aria-invalid on the control. For disabled: data-disabled on Field, disabled on the control.

Dialog, Sheet, and Drawer always need a Title. DialogTitle, SheetTitle, DrawerTitle required for accessibility. Use className="sr-only" if visually hidden.

Use full Card composition. CardHeader/CardTitle/CardDescription/CardContent/CardFooter. Don't dump everything in CardContent.

Button has noisPending/isLoading. Compose with Spinner + data-icon + disabled.

TabsTrigger must be inside TabsList. Never render triggers directly in Tabs.

Avatar always needs AvatarFallback. For when the image fails to load.

UseSkeleton for loading placeholders. No custom animate-pulse divs.

UseBadge instead of custom styled spans.

tailwind.config.js

tailwindCssFile → the global CSS file where custom CSS variables are defined. Always edit this file, never create a new one.

style → component visual treatment (e.g. nova, vega).

base → primitive library (radix or base). Affects component APIs and available props.

iconLibrary → determines icon imports. Use lucide-react for lucide, @tabler/icons-react for tabler, etc. Never assume lucide-react.

resolvedPaths → exact file-system destinations for components, utils, hooks, etc.

framework → routing and file conventions (e.g. Next.js App Router vs Vite SPA).

packageManager → use this for any non-shadcn dependency installs (e.g. pnpm add date-fns vs npm install date-fns).

Install or update — npx shadcn@latest add. When updating existing components, use --dry-run and --diff to preview changes first (see Updating Components below).

Fix imports in third-party components — After adding components from community registries (e.g. @bundui, @magicui), check the added non-UI files for hardcoded import paths like @/components/ui/.... These won't match the project's actual aliases. Use npx shadcn@latest info to get the correct ui alias (e.g. @workspace/ui/components) and rewrite the imports accordingly. The CLI rewrites imports for its own UI files, but third-party registry components may use default paths that don't match the project.

Review added components — After adding a component or block from any registry, always read the added files and verify they are correct. Check for missing sub-components (e.g. SelectItem without SelectGroup), missing imports, incorrect composition, or violations of the Critical Rules. Also replace any icon imports with the project's iconLibrary from the project context (e.g. if the registry item uses lucide-react but the project uses hugeicons, swap the imports and icon names accordingly). Fix all issues before moving on.

Registry must be explicit — When the user asks to add a block or component, do not guess the registry. If no registry is specified (e.g. user says "add a login block" without specifying @shadcn, @tailark, etc.), ask which registry to use. Never default to a registry on behalf of the user.

Switching presets — Ask the user first: reinstall , merge , or skip?

Reinstall : npx shadcn@latest init --preset <code> --force --reinstall. Overwrites all components.
Merge : npx shadcn@latest init --preset <code> --force --no-reinstall, then run npx shadcn@latest info to list installed components, then for each installed component use --dry-run and --diff to smart merge it individually.
Skip : npx shadcn@latest init --preset <code> --force --no-reinstall. Only updates config and CSS, leaves components as-is.
Important : Always run preset commands inside the user's project directory. The CLI automatically preserves the current base (base vs radix) from components.json. If you must use a scratch/temp directory (e.g. for --dry-run comparisons), pass --base <current-base> explicitly — preset codes do not encode the base.

shadcn/ui 框架：React 组件库与 UI 设计系统，Tailwind CSS 最佳实践

🇨🇳中文介绍

shadcn/ui

当前项目上下文

相关 Skills

原则

关键规则

样式与 Tailwind → styling.md

表单与输入 → forms.md

组件结构 → composition.md

使用组件，而非自定义标记 → composition.md

图标 → icons.md

CLI

关键模式

组件选择

关键字段

组件文档、示例和用法

工作流程

更新组件

快速参考

详细参考

🇺🇸English

shadcn/ui

Current Project Context

Principles

Critical Rules

Styling & Tailwind → styling.md

Forms & Inputs → forms.md

Component Structure → composition.md

Use Components, Not Custom Markup → composition.md

Icons → icons.md

CLI

Key Patterns

Component Selection

Key Fields

Component Docs, Examples, and Usage

Workflow

Updating Components

Quick Reference

Detailed References

最新 Skills