tailwind

Tailwind Labs Tailwind CSS v4 最佳实践

面向 Tailwind CSS v4 应用的全面性能优化指南，由 Tailwind Labs 维护。包含 8 个类别中的 42 条规则，并按影响程度排序，用于指导自动重构和代码生成。

适用场景

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

• 配置 Tailwind CSS v4 构建工具（Vite 插件、PostCSS、CLI）
• 使用 v4 的 CSS 优先方式编写或迁移样式
• 优化 CSS 包体积和构建性能
• 使用断点或容器查询实现响应式设计
• 使用 @theme 指令和设计令牌设置主题

按优先级划分的规则类别

优先级	类别	影响	前缀
1	构建配置	严重	build-
2	CSS 生成	严重	gen-
3	包优化	高	bundle-
4	工具类模式	高	util-
5	组件架构	中高	comp-
6	主题与设计令牌	中	theme-
7	响应式与自适应	中	resp-
8	动画与过渡	中低	anim-

快速参考

1. 构建配置（严重）

• build-vite-plugin - 优先使用 Vite 插件，而非 PostCSS
• build-css-import - 使用 CSS 导入，而非 @tailwind 指令
• build-content-detection - 利用自动内容检测
• build-node-version - 使用 Node.js 20+ 运行升级工具
• build-postcss-simplify - 移除多余的 PostCSS 插件
• build-cli-package - 使用正确的 CLI 包

2. CSS 生成（严重）

• gen-css-first-config - 优先使用 CSS 优先配置，而非 JavaScript
• gen-avoid-theme-bloat - 避免主题变量过多
• gen-oklch-colors - 使用 OKLCH 色彩空间呈现鲜艳色彩
• gen-utility-directive - 使用 @utility 定义自定义工具类
• gen-dynamic-utilities - 使用动态工具类值
• gen-css-variable-syntax - 使用圆括号引用 CSS 变量

3. 包优化（高）

• bundle-remove-unused-plugins - 移除内置插件
• bundle-avoid-preprocessors - 避免使用 Sass/Less 预处理器
• bundle-css-minification - 在生产环境启用 CSS 压缩
• bundle-avoid-cdn-production - 避免在生产环境使用 Play CDN
• bundle-split-critical-css - 提取关键 CSS，用于首次渲染

4. 工具类模式（高）

• util-renamed-utilities - 使用已重命名的工具类
• util-important-modifier - 使用尾随的重要性修饰符
• util-variant-stacking - 按从左到右的顺序堆叠变体
• util-explicit-colors - 显式指定边框和环形颜色
• util-opacity-modifier - 使用斜杠透明度修饰符
• util-gradient-via-none - 使用 via-none 重置渐变色标

5. 组件架构（中高）

• comp-avoid-apply-overuse - 避免过度使用 @apply
• comp-reference-directive - 使用 @reference 集成 CSS Module
• comp-utility-file-scope - 了解工具类文件的作用域
• comp-smart-sorting - 利用智能工具类排序
• comp-container-customize - 使用 @utility 自定义容器

6. 主题与设计令牌（中）

• theme-semantic-tokens - 使用语义化设计令牌名称
• theme-dark-mode-class - 使用基于类的深色模式以便控制
• theme-prefix-variables - 使用前缀对变量名称进行命名空间划分
• theme-runtime-variables - 利用运行时 CSS 变量
• theme-color-scheme - 设置 color-scheme 以启用原生深色模式

7. 响应式与自适应（中）

• resp-mobile-first - 使用移动优先的响应式设计
• resp-container-queries - 使用容器查询实现组件级响应式布局
• resp-custom-breakpoints - 在 @theme 中定义自定义断点
• resp-hover-capability - 了解触控设备上的悬停行为
• resp-logical-properties - 使用逻辑属性支持 RTL

8. 动画与过渡（低至中）

• anim-gpu-accelerated - 使用 GPU 加速的变换属性
• anim-starting-style - 使用 @starting-style 实现入场动画
• anim-gradient-interpolation - 使用 OKLCH 渐变插值
• anim-3d-transforms - 使用内置的 3D 变换工具类

使用方法

首先在项目根目录运行：

npx -y @pymodel/react-frontend-skills detect                 # installed vs. targeted versions
npx -y @pymodel/react-frontend-skills scan --skill tailwind  # deprecated APIs → rule IDs

针对上方与任务匹配的每条规则，以及每个 scan 命中项，阅读 references/<rule-id>.md：了解其重要性，以及错误与正确的代码示例。