Back to Details

tailwind-css

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Tailwind CSS v4 & tailwind-variants

Tailwind CSS v4 与 tailwind-variants

Your Role

你的角色

You are an expert in Tailwind CSS v4. You understand CSS-first configuration, modern utility patterns, and type-safe component styling with tailwind-variants.
你是Tailwind CSS v4方面的专家，了解CSS优先配置、现代工具类模式，以及使用tailwind-variants进行类型安全的组件样式设计。

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
  • Tailwind v4 规则与最佳实践: 
    ./references/TAILWIND_V4_RULES.md
    • 破坏性变更、已移除/重命名的工具类、布局规则、排版、渐变、CSS变量、v4新特性、常见陷阱
  • tailwind-variants 模式: 
    ./references/TAILWIND_VARIANTS.md
    • 组件变体、插槽API、组合、TypeScript集成、响应式变体

Core Principles

核心原则

  • Always use Tailwind CSS v4.1+
  • Do not use deprecated or removed utilities - Use the replacement
  • Never use 
    @apply
     - Use CSS variables, the 
    --spacing()
    function, or framework components instead
  • Check for redundant classes - Remove any classes that aren't necessary
  • 始终使用Tailwind CSS v4.1+版本
  • 不要使用已废弃或已移除的工具类 - 使用替代方案
  • 绝不使用
    @apply
     - 改用CSS变量、
    --spacing()
    函数或框架组件
  • 检查冗余类 - 移除所有不必要的类

Configuration Method

配置方法

Tailwind CSS v4 uses CSS-only configuration:
  • No 
    tailwind.config.ts
    file needed
  • Define theme tokens with 
    @theme { }
    or 
    @theme static { }
  • Create custom utilities with 
    @utility { }
  • Define custom variants with 
    @custom-variant { }
css
@import "tailwindcss";

@theme {
  --color-primary: oklch(0.72 0.11 178);
  --spacing-edge: 1.5rem;
}
Tailwind CSS v4采用纯CSS配置:
  • 无需
    tailwind.config.ts
    文件
  • 使用
    @theme { }
    或
    @theme static { }
    定义主题令牌
  • 使用
    @utility { }
    创建自定义工具类
  • 使用
    @custom-variant { }
    定义自定义变体
css
@import "tailwindcss";

@theme {
  --color-primary: oklch(0.72 0.11 178);
  --spacing-edge: 1.5rem;
}

Critical Breaking Changes (v3 → v4)

关键破坏性变更（v3 → v4）

Renamed Utilities

重命名的工具类

v3 (deprecated)v4 (use instead)
bg-gradient-*
bg-linear-*
shadow-sm
shadow-xs
shadow
shadow-sm
blur-sm
blur-xs
blur
blur-sm
rounded-sm
rounded-xs
rounded
rounded-sm
outline-none
outline-hidden
ring
ring-3
drop-shadow-sm
drop-shadow-xs
drop-shadow
drop-shadow-sm
backdrop-blur-sm
backdrop-blur-xs
backdrop-blur
backdrop-blur-sm
v3（已废弃）v4（推荐使用）
bg-gradient-*
bg-linear-*
shadow-sm
shadow-xs
shadow
shadow-sm
blur-sm
blur-xs
blur
blur-sm
rounded-sm
rounded-xs
rounded
rounded-sm
outline-none
outline-hidden
ring
ring-3
drop-shadow-sm
drop-shadow-xs
drop-shadow
drop-shadow-sm
backdrop-blur-sm
backdrop-blur-xs
backdrop-blur
backdrop-blur-sm

Removed Utilities

已移除的工具类

DeprecatedReplacement
bg-opacity-*
Use opacity modifier: 
bg-black/50
text-opacity-*
Use opacity modifier: 
text-black/50
border-opacity-*
Use opacity modifier: 
border-black/50
flex-shrink-*
shrink-*
flex-grow-*
grow-*
overflow-ellipsis
text-ellipsis
已废弃工具类替代方案
bg-opacity-*
使用不透明度修饰符: 
bg-black/50
text-opacity-*
使用不透明度修饰符: 
text-black/50
border-opacity-*
使用不透明度修饰符: 
border-black/50
flex-shrink-*
shrink-*
flex-grow-*
grow-*
overflow-ellipsis
text-ellipsis

Gradient Syntax

渐变语法

Use v4 gradient syntax:
html
<!-- Linear gradients -->
<div class="bg-linear-to-br from-violet-500 to-fuchsia-500"></div>

<!-- Radial gradients -->
<div class="bg-radial-[at_50%_75%] from-sky-200 to-indigo-900"></div>

<!-- Conic gradients -->
<div class="bg-conic-180 from-indigo-600 via-indigo-50 to-indigo-600"></div>

<!-- Deprecated syntax -->
<div class="bg-gradient-to-br ..."></div>
<!-- Wrong! -->
使用v4渐变语法:
html
<!-- 线性渐变 -->
<div class="bg-linear-to-br from-violet-500 to-fuchsia-500"></div>

<!-- 径向渐变 -->
<div class="bg-radial-[at_50%_75%] from-sky-200 to-indigo-900"></div>

<!-- 锥形渐变 -->
<div class="bg-conic-180 from-indigo-600 via-indigo-50 to-indigo-600"></div>

<!-- 已废弃语法 -->
<div class="bg-gradient-to-br ..."></div>
<!-- 错误！ -->

Responsive Design (Mobile-First)

响应式设计（移动端优先）

Tailwind is mobile-first:
  • Default classes (no prefix) apply to all screen sizes
  • Breakpoint prefixes (
    md:
    , 
    lg:
    ) apply at that breakpoint and above
  • Never use 
    sm:
    for mobile     - it's redundant
html
<!-- Correct: Mobile first, then scale up -->
<div class="text-sm md:text-base lg:text-lg">
  <div class="flex-col md:flex-row">
    <div class="px-4 md:px-6 lg:px-8">
      <!-- Hide on mobile, show on desktop -->
      <div class="hidden lg:block"></div>
    </div>
  </div>
</div>
Tailwind采用移动端优先策略:
  • 默认类（无前缀）适用于所有屏幕尺寸
  • 断点前缀(
    md:
    , 
    lg:
    )在该断点及以上尺寸生效
  • 绝不要为移动端使用
    sm:
    前缀     - 这是多余的
html
<!-- 正确：移动端优先，然后向上适配 -->
<div class="text-sm md:text-base lg:text-lg">
  <div class="flex-col md:flex-row">
    <div class="px-4 md:px-6 lg:px-8">
      <!-- 移动端隐藏，桌面端显示 -->
      <div class="hidden lg:block"></div>
    </div>
  </div>
</div>

Layout Best Practices

布局最佳实践

Always use gap for flex/grid spacing

始终为flex/grid布局使用gap设置间距

html
<!-- Don't use space utilities in flex/grid -->
<div class="flex space-x-4">...</div>
<!-- Wrong! -->

<!-- Use gap -->
<div class="flex gap-4">...</div>
<!-- Correct -->
html
<!-- 不要在flex/grid中使用space工具类 -->
<div class="flex space-x-4">...</div>
<!-- 错误！ -->

<!-- 使用gap -->
<div class="flex gap-4">...</div>
<!-- 正确 -->

Use 
min-h-dvh
instead of 
min-h-screen

使用
min-h-dvh
替代
min-h-screen

min-h-screen
is buggy on mobile Safari.
min-h-screen
在移动端Safari上存在问题。

Use 
size-*
for equal width/height

使用
size-*
设置等宽高

html
<div class="w-10 h-10">...</div>
<!-- Verbose -->
<div class="size-10">...</div>
<!-- Preferred -->
html
<div class="w-10 h-10">...</div>
<!-- 冗余写法 -->
<div class="size-10">...</div>
<!-- 推荐写法 -->

Typography

排版

Use line-height modifiers, not 
leading-*
classes:
html
<!-- Don't use separate leading classes -->
<p class="text-base leading-7">...</p>
<!-- Wrong! -->

<!-- Use line-height modifiers -->
<p class="text-base/7">...</p>
<!-- Correct -->
使用行高修饰符，而非
leading-*
类:
html
<!-- 不要使用单独的leading类 -->
<p class="text-base leading-7">...</p>
<!-- 错误！ -->

<!-- 使用行高修饰符 -->
<p class="text-base/7">...</p>
<!-- 正确 -->

CSS Variables

CSS变量

Tailwind v4 exposes theme values as CSS variables:
css
.custom-element {
  background: var(--color-red-500);
  padding: var(--spacing-4);
  border-radius: var(--radius-lg);
}
Use 
--spacing()
function for calculations:
css
.custom-class {
  margin-top: calc(100vh - --spacing(16));
}
Tailwind v4将主题值暴露为CSS变量:
css
.custom-element {
  background: var(--color-red-500);
  padding: var(--spacing-4);
  border-radius: var(--radius-lg);
}
使用
--spacing()
函数进行计算:
css
.custom-class {
  margin-top: calc(100vh - --spacing(16));
}

tailwind-variants Quick Start

tailwind-variants 快速入门

Type-safe component variants with automatic class conflict resolution:
typescript
import { tv, type VariantProps } from "tailwind-variants";

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

type ButtonVariants = VariantProps<typeof button>;

// Usage
button(); // Uses defaults
button({ color: "secondary", size: "lg" });
See 
./references/TAILWIND_VARIANTS.md
 for:
  • Slots API for multi-part components
  • Compound variants
  • Component composition with 
    extend
  • TypeScript integration patterns
具备自动类冲突解决的类型安全组件变体:
typescript
import { tv, type VariantProps } from "tailwind-variants";

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

type ButtonVariants = VariantProps<typeof button>;

// 使用示例
button(); // 使用默认值
button({ color: "secondary", size: "lg" });
更多内容请查看 
./references/TAILWIND_VARIANTS.md
:
  • 适用于多部分组件的Slots API
  • 复合变体
  • 使用
    extend
    进行组件组合
  • TypeScript集成模式

Quick Reference

快速参考

TopicPattern
Gradients
bg-linear-*
, 
bg-radial
, 
bg-conic
Opacity
bg-red-500/50
(not 
bg-opacity-*
)
Line height
text-base/7
(not 
leading-*
)
SpacingUse 
gap-*
in flex/grid
Equal size
size-10
(not 
w-10 h-10
)
Full height
min-h-dvh
(not 
min-h-screen
)
Component variants
tv()
from tailwind-variants
主题写法模式
渐变
bg-linear-*
, 
bg-radial
, 
bg-conic
不透明度
bg-red-500/50
（而非
bg-opacity-*
）
行高
text-base/7
（而非
leading-*
）
间距在flex/grid中使用
gap-*
等宽高
size-10
（而非
w-10 h-10
）
全屏高度
min-h-dvh
（而非
min-h-screen
）
组件变体来自tailwind-variants的
tv()

Common Tasks

常见任务

Creating a component with variants:
  1. Read 
    ./references/TAILWIND_VARIANTS.md
     for patterns
  2. Use 
    tv()
    for type-safe variants
  3. Extract types with 
    VariantProps<typeof component>
Debugging styles:
  1. Check 
    ./references/TAILWIND_V4_RULES.md
     for breaking changes
  2. Verify gradient syntax (
    bg-linear-*
    , not 
    bg-gradient-*
    )
  3. Check opacity syntax (
    bg-red-500/50
    , not 
    bg-opacity-*
    )
创建带变体的组件:
  1. 查看 
    ./references/TAILWIND_VARIANTS.md
     了解相关模式
  2. 使用
    tv()
    创建类型安全的变体
  3. 使用
    VariantProps<typeof component>
    提取类型
调试样式:
  1. 查看 
    ./references/TAILWIND_V4_RULES.md
     了解破坏性变更
  2. 验证渐变语法（使用
    bg-linear-*
    ，而非
    bg-gradient-*
    ）
  3. 检查不透明度语法（使用
    bg-red-500/50
    ，而非
    bg-opacity-*
    ）