shadcn-ui

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

<essential_principles>

How shadcn/ui Works

shadcn/ui 工作原理

shadcn/ui is NOT a component library - it's a collection of re-usable components you copy into your project and own. This philosophy changes everything about how you work with it.

shadcn/ui 并非组件库——它是一组可复用组件的集合，你可以将其复制到自己的项目中并完全拥有。这一理念彻底改变了你的使用方式。

1. You Own the Code

1. 你完全拥有代码

Components are copied directly into your

components/ui/

directory. You can and should modify them. Don't wrap components - edit them directly. This is intentional.

bash

undefined

组件会直接复制到你的

components/ui/

目录中。你可以且应该对其进行修改。不要封装组件——直接编辑它们。这是有意设计的。

bash

undefined

Install a component

npx shadcn@latest add button

Components land in your project

src/components/ui/button.tsx

undefined

undefined

2. Composition Over Monoliths

2. 组合优先，而非单体化

Build complex UIs by composing primitives. Every component follows consistent patterns:

Radix UI primitives for accessibility
CVA (class-variance-authority) for variants
cn() utility for conditional classes
data-slot attributes for styling hooks

tsx

// Composition pattern - build from primitives
<Dialog>
  <DialogTrigger asChild>
    <Button variant="outline">Open</Button>
  </DialogTrigger>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Title</DialogTitle>
      <DialogDescription>Description</DialogDescription>
    </DialogHeader>
    {/* Content */}
    <DialogFooter>
      <Button>Save</Button>
    </DialogFooter>
  </DialogContent>
</Dialog>

通过组合基础元素构建复杂界面。每个组件都遵循一致的模式：

Radix UI primitives 用于无障碍访问
CVA (class-variance-authority) 用于变体管理
cn() 工具函数 用于条件类名
data-slot 属性 用于样式钩子

tsx

// Composition pattern - build from primitives
<Dialog>
  <DialogTrigger asChild>
    <Button variant="outline">Open</Button>
  </DialogTrigger>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Title</DialogTitle>
      <DialogDescription>Description</DialogDescription>
    </DialogHeader>
    {/* Content */}
    <DialogFooter>
      <Button>Save</Button>
    </DialogFooter>
  </DialogContent>
</Dialog>

3. The asChild Pattern

3. asChild 模式

Use

asChild

prop to merge behavior onto a different element. Critical for navigation, forms, and custom triggers.

tsx

// asChild merges Button behavior onto Link
<Button asChild>
  <Link href="/dashboard">Dashboard</Link>
</Button>

// asChild on DialogTrigger
<DialogTrigger asChild>
  <Button>Open Dialog</Button>
</DialogTrigger>

使用

asChild

属性将组件行为合并到其他元素上。这在导航、表单和自定义触发器场景中至关重要。

tsx

// asChild merges Button behavior onto Link
<Button asChild>
  <Link href="/dashboard">Dashboard</Link>
</Button>

// asChild on DialogTrigger
<DialogTrigger asChild>
  <Button>Open Dialog</Button>
</DialogTrigger>

4. Variant-Driven Design

4. 变体驱动设计

Use CVA for consistent variant APIs. Every button, badge, and alert follows this pattern:

tsx

const buttonVariants = cva(
  "inline-flex items-center justify-center rounded-md...", // Base
  {
    variants: {
      variant: {
        default: "bg-primary text-primary-foreground",
        destructive: "bg-destructive text-white",
        outline: "border bg-background",
        ghost: "hover:bg-accent",
      },
      size: {
        default: "h-9 px-4",
        sm: "h-8 px-3",
        lg: "h-10 px-6",
        icon: "size-9",
      },
    },
    defaultVariants: {
      variant: "default",
      size: "default",
    },
  }
)

使用CVA实现一致的变体API。每个按钮、徽章和提示框都遵循此模式：

tsx

const buttonVariants = cva(
  "inline-flex items-center justify-center rounded-md...", // Base
  {
    variants: {
      variant: {
        default: "bg-primary text-primary-foreground",
        destructive: "bg-destructive text-white",
        outline: "border bg-background",
        ghost: "hover:bg-accent",
      },
      size: {
        default: "h-9 px-4",
        sm: "h-8 px-3",
        lg: "h-10 px-6",
        icon: "size-9",
      },
    },
    defaultVariants: {
      variant: "default",
      size: "default",
    },
  }
)

5. CSS Variables for Theming

5. CSS变量用于主题配置

All colors use CSS variables. Theme by changing variables, not component code:

css

/* Light mode */
:root {
  --background: 0 0% 100%;
  --foreground: 222.2 84% 4.9%;
  --primary: 222.2 47.4% 11.2%;
  --primary-foreground: 210 40% 98%;
}

/* Dark mode */
.dark {
  --background: 222.2 84% 4.9%;
  --foreground: 210 40% 98%;
}

所有颜色均使用CSS变量。通过修改变量而非组件代码来配置主题：

css

/* Light mode */
:root {
  --background: 0 0% 100%;
  --foreground: 222.2 84% 4.9%;
  --primary: 222.2 47.4% 11.2%;
  --primary-foreground: 210 40% 98%;
}

/* Dark mode */
.dark {
  --background: 222.2 84% 4.9%;
  --foreground: 210 40% 98%;
}

6. React 19 Patterns

6. React 19 模式

shadcn/ui uses modern React patterns - no forwardRef (React 19), data-slot attributes, and function components:

tsx

// Modern pattern (no forwardRef in React 19)
function Button({ className, variant, size, asChild = false, ...props }) {
  const Comp = asChild ? Slot : "button"
  return (
    <Comp
      data-slot="button"
      className={cn(buttonVariants({ variant, size, className }))}
      {...props}
    />
  )
}

</essential_principles>

<intake> **What would you like to do?**

Add a new shadcn component to the project
Build a form with validation
Build a data table with sorting/filtering
Customize an existing component
Create a compound component
Add animations/transitions
Set up or modify theming
Debug a component issue
Something else

Then read the matching workflow from
workflows/
and follow it. </intake>

<routing> | Response | Workflow | |----------|----------| | 1, "add", "install", "component" | `workflows/add-component.md` | | 2, "form", "validation", "input" | `workflows/build-form.md` | | 3, "table", "data table", "sorting", "filtering" | `workflows/build-data-table.md` | | 4, "customize", "modify", "change", "edit" | `workflows/customize-component.md` | | 5, "compound", "create", "new component", "build component" | `workflows/build-compound-component.md` | | 6, "animation", "motion", "transition", "animate" | `workflows/add-animations.md` | | 7, "theme", "dark mode", "colors", "styling" | `workflows/setup-theming.md` | | 8, "debug", "fix", "broken", "not working", "issue" | `workflows/debug-component.md` | | 9, other | Clarify, then select workflow or references |

After reading the workflow, follow it exactly. </routing>

<verification_loop>

shadcn/ui 使用现代React模式——无需forwardRef（React 19）、data-slot属性和函数组件：

tsx

// Modern pattern (no forwardRef in React 19)
function Button({ className, variant, size, asChild = false, ...props }) {
  const Comp = asChild ? Slot : "button"
  return (
    <Comp
      data-slot="button"
      className={cn(buttonVariants({ variant, size, className }))}
      {...props}
    />
  )
}

</essential_principles>

<intake> **你想要执行什么操作？**

向项目中添加新的shadcn组件
构建带验证功能的表单
构建带排序/筛选功能的数据表格
自定义现有组件
创建复合组件
添加动画/过渡效果
设置或修改主题
调试组件问题
其他操作

然后阅读
workflows/
中对应的工作流并遵循其步骤。 </intake>

<routing> | 响应内容 | 工作流 | |----------|----------| | 1, "add", "install", "component" | `workflows/add-component.md` | | 2, "form", "validation", "input" | `workflows/build-form.md` | | 3, "table", "data table", "sorting", "filtering" | `workflows/build-data-table.md` | | 4, "customize", "modify", "change", "edit" | `workflows/customize-component.md` | | 5, "compound", "create", "new component", "build component" | `workflows/build-compound-component.md` | | 6, "animation", "motion", "transition", "animate" | `workflows/add-animations.md` | | 7, "theme", "dark mode", "colors", "styling" | `workflows/setup-theming.md` | | 8, "debug", "fix", "broken", "not working", "issue" | `workflows/debug-component.md` | | 9, other | 先明确需求，再选择对应的工作流或参考文档 |

阅读工作流后，请严格按照其步骤执行。 </routing>

<verification_loop>

After Every Change

每次修改后执行以下检查

TypeScript compiles?

bash

bunx tsc --noEmit

Component renders? Check the dev server - no console errors
Accessibility check:

Keyboard navigation works
Focus states visible
ARIA attributes present

Visual check:

Matches design intent
Works in light/dark mode
Responsive on mobile

Report: "TypeScript: ✓ | Renders: ✓ | A11y: ✓ | Visual: ✓" </verification_loop>

<reference_index>

TypeScript 能否编译？

bash

bunx tsc --noEmit

组件能否正常渲染？ 检查开发服务器——控制台无错误
无障碍访问检查：

键盘导航正常工作
焦点状态可见
ARIA 属性存在

视觉检查：

符合设计预期
支持亮色/暗色模式
在移动端响应正常

报告格式："TypeScript: ✓ | 渲染: ✓ | 无障碍: ✓ | 视觉: ✓" </verification_loop>

<reference_index>

Domain Knowledge

领域知识文档

All in

references/

Core:

core-components.md - Button, Input, Label, Card, Badge, etc.
composition-patterns.md - asChild, Slot, compound components

Forms:

form-components.md - Form, Field, Input, Select, Combobox, etc.
form-validation.md - Zod, React Hook Form, TanStack Form

Data Display:

data-table.md - TanStack Table integration
data-components.md - Kanban, Gantt, List, Calendar

Navigation:

navigation-components.md - Sidebar, Tabs, Breadcrumb, Command

Overlays:

overlay-components.md - Dialog, Sheet, Drawer, Popover, Tooltip

Feedback:

feedback-components.md - Toast/Sonner, Alert, Progress, Skeleton

Hooks:

hooks.md - useLocalStorage, useMediaQuery, useDebounce, etc.

Animation:

animation-patterns.md - Framer Motion, micro-interactions

Theming:

theming.md - CSS variables, dark mode, color system

Advanced:

cli-registry.md - CLI commands, custom registries
accessibility.md - WCAG compliance, keyboard navigation </reference_index>

<workflows_index>

所有文档均位于

references/

目录下：

核心内容：

core-components.md - 按钮、输入框、标签、卡片、徽章等
composition-patterns.md - asChild、Slot、复合组件

表单：

form-components.md - 表单、字段、输入框、选择器、组合框等
form-validation.md - Zod、React Hook Form、TanStack Form

数据展示：

data-table.md - TanStack Table 集成
data-components.md - 看板、甘特图、列表、日历

导航：

navigation-components.md - 侧边栏、标签页、面包屑、命令面板

浮层：

overlay-components.md - 对话框、侧边抽屉、弹出框、工具提示

反馈：

feedback-components.md - 提示框/Sonner、警告、进度条、骨架屏

钩子：

hooks.md - useLocalStorage、useMediaQuery、useDebounce等

动画：

animation-patterns.md - Framer Motion、微交互

主题：

theming.md - CSS变量、暗色模式、颜色系统

进阶内容：

cli-registry.md - CLI命令、自定义注册表
accessibility.md - WCAG合规、键盘导航 </reference_index>

<workflows_index>

Workflows

工作流文档

All in

workflows/

File	Purpose
add-component.md	Install and configure a shadcn component
build-form.md	Build forms with validation
build-data-table.md	Build tables with TanStack Table
customize-component.md	Modify existing components
build-compound-component.md	Create new compound components
add-animations.md	Add Framer Motion animations
setup-theming.md	Configure theming and dark mode
debug-component.md	Troubleshoot component issues
</workflows_index>

所有文档均位于

workflows/

目录下：

文件	用途
add-component.md	安装并配置shadcn组件
build-form.md	构建带验证功能的表单
build-data-table.md	使用TanStack Table构建表格
customize-component.md	修改现有组件
build-compound-component.md	创建新的复合组件
add-animations.md	添加Framer Motion动画
setup-theming.md	配置主题与暗色模式
debug-component.md	排查组件问题
</workflows_index>