tailwind-v4-shadcn

Tailwind v4 + shadcn/ui 生产级技术栈

已通过生产环境测试：WordPress Auditor（https://wordpress-auditor.webfonts.workers.dev） 最后更新：2025-12-04 状态：已可用于生产环境 ✅

目录

1. 开始之前
2. 快速开始
3. 四步架构
4. 深色模式设置
5. 关键规则
6. 语义颜色令牌
7. 常见问题与修复
8. 文件模板
9. 设置检查清单
10. 高级主题
11. 依赖项
12. Tailwind v4 插件
13. 参考文档
14. 何时加载参考文档

---

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

对 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 次以上提交
• ❌ 令牌用量：约 65k
• ❌ 用户信心：需要调试

激活技能后：

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

此技能可避免的已知问题

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

启用此技能后，以上问题都会自动处理。

---

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

1. 安装依赖项

bun add tailwindcss @tailwindcss/vite
# or: npm install tailwindcss @tailwindcss/vite

bun add -d @types/node

# Note: Using pnpm for shadcn init due to known Bun compatibility issues
# (bunx has "Script not found" and postinstall/msw problems)
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 使用未包装的变量
• 已安装主题提供器并用于包装应用
• 已创建暗色模式切换组件
• 已在浏览器中测试主题切换是否正常

---

进阶主题

加载 references/advanced-usage.md，了解进阶模式，包括：

• 自定义颜色：添加默认调色板以外的语义颜色
• v3 迁移：参阅 references/migration-guide.md 获取完整指南
• 组件最佳实践：语义令牌、cn() 工具、组合模式

快速示例：

:root { --brand: hsl(280 65% 60%); }
@theme inline { --color-brand: var(--brand); }

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

有关详细模式和组件组合示例，请加载 references/advanced-usage.md。

---

依赖项

✅ 安装这些

{
  "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.554.0",
    "react": "^19.2.0",
    "react-dom": "^19.2.0"
  },
  "devDependencies": {
    "@types/node": "^24.10.1",
    "@vitejs/plugin-react": "^5.2.0",
    "vite": "^7.2.4",
    "typescript": "~5.9.3"
  }
}

❌ 绝不要安装这些（在 v4 中已弃用）

# These packages will cause build errors:
bun add tailwindcss-animate  # ❌ Deprecated
# or: npm install tailwindcss-animate  # ❌ Deprecated

bun add tw-animate-css      # ❌ Doesn't exist

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

---

Tailwind v4 插件

Tailwind v4 支持使用 CSS 中的 @plugin 指令启用官方插件。

快速示例：

@import "tailwindcss";
@plugin "@tailwindcss/typography";
@plugin "@tailwindcss/forms";

常见错误： ❌ 错误：@import "@tailwindcss/typography"（不起作用） ✅ 正确：@plugin "@tailwindcss/typography"（使用 @plugin 指令）

**内置功能：**容器查询现已内置（无需使用 @tailwindcss/container-queries 插件）。

加载 references/plugins-reference.md，查看完整文档，包括 Typography 插件（prose 类）、Forms 插件、安装步骤和常见插件错误。

---

参考文档

如需深入了解，请参阅：

• common-gotchas.md — 所有可能出错的情况（及修复方法）
• dark-mode.md — 完整的深色模式实现
• migration-guide.md — 将硬编码颜色迁移为 CSS 变量
• plugins-reference.md — 官方 Tailwind v4 插件（Typography、Forms）
• advanced-usage.md — 自定义颜色和高级模式

---

何时加载参考文档

根据用户的具体需求加载参考文件：

在以下情况下加载 references/common-gotchas.md：

• 用户反馈“颜色不起作用”或“bg-primary 不存在”
• 深色模式无法正常切换
• 构建因 Tailwind 错误而失败
• 用户遇到任何 CSS/配置问题
• 调试主题问题

在以下情况下加载 references/dark-mode.md：

• 用户要求实现深色模式
• 主题切换无法正常工作
• 需要 ThemeProvider 组件代码
• 询问系统主题检测

在以下情况下加载 references/migration-guide.md：

• 从 Tailwind v3 迁移到 v4
• 用户有需要迁移的硬编码颜色
• 询问 v3 → v4 的变更
• 需要迁移清单

在以下情况下加载 references/plugins-reference.md：

• 用户需要 Typography 插件（prose 类）
• 用户需要 Forms 插件
• 询问 @plugin 指令
• 插件安装错误

在以下情况下加载 references/advanced-usage.md：

• 用户询问默认颜色之外的自定义颜色
• 需要高级组件模式
• 询问组件最佳实践
• 组件组合问题

---

官方文档

• 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

---

安全安装

安装 Tailwind 和 shadcn/ui 包时，请遵循供应链安全最佳实践：

• 阻止安装后脚本 — npm config set ignore-scripts true（或使用 Bun：默认已禁用）
• 冷却期 — 等待 7 天，让社区审查新版本的包
• 安装前审计 — 运行 socket package score npm <pkg>，或使用 socket npm install <pkg> 检查包

加载 dependency-upgrade 技能，获取完整的安全配置，包括 Socket CLI 集成、冷却期设置、锁文件验证和 CI 强制执行。

生产环境示例

此技能基于 WordPress Auditor 项目：

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

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

---

有疑问？遇到问题？

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