tailwind-v4-shadcn

Tailwind v4 + shadcn/ui 生产技术栈

经过生产环境测试：WordPress Auditor (https://wordpress-auditor.webfonts.workers.dev) 最后更新：2025-10-29 状态：可用于生产环境 ✅

---

⚠️ 开始前（请阅读！）

对 AI Agent 至关重要：如果你是 Claude Code，正在帮助用户设置 Tailwind v4：

1. 在对话开始时明确说明你正在使用此技能
2. 参考此技能中的模式，而非一般知识
3. 避免 reference/common-gotchas.md 中列出的已知问题
4. 不要猜测——如果不确定，请查阅技能文档

需要用户采取行动：告诉 Claude 先查看此技能！

请说：“我正在设置 Tailwind v4 + shadcn/ui——请先查看 tailwind-v4-shadcn 技能”

为什么这很重要（实际结果）

未启用技能时：

• ❌ 设置时间：约 5 分钟
• ❌ 遇到的错误：2-3 个（tw-animate-css、重复的 @layer base）
• ❌ 需要手动修复：2 个以上提交
• ❌ Token 用量：约 65k
• ❌ 用户信心：需要调试

启用技能后：

• ✅ 设置时间：约 1 分钟
• ✅ 遇到的错误：0 个
• ✅ 需要手动修复：0 个
• ✅ Token 用量：约 20k（减少 70%）
• ✅ 用户信心：立即成功

此技能可预防的已知问题

1. tw-animate-css 导入错误（在 v4 中已弃用）
2. 重复的 @layer base 代码块（shadcn init 会添加自己的代码块）
3. 选择了错误的模板（原生 TS 而非 React）
4. 缺少初始化后的清理（不兼容的 CSS 规则）
5. 插件语法错误（使用 @import 或 require()，而不是 @plugin 指令）

启用技能后，所有这些问题都会自动处理。

---

快速开始（5 分钟——请严格按此顺序操作）

1. 安装依赖

pnpm add tailwindcss @tailwindcss/vite
pnpm add -D @types/node
pnpm dlx shadcn@latest init

2. 配置 Vite

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'
import path from 'path'

export default defineConfig({
  plugins: [react(), tailwindcss()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src')
    }
  }
})

3. 更新 components.json

{
  "tailwind": {
    "config": "",              // ← CRITICAL: Empty for v4
    "css": "src/index.css",
    "cssVariables": true
  }
}

4. 删除 tailwind.config.ts

rm tailwind.config.ts  # v4 doesn't use this file

---

四步架构（至关重要）

此模式必须遵循——跳过步骤会导致主题失效。

步骤 1：在根级定义 CSS 变量

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

:root {
  --background: hsl(0 0% 100%);      /* ← hsl() wrapper required */
  --foreground: hsl(222.2 84% 4.9%);
  --primary: hsl(221.2 83.2% 53.3%);
  /* ... all light mode colors */
}

.dark {
  --background: hsl(222.2 84% 4.9%);
  --foreground: hsl(210 40% 98%);
  --primary: hsl(217.2 91.2% 59.8%);
  /* ... all dark mode colors */
}

重要规则：

• ✅ 在根级定义（不要放在 @layer base 内）
• ✅ 所有颜色值都使用 hsl() 包装
• ✅ 深色模式使用 .dark（不要使用 .dark { @theme { } }）

步骤 2：将变量映射到 Tailwind 工具类

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-primary: var(--primary);
  /* ... map ALL CSS variables */
}

为什么必须这样做：

• 生成工具类（bg-background、text-primary）
• 如果没有这一步，bg-primary 等类将不存在

步骤 3：应用基础样式

@layer base {
  body {
    background-color: var(--background);  /* NO hsl() here */
    color: var(--foreground);
  }
}

重要规则：

• ✅ 直接引用变量：var(--background)
• ❌ 不要重复包装：hsl(var(--background))

步骤 4：结果——自动深色模式

<div className="bg-background text-foreground">
  {/* No dark: variants needed - theme switches automatically */}
</div>

---

深色模式设置

1. 创建 ThemeProvider

完整实现请参阅 reference/dark-mode.md，或使用模板：

// Copy from: templates/theme-provider.tsx

2. 包装应用

// src/main.tsx
import { ThemeProvider } from '@/components/theme-provider'

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <ThemeProvider defaultTheme="dark" storageKey="vite-ui-theme">
      <App />
    </ThemeProvider>
  </React.StrictMode>,
)

3. 添加主题切换按钮

pnpm dlx shadcn@latest add dropdown-menu

ModeToggle 组件代码请参阅 reference/dark-mode.md。

---

重要规则（必须遵守）

✅ 务必做到：

1. 在 :root 和 .dark 中使用 hsl() 包装颜色值

   --background: hsl(0 0% 100%);  /* ✅ Correct */
   

2. 使用 @theme inline 映射所有 CSS 变量

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

3. 在 components.json 中设置 "tailwind.config": ""

   { "tailwind": { "config": "" } }
   

4. 如果 tailwind.config.ts 存在，请将其删除

5. 使用 @tailwindcss/vite 插件（不要使用 PostCSS）

6. 使用 cn() 处理条件类名

   import { cn } from "@/lib/utils"
   <div className={cn("base", isActive && "active")} />
   

❌ 绝不要：

1. 将 :root 或 .dark 放入 @layer base 内

   /* WRONG */
   @layer base {
     :root { --background: hsl(...); }
   }
   

2. 使用 .dark { @theme { } } 模式

   /* WRONG - v4 doesn't support nested @theme */
   .dark {
     @theme {
       --color-primary: hsl(...);
     }
   }
   

3. 重复包装颜色值

   /* WRONG */
   body {
     background-color: hsl(var(--background));
   }
   

4. 使用 tailwind.config.ts 设置主题颜色

   /* WRONG - v4 ignores this */
   export default {
     theme: {
       extend: {
         colors: { primary: 'hsl(var(--primary))' }
       }
     }
   }
   

5. 使用 @apply 指令（在 v4 中已弃用）

6. 对语义颜色使用 dark: 变体

   /* WRONG */
   <div className="bg-primary dark:bg-primary-dark" />
   
   /* CORRECT */
   <div className="bg-primary" />
   

---

语义颜色令牌

颜色始终使用语义名称：

:root {
  --destructive: hsl(0 84.2% 60.2%);        /* Red - errors, critical */
  --success: hsl(142.1 76.2% 36.3%);        /* Green - success states */
  --warning: hsl(38 92% 50%);               /* Yellow - warnings */
  --info: hsl(221.2 83.2% 53.3%);           /* Blue - info, primary */
}

用法：

<div className="bg-destructive text-destructive-foreground">Critical</div>
<div className="bg-success text-success-foreground">Success</div>
<div className="bg-warning text-warning-foreground">Warning</div>
<div className="bg-info text-info-foreground">Info</div>

---

常见问题与快速修复

症状	原因	修复方法
bg-primary 不起作用	缺少 @theme inline 映射	添加 @theme inline 代码块
所有颜色都变成黑色/白色	重复使用 hsl() 包裹	使用 var(--color)，而不是 hsl(var(--color))
深色模式无法切换	缺少 ThemeProvider	使用 <ThemeProvider> 包裹应用
构建失败	存在 tailwind.config.ts	删除该文件
文本不可见	对比度颜色错误	检查 :root/.dark 中的颜色定义

请参阅 reference/common-gotchas.md，查看完整的故障排除指南。

---

文件模板

所有模板都位于 templates/ 目录中：

• index.css - 包含所有颜色变量的完整 CSS 配置
• components.json - shadcn/ui v4 配置
• vite.config.ts - Vite + Tailwind 插件配置
• tsconfig.app.json - 带路径别名的 TypeScript 配置
• theme-provider.tsx - 使用 localStorage 的深色模式提供程序
• utils.ts - 用于合并类名的 cn() 工具函数

将这些文件复制到项目中，并根据需要进行自定义。

---

完整配置检查清单

• 已创建 Vite + React + TypeScript 项目
• 已安装 @tailwindcss/vite（不是 postcss）
• vite.config.ts 使用 tailwindcss() 插件
• tsconfig.json 已配置路径别名
• components.json 存在，且包含 "config": ""
• 不存在 tailwind.config.ts 文件
• src/index.css 遵循 v4 模式：
  • :root 和 .dark 位于根级别（不在 @layer 中）
  • 使用 hsl() 包裹颜色
  • @theme inline 映射所有变量
  • @layer base 使用未包裹的变量
• 已安装主题提供程序并用于包裹应用
• 已创建深色模式切换组件
• 已在浏览器中测试主题切换是否正常

---

进阶主题

自定义颜色

添加新的语义颜色：

:root {
  --brand: hsl(280 65% 60%);
  --brand-foreground: hsl(0 0% 100%);
}

.dark {
  --brand: hsl(280 75% 70%);
  --brand-foreground: hsl(280 20% 10%);
}

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

用法：<div className="bg-brand text-brand-foreground">Branded</div>

从 v3 迁移

请参阅 reference/migration-guide.md，查看完整的 v3 → v4 迁移步骤。

组件最佳实践

1. 始终使用语义令牌

   <Button variant="destructive">Delete</Button>  /* ✅ */
   <Button className="bg-red-600">Delete</Button>  /* ❌ */
   

2. 使用 cn() 进行条件样式设置

   import { cn } from "@/lib/utils"
   
   <div className={cn(
     "base-class",
     isActive && "active-class",
     hasError && "error-class"
   )} />
   

3. 组合使用 shadcn/ui 组件

   <Dialog>
     <DialogTrigger asChild>
       <Button>Open</Button>
     </DialogTrigger>
     <DialogContent>
       <DialogHeader>
         <DialogTitle>Title</DialogTitle>
       </DialogHeader>
     </DialogContent>
   </Dialog>
   

---

依赖项

✅ 安装以下依赖项

{
  "dependencies": {
    "tailwindcss": "^4.1.14",
    "@tailwindcss/vite": "^4.1.14",
    "clsx": "^2.1.1",
    "tailwind-merge": "^3.3.1",
    "@radix-ui/react-*": "latest",
    "lucide-react": "^0.545.0",
    "react": "^19.2.0",
    "react-dom": "^19.2.0"
  },
  "devDependencies": {
    "@types/node": "^24.0.0",
    "@vitejs/plugin-react": "^5.0.4",
    "vite": "^7.0.0",
    "typescript": "~5.9.0"
  }
}

❌ 绝对不要安装以下依赖项（v4 中已弃用）

# These packages will cause build errors:
npm install tailwindcss-animate  # ❌ Deprecated
npm install tw-animate-css      # ❌ Doesn't exist

如果这些包出现导入错误，请移除它们，并改用原生 CSS 动画或 @tailwindcss/motion。

---

Tailwind v4 插件

Tailwind v4 支持在 CSS 中使用 @plugin 指令加载官方插件。

官方插件（Tailwind Labs）

Typography 插件 - 为 Markdown/CMS 内容设置样式

**适用场景：**显示博客文章、文档，或任何来自 Markdown/CMS 的 HTML 内容。

安装：

pnpm add -D @tailwindcss/typography

配置（v4 语法）：

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

用法：

<article class="prose lg:prose-xl dark:prose-invert">
  {{ markdown_content }}
</article>

可用类名：

• prose - 基本排版样式
• prose-sm、prose-base、prose-lg、prose-xl、prose-2xl - 尺寸变体
• dark:prose-invert - 深色模式样式

---

Forms 插件 - 重置表单元素样式

**适用场景：**不使用 shadcn/ui 组件构建自定义表单，或需要统一的跨浏览器表单样式。

安装：

pnpm add -D @tailwindcss/forms

配置（v4 语法）：

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

功能：

• 重置浏览器默认的表单样式
• 使表单元素可以使用 Tailwind 工具类设置样式
• 修复输入框、选择框、复选框和单选按钮的跨浏览器差异

**注意：**对于 shadcn/ui 用户来说，这个插件没那么重要（它们已经提供预设样式的表单组件），但对基本表单仍然有用。

---

常见插件错误

在 v4 项目中使用 v3 语法时会出现以下错误：

❌ 错误（v3 配置文件语法）：

// tailwind.config.js
module.exports = {
  plugins: [require('@tailwindcss/typography')]
}

❌ 错误（使用 @import 而不是 @plugin）：

@import "@tailwindcss/typography";  /* Doesn't work */

✅ 正确（v4 @plugin 指令）：

/* src/index.css */
@import "tailwindcss";
@plugin "@tailwindcss/typography";
@plugin "@tailwindcss/forms";

---

内置功能（无需插件）

容器查询是 Tailwind v4 核心内置功能，无需插件：

<div className="@container">
  <div className="@md:text-lg">
    Responds to container width, not viewport
  </div>
</div>

❌ 不要安装： @tailwindcss/container-queries（已弃用，现为核心功能）

---

参考文档

如需深入了解，请参阅：

• architecture.md - 深入介绍 4 步模式
• dark-mode.md - 完整的深色模式实现
• common-gotchas.md - 所有可能出错的情况及修复方法
• migration-guide.md - 将硬编码颜色迁移为 CSS 变量

---

官方文档

• shadcn/ui Vite Setup：https://ui.shadcn.com/docs/installation/vite
• shadcn/ui Tailwind v4 Guide：https://ui.shadcn.com/docs/tailwind-v4
• shadcn/ui Dark Mode (Vite)：https://ui.shadcn.com/docs/dark-mode/vite
• Tailwind v4 Docs：https://tailwindcss.com/docs
• shadcn/ui Theming：https://ui.shadcn.com/docs/theming

---

生产环境示例

此技能基于 WordPress Auditor 项目：

• 在线体验：https://wordpress-auditor.webfonts.workers.dev
• 技术栈：Vite + React 19 + Tailwind v4 + shadcn/ui + Cloudflare Workers
• 深色模式：完整支持系统、浅色和深色模式
• 版本：Tailwind v4.1.14 + shadcn/ui 最新版（2025 年 10 月）

此技能中的所有模式均已在生产环境中验证。

---

有疑问？遇到问题？

1. 首先查看 reference/common-gotchas.md
2. 检查 4 步架构中的所有步骤
3. 确保 components.json 中包含 "config": ""
4. 如果存在 tailwind.config.ts，请将其删除
5. 查看官方文档：https://ui.shadcn.com/docs/tailwind-v4