[!info] related notes

• 所属：设计系统
• 相关：命名约定 · CSS 变量

Tailwind 主题与设计 Token

这个概念为什么出现

品牌色与间距需要共享命名才能统一调整。任意值适合少数局部例外，反复复制同一个设计值时应考虑 token。

[!abstract] 一句话理解 theme/token 是设计系统配置面；业务优先写 bg-brand-600 而不是裸 hex。

v4 定义与使用

@import "tailwindcss";
@theme {
  --color-brand-600: #059669;
  --radius-card: 0.75rem;
}

源码中使用 bg-brand-600 rounded-card，Tailwind 才会生成对应工具类。普通 :root 变量不会仅因存在就自动变成工具类；@theme 通过规定的命名空间声明这些工具类的设计值。

运行时主题可将语义 token 映射到普通 CSS 变量：

:root { --app-surface: #ffffff; }
[data-theme="dark"] { --app-surface: #0f172a; }
@theme inline {
  --color-surface: var(--app-surface);
}

bg-surface 使用当前作用域的 --app-surface。inline 让生成的工具类直接引用映射值，避免中间变量的解析作用域造成意外；这与 dark: 变体的激活配置是两件事。

v3 与实践

v3 通常在 tailwind.config.js 的 theme.extend 扩展主题；上面的 CSS-first 指令属于 v4，不是 v3 配置的同义写法。

实践

• 按版本对应的配置方式定义颜色、间距、圆角和字号
• 命名遵循团队约定
• 可映射到 CSS 变量做运行时主题
• 任意值 [] 当逃逸舱而非主路

本节总结

先 token，后页面；utility 调用 token，不发明私有色。

自测题

1. 为什么任意值应少用？

参考答案

绕过 scale 会导致不一致与难收敛；设计审查更困难。

参考

• Tailwind v4 Theme variables