tailwind

社区 Tailwind CSS v4 最佳实践

针对 Tailwind CSS v4 的 8 个类别，共 44 条规则，按影响程度排序，为自动重构和代码生成提供指导。

适用场景

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

基础设置（Bun、Vite）

bun add tailwindcss @tailwindcss/vite   # PostCSS projects: @tailwindcss/postcss

/* src/index.css */
@import "tailwindcss";
@custom-variant dark (&:where(.dark, .dark *));

@theme {
  --color-brand: oklch(0.55 0.21 260);
}

不需要 tailwind.config.*，也不需要 theme.extend：配置、令牌、插件和变体都放在 CSS 中。有关 shadcn/ui 令牌配置（@theme inline），请参阅 shadcn 技能。

按优先级划分的规则类别

优先级	类别	影响	前缀
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 - 使用末尾的 Important 修饰符
• 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 自定义容器
• comp-custom-variant - 使用 @custom-variant 定义自定义变体

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

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

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 变换工具

使用方法

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

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

参考文件

文件	说明
references/_sections.md	类别定义和排序
assets/templates/_template.md	新规则模板