shadcn-v3

用途

shadcn-v3 是一个用于在 Tailwind CSS v4 环境下配置和使用 shadcn/ui 的技能，聚焦于 @theme inline 模式与 CSS 变量架构。它适用于 Tailwind v4 与 shadcn/ui 的搭建、CSS 变量架构、暗色模式、主题配置、组件组合模式、无障碍以及表单集成。该技能明确不覆盖 Tailwind v3 与 PostCSS 配置。

主要能力

使用 @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 原语获得内置无障碍支持。

使用方式

技能中给出的 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 应用，Next.js CSS-first 设置可跳过）：

// 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 以获取完整设置。

适用场景

适用于使用 Tailwind CSS v4+、shadcn/ui 最新版、Next.js 16（该仓库）、React 18+ 或 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+。

限制与约束

必须（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 保证类型安全。

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

资源：shadcn/ui Tailwind v4 指南、Tailwind v4 文档。