TailwindCSSV4MasterySkill tailwind-css-v4-mastery

Tailwind CSS V4 Mastery Skill

哲学：CSS优先思考

Tailwind V4代表了从以JavaScript为中心的实用程序框架到CSS原生，声明式样式的哲学转变。这项技能安装了这种思维模式：

• 配置是CSS — @theme {} 替换 tailwind.config.js
• 速度是架构 — Oxide引擎（Rust）替换JavaScript解析器
• 现代标准优先 — 利用 @property，color-mix()，CSS嵌套
• 性能作为一等公民 — 比v3快10-100倍

V4的正确思维模式：“CSS是真理的源泉。JavaScript配置已过时。”

---

核心概念景观

1. Oxide引擎革命

变化是什么：

v3: JavaScript → JavaScript解析器 → CSS输出
v4: CSS @theme → Rust/Oxide引擎 → 优化CSS输出

为什么这很重要：

• 性能： 构建时间快10-100倍，HMR快15-30倍
• 简单性： 一种语言（CSS）而不是两种（JS + CSS）
• 未来证明： 与原生浏览器能力对齐

思维模式： 将Oxide引擎视为编译器，而不是预处理器。它将CSS声明编译成优化输出。

2. CSS优先配置范式

核心转变：

方面	v3	v4
配置格式	JavaScript对象	CSS @theme {} 块
位置	tailwind.config.js	styles.css
执行	构建时Node.js	Oxide引擎
调试	控制台日志，文件检查	CSS DevTools
范围	全局导入	CSS级联感知

为什么这很重要： CSS优先配置更易于维护，调试，并且与浏览器的实际工作方式对齐。你不再与抽象层作斗争。

3. 浏览器需求和现代CSS特性

Tailwind V4需要现代浏览器能力：

• Safari 16.4+ （OKLch颜色空间，@property）
• Chrome 111+ （color-mix()）
• Firefox 128+ （CSS嵌套）

这是有意为之的。V4假设现代CSS并围绕它进行优化。旧版支持需要v3.4.x。

---

程序工作流程

工作流程1：从V3迁移到V4

触发器： 用户希望将现有Tailwind项目从v3升级到v4

步骤：

1. 审计阶段

   • 列出所有tailwind.config.js覆盖
   • 识别自定义实用程序和组件
   • 扫描弃用的实用程序使用（不透明度，flex-shrink等）
   • 检查浏览器支持需求

2. 安装阶段

   npm install -D tailwindcss@latest
   npm install -D @tailwindcss/vite  # （或@tailwindcss/postcss或@tailwindcss/cli）
   

3. 配置迁移

   • 转换theme: {} → @theme { --var: value; }
   • 转换extend: {} → @theme中的额外--var
   • 替换@tailwind base/components/utilities → @import "tailwindcss"

4. 实用程序重构

   • .shadow → .shadow-sm
   • .rounded → .rounded-sm
   • .outline-none → .outline-hidden
   • .bg-opacity-* → .bg-black/* （斜杠语法）

5. 验证

   • 测试响应式断点
   • 验证暗色模式
   • 检查自定义组件
   • 性能基线

决策树：

这是新项目吗？
  ├─ YES → 使用@theme配置直接使用V4
  └─ NO → 执行上述迁移工作流程
     ├─ v3广泛使用自定义配置？
     │  ├─ YES → 分配迁移时间，逐步进行
     │  └─ NO → 快速迁移，30分钟
     └─ 您使用的是旧版浏览器吗？
        ├─ YES → 继续使用v3.4
        └─ NO → 继续使用v4

工作流程2：组件系统设计

触发器： 用户希望使用Tailwind V4构建可重用的组件库

步骤：

1. 定义组件范围

   • 列出组件原语（按钮，卡片，输入等）
   • 识别共享样式模式
   • 计划主题定制

2. 创建基础主题

   @import "tailwindcss";
   
   @theme {
     /* 颜色系统 */
     --color-primary-*: oklch(...);
     --color-neutral-*: oklch(...);
     
     /* 间距比例 */
     --spacing-xs: 0.25rem;
     --spacing-sm: 0.5rem;
     --spacing-md: 1rem;
     
     /* 排版 */
     --font-display: "Custom", sans-serif;
     --font-body: "System", sans-serif;
   }
   

3. 构建组件类

   @layer components {
     .btn-primary {
       @apply px-4 py-2 rounded-sm bg-primary text-white
              font-semibold transition-all hover:opacity-90;
     }
     
     .card {
       @apply p-6 rounded-lg bg-white shadow-md border border-gray-200;
     }
   }
   

4. 建立修饰符约定

   • 大小修饰符：.btn-sm，.btn-lg
   • 状态修饰符：.btn-disabled，.btn-loading
   • 变体修饰符：.btn-primary，.btn-secondary

5. 文档和导出

   • 创建组件参考
   • 提供使用示例
   • 文档主题变量

输出： 用于生产的组件库CSS文件

工作流程3：性能优化

触发器： 用户需要优化Tailwind V4性能

步骤：

1. 基线测量

   • 测量当前构建时间
   • 检查CSS文件大小
   • 监控HMR速度

2. 插件选择

   • 使用@tailwindcss/vite（最快选项）
   • 如果使用PostCSS，则启用Lightning CSS
   • 禁用不必要的优化

3. 配置调整

   // vite.config.ts
   import tailwindcss from "@tailwindcss/vite";
   
   export default defineConfig({
     plugins: [react(), tailwindcss()]
   });
   

4. CSS变量优化

   • 使用原生CSS变量而不是计算值
   • 利用级联进行作用域主题
   • 最小化@theme块重复

5. 验证

   • 验证构建时间改进
   • 检查文件大小减少
   • 确认视觉一致性

预期结果：

• 构建时间：100-500ms（与v3的5-10s相比）
• 热重载：50-200ms（与v3的3s相比）
• CSS大小：减少15-20%

---

重要决策树

决策1：插件选择

你使用什么构建工具？
├─ Vite（React，Vue，Svelte）
│  └─ 使用@tailwindcss/vite（最快，推荐）
├─ Webpack（NextJS，CRA）
│  └─ 使用@tailwindcss/postcss
├─ 独立/无捆绑器
│  └─ 使用@tailwindcss/cli
└─ PostCSS管道
   └─ 使用@tailwindcss/postcss

决策2：配置方法

你的主题有多复杂？
├─ 简单（5-10种颜色覆盖）
│  └─ 使用styles.css中的内联@theme块
├─ 中等（自定义颜色，间距，字体）
│  └─ 使用有组织的单个@theme块
├─ 复杂（多主题，广泛定制）
│  └─ 分割成具有[data-theme]选择器的@layer基础块
└─ 企业级（多个品牌）
   └─ 使用CSS变量策略和回退

决策3：组件提取

我应该何时使用@layer components？
├─ 重复的实用程序组合
│  └─ YES → 提取为.btn-primary，.card等
├─ 一次性布局
│  └─ NO → 直接在HTML中使用实用程序
├─ 需要设计系统合规性
│  └─ YES → 提取为组件类
└─ 用户将根据实例定制
   └─ NO → 保留为实用程序组合

---

常见陷阱和解决方案

陷阱1：期望tailwind.config.js仍然有效

问题： 文件在v4中被忽略。 解决方案： 改用CSS中的@theme {}。 预防： 迁移过程中尽早删除tailwind.config.js。

陷阱2：默认边框颜色破坏布局

问题： v3使用currentColor（继承文本），v4使用#e5e7eb。 解决方案： 如果需要继承颜色，请使用.border-current。 预防： 迁移过程中测试所有边框实用程序。

陷阱3：环宽改变（3px → 1px）

问题： 现有的.ring类现在有更细的轮廓。 解决方案： 使用.ring-3获得旧的3px行为，.ring-1获得新的默认值。 预防： 迁移过程中查找/替换.ring → .ring-1。

陷阱4：CSS变量必须有--前缀

问题： @theme { color-primary: value; }被忽略。 解决方案： 使用@theme { --color-primary: value; }。 预防： @theme块中始终使用--。

陷阱5：不透明度实用程序已移除

问题： .bg-opacity-50不再存在。 解决方案： 使用CSS颜色修饰符：.bg-black/50。 预防： 迁移过程中搜索代码库中的不透明度实用程序并替换。

---

参考材料

所有详细参考资料都存储在references/中：

• breaking-changes.md — API移除和重命名的完整列表
• configuration-guide.md — 综合@theme设置模式
• utility-migration-table.md — v3 → v4实用程序映射
• color-space-guide.md — OKLch，HSL和颜色迁移策略
• performance-tuning.md — 优化技术和测量

---

何时使用这项技能

✅ 使用这项技能时：

• 用户特别询问Tailwind V4（而不是v3）
• 设计组件系统或样式架构
• 从Tailwind v3迁移到v4
• 优化Tailwind性能
• 排除CSS优先配置问题
• 使用Tailwind V4构建设计系统
• 创建自定义主题配置

❌ 不要使用这项技能时：

• 用户询问Tailwind v3或更旧版本（使用通用CSS知识）
• 问题涉及HTML/JavaScript/Framework特定问题（不是Tailwind领域）
• 用户需要通用CSS辅导（使用CSS基础知识）
• 构建非Web项目

---

执行标准

当用户查询激活时：

1. 澄清意图 — 询问他们正在构建什么以及为什么（组件？迁移？优化？）
2. 选择工作流程 — 路由到适当的程序路径
3. 提供参考 — 链接到相关参考资料
4. 展示代码示例 — 具体的，可复制粘贴的示例
5. 解释权衡 — 为什么某些决策很重要
6. 测试假设 — 在深入工作前验证理解

---

高级能力

这项技能使Claude能够：

• 设计组件系统，利用Tailwind V4的架构
• 执行迁移，从v3到v4，风险最小
• 优化构建，使用Oxide引擎功能
• 排除CSS优先配置问题，系统地
• 教授Tailwind V4哲学给团队
• **使用CSS变量+Tailwind架构设计系统
• 处理边缘情况，围绕浏览器支持和功能检测

---

资源和参考资料

• 官方文档：https://tailwindcss.com/docs
• GitHub：https://github.com/tailwindlabs/tailwindcss
• 游乐场：https://play.tailwindcss.com
• Discord：https://tailwindcss.com/discord

---

技能版本： 1.0.0
最后更新： 2025-01-01
状态： 生产就绪