tailwind-v4-best-practices

Tailwind CSS v4 最佳实践

面向生产环境的 Tailwind CSS v4，注重设计系统思维、可维护性和性能。

核心原则

1. 使用设计令牌，而非直接指定颜色

使用语义令牌，而非 Tailwind 的默认调色板。这样无需修改组件即可切换主题。

<button class="bg-blue-500 text-white hover:bg-blue-600">
<span class="text-red-600">Error</span>


<button class="bg-primary text-primary-foreground hover:bg-primary-hover">
<span class="text-error">Error</span>

2. 优先使用语义化工具类，而非任意值

使用内置的取值范围。仅在确实需要个别特殊值时使用任意值。

<h1 class="text-[20px]">
<div class="p-[16px] gap-[24px]">


<h1 class="text-2xl">
<div class="p-4 gap-6">

3. 只使用完整的类名

Tailwind 编译器需要在构建时获取完整的类名。不要动态构造类名。

// ❌ Tailwind can't detect these
<div className={`bg-${color}-500`}>

// ✅ Complete class names or CSS variables
<div className={color === 'blue' ? 'bg-blue-500' : 'bg-red-500'}>
<div className="bg-[var(--dynamic-color)]">

4. 避免使用 @apply

Tailwind v4 不建议使用 @apply。请直接在模板中使用工具类，或者在需要自定义组件类时于 CSS 中使用 theme()。

/* ❌ v3 pattern */
.button { @apply px-4 py-2 bg-blue-500 text-white rounded; }

/* ✅ v4 — use theme() if you need CSS */
.button {
  padding-inline: theme(spacing.4);
  background-color: theme(colors.primary);
}

@theme 配置

Tailwind v4 将配置从 JavaScript 移至 CSS。使用 @theme 定义设计令牌：

@import "tailwindcss";

@theme {
  /* Semantic colors using OKLCH */
  --color-primary: oklch(0.55 0.25 250);
  --color-primary-hover: oklch(0.50 0.25 250);
  --color-primary-foreground: oklch(0.98 0 0);

  --color-error: oklch(0.60 0.22 25);
  --color-success: oklch(0.65 0.18 145);

  /* Surface colors */
  --color-background: oklch(1.0 0 0);
  --color-foreground: oklch(0.20 0.01 250);
  --color-surface: oklch(0.98 0.01 250);
  --color-border: oklch(0.90 0.01 250);

  /* Typography */
  --font-family-heading: "Inter", sans-serif;
  --font-family-body: "Inter", sans-serif;
  --font-family-mono: "Fira Code", monospace;
}

完整的令牌架构（基础层 → 语义层 → 组件层）请参阅 references/design-tokens.md。

OKLCH 颜色

Tailwind v4 默认使用 OKLCH，以获得更好的感知均匀性。

oklch(lightness chroma hue / alpha)

• 明度：0（黑色）到 1（白色）
• 色度：0（灰色）到约 0.4（鲜艳）
• 色相：0–360 度
• 透明度：0–1（可选）

--color-brand: oklch(0.55 0.25 270);      /* vivid purple */
--color-subtle: oklch(0.96 0.02 250);     /* muted gray */
--color-overlay: oklch(0.0 0 0 / 0.5);   /* translucent black */

v3 → v4 类名更改

v3                     →  v4
───────────────────────────────
bg-gradient-to-r       →  bg-linear-to-r
bg-gradient-to-br      →  bg-linear-to-br
flex-shrink-0          →  shrink-0
flex-grow              →  grow
decoration-clone       →  box-decoration-clone
decoration-slice       →  box-decoration-slice

运行自动升级命令：npx @tailwindcss/upgrade

Vite 配置（最快）

import tailwindcss from '@tailwindcss/vite'

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

v4 会自动检测内容，无需配置内容路径。生产环境中会自动通过树摇移除未使用的工具类。

参考资料

仅加载当前任务所需的内容：

参考资料	加载时机
design-tokens.md	设置令牌架构、组件令牌和状态颜色模式时
theming.md	配置深色模式、运行时主题切换、品牌变体和用户偏好检测时
advanced-patterns.md	使用动画、网格布局、容器查询、自定义工具类、插件和性能优化时
migration.md	将项目从 Tailwind v3 迁移到 v4 时