shadcn-v3

用途

shadcn-v3 是一个技能（Skill），用于在 Tailwind CSS v4 环境下搭建与使用 shadcn/ui。其范围包括：Tailwind v4 与 shadcn/ui 的配置、CSS 变量架构、暗色模式、主题配置、组件组合模式、无障碍以及表单集成。

该技能明确不覆盖 Tailwind v3 与 PostCSS 配置。

前提假设

资料中列出的假设条件为：

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

主要原则

使用 @theme inline 将 CSS 变量映射为 Tailwind token
在 :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 原语组合出复杂组件
通过包装模式扩展组件（不修改原始组件）
使用 CVA（class-variance-authority）构建变体系统
仅在父级必须附加 ref 时使用 forwardRef（React 19 默认不再要求）
利用 Radix UI 原语获得内置无障碍能力

约束

必须（MUST）

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

应当（SHOULD）

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

避免（AVOID）

将 :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
  }
}

完整设置参见 Templates（含组件扩展）与 Architecture。

参考文档

Architecture - 完整设置模式
Dark Mode - 暗色模式实现
Common Gotchas - 常见问题与修复
Migration Guide - 从 v3 迁移
Component Patterns - 组合、CVA、扩展模式
Accessibility - ARIA、键盘导航、屏幕阅读器
Form Patterns - React Hook Form 集成

资源

shadcn/ui Tailwind v4 Guide
Tailwind v4 Docs

适用场景与限制

该技能适用于使用 Tailwind CSS v4 与 shadcn/ui 的前端项目，尤其是 Next.js 应用中的主题与组件体系搭建，以及需要暗色模式、无障碍与表单集成的场景。限制方面：不覆盖 Tailwind v3 与 PostCSS 配置；资料未提供收费、价格、平台支持范围或效果承诺等信息。