shadcn-v3

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill: shadcn

Scope

范围

Applies to: Tailwind v4 with shadcn/ui setup, CSS variable architecture, dark mode, theme configuration, component composition patterns, accessibility, form integration
Does NOT cover: Tailwind v3, PostCSS configuration

适用于：Tailwind v4 与 shadcn/ui 配置、CSS 变量架构、暗模式、主题配置、组件组合模式、可访问性、表单集成
不涵盖：Tailwind v3、PostCSS 配置

Assumptions

前提条件

Tailwind CSS v4+
shadcn/ui latest
Next.js 16 (this repo); CSS-first Tailwind v4, not Vite
React 18+ or Next.js 14+
TypeScript 6+

Tailwind CSS v4+
最新版 shadcn/ui
Next.js 16（此仓库）；采用 CSS-first 的 Tailwind v4，而非 Vite
React 18+ 或 Next.js 14+
TypeScript 6+

Principles

原则

Use
```
@theme inline
```
to map CSS variables to Tailwind tokens
Use
```
hsl()
```
wrapper for color values in
```
:root
```
and
```
.dark
```
Set
```
"tailwind.config": ""
```
in
```
components.json
```
(empty for v4)
Delete
```
tailwind.config.ts
```
if it exists (v4 uses CSS-based config)
Use CSS-first Tailwind v4 in the Next app (not
```
@tailwindcss/vite
```
)
Use
```
cn()
```
utility for conditional classes
Semantic colors automatically adapt to dark mode (no
```
dark:
```
variants needed)
Use
```
@plugin
```
directive for plugins (not
```
@import
```
or
```
require()
```
)
Compose complex components from smaller shadcn primitives
Extend components via wrapper pattern (don't modify originals)
Use CVA (class-variance-authority) for variant systems
Use
```
forwardRef
```
only when a parent must attach a ref (React 19 does not require it by default)
Leverage Radix UI primitives for built-in accessibility

使用
```
@theme inline
```
将 CSS 变量映射到 Tailwind tokens
在
```
:root
```
和
```
.dark
```
中使用
```
hsl()
```
包装颜色值
在
```
components.json
```
中设置
```
"tailwind.config": ""
```
（v4 下留空）
如果
```
tailwind.config.ts
```
存在，则将其删除（v4 使用基于 CSS 的配置）
在 Next 应用中使用 CSS-first 的 Tailwind v4（而不是
```
@tailwindcss/vite
```
）
使用
```
cn()
```
工具函数处理条件类名
语义颜色会自动适应暗模式（无需使用
```
dark:
```
变体）
使用
```
@plugin
```
指令加载插件（而不是
```
@import
```
或
```
require()
```
）
由较小的 shadcn 基础组件组合出复杂组件
通过 wrapper pattern 扩展组件（不要直接修改原始组件）
使用 CVA（class-variance-authority）实现变体系统
仅当父组件必须附加 ref 时才使用
```
forwardRef
```
（React 19 默认不再要求使用）
利用 Radix UI primitives 提供内置可访问性能力

Constraints

约束

MUST

必须

Wrap color values with
```
hsl()
```
in
```
:root
```
and
```
.dark
```
Use
```
@theme inline
```
to map all CSS variables
Set
```
"tailwind.config": ""
```
in
```
components.json
```
Delete
```
tailwind.config.ts
```
if it exists
Use CSS-first Tailwind v4 in Next apps (
```
@import "tailwindcss"
```
in CSS)

在
```
:root
```
和
```
.dark
```
中使用
```
hsl()
```
包装颜色值
使用
```
@theme inline
```
映射所有 CSS 变量
在
```
components.json
```
中设置
```
"tailwind.config": ""
```
如果
```
tailwind.config.ts
```
存在，则将其删除
在 Next 应用中使用 CSS-first 的 Tailwind v4（在 CSS 中使用
```
@import "tailwindcss"
```
）

SHOULD

建议

Use semantic color tokens (
```
--background
```
,
```
--foreground
```
, etc.)
Use
```
cn()
```
utility for conditional classes
Use
```
@plugin
```
directive for plugins
Compose components from smaller shadcn primitives
Use wrapper pattern to extend components (don't modify originals)
Use CVA for variant systems in custom components
Use
```
forwardRef
```
when a parent must attach a ref
Test accessibility with keyboard navigation and screen readers
Use Radix UI primitives for complex interactions (dialogs, dropdowns, etc.)
Provide ARIA labels for icon-only buttons and interactive elements
Use
```
@tailwindcss/vite
```
only when the app is Vite-based (not Next.js)

使用语义颜色 tokens（
```
--background
```
、
```
--foreground
```
等）
使用
```
cn()
```
工具函数处理条件类名
使用
```
@plugin
```
指令加载插件
由较小的 shadcn primitives 组合组件
使用 wrapper pattern 扩展组件（不要直接修改原始组件）
在自定义组件的变体系统中使用 CVA
当父组件必须附加 ref 时使用
```
forwardRef
```
使用键盘导航和屏幕阅读器测试可访问性
对复杂交互（对话框、下拉菜单等）使用 Radix UI primitives
为仅含图标的按钮和可交互元素提供 ARIA 标签
仅在应用基于 Vite 时使用
```
@tailwindcss/vite
```
（Next.js 不适用）

AVOID

避免

Putting
```
:root
```
or
```
.dark
```
inside
```
@layer base
```
Using
```
.dark { @theme { } }
```
pattern (v4 doesn't support nested @theme)
Double-wrapping colors (
```
hsl(var(--background))
```
in body)
Using
```
tailwind.config.ts
```
for theme colors
Using
```
@apply
```
directive (deprecated in v4)
Using
```
dark:
```
variants for semantic colors
Using
```
@import
```
or
```
require()
```
for plugins (use
```
@plugin
```
)
Modifying base shadcn components directly (use wrapper pattern)
Building custom dropdowns/dialogs from scratch (use Radix primitives)
Relying on color alone for state indication
Skipping accessibility testing

将
```
:root
```
或
```
.dark
```
放在
```
@layer base
```
内
使用
```
.dark { @theme { } }
```
模式（v4 不支持嵌套的
```
@theme
```
）
对颜色进行双重包装（例如在 body 中使用
```
hsl(var(--background))
```
）
使用
```
tailwind.config.ts
```
配置主题颜色
使用
```
@apply
```
指令（v4 中已弃用）
对语义颜色使用
```
dark:
```
变体
使用
```
@import
```
或
```
require()
```
加载插件（应使用
```
@plugin
```
）
直接修改 shadcn 基础组件（应使用 wrapper pattern）
从零开始构建自定义 dropdown 或 dialog（应使用 Radix primitives）
仅依靠颜色表示状态
跳过可访问性测试

Interactions

交互

Works with next for App Router setup
Uses typescript for type safety

与 next 配合使用，用于 App Router 配置
使用 typescript 确保类型安全

Patterns

模式

CSS Variable Setup

CSS 变量配置

css

/* src/index.css */
@import "tailwindcss";

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
}

:root {
  --background: hsl(0 0% 100%);
  --foreground: hsl(222.2 84% 4.9%);
}

.dark {
  --background: hsl(222.2 84% 4.9%);
  --foreground: hsl(210 40% 98%);
}

css

/* src/index.css */
@import "tailwindcss";

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
}

:root {
  --background: hsl(0 0% 100%);
  --foreground: hsl(222.2 84% 4.9%);
}

.dark {
  --background: hsl(222.2 84% 4.9%);
  --foreground: hsl(210 40% 98%);
}

Vite Configuration (Vite apps only)

Vite 配置（仅限 Vite 应用）

typescript

// vite.config.ts — skip for Next.js CSS-first setups
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  plugins: [react(), tailwindcss()],
})

typescript

// vite.config.ts — skip for Next.js CSS-first setups
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  plugins: [react(), tailwindcss()],
})

Components Config

组件配置

json

{
  "tailwind": {
    "config": "",
    "css": "src/index.css",
    "baseColor": "slate",
    "cssVariables": true
  }
}

See Templates (including Component Extension) and Architecture for complete setup.

json

{
  "tailwind": {
    "config": "",
    "css": "src/index.css",
    "baseColor": "slate",
    "cssVariables": true
  }
}

查看模板（包括组件扩展）和架构，了解完整配置。

References

参考资料

Architecture - Complete setup pattern
Dark Mode - Dark mode implementation
Common Gotchas - Common issues and fixes
Migration Guide - Migrating from v3
Component Patterns - Composition, CVA, extension patterns
Accessibility - ARIA, keyboard navigation, screen readers
Form Patterns - React Hook Form integration

架构 - 完整配置模式
暗模式 - 暗模式实现
常见问题 - 常见问题与修复方法
迁移指南 - 从 v3 迁移
组件模式 - 组合、CVA 和扩展模式
可访问性 - ARIA、键盘导航和屏幕阅读器
表单模式 - React Hook Form 集成

shadcn-v3

Original

Translation

Skill: shadcn

Skill: shadcn

Scope

范围

Assumptions

前提条件

Principles

原则

Constraints

约束

MUST

必须

SHOULD

建议

AVOID

避免

Interactions

交互

Patterns

模式

CSS Variable Setup

CSS 变量配置

Vite Configuration (Vite apps only)

Vite 配置（仅限 Vite 应用）

Components Config

组件配置

References

参考资料

Resources

资源