tailwind-v4-shadcn

Tailwind v4 + shadcn/ui 生产技术栈

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

---

⚠️ 开始之前（请阅读！）

对 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. 选择了错误的模板（vanilla 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",
    "baseColor": "slate",      // Base color palette
    "cssVariables": true,
    "prefix": ""               // No prefix for utility classes
  }
}

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 已配置路径别名
• 存在包含 "config": "" 的 components.json
• 不存在 tailwind.config.ts 文件
• src/index.css 遵循 v4 模式：
  • :root 和 .dark 位于根级别（不在 @layer 中）
  • 颜色使用 hsl() 包裹
  • @theme inline 映射所有变量
  • @layer base 使用未包裹的变量
• 已安装 Theme provider，并用于包裹应用
• 已创建深色模式切换组件
• 已在浏览器中测试主题切换是否正常

---

进阶主题

自定义颜色

添加新的语义颜色：

: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.17",
    "@tailwindcss/vite": "^4.1.17",
    "clsx": "^2.1.1",
    "tailwind-merge": "^3.3.1",
    "@radix-ui/react-*": "latest",
    "lucide-react": "^0.553.0",
    "react": "^19.2.0",
    "react-dom": "^19.2.0"
  },
  "devDependencies": {
    "@types/node": "^24.10.0",
    "@vitejs/plugin-react": "^5.1.0",
    "vite": "^7.2.2",
    "typescript": "~5.9.0",
    "tw-animate-css": "^1.4.0"
  }
}

动画包（2025 年 11 月更新）

shadcn/ui 已弃用 tailwindcss-animate，改用兼容 Tailwind v4 的 tw-animate-css。

✅ 应安装（兼容 v4）：

pnpm add -D tw-animate-css

然后添加到 src/index.css：

@import "tailwindcss";
@import "tw-animate-css";

❌ 不要安装：

npm install tailwindcss-animate  # Deprecated - v3 only

原因：tw-animate-css 是官方兼容 v4 的动画替代方案，也是 shadcn/ui 组件所必需的。

参考：https://ui.shadcn.com/docs/tailwind-v4

---

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 设置：https://ui.shadcn.com/docs/installation/vite
• shadcn/ui Tailwind v4 指南：https://ui.shadcn.com/docs/tailwind-v4
• shadcn/ui 深色模式（Vite）：https://ui.shadcn.com/docs/dark-mode/vite
• Tailwind v4 文档：https://tailwindcss.com/docs
• shadcn/ui 主题设置：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