Tailwind CSS v4 完全指南：CSS 优先配置、ESLint 集成与最佳实践

tailwind-css by paulrberg/agent-skills

90 周安装量

41 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/paulrberg/agent-skills --skill tailwind-css

CSS 开发代码规范

🇨🇳中文介绍

Tailwind CSS v4

Tailwind CSS v4 的专家指导，涵盖 CSS 优先配置、现代工具类模式以及使用 tailwind-variants 进行类型安全的组件样式设计。

CSS 优先配置

Tailwind CSS v4 移除了 tailwind.config.ts，转而采用纯 CSS 配置。所有配置都通过特殊指令存在于 CSS 文件中。

核心指令：

@import "tailwindcss" - 加载 Tailwind 的入口点
@theme { } - 定义或扩展设计令牌
@theme static { } - 定义不应生成工具类的令牌
@utility - 创建自定义工具类
@custom-variant - 定义自定义变体

最小示例：

@import "tailwindcss";

@theme {
  --color-brand: oklch(0.72 0.11 178);
  --font-display: "Inter", sans-serif;
  --spacing-edge: 1.5rem;
}

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

颜色与不透明度

使用不透明度修饰符语法，而非单独的不透明度工具类：

所有 *-opacity-* 工具类在 Tailwind v4 中已被移除。请改用修饰符语法。

// ✅ 正确：不透明度修饰符
<div className="bg-red-500/60">

// ❌ 错误：在 v4 中已移除
<div className="bg-red-500 bg-opacity-60">

优先使用设计令牌而非任意的十六进制值：

在使用任意颜色值之前，请先检查项目的 @theme 配置。

// ✅ 正确：主题令牌
<div className="bg-brand">

// ❌ 避免：任意的十六进制值（先检查主题）
<div className="bg-[#4f46e5]">

Tailwind v4 重命名了边框半径工具类：

v3	v4（等效）	大小
`rounded-sm`	`rounded-xs`	2px
`rounded`	`rounded-sm`	4px
`rounded-md`	`rounded`	6px
`rounded-lg`	`rounded-md`	8px

编写新代码时请使用 v4 的名称。

Tailwind v4 重命名了渐变工具类并添加了新的渐变类型。

使用bg-linear-*，而非 bg-gradient-*：

// ✅ 正确：v4 语法
<div className="bg-linear-to-r from-blue-500 to-purple-500">

// ❌ 错误：在 v4 中已移除
<div className="bg-gradient-to-r from-blue-500 to-purple-500">

新的渐变类型：

bg-radial - 径向渐变
bg-conic - 锥形渐变

<div className="bg-radial from-blue-500 to-purple-500">
<div className="bg-conic from-red-500 via-yellow-500 to-green-500">

始终优先使用 Tailwind 的预定义比例：

在使用任意值之前，请先检查项目的 @theme 配置以获取可用的令牌。

// ✅ 正确：预定义比例
<div className="ml-4">

// ❌ 避免：任意的像素值
<div className="ml-[16px]">

通用规则： 优先使用尺寸比例而非像素值。三行相似的代码优于过早的抽象。

常见的模式是结合 clsx 和 tailwind-merge 的 cn 工具函数。

使用cn 用于：

静态常量：const CARD_BASE = cn("fixed classes")
条件类：cn("base", condition && "conditional")
动态合并：cn(baseClasses, className)
冲突解决：cn("p-4", "p-6") → "p-6"

不要使用cn 用于：

className 属性中的静态字符串：className="fixed classes"

// ✅ 正确：className 中的静态字符串
<button className="rounded-lg px-4 py-2 font-medium bg-blue-600">

// ✅ 正确：使用 cn 的静态常量
const CARD_BASE = cn("rounded-lg border border-gray-300 p-4");
<div className={CARD_BASE} />

// ✅ 正确：使用 cn 的条件类
<button className={cn(
  "rounded-lg px-4 py-2 font-medium",
  isActive ? "bg-blue-600" : "bg-gray-700",
  disabled && "opacity-50"
)} />

// ❌ 错误：在静态 className 属性中不必要地使用 cn
<button className={cn("rounded-lg px-4 py-2 font-medium")} />

对于 Image 组件，使用 Tailwind 尺寸类而非像素值。

// ✅ 正确：Tailwind 单位
<Image src={src} alt={alt} className="size-16" />
<Image src={src} alt={alt} className="w-24 h-auto" />

// ❌ 错误：像素值
<Image src={src} alt={alt} width={64} height={64} />

将 z-index 值定义为 @theme 中的 CSS 自定义属性，然后使用 z-(--z-*) 语法引用它们。

切勿使用任意的 z-index 数字：

// ✅ 正确：主题 z-index 值
<div className="z-(--z-modal)">
<div className="z-(--z-sticky)">

// ❌ 错误：任意的 z-index 数字
<div className="z-[100]">
<div className="z-[9999]">

在 CSS 中定义 z-index 令牌：

@theme {
  --z-base: 0;
  --z-sticky: 10;
  --z-modal: 100;
  --z-tooltip: 1000;
}

使用简单的 dark: 变体来处理深色模式样式。

先编写浅色模式样式，然后添加深色模式覆盖。

// ✅ 正确：先浅色模式，后深色覆盖
<div className="bg-white text-gray-900 dark:bg-gray-900 dark:text-white">

// ❌ 避免：先深色模式（可读性较差）
<div className="dark:bg-gray-900 dark:text-white bg-white text-gray-900">

仅当无法用 Tailwind 类轻松编写复杂 CSS 时，才将 CSS 模块作为最后的手段。

所有 .module.css 文件必须在顶部包含 @reference "#tailwind";，以在模块内启用 Tailwind 工具类和主题令牌。

/* component.module.css */
@reference "#tailwind";

.component {
  /* 无法用 Tailwind 工具类表达的复杂 CSS */
  /* 仍然可以使用 Tailwind 工具类和主题令牌 */
}

添加带变体的组件

阅读 references/tailwind-variants.md 了解模式
检查项目的 @theme 配置以获取可用的令牌
使用 tailwind-variants 中的 tv() 进行类型安全的变体设计

import { tv } from "tailwind-variants";

const button = tv({
  base: "rounded-lg px-4 py-2 font-medium",
  variants: {
    color: {
      primary: "bg-blue-600 text-white",
      secondary: "bg-gray-600 text-white",
    },
    size: {
      sm: "text-sm",
      md: "text-base",
      lg: "text-lg",
    },
  },
});

检查 references/tailwind-v4-rules.md 了解破坏性变更
验证渐变语法（bg-linear-*，而非 bg-gradient-*）
验证 CSS 变量语法（bg-my-color，而非 bg-[--var-my-color]）
检查任意值是否存在于项目的 @theme 配置中

首先检查项目的 @theme 配置以查看可用的颜色
有语义化颜色名称时优先使用
使用不透明度修饰符实现透明度（/20、/50 等）
除非绝对必要，避免使用任意颜色

// ✅ 正确：带不透明度的主题令牌
<div className="bg-brand/20 text-brand">

// ❌ 避免：任意的十六进制值
<div className="bg-[#4f46e5]/20 text-[#4f46e5]">

阅读 references/tw-animate-css.md 了解可用的动画
将基类（animate-in 或 animate-out）与效果类组合使用
注意小数间距问题：使用 [0.625rem] 语法，而非 2.5

// 进入：淡入 + 从底部滑入
<div className="fade-in slide-in-from-bottom-4 duration-300 animate-in">

// 退出：淡出 + 向底部滑出
<div className="fade-out slide-out-to-bottom-4 duration-200 animate-out">

方面	模式
配置	纯 CSS：`@theme`、`@utility`、`@custom-variant`
渐变	`bg-linear-*`、`bg-radial`、`bg-conic`
不透明度	修饰符语法：`bg-black/50`
行高	修饰符语法：`text-base/7`
字体特性	`font-features-zero`、`font-features-ss01` 等
CSS 变量	`bg-my-color`（从 `@theme` 自动创建）
CSS 模块	顶部 `@reference "#tailwind";`
类合并	`cn()` 用于条件类；静态类用纯字符串
视口	`min-h-dvh`（非 `min-h-screen`）
组件变体	`references/tailwind-variants.md`
动画	`references/tw-animate-css.md`
V4 规则	`references/tailwind-v4-rules.md`

Tailwind v4 规则与最佳实践： references/tailwind-v4-rules.md — 破坏性变更、已移除/重命名的工具类、布局规则、排版、渐变、CSS 变量、新的 v4 功能、常见陷阱
tailwind-variants 模式： references/tailwind-variants.md — 组件变体、插槽 API、组合、TypeScript 集成、响应式变体
tw-animate-css 参考： references/tw-animate-css.md — 进入/退出动画、滑动/淡入淡出/缩放工具类、间距问题

🇺🇸English

Tailwind CSS v4

Expert guidance for Tailwind CSS v4, CSS-first configuration, modern utility patterns, and type-safe component styling with tailwind-variants.

CSS-First Configuration

Tailwind CSS v4 eliminates tailwind.config.ts in favor of CSS-only configuration. All configuration lives in CSS files using special directives.

Core Directives:

@import "tailwindcss" - Entry point that loads Tailwind
@theme { } - Define or extend design tokens
@theme static { } - Define tokens that should not generate utilities
@utility - Create custom utilities
@custom-variant - Define custom variants

Minimal Example:

@import "tailwindcss";

@theme {
  --color-brand: oklch(0.72 0.11 178);
  --font-display: "Inter", sans-serif;
  --spacing-edge: 1.5rem;
}

All theme tokens defined with @theme automatically become available as utility classes. For example, --color-brand can be used as bg-brand, text-brand, border-brand, etc.

ESLint Integration

Use eslint-plugin-better-tailwindcss for Tailwind CSS v4 class validation and style enforcement.

Correctness Rules (errors):

no-conflicting-classes - Detect classes that override each other
no-unknown-classes - Flag classes not registered with Tailwind

Stylistic Rules (warnings):

enforce-canonical-classes - Use standard v4 class names
enforce-shorthand-classes - Use abbreviated class versions
no-deprecated-classes - Remove outdated class names
no-duplicate-classes - Eliminate redundant declarations
no-unnecessary-whitespace - Clean up extra spacing

Examples:

// ❌ Bad: separate padding
<div className="px-6 py-6">

// ✅ Good: shorthand
<div className="p-6">



// ❌ Bad: separate width/height
<div className="w-6 h-6">

// ✅ Good: size utility
<div className="size-6">

Run the project's ESLint check after modifying Tailwind classes to validate all changes across the codebase.

Coding Preferences

Layout and Spacing

Usegap for flex/grid spacing, not space-x/space-y:

The gap utilities handle wrapping correctly, while space-* utilities break when flex/grid items wrap to multiple lines.

// ✅ Good: gap handles wrapping
<div className="flex gap-4">

// ❌ Bad: breaks when items wrap
<div className="flex space-x-4">

Prefersize-* over separate w-*/h-* for equal dimensions:

// ✅ Good: concise
<div className="size-16">

// ❌ Bad: redundant
<div className="w-16 h-16">

Always usemin-h-dvh instead of min-h-screen:

Dynamic viewport height (dvh) accounts for mobile browser chrome, while vh units ignore it and cause layout issues on mobile Safari.

// ✅ Good: works on mobile Safari
<main className="min-h-dvh">

// ❌ Bad: buggy on mobile Safari
<main className="min-h-screen">

Prefer top/left margins over bottom/right:

Consistent directionality improves layout predictability.

// ✅ Good: top margin
<div className="mt-4">

// ❌ Avoid: bottom margin (unless needed)
<div className="mb-4">

Use padding on parent containers instead of bottom margins on last child:

Padding provides consistent spacing without needing :last-child selectors.

// ✅ Good: padding on parent
<section className="pb-8">
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</section>

// ❌ Avoid: margin on children
<section>
  <div className="mb-4">Item 1</div>
  <div className="mb-4">Item 2</div>
  <div>Item 3</div>
</section>

For max-widths, prefer container scale over pixel values:

// ✅ Good: semantic container size
<div className="max-w-2xl">

// ❌ Avoid: arbitrary pixel value
<div className="max-w-[672px]">

Typography

Avoidleading-* classes; use line height modifiers:

Tailwind v4 supports inline line height modifiers with the text-{size}/{leading} syntax.

// ✅ Good: combined size and line height
<p className="text-base/7">

// ❌ Bad: separate utilities
<p className="text-base leading-7">

Font Size Reference:

Class	Size
`text-xs`	12px
`text-sm`	14px
`text-base`	16px
`text-lg`	18px
`text-xl`	20px

Colors and Opacity

Use opacity modifier syntax, not separate opacity utilities:

All *-opacity-* utilities were removed in Tailwind v4. Use the modifier syntax instead.

// ✅ Good: opacity modifier
<div className="bg-red-500/60">

// ❌ Bad: removed in v4
<div className="bg-red-500 bg-opacity-60">

Prefer design tokens over arbitrary hex values:

Check the project's @theme configuration before using arbitrary color values.

// ✅ Good: theme token
<div className="bg-brand">

// ❌ Avoid: arbitrary hex (check theme first)
<div className="bg-[#4f46e5]">

Border Radius

Tailwind v4 renamed border radius utilities:

v3	v4 (equivalent)	Size
`rounded-sm`	`rounded-xs`	2px
`rounded`	`rounded-sm`	4px
`rounded-md`	`rounded`	6px
`rounded-lg`

Use the v4 names when writing new code.

Gradients

Tailwind v4 renamed gradient utilities and added new gradient types.

Usebg-linear-*, not bg-gradient-*:

// ✅ Good: v4 syntax
<div className="bg-linear-to-r from-blue-500 to-purple-500">

// ❌ Bad: removed in v4
<div className="bg-gradient-to-r from-blue-500 to-purple-500">

New gradient types:

bg-radial - Radial gradients
bg-conic - Conic gradients

Example:

<div className="bg-radial from-blue-500 to-purple-500">
<div className="bg-conic from-red-500 via-yellow-500 to-green-500">

Arbitrary Values

Always prefer Tailwind's predefined scale:

Check the project's @theme configuration for available tokens before using arbitrary values.

// ✅ Good: predefined scale
<div className="ml-4">

// ❌ Avoid: arbitrary pixel value
<div className="ml-[16px]">

General rule: Prefer sizing scale over pixel values. Three similar lines of code is better than a premature abstraction.

Class Merging

The common pattern is a cn utility combining clsx + tailwind-merge.

Usecn for:

Static constants: const CARD_BASE = cn("fixed classes")
Conditional classes: cn("base", condition && "conditional")
Dynamic merging: cn(baseClasses, className)
Conflict resolution: cn("p-4", "p-6") → "p-6"

Do NOT usecn for:

Static strings in className attributes: className="fixed classes"

Examples:

// ✅ Good: static string in className
<button className="rounded-lg px-4 py-2 font-medium bg-blue-600">

// ✅ Good: static constant with cn
const CARD_BASE = cn("rounded-lg border border-gray-300 p-4");
<div className={CARD_BASE} />

// ✅ Good: conditional with cn
<button className={cn(
  "rounded-lg px-4 py-2 font-medium",
  isActive ? "bg-blue-600" : "bg-gray-700",
  disabled && "opacity-50"
)} />

// ❌ Bad: unnecessary cn for static className attribute
<button className={cn("rounded-lg px-4 py-2 font-medium")} />

Image Sizing

Use Tailwind size classes instead of pixel values for Image components.

// ✅ Good: Tailwind units
<Image src={src} alt={alt} className="size-16" />
<Image src={src} alt={alt} className="w-24 h-auto" />

// ❌ Bad: pixel values
<Image src={src} alt={alt} width={64} height={64} />

Z-Index

Define z-index values as CSS custom properties in @theme, then reference them with the z-(--z-*) syntax.

Never use arbitrary z-index numbers:

// ✅ Good: theme z-index value
<div className="z-(--z-modal)">
<div className="z-(--z-sticky)">

// ❌ Bad: arbitrary z-index numbers
<div className="z-[100]">
<div className="z-[9999]">

Define z-index tokens in CSS:

@theme {
  --z-base: 0;
  --z-sticky: 10;
  --z-modal: 100;
  --z-tooltip: 1000;
}

Dark Mode

Use the plain dark: variant for dark mode styles.

Pattern:

Write light mode styles first, then add dark mode overrides.

// ✅ Good: light mode first, then dark override
<div className="bg-white text-gray-900 dark:bg-gray-900 dark:text-white">

// ❌ Avoid: dark mode first (less readable)
<div className="dark:bg-gray-900 dark:text-white bg-white text-gray-900">

CSS Modules

Use CSS Modules only as a last resort for complex CSS that cannot be easily written with Tailwind classes.

All .module.css files must include @reference "#tailwind"; at the top to enable Tailwind utilities and theme tokens inside the module.

Example:

/* component.module.css */
@reference "#tailwind";

.component {
  /* Complex CSS that can't be expressed with Tailwind utilities */
  /* Can still use Tailwind utilities and theme tokens */
}

Common Tasks

Adding a Component with Variants

Read references/tailwind-variants.md for patterns
Check the project's @theme configuration for available tokens
Use tv() from tailwind-variants for type-safe variants

Example:

import { tv } from "tailwind-variants";

const button = tv({
  base: "rounded-lg px-4 py-2 font-medium",
  variants: {
    color: {
      primary: "bg-blue-600 text-white",
      secondary: "bg-gray-600 text-white",
    },
    size: {
      sm: "text-sm",
      md: "text-base",
      lg: "text-lg",
    },
  },
});

Debugging Styles

Check references/tailwind-v4-rules.md for breaking changes
Verify gradient syntax (bg-linear-*, not bg-gradient-*)
Verify CSS variable syntax (bg-my-color, not bg-[--var-my-color])
Check if arbitrary value exists in the project's @theme configuration

Working with Colors

Check the project's @theme configuration first to see available colors
Use semantic color names when available
Use opacity modifiers for transparency (/20, /50, etc.)
Avoid arbitrary colors unless absolutely necessary

Example:

// ✅ Good: theme token with opacity
<div className="bg-brand/20 text-brand">

// ❌ Avoid: arbitrary hex
<div className="bg-[#4f46e5]/20 text-[#4f46e5]">

Adding Animations

Read references/tw-animate-css.md for available animations
Combine a base class (animate-in or animate-out) with effect classes
Note decimal spacing gotcha: use [0.625rem] syntax, not 2.5

Example:

// Enter: fade + slide up
<div className="fade-in slide-in-from-bottom-4 duration-300 animate-in">

// Exit: fade + slide down
<div className="fade-out slide-out-to-bottom-4 duration-200 animate-out">

Quick Reference Table

Aspect	Pattern
Configuration	CSS-only: `@theme`, `@utility`, `@custom-variant`
Gradients	`bg-linear-*`, `bg-radial`, `bg-conic`
Opacity	Modifier syntax: `bg-black/50`
Line Height	Modifier syntax: `text-base/7`

Reference Documentation

Tailwind v4 Rules & Best Practices: references/tailwind-v4-rules.md — Breaking changes, removed/renamed utilities, layout rules, typography, gradients, CSS variables, new v4 features, common pitfalls
tailwind-variants Patterns: references/tailwind-variants.md — Component variants, slots API, composition, TypeScript integration, responsive variants
tw-animate-css Reference: references/tw-animate-css.md — Enter/exit animations, slide/fade/zoom utilities, spacing gotchas

Weekly Installs

Repository

paulrberg/agent-skills

GitHub Stars

First Seen

Feb 14, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

claude-code83

kimi-cli81

gemini-cli81

github-copilot81

amp81

codex81

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

118,000 周安装

Tailwind CSS v4 完全指南：CSS 优先配置、ESLint 集成与最佳实践

🇨🇳中文介绍

Tailwind CSS v4

CSS 优先配置

相关 Skills

ESLint 集成

编码偏好

布局与间距

排版

颜色与不透明度

边框半径

渐变

任意值

类合并

图像尺寸

Z-Index

深色模式

CSS 模块

常见任务

添加带变体的组件

调试样式

处理颜色

添加动画

快速参考表

参考文档

🇺🇸English

Tailwind CSS v4

CSS-First Configuration

ESLint Integration

Coding Preferences

Layout and Spacing

Typography

Colors and Opacity

Border Radius

Gradients

Arbitrary Values

Class Merging

Image Sizing

Z-Index

Dark Mode

CSS Modules

Common Tasks

Adding a Component with Variants

Debugging Styles

Working with Colors

Adding Animations

Quick Reference Table

Reference Documentation

最新 Skills