tailwind-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

When to use

适用场景

Use this skill when working with Tailwind CSS code. AI agents are trained on Tailwind v3 data and consistently generate outdated patterns - wrong config files, deprecated directives, removed utilities, and verbose class lists. This skill enforces Tailwind CSS v4 patterns.

在处理Tailwind CSS代码时使用本技能。AI Agent基于Tailwind v3数据训练，会持续生成过时的代码模式——错误的配置文件、已弃用的指令、已移除的工具类以及冗长的类名列表。本技能可强制遵循Tailwind CSS v4的代码模式。

Critical Rules

核心规则

1. Use CSS @import Instead of @tailwind Directives

1. 使用CSS @import替代@tailwind指令

Wrong (agents do this):

css

@tailwind base;
@tailwind components;
@tailwind utilities;

Correct:

css

@import "tailwindcss";

Why: Tailwind v4 removed

@tailwind

directives entirely. Use a standard CSS

@import

statement.

错误写法（AI Agent常这么生成）：

css

@tailwind base;
@tailwind components;
@tailwind utilities;

正确写法：

css

@import "tailwindcss";

原因： Tailwind v4已完全移除

@tailwind

指令，需使用标准CSS的

@import

语句。

2. Use CSS-First Configuration with @theme

2. 使用@theme实现CSS优先配置

Wrong (agents do this):

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        brand: "#3b82f6",
      },
      spacing: {
        18: "4.5rem",
      },
    },
  },
};

Correct:

css

@import "tailwindcss";

@theme {
  --color-brand: #3b82f6;
  --spacing-18: 4.5rem;
}

Why: Tailwind v4 uses CSS-first configuration with the

@theme

directive. No

tailwind.config.js

needed for most projects.

错误写法（AI Agent常这么生成）：

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        brand: "#3b82f6",
      },
      spacing: {
        18: "4.5rem",
      },
    },
  },
};

正确写法：

css

@import "tailwindcss";

@theme {
  --color-brand: #3b82f6;
  --spacing-18: 4.5rem;
}

原因： Tailwind v4采用CSS优先的配置方式，通过

@theme

指令实现。大多数项目无需

tailwind.config.js

文件。

3. Use @tailwindcss/postcss Plugin

3. 使用@tailwindcss/postcss插件

Wrong (agents do this):

// postcss.config.mjs
export default {
  plugins: {
    "postcss-import": {},
    tailwindcss: {},
    autoprefixer: {},
  },
};

Correct:

// postcss.config.mjs
export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

Why: In v4,

postcss-import

and

autoprefixer

are handled automatically. The plugin is

@tailwindcss/postcss

, not

tailwindcss

错误写法（AI Agent常这么生成）：

// postcss.config.mjs
export default {
  plugins: {
    "postcss-import": {},
    tailwindcss: {},
    autoprefixer: {},
  },
};

正确写法：

// postcss.config.mjs
export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

原因： 在v4版本中，

postcss-import

和

autoprefixer

已自动集成。需使用

@tailwindcss/postcss

插件，而非

tailwindcss

。

4. Use Modern Opacity Syntax

4. 使用现代透明度语法

Wrong (agents do this):

html

<div class="bg-red-500 bg-opacity-50">
  <div class="text-blue-600 text-opacity-75"></div>
</div>

Correct:

html

<div class="bg-red-500/50">
  <div class="text-blue-600/75"></div>
</div>

Why: The

bg-opacity-*

text-opacity-*

border-opacity-*

, and

placeholder-opacity-*

utilities were removed in v4. Use the slash modifier syntax.

错误写法（AI Agent常这么生成）：

html

<div class="bg-red-500 bg-opacity-50">
  <div class="text-blue-600 text-opacity-75"></div>
</div>

正确写法：

html

<div class="bg-red-500/50">
  <div class="text-blue-600/75"></div>
</div>

原因： Tailwind v4已移除

bg-opacity-*

、

text-opacity-*

、

border-opacity-*

和

placeholder-opacity-*

工具类，需使用斜杠修饰符语法。

5. Use CSS Variables for Custom Colors

5. 使用CSS变量定义自定义颜色

Wrong (agents do this):

html

<div class="bg-[#3b82f6]"></div>

Correct:

css

@theme {
  --color-brand: #3b82f6;
}

html

<div class="bg-brand"></div>

Why: Arbitrary values (

bg-[#3b82f6]

) should be rare. Define custom colors in

@theme

so they're reusable and consistent.

错误写法（AI Agent常这么生成）：

html

<div class="bg-[#3b82f6]"></div>

正确写法：

css

@theme {
  --color-brand: #3b82f6;
}

html

<div class="bg-brand"></div>

原因： 应尽量避免使用任意值写法（如

bg-[#3b82f6]

）。在

@theme

中定义自定义颜色可确保复用性和一致性。

6. Use Container Queries with @container

6. 使用@container实现容器查询

Wrong (agents do this):

html

<div class="md:flex-row flex-col"></div>

Correct (when sizing should be based on parent, not viewport):

html

<div class="@container">
  <div class="flex flex-col @md:flex-row">
    <!-- Responds to container width, not viewport -->
  </div>
</div>

Why: Tailwind v4 has built-in container query support. Use

@container

on the parent and

@sm:

@md:

@lg:

variants on children for component-level responsive design.

错误写法（AI Agent常这么生成）：

html

<div class="md:flex-row flex-col"></div>

正确写法（当尺寸需基于父容器而非视口时）：

html

<div class="@container">
  <div class="flex flex-col @md:flex-row">
    <!-- 响应容器宽度而非视口宽度 -->
  </div>
</div>

原因： Tailwind v4内置容器查询支持。在父元素上使用

@container

，在子元素上使用

@sm:

、

@md:

、

@lg:

变体可实现组件级响应式设计。

7. Use @utility for Custom Utilities

7. 使用@utility定义自定义工具类

Wrong (agents do this):

css

@layer utilities {
  .content-auto {
    content-visibility: auto;
  }
}

Correct:

css

@utility content-auto {
  content-visibility: auto;
}

Why: Tailwind v4 uses

@utility

directive instead of

@layer utilities

for custom utilities.

错误写法（AI Agent常这么生成）：

css

@layer utilities {
  .content-auto {
    content-visibility: auto;
  }
}

正确写法：

css

@utility content-auto {
  content-visibility: auto;
}

原因： Tailwind v4使用

@utility

指令替代

@layer utilities

来定义自定义工具类。

8. Use Correct Important Modifier

8. 使用正确的!important修饰符

Wrong (agents do this):

// tailwind.config.js
module.exports = {
  important: true,
};

Correct:

css

@import "tailwindcss" important;

Why: The

important

option moved from config to the CSS import statement in v4.

错误写法（AI Agent常这么生成）：

// tailwind.config.js
module.exports = {
  important: true,
};

正确写法：

css

@import "tailwindcss" important;

原因： Tailwind v4中，

important

配置项已从配置文件移至CSS导入语句中。

9. Use Renamed Utilities

9. 使用重命名后的工具类

Wrong (agents do this):

html

<div class="shadow-sm ring-1 ring-gray-900/5">
  <div class="blur-sm">
    <div class="rounded-sm"></div>
  </div>
</div>

Correct:

html

<div class="shadow-xs ring-1 ring-gray-900/5">
  <div class="blur-xs">
    <div class="rounded-xs"></div>
  </div>
</div>

Why: In v4,

shadow-sm

was renamed to

shadow-xs

shadow

shadow-sm

blur-sm

blur-xs

rounded-sm

rounded-xs

, etc. The old

-sm

values now map to what was previously the default.

错误写法（AI Agent常这么生成）：

html

<div class="shadow-sm ring-1 ring-gray-900/5">
  <div class="blur-sm">
    <div class="rounded-sm"></div>
  </div>
</div>

正确写法：

html

<div class="shadow-xs ring-1 ring-gray-900/5">
  <div class="blur-xs">
    <div class="rounded-xs"></div>
  </div>
</div>

原因： Tailwind v4中，

shadow-sm

已重命名为

shadow-xs

，

shadow

重命名为

shadow-sm

，

blur-sm

重命名为

blur-xs

，

rounded-sm

重命名为

rounded-xs

等。原有的

-sm

后缀现在对应之前的默认值。

10. Use Modern Gradient Syntax

10. 使用现代渐变语法

Wrong (agents do this):

html

<div class="bg-gradient-to-r from-blue-500 to-purple-500"></div>

Correct:

html

<div class="bg-linear-to-r from-blue-500 to-purple-500"></div>

Why: Tailwind v4 renamed

bg-gradient-to-*

bg-linear-to-*

and added support for other gradient types like

bg-conic-*

and

bg-radial-*

错误写法（AI Agent常这么生成）：

html

<div class="bg-gradient-to-r from-blue-500 to-purple-500"></div>

正确写法：

html

<div class="bg-linear-to-r from-blue-500 to-purple-500"></div>

原因： Tailwind v4已将

bg-gradient-to-*

重命名为

bg-linear-to-*

，并新增了

bg-conic-*

和

bg-radial-*

等其他渐变类型的支持。

11. Use not-* Variant for Negation

11. 使用not-*变体实现否定样式

Wrong (agents do this):

html

<div class="hover:bg-blue-500">
  <!-- No way to style non-hovered state specifically -->
</div>

Correct:

html

<div class="not-hover:opacity-75 hover:opacity-100"></div>

Why: Tailwind v4 added the

not-*

variant for styling elements that do NOT match a condition.

错误写法（AI Agent常这么生成）：

html

<div class="hover:bg-blue-500">
  <!-- 无法专门设置非 hover 状态的样式 -->
</div>

正确写法：

html

<div class="not-hover:opacity-75 hover:opacity-100"></div>

原因： Tailwind v4新增了

not-*

变体，用于为不满足特定条件的元素设置样式。

12. Use @starting-style for Entry Animations

12. 使用@starting-style实现入场动画

Wrong (agents do this):

css

.modal {
  opacity: 0;
  transition: opacity 0.3s;
}
.modal.open {
  opacity: 1;
}

Correct:

html

<div class="starting:opacity-0 opacity-100 transition-opacity duration-300"></div>

Why: Tailwind v4 supports

@starting-style

via the

starting:

variant for CSS-only entry animations without JavaScript.

错误写法（AI Agent常这么生成）：

css

.modal {
  opacity: 0;
  transition: opacity 0.3s;
}
.modal.open {
  opacity: 1;
}

正确写法：

html

<div class="starting:opacity-0 opacity-100 transition-opacity duration-300"></div>

原因： Tailwind v4通过

starting:

变体支持

@starting-style

，无需JavaScript即可实现纯CSS入场动画。

Patterns

Anti-Patterns

反模式

NEVER create a
```
tailwind.config.js
```
unless you need JavaScript-based dynamic config

NEVER use

@tailwind base/components/utilities

- use

@import "tailwindcss"

NEVER use
```
bg-opacity-*
```
,
```
text-opacity-*
```
- use slash modifier syntax
NEVER use
```
@layer utilities
```
for custom utilities - use
```
@utility
```
NEVER use
```
bg-gradient-to-*
```
- use
```
bg-linear-to-*
```
NEVER use
```
postcss-import
```
or
```
autoprefixer
```
with v4 - they're built in
NEVER use
```
shadow-sm
```
when you mean the smallest shadow - it's now
```
shadow-xs
```

除非需要基于JavaScript的动态配置，否则绝不创建
```
tailwind.config.js
```
文件

绝不使用

@tailwind base/components/utilities

——应使用

@import "tailwindcss"

绝不使用
```
bg-opacity-*
```
、
```
text-opacity-*
```
——应使用斜杠修饰符语法
绝不使用
```
@layer utilities
```
定义自定义工具类——应使用
```
@utility
```
绝不使用
```
bg-gradient-to-*
```
——应使用
```
bg-linear-to-*
```
绝不与v4版本搭配使用
```
postcss-import
```
或
```
autoprefixer
```
——它们已内置
当需要最小阴影时，绝不使用
```
shadow-sm
```
——现在对应的是
```
shadow-xs
```

tailwind-best-practices

Original

Translation

When to use

适用场景

Critical Rules

核心规则

1. Use CSS @import Instead of @tailwind Directives

1. 使用CSS @import替代@tailwind指令

2. Use CSS-First Configuration with @theme

2. 使用@theme实现CSS优先配置

3. Use @tailwindcss/postcss Plugin

3. 使用@tailwindcss/postcss插件

4. Use Modern Opacity Syntax

4. 使用现代透明度语法

5. Use CSS Variables for Custom Colors

5. 使用CSS变量定义自定义颜色

6. Use Container Queries with @container

6. 使用@container实现容器查询

7. Use @utility for Custom Utilities

7. 使用@utility定义自定义工具类

8. Use Correct Important Modifier

8. 使用正确的!important修饰符

9. Use Renamed Utilities

9. 使用重命名后的工具类

10. Use Modern Gradient Syntax

10. 使用现代渐变语法

11. Use not-* Variant for Negation

11. 使用not-*变体实现否定样式

12. Use @starting-style for Entry Animations

12. 使用@starting-style实现入场动画

Patterns

推荐模式

Anti-Patterns

反模式