tailwind

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Tailwind Labs Tailwind CSS v4 Best Practices

Tailwind Labs Tailwind CSS v4 最佳实践

Comprehensive performance optimization guide for Tailwind CSS v4 applications, maintained by Tailwind Labs. Contains 42 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.

由Tailwind Labs维护的Tailwind CSS v4应用性能优化综合指南。包含8个类别共42条规则，按影响优先级排序，可指导自动化重构与代码生成。

When to Apply

适用场景

Reference these guidelines when:

Configuring Tailwind CSS v4 build tooling (Vite plugin, PostCSS, CLI)
Writing or migrating styles using v4's CSS-first approach
Optimizing CSS bundle size and build performance
Implementing responsive designs with breakpoints or container queries
Setting up theming with @theme directive and design tokens

在以下场景中参考本指南：

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

Rule Categories by Priority

按优先级划分的规则类别


build-
gen-
bundle-
util-
comp-
theme-
resp-
anim-

Priority	Category	Impact	Prefix
1	Build Configuration	CRITICAL	`build-`
2	CSS Generation	CRITICAL	`gen-`
3	Bundle Optimization	HIGH	`bundle-`
4	Utility Patterns	HIGH	`util-`
5	Component Architecture	MEDIUM-HIGH	`comp-`
6	Theming & Design Tokens	MEDIUM	`theme-`
7	Responsive & Adaptive	MEDIUM	`resp-`
8	Animation & Transitions	LOW-MEDIUM	`anim-`


build-
gen-
bundle-
util-
comp-
theme-
resp-
anim-

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

Quick Reference

快速参考

1. Build Configuration (CRITICAL)

1. 构建配置（关键）

```
build-vite-plugin
```
- Use Vite Plugin Over PostCSS
```
build-css-import
```
- Use CSS Import Over @tailwind Directives
```
build-content-detection
```
- Leverage Automatic Content Detection
```
build-node-version
```
- Use Node.js 20+ for Optimal Performance
```
build-postcss-simplify
```
- Remove Redundant PostCSS Plugins
```
build-cli-package
```
- Use Correct CLI Package

```
build-vite-plugin
```
- 优先使用Vite Plugin而非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 Generation (CRITICAL)

2. CSS生成（关键）

```
gen-css-first-config
```
- Use CSS-First Configuration Over JavaScript
```
gen-avoid-theme-bloat
```
- Avoid Excessive Theme Variables
```
gen-oklch-colors
```
- Use OKLCH Color Space for Vivid Colors
```
gen-utility-directive
```
- Use @utility for Custom Utilities
```
gen-dynamic-utilities
```
- Use Dynamic Utility Values
```
gen-css-variable-syntax
```
- Use Parentheses for CSS Variable References

```
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 Optimization (HIGH)

3. 包优化（高）

```
bundle-remove-unused-plugins
```
- Remove Built-in Plugins
```
bundle-avoid-preprocessors
```
- Avoid Sass/Less Preprocessors
```
bundle-css-minification
```
- Enable CSS Minification in Production
```
bundle-avoid-cdn-production
```
- Avoid Play CDN in Production
```
bundle-split-critical-css
```
- Extract Critical CSS for Initial Render

```
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. Utility Patterns (HIGH)

4. 工具类模式（高）

```
util-renamed-utilities
```
- Use Renamed Utility Classes
```
util-important-modifier
```
- Use Trailing Important Modifier
```
util-variant-stacking
```
- Use Left-to-Right Variant Stacking
```
util-explicit-colors
```
- Use Explicit Border and Ring Colors
```
util-opacity-modifier
```
- Use Slash Opacity Modifier
```
util-gradient-via-none
```
- Use via-none to Reset Gradient Stops

```
util-renamed-utilities
```
- 使用重命名后的工具类
```
util-important-modifier
```
- 使用后缀!important修饰符
```
util-variant-stacking
```
- 使用从左到右的变体堆叠方式
```
util-explicit-colors
```
- 使用明确的边框与环形颜色
```
util-opacity-modifier
```
- 使用斜线透明度修饰符
```
util-gradient-via-none
```
- 使用via-none重置渐变停止点

5. Component Architecture (MEDIUM-HIGH)

5. 组件架构（中高）

```
comp-avoid-apply-overuse
```
- Avoid Overusing @apply
```
comp-reference-directive
```
- Use @reference for CSS Module Integration
```
comp-utility-file-scope
```
- Understand Utility File Scope
```
comp-smart-sorting
```
- Leverage Smart Utility Sorting
```
comp-container-customize
```
- Customize Container with @utility

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

6. Theming & Design Tokens (MEDIUM)

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

```
theme-semantic-tokens
```
- Use Semantic Design Token Names
```
theme-dark-mode-class
```
- Use Class-Based Dark Mode for Control
```
theme-prefix-variables
```
- Use Prefix for Variable Namespacing
```
theme-runtime-variables
```
- Leverage Runtime CSS Variables
```
theme-color-scheme
```
- Set color-scheme for Native Dark Mode

```
theme-semantic-tokens
```
- 使用语义化设计令牌名称
```
theme-dark-mode-class
```
- 使用基于类的暗色模式以获得更好控制
```
theme-prefix-variables
```
- 使用前缀实现变量命名空间
```
theme-runtime-variables
```
- 利用运行时CSS变量
```
theme-color-scheme
```
- 设置color-scheme以支持原生暗色模式

7. Responsive & Adaptive (MEDIUM)

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

```
resp-mobile-first
```
- Use Mobile-First Responsive Design
```
resp-container-queries
```
- Use Container Queries for Component-Level Responsiveness
```
resp-custom-breakpoints
```
- Define Custom Breakpoints in @theme
```
resp-hover-capability
```
- Understand Hover Behavior on Touch Devices
```
resp-logical-properties
```
- Use Logical Properties for RTL Support

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

8. Animation & Transitions (LOW-MEDIUM)

8. 动画与过渡（中低）

```
anim-gpu-accelerated
```
- Use GPU-Accelerated Transform Properties
```
anim-starting-style
```
- Use @starting-style for Entry Animations
```
anim-gradient-interpolation
```
- Use OKLCH Gradient Interpolation
```
anim-3d-transforms
```
- Use Built-in 3D Transform Utilities

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

How to Use

使用方法

Read individual reference files for detailed explanations and code examples:

Section definitions - Category structure and impact levels
Rule template - Template for adding new rules

阅读单个参考文件以获取详细说明与代码示例：

Section definitions - 类别结构与影响级别
Rule template - 添加新规则的模板

Full Compiled Document

完整编译文档

For a complete guide with all rules expanded, see AGENTS.md.

如需查看包含所有展开规则的完整指南，请参阅AGENTS.md。

Reference Files

参考文件

File	Description
AGENTS.md	Complete compiled guide with all rules
references/_sections.md	Category definitions and ordering
assets/templates/_template.md	Template for new rules
metadata.json	Version and reference information

文件	描述
AGENTS.md	包含所有规则的完整编译指南
references/_sections.md	类别定义与排序规则
assets/templates/_template.md	新规则模板
metadata.json	版本与参考信息