Tailwind CSS v4 主题简写规范

概述

Tailwind CSS v4 中，@theme 定义的主题变量会自动生成对应的工具类。className 里直接用简写，不要写 [var(--…)] 任意值。var() 只用于普通 CSS 和内联样式。

使用场景

• 编写或清理 className 中出现 xxx-[var(--…)] 写法时
• 从 Tailwind v3 迁移到 v4 的项目
• 评审代码时判断样式写法是否符合 v4 惯例

规则

场景	写法	示例
className 工具类	✅ 简写	text-error
className 工具类	❌ 任意值	text-[var(--color-error)]
普通 CSS（globals.css 等）	✅ var()	color: var(--color-error)
JS 内联 style / 动画库	✅ var()	style={{ color: "var(--color-error)" }}

命名空间速查表

@theme 中变量按命名空间生成工具类（含 Tailwind 默认主题）：

命名空间	工具类前缀	示例
--color-*	bg- text- border- fill- outline- ring-	text-error、border-primary
--font-*	font-	font-display
--text-*	text-（字号）	text-lg
--font-weight-*	font-	font-bold
--tracking-*	tracking-	tracking-wide
--leading-*	leading-	leading-tight
--radius-*	rounded-	rounded-xl
--shadow-*	shadow-	shadow-md
--ease-*	ease-	ease-out
--breakpoint-*	响应式变体	md:flex
--spacing	间距/尺寸	px-4 max-w-md

Before / After

// ❌ 任意值包 var()（v3 习惯）
<p className="text-[var(--color-error)]">
<a className="hover:text-[var(--color-primary-hover)]">
<h1 className="leading-[var(--leading-tight)] tracking-[var(--tracking-wide)]">
<div className="border-[var(--color-primary)]">

// ✅ v4 简写
<p className="text-error">
<a className="hover:text-primary-hover">
<h1 className="leading-tight tracking-wide">
<div className="border-primary">

常见误区

• 带连字符的名字直接拼：--color-primary-hover → hover:text-primary-hover，不需要拆开或转义。
• 默认主题命名空间仍可用：@theme 扩展（不加 --xxx-*: initial）时，tracking-wide、leading-tight、md: 等默认工具类照常可用。
• 变量不在 @theme 里 → 没有工具类：设计令牌应放进 @theme；普通业务变量放 :root，只能用 var()。
• 复杂计算仍用任意值：如 rounded-[calc(var(--radius-xl)-1px)]，涉及 calc() 组合时任意值是正确用法。
• 普通 CSS 里不要强行套工具类：globals.css 的 @layer base 中直接写 var(--color-paper) 是规范用法。