shadcn-ui

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

shadcn/ui

Overview

概述

Guides building accessible, customizable UI with shadcn/ui as a code generation platform (not an npm dependency). Components are copied into your project via the CLI and fully owned. Supports Radix UI or Base UI primitives, Tailwind CSS 4 with oklch color tokens, React 19 direct ref patterns, and type-safe form validation with the Field component and Zod.

When to use: Adding shadcn/ui components, theming with CSS variables and oklch colors, building forms with React Hook Form or TanStack Form, creating custom registries, composing accessible component variants, setting up dark mode.

When NOT to use: Non-React frameworks (use shadcn-vue or shadcn-svelte instead), projects using a different component library (MUI, Chakra), projects not using Tailwind CSS.

本指南介绍如何将shadcn/ui作为代码生成平台（而非npm依赖）构建可访问、可定制的UI。组件通过CLI复制到你的项目中，完全由你方所有。支持Radix UI或Base UI原语、带有oklch颜色令牌的Tailwind CSS 4、React 19直接ref模式，以及基于Field组件和Zod的类型安全表单验证。

适用场景： 添加shadcn/ui组件、使用CSS变量和oklch颜色进行主题配置、使用React Hook Form或TanStack Form构建表单、创建自定义注册表、组合可访问的组件变体、设置暗黑模式。

不适用场景： 非React框架（请改用shadcn-vue或shadcn-svelte）、使用其他组件库的项目（如MUI、Chakra）、未使用Tailwind CSS的项目。

Quick Reference

快速参考

Pattern	API / Approach	Key Points
Init project	`npx shadcn@latest init`	Auto-detects framework, configures CSS variables
Add component	`npx shadcn@latest add [name]`	Copies source code into your project
Custom project	`npx shadcn@latest create`	Pick library (Radix/Base UI), style, theme, fonts
Check updates	`npx shadcn@latest diff [component]`	Shows upstream changes for your components
Search registry	`npx shadcn@latest search @registry`	Browse and install from namespaced registries
Build registry	`npx shadcn@latest build`	Generate registry JSON from `registry.json`
Theme tokens	`:root` vars + `@theme inline` mapping	oklch color values, dark mode via `.dark` class
Dark mode	`@custom-variant dark (&:is(.dark *))`	Swaps CSS variables under `.dark` selector
Component variant	`cva()` from `class-variance-authority`	Type-safe variant definitions
Polymorphic slot	`asChild` prop with `<Slot>` from Radix	Merge props onto child element
Direct ref	`ref` as a regular prop	`forwardRef` is deprecated in React 19
Form (current)	`<Field />` + React Hook Form + Zod	Replaces legacy `<Form />` component
Form (legacy)	`<Form />` + `<FormField />` + Zod	Still works but no longer actively developed
Class merging	`cn()` utility wrapping `clsx` + `twMerge`	Safely merge Tailwind classes without conflicts

模式	API / 实现方式	关键点
初始化项目	`npx shadcn@latest init`	自动检测框架，配置CSS变量
添加组件	`npx shadcn@latest add [name]`	将源代码复制到你的项目中
自定义项目	`npx shadcn@latest create`	选择库（Radix/Base UI）、样式、主题、字体
检查更新	`npx shadcn@latest diff [component]`	显示组件的上游变更
搜索注册表	`npx shadcn@latest search @registry`	浏览并安装命名空间注册表中的组件
构建注册表	`npx shadcn@latest build`	从 `registry.json` 生成注册表JSON
主题令牌	`:root` 变量 + `@theme inline` 映射	oklch颜色值，通过 `.dark` 类实现暗黑模式
暗黑模式	`@custom-variant dark (&:is(.dark *))`	在 `.dark` 选择器下切换CSS变量
组件变体	`class-variance-authority` 提供的 `cva()`	类型安全的变体定义
多态插槽	Radix提供的 `<Slot>` 结合 `asChild` 属性	将属性合并到子元素上
直接Ref	将 `ref` 作为常规属性传递	React 19中 `forwardRef` 已被弃用
表单（当前版本）	`<Field />` + React Hook Form + Zod	替代旧版 `<Form />` 组件
表单（旧版）	`<Form />` + `<FormField />` + Zod	仍可使用但不再积极开发
类名合并	基于 `clsx` + `twMerge` 封装的 `cn()` 工具	安全合并Tailwind类名，避免冲突

Common Mistakes

常见错误

Mistake	Correct Pattern
Installing shadcn/ui as an npm dependency	Use the CLI ( `npx shadcn@latest add` ) to copy source into your project
Using `forwardRef` with React 19 components	Pass `ref` directly as a prop -- `forwardRef` is deprecated in React 19
Using HSL values for color tokens	Use oklch format: `--primary: oklch(0.205 0 0)`
Wrapping variables with `hsl()` or `oklch()` in utilities	Reference CSS variables directly: `var(--primary)`
Putting tokens directly in `@theme {}`	Use `:root` for values + `@theme inline` to map them to Tailwind
Using legacy `<Form />` for new forms	Use `<Field />` component with React Hook Form or TanStack Form
Skipping Zod validation in form components	Always pair forms with Zod schemas for type-safe validation
Using `div` elements for interactive controls	Use Radix or Base UI primitives for semantic HTML and accessibility
Modifying components in `node_modules`	Components live in your source tree -- own and customize directly
Using old CLI command `shadcn-ui@canary`	Use `npx shadcn@latest` for all CLI operations

错误	正确做法
将shadcn/ui作为npm依赖安装	使用CLI（ `npx shadcn@latest add` ）将源代码复制到你的项目中
在React 19组件中使用 `forwardRef`	直接将 `ref` 作为属性传递——React 19中 `forwardRef` 已被弃用
为颜色令牌使用HSL值	使用oklch格式： `--primary: oklch(0.205 0 0)`
在工具类中用 `hsl()` 或 `oklch()` 包裹变量	直接引用CSS变量： `var(--primary)`
将令牌直接放入 `@theme {}` 中	在 `:root` 中定义值 + 使用 `@theme inline` 将其映射到Tailwind
为新表单使用旧版 `<Form />` 组件	结合React Hook Form或TanStack Form使用 `<Field />` 组件
在表单组件中跳过Zod验证	始终将表单与Zod模式配对，实现类型安全验证
使用 `div` 元素作为交互控件	使用Radix或Base UI原语以确保语义化HTML和可访问性
修改 `node_modules` 中的组件	组件位于你的源代码目录中——可直接拥有并自定义
使用旧版CLI命令 `shadcn-ui@canary`	所有CLI操作均使用 `npx shadcn@latest`

Delegation

任务分工

Component discovery and primitive lookup: Use
```
Explore
```
agent
Theme migration or multi-file refactoring: Use
```
Task
```
agent
Design system architecture planning: Use
```
Plan
```
agent
Registry setup and distribution: Use
```
Task
```
agent

组件发现与原语查找：使用
```
Explore
```
agent
主题迁移或多文件重构：使用
```
Task
```
agent
设计系统架构规划：使用
```
Plan
```
agent
注册表设置与分发：使用
```
Task
```
agent

References

参考资料

Theming and dark mode
Component patterns and variants
Form patterns with Field, React Hook Form, and Zod
CLI and registry

主题与暗黑模式
组件模式与变体
基于Field、React Hook Form和Zod的表单模式
CLI与注册表