ia-tailwind-css

核心用法

Tailwind CSS v4 是一次架构级重构，将配置从 JavaScript 完全迁移至 CSS。核心入口变为 @import "tailwindcss"，设计令牌通过 @theme { } 定义并自动生成工具类。@utility 指令取代 v3 的 @layer components + @apply，@custom-variant 实现纯 CSS 变体定义。支持 @theme inline 映射现有 CSS 变量，@theme static 定义非工具类令牌。

显著优点

1. 零配置启动：删除 tailwind.config.ts，配置即 CSS，降低心智负担
2. 原生 CSS 生态兼容：CSS Modules 通过 @reference "#tailwind" 访问主题令牌
3. 类型安全变体：tailwind-variants (tv()) 提供完整 TypeScript 支持，优于传统条件类名
4. ESLint 深度集成：eslint-plugin-better-tailwindcss 自动检测冲突类、未知类、废弃类与重复类
5. 现代化默认值：min-h-dvh 处理移动端浏览器栏，size-6 简写等宽高等高，gap 取代有缺陷的 space-x/y

潜在局限

• 迁移成本：v3 项目需运行 @tailwindcss/upgrade codemod，半径、渐变、透明度等类名存在破坏性变更
• 构建链路敏感：动态类名构造（text-${color}-500）无法被检测，需强制使用完整字符串
• 生态阵痛期：tailwindcss-animate 等插件需替换为 tw-animate-css，部分第三方库适配滞后

适合人群

• 新建项目团队：直接采用 v4 获得最优 DX
• v3 存量项目维护者：需评估迁移 ROI，复杂项目建议渐进迁移
• 设计系统开发者：@theme + tv() 组合适合构建可主题化的组件库
• 追求构建性能团队：CSS-first 配置减少 JS 运行时开销

常规风险

| 风险场景 | 缓解措施 |

|---------|---------|

| 训练数据陈旧导致 v4 语法错误 | 强制 `search_docs` 验证后再编码 |

| 动态类名丢失样式 | 禁止模板字符串构造类名，使用 `cn()` 合并静态字符串 |

| v3 残留配置冲突 | 迁移后彻底删除 `tailwind.config.ts` |

| 深色模式实现错误 | 避免嵌套 `@theme`，采用 `:root`/`.dark` + `@theme inline` 模式 |