核心用法
本技能提供 Tailwind CSS v4 的完整开发指引，覆盖从配置到部署的全流程：
- CSS-First 配置：v4 彻底移除
tailwind.config.ts，所有设计令牌通过@theme { }在 CSS 中定义，自动生成对应 utility class。支持@theme inline（映射既有 CSS 变量）、@theme static（仅定义不生成工具类）及@utility（自定义工具类，替代 v3 的@layer components+@apply）。 - v3 → v4 迁移：详列破坏性变更——如
tailwind.config.ts删除、@tailwind三指令合并为@import "tailwindcss"、dark mode 配置转为@custom-variant、圆角命名整体下移（rounded-sm→rounded-xs）、所有*-opacity-*工具类移除（改用/50修饰符）、渐变方向类更名（bg-gradient-to-r→bg-linear-to-r）等，并建议使用官方@tailwindcss/upgradecodemod。 - 编码规范：强制使用
gap替代space-x/y（处理换行更健壮）、size-*替代等宽高的w-* h-*、min-h-dvh替代min-h-screen（适配移动端浏览器工具栏），并禁止动态拼接 class（如text-${color}-500）以避免 Purge 失效。 - 组件变体管理：推荐
tailwind-variants（tv()）或class-variance-authority（cva()）实现类型安全的变体组件，结合cn()（clsx+tailwind-merge）处理条件类合并。 - 工具链整合：引入
eslint-plugin-better-tailwindcss实现冲突类检测、未知类标记、废弃类提示及类名排序；CSS Modules 场景需添加@reference "#tailwind"以访问 theme token。 - Dark Mode 新模式：通过
:root/.darkCSS 变量 +@theme inline映射，实现语义化颜色（bg-background）自动切换，无需逐元素写dark:修饰符。
显著优点
1. 权威源文档：内容直接映射 Tailwind v4 官方语法（@theme、@utility、@custom-variant），并显式警示训练数据可能滞后，要求 search_docs 验证，确保信息时效性。
2. 迁移零盲区：v3/v4 对照表 + codemod 建议 + 常见错误排查（如 hsl() 双重包裹、@apply 失效），大幅降低升级成本。
3. 工程化闭环：从 ESLint 规则、类名合并工具到组件变体模式，提供可落地的代码质量保障方案。
4. 移动端优先：dvh、size-*、gap 等推荐体现对现代浏览器及移动场景的针对性优化。
潜在缺点与局限性
- 版本锁定严格：仅覆盖 v4，v3 遗留项目需完整迁移，无法渐进混用。
- 生态依赖：
tailwind-variants、tw-animate-css、eslint-plugin-better-tailwindcss等工具链需额外引入，增加依赖复杂度。 - CSS Modules 额外配置：需记忆
@reference指令，易遗漏导致 token 失效。 - 动态类名限制：禁止运行时拼接 class 的设计虽利于 Tree-shaking，但对高度动态化场景（如用户自定义主题色）需前置生成完整类名表，开发体验受限。
适合人群
- 正在或计划从 Tailwind v3 升级至 v4 的前端开发者
- 需要建立团队级 Tailwind 编码规范的技术负责人
- 追求类型安全组件变体（TypeScript +
tv()/cva()）的 React/Vue/Svelte 开发者 - 希望用纯 CSS 配置替代 JS 配置、简化构建链的工程师
常规风险
1. 破坏性升级风险：v4 配置体系与 v3 不兼容，未完整执行迁移步骤（如未删除 tailwind.config.ts）将导致构建失败。
2. 类名冲突与遗漏：动态拼接类名或未及时更新 ESLint 配置，可能引发生成环境样式丢失（Purge 误删）。
3. 暗色模式实现偏差：错误使用嵌套 @theme 或 hsl(var(--color)) 双重包裹会导致色彩异常。
4. 浏览器兼容性：dvh、oklch 等新特性需确认目标浏览器支持范围，老旧项目需 fallback 方案。