tailwind-patterns

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Tailwind CSS Patterns (v4 - 2025)

Tailwind CSS 布局模式（v4 - 2025）

Modern utility-first CSS with CSS-native configuration.

基于CSS原生配置的现代实用优先CSS框架。

1. Tailwind v4 Architecture

1. Tailwind v4 架构

What Changed from v3

与v3版本的主要变化

v3 (Legacy)	v4 (Current)
`tailwind.config.js`	CSS-based `@theme` directive
PostCSS plugin	Oxide engine (10x faster)
JIT mode	Native, always-on
Plugin system	CSS-native features
`@apply` directive	Still works, discouraged

v3（旧版）	v4（当前版）
`tailwind.config.js`	基于CSS的 `@theme` 指令
PostCSS 插件	Oxide 引擎（速度提升10倍）
JIT 模式	原生内置、始终启用
插件系统	CSS原生特性
`@apply` 指令	仍可使用，但不推荐

v4 Core Concepts

v4 核心概念

Concept	Description
CSS-first	Configuration in CSS, not JavaScript
Oxide Engine	Rust-based compiler, much faster
Native Nesting	CSS nesting without PostCSS
CSS Variables	All tokens exposed as `--*` vars

概念	描述
CSS优先	配置在CSS中完成，而非JavaScript
Oxide 引擎	基于Rust的编译器，速度大幅提升
原生嵌套	无需PostCSS即可实现CSS嵌套
CSS Variables	所有令牌均以 `--*` 变量形式暴露

2. CSS-Based Configuration

2. 基于CSS的配置

Theme Definition

主题定义

@theme {
  /* Colors - use semantic names */
  --color-primary: oklch(0.7 0.15 250);
  --color-surface: oklch(0.98 0 0);
  --color-surface-dark: oklch(0.15 0 0);
  
  /* Spacing scale */
  --spacing-xs: 0.25rem;
  --spacing-sm: 0.5rem;
  --spacing-md: 1rem;
  --spacing-lg: 2rem;
  
  /* Typography */
  --font-sans: 'Inter', system-ui, sans-serif;
  --font-mono: 'JetBrains Mono', monospace;
}

@theme {
  /* Colors - use semantic names */
  --color-primary: oklch(0.7 0.15 250);
  --color-surface: oklch(0.98 0 0);
  --color-surface-dark: oklch(0.15 0 0);
  
  /* Spacing scale */
  --spacing-xs: 0.25rem;
  --spacing-sm: 0.5rem;
  --spacing-md: 1rem;
  --spacing-lg: 2rem;
  
  /* Typography */
  --font-sans: 'Inter', system-ui, sans-serif;
  --font-mono: 'JetBrains Mono', monospace;
}

When to Extend vs Override

扩展与覆盖的适用场景

Action	Use When
Extend	Adding new values alongside defaults
Override	Replacing default scale entirely
Semantic tokens	Project-specific naming (primary, surface)

操作	适用场景
扩展	在默认值基础上添加新值
覆盖	完全替换默认的比例体系
语义令牌	项目专属命名（如primary、surface）

3. Container Queries (v4 Native)

3. 容器查询（v4 原生支持）

Breakpoint vs Container

断点与容器的区别

Type	Responds To
Breakpoint ( `md:` )	Viewport width
Container ( `@container` )	Parent element width

类型	响应对象
断点（ `md:` ）	视口宽度
容器（ `@container` ）	父元素宽度

Container Query Usage

容器查询用法

Pattern	Classes
Define container	`@container` on parent
Container breakpoint	`@sm:` , `@md:` , `@lg:` on children
Named containers	`@container/card` for specificity

模式	类名
定义容器	在父元素上使用 `@container`
容器断点	在子元素上使用 `@sm:` 、 `@md:` 、 `@lg:`
命名容器	使用 `@container/card` 以提高特异性

When to Use

适用场景

Scenario	Use
Page-level layouts	Viewport breakpoints
Component-level responsive	Container queries
Reusable components	Container queries (context-independent)

场景	选择方案
页面级布局	视口断点
组件级响应式	容器查询
可复用组件	容器查询（与上下文无关）

4. Responsive Design

4. 响应式设计

Breakpoint System

断点系统

Prefix	Min Width	Target
(none)	0px	Mobile-first base
`sm:`	640px	Large phone / small tablet
`md:`	768px	Tablet
`lg:`	1024px	Laptop
`xl:`	1280px	Desktop
`2xl:`	1536px	Large desktop

前缀	最小宽度	目标设备
（无）	0px	移动端优先基础样式
`sm:`	640px	大屏手机/小平板
`md:`	768px	平板
`lg:`	1024px	笔记本电脑
`xl:`	1280px	桌面端
`2xl:`	1536px	大屏桌面端

Mobile-First Principle

移动端优先原则

Write mobile styles first (no prefix)
Add larger screen overrides with prefixes
Example:
```
w-full md:w-1/2 lg:w-1/3
```

先编写移动端样式（无前缀）
使用前缀添加大屏设备的覆盖样式
示例：
```
w-full md:w-1/2 lg:w-1/3
```

5. Dark Mode

5. 暗黑模式

Configuration Strategies

配置策略

Method	Behavior	Use When
`class`	`.dark` class toggles	Manual theme switcher
`media`	Follows system preference	No user control
`selector`	Custom selector (v4)	Complex theming

方法	行为	适用场景
`class`	通过 `.dark` 类切换	手动主题切换器
`media`	跟随系统偏好设置	无需用户控制
`selector`	自定义选择器（v4新增）	复杂主题配置

Dark Mode Pattern

暗黑模式实现模式

Element	Light	Dark
Background	`bg-white`	`dark:bg-zinc-900`
Text	`text-zinc-900`	`dark:text-zinc-100`
Borders	`border-zinc-200`	`dark:border-zinc-700`

元素	亮色模式	暗色模式
背景	`bg-white`	`dark:bg-zinc-900`
文本	`text-zinc-900`	`dark:text-zinc-100`
边框	`border-zinc-200`	`dark:border-zinc-700`

6. Modern Layout Patterns

6. 现代布局模式

Flexbox Patterns

Flexbox 布局模式

Pattern	Classes
Center (both axes)	`flex items-center justify-center`
Vertical stack	`flex flex-col gap-4`
Horizontal row	`flex gap-4`
Space between	`flex justify-between items-center`
Wrap grid	`flex flex-wrap gap-4`

模式	类名
居中对齐（双轴）	`flex items-center justify-center`
垂直堆叠	`flex flex-col gap-4`
水平排列	`flex gap-4`
两端对齐	`flex justify-between items-center`
自动换行网格	`flex flex-wrap gap-4`

Grid Patterns

Grid 布局模式

Pattern	Classes
Auto-fit responsive	`grid grid-cols-[repeat(auto-fit,minmax(250px,1fr))]`
Asymmetric (Bento)	`grid grid-cols-3 grid-rows-2` with spans
Sidebar layout	`grid grid-cols-[auto_1fr]`

Note: Prefer asymmetric/Bento layouts over symmetric 3-column grids.

模式	类名
自适应响应式	`grid grid-cols-[repeat(auto-fit,minmax(250px,1fr))]`
非对称布局（Bento）	`grid grid-cols-3 grid-rows-2` 配合跨度属性
侧边栏布局	`grid grid-cols-[auto_1fr]`

注意： 优先使用非对称/Bento布局，而非对称的3列网格。

7. Modern Color System

7. 现代色彩系统

OKLCH vs RGB/HSL

OKLCH 与 RGB/HSL 的对比

Format	Advantage
OKLCH	Perceptually uniform, better for design
HSL	Intuitive hue/saturation
RGB	Legacy compatibility

格式	优势
OKLCH	感知均匀，更适合设计
HSL	色相/饱和度更直观
RGB	兼容旧系统

Color Token Architecture

色彩令牌架构

Layer	Example	Purpose
Primitive	`--blue-500`	Raw color values
Semantic	`--color-primary`	Purpose-based naming
Component	`--button-bg`	Component-specific

层级	示例	用途
基础层	`--blue-500`	原始色彩值
语义层	`--color-primary`	基于用途的命名
组件层	`--button-bg`	组件专属令牌

8. Typography System

8. 排版系统

Font Stack Pattern

字体栈推荐

Type	Recommended
Sans	`'Inter', 'SF Pro', system-ui, sans-serif`
Mono	`'JetBrains Mono', 'Fira Code', monospace`
Display	`'Outfit', 'Poppins', sans-serif`

类型	推荐方案
Sans	`'Inter', 'SF Pro', system-ui, sans-serif`
Mono	`'JetBrains Mono', 'Fira Code', monospace`
Display	`'Outfit', 'Poppins', sans-serif`

Type Scale

字体大小体系

Class	Size	Use
`text-xs`	0.75rem	Labels, captions
`text-sm`	0.875rem	Secondary text
`text-base`	1rem	Body text
`text-lg`	1.125rem	Lead text
`text-xl` +	1.25rem+	Headings

类名	大小	用途
`text-xs`	0.75rem	标签、说明文字
`text-sm`	0.875rem	次要文本
`text-base`	1rem	正文文本
`text-lg`	1.125rem	引导文本
`text-xl` +	1.25rem+	标题

9. Animation & Transitions

9. 动画与过渡

Built-in Animations

内置动画

Class	Effect
`animate-spin`	Continuous rotation
`animate-ping`	Attention pulse
`animate-pulse`	Subtle opacity pulse
`animate-bounce`	Bouncing effect

类名	效果
`animate-spin`	持续旋转
`animate-ping`	脉冲提醒
`animate-pulse`	微妙的透明度脉冲
`animate-bounce`	弹跳效果

Transition Patterns

过渡模式

Pattern	Classes
All properties	`transition-all duration-200`
Specific	`transition-colors duration-150`
With easing	`ease-out` or `ease-in-out`
Hover effect	`hover:scale-105 transition-transform`

模式	类名
所有属性过渡	`transition-all duration-200`
指定属性过渡	`transition-colors duration-150`
缓动效果	`ease-out` 或 `ease-in-out`
悬停效果	`hover:scale-105 transition-transform`

10. Component Extraction

10. 组件提取

When to Extract

提取时机

Signal	Action
Same class combo 3+ times	Extract component
Complex state variants	Extract component
Design system element	Extract + document

信号	操作
相同类组合出现3次以上	提取为组件
包含复杂状态变体	提取为组件
属于设计系统元素	提取并文档化

Extraction Methods

提取方法

Method	Use When
React/Vue component	Dynamic, JS needed
@apply in CSS	Static, no JS needed
Design tokens	Reusable values

方法	适用场景
React/Vue 组件	需要动态逻辑或JavaScript支持
CSS 中使用 `@apply`	静态样式，无需JavaScript
设计令牌	可复用的样式值

11. Anti-Patterns

11. 反模式

Don't	Do
Arbitrary values everywhere	Use design system scale
`!important`	Fix specificity properly
Inline `style=`	Use utilities
Duplicate long class lists	Extract component
Mix v3 config with v4	Migrate fully to CSS-first
Use `@apply` heavily	Prefer components

不推荐做法	推荐做法
大量使用任意值	使用设计系统的比例体系
使用 `!important`	正确修复特异性问题
使用内联 `style=`	使用实用类
重复冗长的类列表	提取为组件
混合使用v3与v4配置	完全迁移到CSS优先的配置方式
大量使用 `@apply`	优先使用组件

12. Performance Principles

12. 性能优化原则

Principle	Implementation
Purge unused	Automatic in v4
Avoid dynamism	No template string classes
Use Oxide	Default in v4, 10x faster
Cache builds	CI/CD caching

Remember: Tailwind v4 is CSS-first. Embrace CSS variables, container queries, and native features. The config file is now optional.

原则	实现方式
清除未使用样式	v4 自动完成
避免动态类名	不使用模板字符串生成类名
使用Oxide引擎	v4 默认启用，速度提升10倍
缓存构建结果	在CI/CD中配置缓存

记住： Tailwind v4 是CSS优先的框架。拥抱CSS变量、容器查询和原生特性。配置文件现在是可选的。