shadcn-v3

Skill：shadcn

范围

• 适用于：使用 shadcn/ui 配置的 Tailwind v4、CSS 变量架构、深色模式、主题配置、组件组合模式、无障碍性、表单集成
• 不涵盖：Tailwind v3、PostCSS 配置

假设

• Tailwind CSS v4+
• shadcn/ui 最新版本
• Next.js 16（本仓库）；使用 CSS 优先的 Tailwind v4，而不是 Vite
• React 18+ 或 Next.js 14+
• TypeScript 6+

原则

• 使用 @theme inline 将 CSS 变量映射到 Tailwind 令牌
• 在 :root 和 .dark 中使用 hsl() 包装颜色值
• 在 components.json 中设置 "tailwind.config": ""（v4 中留空）
• 如果存在 tailwind.config.ts，则将其删除（v4 使用基于 CSS 的配置）
• 在 Next 应用中使用 CSS 优先的 Tailwind v4（而不是 @tailwindcss/vite）
• 使用 cn() 工具函数处理条件类名
• 语义颜色会自动适配深色模式（无需 dark: 变体）
• 使用 @plugin 指令添加插件（而不是 @import 或 require()）
• 使用较小的 shadcn 基元组件组合复杂组件
• 通过包装器模式扩展组件（不要修改原始组件）
• 使用 CVA（class-variance-authority）实现变体系统
• 仅当父组件必须附加 ref 时才使用 forwardRef（React 19 默认不需要）
• 利用 Radix UI 基元组件实现内置无障碍功能

约束

必须

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

应当

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

避免

• 将 :root 或 .dark 放在 @layer base 内
• 使用 .dark { @theme { } } 模式（v4 不支持嵌套的 @theme）
• 对颜色进行双重包装（在 body 中使用 hsl(var(--background))）
• 使用 tailwind.config.ts 设置主题颜色
• 使用 @apply 指令（v4 中已弃用）
• 对语义颜色使用 dark: 变体
• 使用 @import 或 require() 添加插件（请使用 @plugin）
• 直接修改 shadcn 基础组件（请使用包装器模式）
• 从头构建自定义下拉菜单或对话框（请使用 Radix 基元组件）
• 仅依靠颜色指示状态
• 跳过无障碍性测试

交互

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

模式

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 配置（仅适用于 Vite 应用）

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

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

组件配置

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

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

参考

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

Resources

• shadcn/ui Tailwind v4 Guide
• Tailwind v4 Docs