tailwind-best-practices

适用场景

在编写 Tailwind CSS 代码时使用此技能。AI Agent 的训练数据基于 Tailwind v3，因此经常生成过时的写法——错误的配置文件、已弃用的指令、已移除的工具类，以及冗长的类列表。此技能可确保使用 Tailwind CSS v4 的写法。

关键规则

1. 使用 CSS @import，而不是 @tailwind 指令

错误（Agent 会这样做）：

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

正确：

@import "tailwindcss";

**原因：**Tailwind v4 已完全移除 @tailwind 指令。请使用标准 CSS @import 语句。

2. 使用 CSS 优先配置和 @theme

错误（Agent 会这样做）：

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

正确：

@import "tailwindcss";

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

**原因：**Tailwind v4 使用 CSS 优先配置，并采用 @theme 指令。大多数项目无需 tailwind.config.js。

3. 使用 @tailwindcss/postcss 插件

错误（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. 使用现代不透明度语法

错误（Agent 会这样做）：

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

正确：

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

**原因：**v4 已移除 bg-opacity-*、text-opacity-*、border-opacity-* 和 placeholder-opacity-* 工具类。请使用斜杠修饰符语法。

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

错误（Agent 会这样做）：

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

正确：

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

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

**原因：**任意值（bg-[#3b82f6]）应少用。请在 @theme 中定义自定义颜色，以便重复使用并保持一致。

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

错误（Agent 会这样做）：

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

正确（需要根据父元素而非视口确定尺寸时）：

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

**原因：**Tailwind v4 内置了容器查询支持。在父元素上使用 @container，并在子元素上使用 @sm:、@md:、@lg: 变体，以实现组件级响应式设计。

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

错误（Agent 会这样做）：

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

正确：

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

**原因：**Tailwind v4 使用 @utility 指令来定义自定义工具类，而不是 @layer utilities。

8. 使用正确的重要性修饰符

错误（Agent 会这样做）：

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

正确：

@import "tailwindcss" important;

**原因：**在 v4 中，important 选项已从配置文件移至 CSS 导入语句中。

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

错误（Agent 会这样做）：

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

正确：

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

**原因：**在 v4 中，shadow-sm 重命名为 shadow-xs，shadow 重命名为 shadow-sm，blur-sm 重命名为 blur-xs，rounded-sm 重命名为 rounded-xs，等等。旧的 -sm 值现在对应过去的默认值。

10. 使用现代渐变语法

错误（Agent 会这样做）：

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

正确：

<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. 使用 not-* 变体表示否定条件

错误（Agent 会这样做）：

<div class="hover:bg-blue-500">
  
</div>

正确：

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

**原因：**Tailwind v4 新增了 not-* 变体，可用于为不符合某个条件的元素设置样式。

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

错误（Agent 会这样做）：

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

正确：

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

**原因：**Tailwind v4 通过 starting: 变体支持 @starting-style，可在不使用 JavaScript 的情况下实现纯 CSS 进入动画。

模式

• 在 @theme 代码块中定义所有自定义设计令牌
• 使用 @import "tailwindcss" 作为唯一入口
• 使用容器查询（@container + @md:）实现组件级响应式设计
• 使用斜杠修饰符表示不透明度：bg-blue-500/50、text-gray-900/75
• 使用 @utility 定义自定义工具类，使用 @variant 定义自定义变体
• 使用 bg-linear-to-* 表示渐变（而不是 bg-gradient-to-*）

反模式

• 绝不要创建 tailwind.config.js，除非需要基于 JavaScript 的动态配置
• 绝不要使用 @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