⚡

Tailwindv4+shadcn/ui生产堆栈技能 tailwind-v4-shadcn

这个技能提供了一个生产就绪的设置指南，用于使用 Tailwind CSS v4、shadcn/ui、Vite 和 React 构建前端项目。它涵盖了暗色模式实现、CSS 变量架构、常见问题修复和最佳实践，帮助开发者高效搭建和调试现代 Web 应用。关键词：Tailwind v4, shadcn/ui, Vite, React, 暗色模式, CSS 变量, 前端开发, 生产部署, SEO。

前端开发 0 次安装 0 次浏览 更新于 3/7/2026

名称: tailwind-v4-shadcn 描述: | 为 Tailwind CSS v4 与 shadcn/ui、Vite 和 React 提供的生产就绪设置指南。

使用场景：初始化使用 Tailwind v4 的 React 项目、设置 shadcn/ui、 实现暗色模式、调试 CSS 变量问题、修复主题切换问题、 从 Tailwind v3 迁移，或遇到颜色/主题问题。

涵盖：@theme 内联模式、CSS 变量架构、使用 ThemeProvider 的暗色模式、 组件组合、vite.config 设置、常见 v4 陷阱，以及生产就绪模式。

关键词：Tailwind v4, shadcn/ui, @tailwindcss/vite, @theme 内联, 暗色模式, CSS 变量, hsl() 包装器, components.json, React 主题化, 主题切换, 颜色无效, 变量损坏, 主题不应用, @plugin 指令, 排版插件, 表单插件, prose 类, @tailwindcss/typography, @tailwindcss/forms 许可证: MIT

Tailwind v4 + shadcn/ui 生产堆栈

生产就绪：WordPress 审计器 (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 代理关键：如果您是 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 init 添加了自己的）
  3. 错误的模板选择（vanilla TS 与 React）
  4. 缺少初始化后清理（不兼容的 CSS 规则）
  5. 错误的插件语法（使用 @import 或 require() 而不是 @plugin 指令）

激活技能后，所有这些都会自动处理。

快速开始（5 分钟 - 按此顺序执行）

1. 安装依赖项

bun add tailwindcss @tailwindcss/vite
# 或：npm install tailwindcss @tailwindcss/vite

bun add -d @types/node

# 注意：使用 pnpm 进行 shadcn init，因为已知有 Bun 兼容性问题
# （bunx 有“脚本未找到”和 postinstall/msw 问题）
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": "",              // ← 关键：v4 中为空
    "css": "src/index.css",
    "cssVariables": true
  }
}

4. 删除 tailwind.config.ts

rm tailwind.config.ts  # v4 不使用此文件

四步架构（关键）

此模式是强制性的——跳过步骤会破坏您的主题。

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

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

:root {
  --background: hsl(0 0% 100%);      /* ← 需要 hsl() 包装器 */
  --foreground: hsl(222.2 84% 4.9%);
  --primary: hsl(221.2 83.2% 53.3%);
  /* ... 所有亮色模式颜色 */
}

.dark {
  --background: hsl(222.2 84% 4.9%);
  --foreground: hsl(210 40% 98%);
  --primary: hsl(217.2 91.2% 59.8%);
  /* ... 所有暗色模式颜色 */
}

关键规则：

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

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

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-primary: var(--primary);
  /* ... 映射所有 CSS 变量 */
}

为什么这是必需的：

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

步骤 3：应用基础样式

@layer base {
  body {
    background-color: var(--background);  /* 此处不要使用 hsl() */
    color: var(--foreground);
  }
}

关键规则：

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

步骤 4：结果 - 自动暗色模式

<div className="bg-background text-foreground">
  {/* 不需要 dark: 变体 - 主题自动切换 */}
</div>

暗色模式设置

1. 创建 ThemeProvider

查看 reference/dark-mode.md 获取完整实现或使用模板：

// 从模板复制：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

查看 reference/dark-mode.md 获取 ModeToggle 组件代码。

关键规则（必须遵守）

✅ 始终执行：

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

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

  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 内

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

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

    /* 错误 - v4 不支持嵌套 @theme */
.dark {
  @theme {
    --color-primary: hsl(...);
  }
}

  3. 双重包装颜色

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

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

    /* 错误 - v4 忽略此 */
export default {
  theme: {
    extend: {
      colors: { primary: 'hsl(var(--primary))' }
    }
  }
}

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

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

    /* 错误 */
<div className="bg-primary dark:bg-primary-dark" />

/* 正确 */
<div className="bg-primary" />

语义颜色令牌

始终对颜色使用语义名称：

:root {
  --destructive: hsl(0 84.2% 60.2%);        /* 红色 - 错误、关键 */
  --success: hsl(142.1 76.2% 36.3%);        /* 绿色 - 成功状态 */
  --warning: hsl(38 92% 50%);               /* 黄色 - 警告 */
  --info: hsl(221.2 83.2% 53.3%);           /* 蓝色 - 信息、主要 */
}

用法：

<div className="bg-destructive text-destructive-foreground">关键</div>
<div className="bg-success text-success-foreground">成功</div>
<div className="bg-warning text-warning-foreground">警告</div>
<div className="bg-info text-info-foreground">信息</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 使用未包装的变量
  • [ ] 安装并包装应用的 ThemeProvider
  • [ ] 创建了暗色模式切换组件
  • [ ] 在浏览器中测试主题切换有效

高级主题

加载 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">品牌化</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.1.1",
    "vite": "^7.2.4",
    "typescript": "~5.9.3"
  }
}

❌ 永远不要安装这些（v4 已弃用）

# 这些包将导致构建错误：
bun add tailwindcss-animate  # ❌ 已弃用
# 或：npm install tailwindcss-animate  # ❌ 已弃用

bun add tw-animate-css      # ❌ 不存在

如果您看到这些包的导入错误，请移除它们并使用原生 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 获取完整文档，包括排版插件（prose 类）、表单插件、安装步骤和常见插件错误。

参考文档

如需更深入理解，请查看：

何时加载参考

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

加载 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 当：

  • 用户需要排版插件（prose 类）
  • 用户需要表单插件
  • 有关 @plugin 指令的问题
  • 插件安装错误

加载 references/advanced-usage.md 当：

  • 用户询问超出默认值的自定义颜色
  • 需要高级组件模式
  • 有关组件最佳实践的问题
  • 组件组合问题

官方文档

生产示例

此技能基于 WordPress 审计器项目：

  • 在线：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. 验证四步架构中的所有步骤
  3. 确保 components.json 设置 "config": ""
  4. 删除 tailwind.config.ts 如果存在
  5. 检查官方文档：https://ui.shadcn.com/docs/tailwind-v4