# Tailwind v4 + shadcn/ui 生产堆栈 **生产测试**：WordPress Auditor () **最后更新**：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. **不要猜测** \-如果不确定，请查看技能文档 **需要用户操作**：告诉克劳德先检查这个技能！说：**“我正在设置 Tailwind v4 + shadcn/ui - 首先检查 tailwind-v4-shadcn 技能”** ### 为什么这很重要（现实世界的结果） **没有技能激活：** * ❌ 设置时间：~5 分钟 *❌遇到的错误：2-3（tw-animate-css，重复的@layer基础） * ❌ 需要手动修复：2+ 次提交 * ❌ 代币使用量：~65k * ❌用户信心：需要调试 **激活技能后：** * ✅ 设置时间：~1 分钟 * ✅ 遇到的错误：0 * ✅ 需要手动修复：0 * ✅ 代币使用量：~20k（减少 70%） * ✅ 用户信心：立竿见影的成功 ### 此技能可防止的已知问题 1. **tw-animate-css 导入错误**（在 v4 中已弃用） 2. **重复@layer基础块**（shadcn init添加自己的） 3. **错误的模板选择**（普通 TS 与 React） 4. **缺少初始化后清理**（不兼容的 CSS 规则） 5. **错误的插件语法**（使用@import或require()而不是@plugin指令）当技能激活时，所有这些都会自动处理。 ** ** ## 快速入门（5 分钟 - 严格遵循此顺序） ### 1\.安装依赖项发髻添加 tailwindcss @tailwindcss/vite # 或者：npm install tailwindcss @tailwindcss/vite 面包添加-d @types/node # 注意：由于已知的 Bun 兼容性问题，使用 pnpm 进行 shadcn init #（bunx 有“找不到脚本”和安装后/msw 问题） pnpm dlx shadcn@最新 init ### 2\.配置Vite // vite.config.ts 从“vite”导入{defineConfig} 从“@vitejs/plugin-react”导入反应从“@tailwindcss/vite”导入 tailwindcss 从“路径”导入路径导出默认的defineConfig({ 插件：[react()、tailwindcss()]、解决：{ 别名：{ '@': path.resolve(__dirname, './src') } } }) ### 3\.更新 Components.json { “顺风”：{ "config": "", // ← CRITICAL: v4 为空 "css": "src/index.css", “cssVariables”：true } } ### 4\.删除 tailwind.config.ts rm tailwind.config.ts # v4 不使用该文件 ** ** ## 四步架构（关键）此模式是**强制** \- 跳过步骤会破坏您的主题。 ### 步骤 1：在根级别定义 CSS 变量 /* src/index.css */ @导入“tailwindcss”；：根{ --背景：hsl(0 0% 100%); /* ← hsl() 需要包装器 */ --前景：hsl(222.2 84% 4.9%); --主要：hsl(221.2 83.2% 53.3%)； /* ...所有灯光模式颜色 */ } .暗{ --背景：hsl(222.2 84% 4.9%); --前景：hsl(210 40% 98%); --主要：hsl(217.2 91.2% 59.8%)； /* ...所有深色模式颜色 */ } **关键规则：** * ✅ 在根级别定义（不在`@layer base`内） * ✅ 对所有颜色值使用 `hsl()` 包装器 * ✅ 使用 `.dark` 进行深色模式（不是 `.dark { @theme { } }`） ### 步骤 2：将变量映射到 Tailwind 实用程序 @主题内联{ --颜色背景：var(--背景); --前景颜色：var(--前景); --颜色主色：var(--primary); /* ... 映射所有 CSS 变量 */ } **为什么需要这样做：** * 生成实用程序类（`bg-background`、`text-primary`） * 没有这个， `bg-primary` 等将不存在 ### 第 3 步：应用基本样式 @层基础{ 身体{ 背景颜色：var(--background); /* 这里没有 hsl() */ 颜色：var(--前景)； } } **关键规则：** * ✅ 直接引用变量：`var(--background)` * ❌ 切勿双重换行：`hsl(var(--background))` ### 步骤 4：结果 - 自动深色模式

{/* 没有深色：需要变体 - 主题自动切换 */}

** ** ## 深色模式设置 ### 1\.创建主题提供者有关完整实现或使用模板，请参阅“reference/dark-mode.md”： // 复制自：templates/theme-provider.tsx ### 2\.包装您的应用程序 // src/main.tsx 从 '@/components/theme-provider' 导入 { ThemeProvider } ReactDOM.createRoot(document.getElementById('root')!).render( <应用程序/> , ） ### 3\.添加主题切换 pnpm dlx shadcn@latest 添加下拉菜单请参阅“reference/dark-mode.md”了解 ModeToggle 组件代码。 ** ** ## 关键规则（必须遵循） ### ✅ 始终这样做： 1. **用`hsl()`将颜色值包裹在`:root`和`.dark`中** --背景：hsl(0 0% 100%); /* ✅ 正确 */ 2. **使用`@theme inline`映射所有CSS变量** @主题内联{ --颜色背景：var(--背景); } 3. **在components.json中设置`"tailwind.config": ""`** { “顺风”: { “配置”: “” } } 4. **删除`tailwind.config.ts`（如果存在）** 5. **使用`@tailwindcss/vite`插件（不是PostCSS）** 6. **对条件类使用`cn()` 从“@/lib/utils”导入 { cn }

### ❌ 切勿这样做： 1. **将`:root`或`.dark`放入`@layer base`** /* 错误 */ @层基础{ :root { --background: hsl(...); } } 2. **使用`.dark { @theme { } }`模式** /* 错误 - v4 不支持嵌套 @theme */ .暗{ @主题{ --颜色主色：hsl(...); } } 3. **双绕颜色** /* 错误 */ 身体{ 背景颜色：hsl(var(--background)); } 4. **使用 `tailwind.config.ts` 作为主题颜色** /* 错误 - v4 忽略这个 */ 导出默认值{ 主题：{ 扩展：{ 颜色：{ 主要： 'hsl(var(--primary))' } } } } 5. **使用`@apply`指令（在v4中已弃用）** 6. **使用`dark:` 语义颜色变体** /* 错误 */

/* 正确 */

** ** ## 语义颜色标记始终使用颜色的语义名称：：根{ --破坏性：hsl(0 84.2% 60.2%)； /* 红色 - 错误，严重 */ --成功：hsl(142.1 76.2% 36.3%); /* 绿色 - 成功状态 */ --警告：hsl(38 92% 50%)； /* 黄色-警告 */ --信息：hsl(221.2 83.2% 53.3%); /* 蓝色 - 信息，主要 */ } **用途：**

严重

成功

警告

信息

** ** ## 常见问题和快速修复症状|原因 |修复 ---|---|--- `bg-primary` 不起作用 |缺少“@theme inline”映射 |添加`@theme inline`块颜色全黑/白 |双 `hsl()` 包装 |使用 `var(--color)` 而不是 `hsl(var(--color))` 深色模式无法切换 |缺少主题提供者 |将应用程序包装在 `` 中构建失败 | `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%); } @主题内联{ --color-brand: var(--brand); } 用法：`

品牌

` 有关详细模式和组件构成示例，请加载“references/advanced-usage.md”。 ** ** ## 依赖关系 ### ✅ 安装这些 { “依赖项”：{ "tailwindcss": "^4.1.17", "@tailwindcss/vite": "^4.1.17", "clsx": "^2.1.1", "tailwind-merge": "^3.3.1", "@radix-ui/react-*": "最新", "lucide-react": "^0.554.0", “反应”：“^19.2.0”， “反应-dom”：“^19.2.0” }, “开发依赖项”：{ "@types/node": "^24.10.1", "@vitejs/plugin-react": "^5.1.1", "vite": "^7.2.4", “打字稿”：“~5.9.3” } } ### ❌ 切勿安装这些（在 v4 中已弃用） # 这些包将导致构建错误： Bun 添加 tailwindcss-animate # ❌ 已弃用 # 或: npm install tailwindcss-animate # ❌ 已弃用 Bun 添加 tw-animate-css # ❌ 不存在 **如果您看到这些包的导入错误**，请将其删除并使用原生 CSS 动画或“@tailwindcss/motion”。 ** ** ## Tailwind v4 插件 Tailwind v4 支持使用 CSS 中的“@plugin”指令的官方插件。 **简单示例：** @导入“tailwindcss”； @plugin“@tailwindcss/版式”； @plugin“@tailwindcss/forms”； **常见错误：** ❌错误：`@import "@tailwindcss/typography"`（不起作用） ✅ 正确：`@plugin "@tailwindcss/typography"`（使用 @plugin 指令） **内置功能：** 容器查询现在是核心（不需要`@tailwindcss/container-queries`插件）。加载 `references/plugins-reference.md` 以获取完整的文档，包括排版插件（散文类）、表单插件、安装步骤和常见插件错误。 ** ** ## 参考文档如需更深入的了解，请参阅： * **common-gotchas.md** \- 它可能破坏（和修复）的所有方式 * **dark-mode.md** \- 完整的暗模式实现 * **migration-guide.md** \- 将硬编码颜色迁移到 CSS 变量 * **plugins-reference.md** \- 官方 Tailwind v4 插件（版式、表单） * **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插件（散文类） * 用户需要Forms插件 * 关于@plugin指令的问题 * 插件安装错误 ### 在以下情况下加载 `references/advanced-usage.md`： * 用户询问默认颜色之外的自定义颜色 * 需要高级组件模式 * 有关组件最佳实践的问题 * 成分构成问题 ** ** ## 官方文档 * **shadcn/ui Vite 设置** : * **shadcn/ui Tailwind v4 指南** : * **shadcn/ui 深色模式（Vite）** : * **Tailwind v4 文档**： * **shadcn/ui 主题** : ** ** ## 制作示例该技能基于 WordPress Auditor 项目： * **实时**： * **堆栈**：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.查看官方文档：

顺风V4 Shadcn

包含技能