tailwind-v4

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Tailwind CSS v4 Best Practices

Tailwind CSS v4 最佳实践

Quick Reference

快速参考

Vite Plugin Setup:

// vite.config.ts
import tailwindcss from '@tailwindcss/vite';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [tailwindcss()],
});

CSS Entry Point:

css

/* src/index.css */
@import 'tailwindcss';

@theme Inline Directive:

css

@theme inline {
  --color-primary: oklch(60% 0.24 262);
  --color-surface: oklch(98% 0.002 247);
}

Vite 插件配置:

// vite.config.ts
import tailwindcss from '@tailwindcss/vite';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [tailwindcss()],
});

CSS 入口文件:

css

/* src/index.css */
@import 'tailwindcss';

@theme 内联指令:

css

@theme inline {
  --color-primary: oklch(60% 0.24 262);
  --color-surface: oklch(98% 0.002 247);
}

Key Differences from v3

与v3的主要差异

Feature	v3	v4
Configuration	tailwind.config.js	@theme in CSS
Build Tool	PostCSS plugin	@tailwindcss/vite
Colors	rgb() / hsl()	oklch() (default)
Theme Extension	extend: {} in JS	CSS variables
Dark Mode	darkMode config option	CSS variants

特性	v3	v4
配置方式	tailwind.config.js	CSS中的@theme指令
构建工具	PostCSS插件	@tailwindcss/vite
颜色格式	rgb() / hsl()	默认使用oklch()
主题扩展	JS中的extend: {}	CSS变量
暗黑模式	darkMode配置项	CSS变体

@theme Directive Modes

@theme 指令模式

default (standard mode)

default（标准模式）

Generates CSS variables that can be referenced elsewhere:

css

@theme {
  --color-brand: oklch(60% 0.24 262);
}

/* Generates: :root { --color-brand: oklch(...); } */
/* Usage: text-brand → color: var(--color-brand) */

Note: You can also use

@theme default

explicitly to mark theme values that can be overridden by non-default @theme declarations.

生成可在其他地方引用的CSS变量:

css

@theme {
  --color-brand: oklch(60% 0.24 262);
}

/* 生成结果: :root { --color-brand: oklch(...); } */
/* 使用方式: text-brand → color: var(--color-brand) */

注意: 你也可以显式使用

@theme default

来标记可被非默认@theme声明覆盖的主题值。

inline

Inlines values directly without CSS variables (better performance):

css

@theme inline {
  --color-brand: oklch(60% 0.24 262);
}

/* Usage: text-brand → color: oklch(60% 0.24 262) */

直接内联值，不使用CSS变量（性能更优）:

css

@theme inline {
  --color-brand: oklch(60% 0.24 262);
}

/* 使用方式: text-brand → color: oklch(60% 0.24 262) */

reference

Inlines values as fallbacks without emitting CSS variables:

css

@theme reference {
  --color-internal: oklch(50% 0.1 180);
}

/* No :root variable, but utilities use fallback */
/* Usage: bg-internal → background-color: var(--color-internal, oklch(50% 0.1 180)) */

将值作为回退内联，不生成CSS变量:

css

@theme reference {
  --color-internal: oklch(50% 0.1 180);
}

/* 不会生成:root变量，但工具类会使用回退值 */
/* 使用方式: bg-internal → background-color: var(--color-internal, oklch(50% 0.1 180)) */

OKLCH Color Format

OKLCH 颜色格式

OKLCH provides perceptually uniform colors with better consistency across hues:

css

oklch(L% C H)

L (Lightness): 0% (black) to 100% (white)
C (Chroma): 0 (gray) to ~0.4 (vibrant)
H (Hue): 0-360 degrees (red → yellow → green → blue → magenta)

Examples:

css

--color-sky-500: oklch(68.5% 0.169 237.323);  /* Bright blue */
--color-red-600: oklch(57.7% 0.245 27.325);   /* Vibrant red */
--color-zinc-900: oklch(21% 0.006 285.885);   /* Near-black gray */

OKLCH提供感知均匀的颜色，在不同色调间具有更好的一致性:

css

oklch(L% C H)

L（亮度）: 0%（黑色）到100%（白色）
C（色度）: 0（灰色）到约0.4（鲜艳色）
H（色相）: 0-360度（红→黄→绿→蓝→品红）

示例:

css

--color-sky-500: oklch(68.5% 0.169 237.323);  /* 亮蓝色 */
--color-red-600: oklch(57.7% 0.245 27.325);   /* 鲜艳红色 */
--color-zinc-900: oklch(21% 0.006 285.885);   /* 近黑灰色 */

CSS Variable Naming

CSS 变量命名规范

Tailwind v4 uses double-dash CSS variable naming conventions:

css

@theme {
  /* Colors: --color-{name}-{shade} */
  --color-primary-500: oklch(60% 0.24 262);

  /* Spacing: --spacing multiplier */
  --spacing: 0.25rem;  /* Base unit for spacing scale */

  /* Fonts: --font-{family} */
  --font-display: 'Inter Variable', system-ui, sans-serif;

  /* Breakpoints: --breakpoint-{size} */
  --breakpoint-lg: 64rem;

  /* Custom animations: --animate-{name} */
  --animate-fade-in: fade-in 0.3s ease-out;
}

Tailwind v4使用双连字符CSS变量命名约定:

css

@theme {
  /* 颜色: --color-{名称}-{色调} */
  --color-primary-500: oklch(60% 0.24 262);

  /* 间距: --spacing 乘数 */
  --spacing: 0.25rem;  /* 间距刻度的基础单位 */

  /* 字体: --font-{字体族} */
  --font-display: 'Inter Variable', system-ui, sans-serif;

  /* 断点: --breakpoint-{尺寸} */
  --breakpoint-lg: 64rem;

  /* 自定义动画: --animate-{名称} */
  --animate-fade-in: fade-in 0.3s ease-out;
}

No Config Files Needed

无需配置文件

Tailwind v4 eliminates configuration files:

No
tailwind.config.js
- Use @theme in CSS instead
No
postcss.config.js
- Use @tailwindcss/vite plugin
TypeScript support - Add
```
@types/node
```
for path resolution

json

{
  "devDependencies": {
    "@tailwindcss/vite": "^4.0.0",
    "@types/node": "^22.0.0",
    "tailwindcss": "^4.0.0",
    "vite": "^6.0.0"
  }
}

Tailwind v4不再需要配置文件:

无
tailwind.config.js
- 改用CSS中的@theme指令
无
postcss.config.js
- 使用@tailwindcss/vite插件
TypeScript 支持 - 添加
```
@types/node
```
用于路径解析

json

{
  "devDependencies": {
    "@tailwindcss/vite": "^4.0.0",
    "@types/node": "^22.0.0",
    "tailwindcss": "^4.0.0",
    "vite": "^6.0.0"
  }
}

Progressive Disclosure

进阶指南

Setup & Installation: See references/setup.md for Vite plugin configuration, package setup, TypeScript config
Theming & Design Tokens: See references/theming.md for @theme modes, color palettes, custom fonts, animations
Dark Mode Strategies: See references/dark-mode.md for media queries, class-based, attribute-based approaches

搭建与安装: 查看references/setup.md了解Vite插件配置、包安装、TypeScript配置
主题与设计令牌: 查看references/theming.md了解@theme模式、调色板、自定义字体、动画
暗黑模式策略: 查看references/dark-mode.md了解媒体查询、基于类、基于属性的实现方式

Decision Guide

决策指南

When to use @theme inline vs default

何时使用@theme inline vs default

Use
@theme inline
:

Better performance (no CSS variable overhead)
Static color values that won't change
Animation keyframes with multiple values
Utilities that need direct value inlining

Use
@theme
(default):

Dynamic theming with JavaScript
CSS variable references in custom CSS
Values that change based on context
Better debugging (inspect CSS variables in DevTools)

使用
@theme inline
的场景:

性能更优（无CSS变量开销）
不会变化的静态颜色值
包含多个值的动画关键帧
需要直接内联值的工具类

使用
@theme
（默认）的场景:

结合JavaScript实现动态主题
自定义CSS中需要引用CSS变量
值会随上下文变化
更便于调试（可在开发者工具中查看CSS变量）

When to use @theme reference

何时使用@theme reference

Use
@theme reference
:

Provide fallback values without CSS variable overhead
Values that should work even if variable isn't defined
Reducing :root bloat while maintaining utility support
Combining with inline for direct value substitution

使用
@theme reference
的场景:

提供回退值且不产生CSS变量开销
即使变量未定义也能正常工作的值
减少:root的代码冗余同时保留工具类支持
与inline结合实现直接值替换

Common Patterns

常见模式

Two-Tier Variable System

双层变量系统

Semantic variables that map to design tokens:

css

@theme {
  /* Design tokens (OKLCH colors) */
  --color-blue-600: oklch(54.6% 0.245 262.881);
  --color-slate-800: oklch(27.9% 0.041 260.031);

  /* Semantic mappings */
  --color-primary: var(--color-blue-600);
  --color-surface: var(--color-slate-800);
}

/* Usage: bg-primary, bg-surface */

映射到设计令牌的语义化变量:

css

@theme {
  /* 设计令牌（OKLCH颜色） */
  --color-blue-600: oklch(54.6% 0.245 262.881);
  --color-slate-800: oklch(27.9% 0.041 260.031);

  /* 语义化映射 */
  --color-primary: var(--color-blue-600);
  --color-surface: var(--color-slate-800);
}

/* 使用方式: bg-primary, bg-surface */

Custom Font Configuration

自定义字体配置

css

@theme {
  --font-display: 'Inter Variable', system-ui, sans-serif;
  --font-mono: 'JetBrains Mono', ui-monospace, monospace;

  --font-display--font-variation-settings: 'wght' 400;
  --font-display--font-feature-settings: 'cv02', 'cv03', 'cv04';
}

/* Usage: font-display, font-mono */

css

@theme {
  --font-display: 'Inter Variable', system-ui, sans-serif;
  --font-mono: 'JetBrains Mono', ui-monospace, monospace;

  --font-display--font-variation-settings: 'wght' 400;
  --font-display--font-feature-settings: 'cv02', 'cv03', 'cv04';
}

/* 使用方式: font-display, font-mono */

Animation Keyframes

动画关键帧

css

@theme inline {
  --animate-beacon: beacon 2s ease-in-out infinite;

  @keyframes beacon {
    0%, 100% {
      opacity: 1;
      transform: scale(1);
    }
    50% {
      opacity: 0.5;
      transform: scale(1.05);
    }
  }
}

/* Usage: animate-beacon */

css

@theme inline {
  --animate-beacon: beacon 2s ease-in-out infinite;

  @keyframes beacon {
    0%, 100% {
      opacity: 1;
      transform: scale(1);
    }
    50% {
      opacity: 0.5;
      transform: scale(1.05);
    }
  }
}

/* 使用方式: animate-beacon */