tailwindcss

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Tailwind CSS v4

Purpose

目的

Provide guidance for using Tailwind CSS v4 effectively in projects that are already configured, with an emphasis on utility-first patterns, maintainability, and theme variables.

为已完成配置的项目提供Tailwind CSS v4的高效使用指南，重点关注工具优先模式、可维护性与主题变量。

Scope

范围

Included: utility composition, variants, responsive and container query patterns, theme variables, and custom CSS hooks.
Excluded: installation, build tooling, and migration guidance.

包含：工具类组合、变体、响应式与容器查询模式、主题变量及自定义CSS钩子。
不包含：安装、构建工具与迁移指导。

When to Use

使用场景

You are authoring or refactoring UI in a Tailwind CSS v4 codebase.
You need best-practice guidance for composing utility classes and managing reuse.
You are defining or extending design tokens using theme variables.
You need patterns for variants, responsive behavior, or container queries.

你正在Tailwind CSS v4代码库中编写或重构UI。
你需要工具类组合与复用管理的最佳实践指导。
你正在使用主题变量定义或扩展设计令牌。
你需要变体、响应式行为或容器查询的实现模式。

Response Guidance

响应指导

Prefer composing utility classes directly in markup; use variants for state, media, and feature conditions.
Manage duplication with components or template partials; for localized repetition, edit class lists directly rather than inventing abstractions.
Use
```
@layer base
```
for default element styles and
```
@layer components
```
for reusable classes that can still be overridden by utilities.
Use
```
@apply
```
only when writing custom CSS or styling third-party markup; avoid turning utilities into permanent abstractions.
Avoid conflicting utilities on the same element; choose one source of truth or expose explicit props.

优先在标记中直接组合工具类；使用变体处理状态、媒体查询与功能条件。
通过组件或模板片段管理重复代码；对于局部重复，直接编辑类列表而非创建抽象层。
使用
```
@layer base
```
设置元素默认样式，使用
```
@layer components
```
定义可被工具类覆盖的可复用类。
仅在编写自定义CSS或为第三方标记设置样式时使用
```
@apply
```
；避免将工具类转化为固定抽象层。
避免在同一元素上使用冲突的工具类；选择单一可信来源或使用显式条件类选择。

Theme Variables

主题变量

Theme variables are defined with

@theme

and generate both utilities and CSS variables.

css

@import "tailwindcss";

@theme {
  --color-mint-500: oklch(0.72 0.11 178);
  --font-poppins: Poppins, sans-serif;
  --breakpoint-3xl: 120rem;
}

Use
```
@theme
```
for design tokens that should map to utilities; use
```
:root
```
for plain CSS variables that should not generate utilities.

Common namespaces include

--color-*

--font-*

--text-*

--spacing-*

--radius-*

--shadow-*

--breakpoint-*

--container-*

, and

--animate-*

Extend defaults by adding new variables, override by redefining, and reset a namespace with
```
--color-*: initial
```
or the entire theme with
```
--*: initial
```
.
Prefer CSS variables for custom CSS and inline styles, for example
```
var(--color-sky-500)
```
or
```
bg-(--my-color)
```
.
Use
```
@theme inline
```
when a theme variable references other variables to avoid unexpected resolution; use
```
@theme static
```
when you want all theme variables emitted regardless of usage.
```
theme()
```
is deprecated in v4; use CSS variables instead and only reach for
```
theme(--breakpoint-*)
```
in edge cases like media queries.

主题变量通过

@theme

定义，同时生成工具类与CSS变量。

css

@import "tailwindcss";

@theme {
  --color-mint-500: oklch(0.72 0.11 178);
  --font-poppins: Poppins, sans-serif;
  --breakpoint-3xl: 120rem;
}

对于需要映射到工具类的设计令牌，使用
```
@theme
```
；对于无需生成工具类的纯CSS变量，使用
```
:root
```
。

常见命名空间包括

--color-*

、

--font-*

、

--text-*

、

--spacing-*

、

--radius-*

、

--shadow-*

、

--breakpoint-*

、

--container-*

与

--animate-*

。

通过添加新变量扩展默认值，通过重定义覆盖默认值，使用
```
--color-*: initial
```
重置单个命名空间，或使用
```
--*: initial
```
重置整个主题。
在自定义CSS与内联样式中优先使用CSS变量，例如
```
var(--color-sky-500)
```
或
```
bg-(--my-color)
```
。
当主题变量引用其他变量时，使用
```
@theme inline
```
以避免意外解析问题；若希望无论是否使用都输出所有主题变量，使用
```
@theme static
```
。
v4中
```
theme()
```
已被弃用；优先使用CSS变量，仅在媒体查询等边缘场景中使用
```
theme(--breakpoint-*)
```
。

Common Patterns

常见模式

Stack variants to express state and media logic in place, for example
```
dark:md:hover:bg-sky-700
```
.
Use
```
group
```
,
```
peer
```
, and named group/peer variants for parent or sibling state, and
```
in-*
```
for implicit parent state when scoping is not required.
Use arbitrary values and variants sparingly for one-offs, for example
```
bg-[#316ff6]
```
,
```
[&.is-dragging]:cursor-grabbing
```
, and
```
text-(length:--size)
```
when ambiguous.
Build responsive layouts with
```
sm:
```
and
```
max-*
```
ranges; use
```
@container
```
with
```
@md
```
or
```
@max-md
```
for container-query components.
For dynamic values, set CSS variables inline and consume them with utilities:

堆叠变体以在标记中表达状态与媒体逻辑，例如
```
dark:md:hover:bg-sky-700
```
。
使用
```
group
```
、
```
peer
```
及命名组/对等变体处理父元素或兄弟元素状态；当无需作用域时，使用
```
in-*
```
处理隐式父元素状态。
仅在特殊场景下使用任意值与变体，例如
```
bg-[#316ff6]
```
、
```
[&.is-dragging]:cursor-grabbing
```
以及存在歧义时的
```
text-(length:--size)
```
。
使用
```
sm:
```
与
```
max-*
```
范围构建响应式布局；将
```
@container
```
与
```
@md
```
或
```
@max-md
```
结合使用，实现容器查询组件。
对于动态值，在内联中设置CSS变量并通过工具类调用：

Pitfalls

常见陷阱

Conflicting utilities target the same property; avoid combining them or use explicit conditional class selection.
```
peer
```
only affects following siblings; it cannot style elements that appear before the peer.
Parent child selectors like
```
*:
```
and
```
**:
```
cannot be overridden by child utilities due to generation order and equal specificity.
Overusing
```
@apply
```
leads to rigid abstractions; prefer components or utility composition unless you need custom CSS.
If theme variables reference other variables, prefer
```
@theme inline
```
to avoid unexpected fallback behavior.

冲突工具类会作用于同一属性；避免组合使用，或使用显式条件类选择。
```
peer
```
仅影响后续兄弟元素；无法为peer之前的元素设置样式。
像
```
*:
```
与
```
**:
```
这样的父子选择器，由于生成顺序与相同优先级，无法被子元素的工具类覆盖。
过度使用
```
@apply
```
会导致僵化的抽象层；除非需要自定义CSS，否则优先使用组件或工具类组合。
若主题变量引用其他变量，优先使用
```
@theme inline
```
以避免意外的回退行为。