Tailwind v4 踩坑记：主题变量、阴影与设计 token 的正确姿势

升级 Tailwind CSS v4 后项目出现了一堆"看起来对但就是不生效"的怪问题，复盘后总结出三个高频坑。

坑一：shadow-* 工具类不生成

v4 里，阴影这类工具类依赖 @theme 中定义的 token 才会生成。如果你只写在普通 :root 里，Tailwind 根本不会生成对应的工具类：

/* ❌ 这样写 shadow-card 不会生成 */
:root {
  --shadow-card: 0 4px 0 #000;
}

/* ✅ 必须放在 @theme inline 里 */
@theme inline {
  --shadow-card: 0 4px 0 var(--color-ink);
  --shadow-hard: 4px 4px 0 var(--color-ink);
}

症状是"卡片没有阴影、hover 像错位"——其实是类根本没进编译产物。

坑二：主题切换变量不生效

v4 的 CSS-first 配置里，:root 和 [data-theme="dark"] 的定义顺序会影响覆盖。双主题切换时，深色主题的变量要放在后面并且有足够的特异性：

:root,
[data-theme="light"] {
  --color-surface: #f4f1e6;
}

[data-theme="dark"] {
  --color-surface: #0e0d1a;
}

如果只在 .dark 类上定义，而 JS 用 data-theme 属性切换，就永远匹配不上。

坑三：oklch 与浏览器兼容

v4 默认生成 oklch 色彩。对现代浏览器没问题，但老旧客户端（尤其 Windows 7 的 Chrome）可能不支持，出现"颜色全部消失"的极端情况。

/* oklch 语法 */
--color-primary: oklch(70% 0.16 55);

/* 兼容兜底：前面写 hex，后面写 oklch 覆盖 */
--color-primary: #e8962e;
--color-primary: oklch(70% 0.16 55);

关于 @theme inline

inline 关键字的意思是把 token 值内联展开到使用处，而不是引用变量。这在两种场景下必要：

• 阴影/渐变等需要组合其它 token 的场景；
• 想让输出的 CSS 更小、不含冗余变量的场景。

@theme inline {
  --color-brand: var(--color-primary);
}

排查工具

v4 里查"类到底生没生成"最快的方式：

# 在编译后的 CSS 里搜类名
grep -o 'shadow-card' .next/static/css/*.css | head

如果编译产物里没有，基本可以断定是 token 定义位置不对。

小结

Tailwind v4 的核心变化是"CSS-first"，一切配置都在 CSS 里完成。迁移时记住三句话：

1. 工具类要生效，token 必须进 @theme；
2. 主题切换用 data-theme 属性要对应 CSS 选择器；
3. 生产环境检查编译产物，别靠"看着像生效了"。

这套博客的像素风就是 v4 落地实践，所有阴影和主题色都严格走 @theme。