tailwind-refactor

Tailwind CSS 重构最佳实践社区指南

面向 Tailwind CSS v4 应用的全面代码质量重构指南。包含 8 个类别中的 50 条规则，并按迁移紧迫程度排序。所有转换都会保留现有的外观和风格——本指南只关注代码整洁度、现代语法和 v4 兼容性。

配套技能： 使用 tailwind-ui-refactor 改进视觉设计，使用 tailwind-responsive-ui 了解响应式布局模式。

何时应用

手动迁移前： 先运行 npx @tailwindcss/upgrade——它会自动处理大部分配置和重命名工具类。然后使用本指南处理自动化工具未涵盖的模式。

以下情况可参考这些指南：

• 将项目从 Tailwind CSS v3 迁移到 v4
• 清理已弃用或已重命名的工具类
• 合并冗长的多类模式
• 用设计令牌替换任意值
• 减少 CSS 文件中过度使用的 @apply
• 将语法更新为符合 v4 规范的形式

按优先级划分的规则类别

优先级	类别	影响	前缀
1	配置迁移	严重	config-
2	替换已弃用的工具类	严重	dep-
3	更新已重命名的工具类	高	rename-
4	合并类	高	class-
5	清理任意值	中高	arb-
6	语法现代化	中	syntax-
7	清理 @apply 和架构	中	arch-
8	采用现代功能	低中	adopt-

快速参考

1. 配置迁移（严重）

• config-import-directive - 用 @import 替换 @tailwind 指令
• config-css-theme - 将 tailwind.config.js 迁移到 CSS @theme
• config-theme-function - 用 CSS 变量替换 theme() 函数
• config-theme-inline - 对非工具类设计令牌使用 @theme inline
• config-utility-directive - 用 @utility 替换 @layer utilities
• config-postcss-plugin - 将 PostCSS 插件更新为 @tailwindcss/postcss
• config-content-autodetect - 移除手动内容配置
• config-custom-variant - 将 addVariant 迁移到 @custom-variant
• config-preflight-defaults - 考虑 v4 中 Preflight 默认值的变化

2. 替换已弃用的工具类（严重）

• dep-opacity-modifiers - 用不透明度修饰符（/50）替换 -opacity-
• dep-flex-shorthand - 用 shrink/grow 替换 flex-shrink/flex-grow
• dep-text-ellipsis - 用 text-ellipsis 替换 overflow-ellipsis
• dep-decoration-utilities - 用 box-decoration-* 替换 decoration-slice/clone
• dep-transform-composites - 用单独的重置类替换 transform-none
• dep-transition-properties - 将 transition-[transform] 更新为单独的属性

3. 重命名工具更新（HIGH）

• rename-shadow-scale - 将阴影工具更新为新尺度
• rename-blur-scale - 将模糊工具更新为新尺度
• rename-rounded-scale - 将边框圆角工具更新为新尺度
• rename-ring-width - 将 ring 替换为 ring-3，以匹配 v3 默认值
• rename-gradient-utilities - 将 bg-gradient-* 替换为 bg-linear-*
• rename-outline-hidden - 将 outline-none 替换为 outline-hidden

4. 类名整合（HIGH）

• class-size-utility - 将匹配的 w-* h-* 替换为 size-*
• class-gap-over-space - 在 flex/grid 中优先使用 gap-，而非 space-x/y-
• class-inset-shorthand - 将 top/right/bottom/left 替换为 inset-*
• class-border-color-explicit - 为 v4 默认值变更显式添加边框颜色
• class-ring-color-explicit - 为 v4 默认值变更显式添加 ring 颜色
• class-redundant-display - 移除冗余的 display 类
• class-hidden-priority - 移除 hidden 属性的 display 覆盖
• class-container-utility - 将 container 插件配置替换为 @utility

5. 任意值清理（MEDIUM-HIGH）

• arb-hex-to-theme - 将任意十六进制颜色替换为主题令牌
• arb-spacing-to-scale - 将任意间距替换为主题尺度
• arb-dynamic-classes - 避免动态构造类名
• arb-breakpoint-to-theme - 将任意断点替换为 @theme
• arb-zindex-to-scale - 将任意 z-index 替换为已定义的尺度

6. 语法现代化（MEDIUM）

• syntax-css-variable-parens - 将 CSS 变量语法从方括号更新为圆括号
• syntax-variant-stacking - 将变体堆叠顺序更新为从左到右
• syntax-important-modifier - 使用末尾的 ! 表示 important 修饰符
• syntax-grid-arbitrary - 在 grid 任意值中使用下划线
• syntax-gradient-preservation - 在变体中显式重置渐变色标
• syntax-hover-media-query - 处理 hover 变体的媒体查询包装

7. @apply 与架构清理（MEDIUM）

• arch-apply-to-component - 将 @apply 代码块提取为框架组件
• arch-layer-to-utility - 将 @layer components 替换为 @utility
• arch-scoped-reference - 在作用域样式中使用 @reference 来应用 @apply
• arch-safelist-to-source - 将 safelist 替换为 @source inline()
• arch-domain-composition - 将 Tailwind 限定用于基础样式，并组合用于领域样式

8. 采用现代特性（低到中）

• adopt-container-queries - 使用容器查询，而非视口断点
• adopt-not-variant - 使用 not-* 变体表示否定条件
• adopt-in-variant - 使用 in-* 变体简化父级状态样式
• adopt-field-sizing - 使用 field-sizing-content 让文本区域自动调整大小
• adopt-starting-variant - 使用 starting 变体实现无需 JS 的入场动画

使用方法

阅读各个参考文件，了解详细说明和代码示例：

• 章节定义 - 类别结构和影响级别
• 规则模板 - 添加新规则的模板

参考文件

文件	描述
references/_sections.md	类别定义和排序
assets/templates/_template.md	新规则模板
metadata.json	版本和参考信息