[!info] related notes

• 所属：设计系统
• 相关：变体 · CSS 变量

Tailwind 暗色模式

这个概念为什么出现

系统偏好与产品内开关是两套需求。策略选错会出现“跟系统走不了”或“跟开关冲突”。

[!abstract] 一句话理解 dark: 为工具类附加激活条件，不会自动反色；默认条件是系统的 prefers-color-scheme: dark。

示例

<div class="bg-white text-slate-900 dark:bg-slate-900 dark:text-slate-100">
  库存看板
</div>

版本与手动开关

Tailwind v4 可覆盖默认 dark 变体，让祖先元素上的 .dark 控制样式：

@import "tailwindcss";
@custom-variant dark (&:where(.dark, .dark *));

在 <html class="dark"> 下，上方 dark:* 类生效；移除 .dark 后恢复普通类。也可使用 data-theme 选择器。仅往 HTML 添加 .dark，而不配置变体，不能覆盖默认系统策略。

v3 项目使用该版本的 darkMode 配置（早期常见 class，v3.4.1 起文档推荐 selector）；不要把 v4 指令直接放进 v3 项目。

实践

1. 明确采用系统偏好还是手动选择器；“亮 / 暗 / 跟随系统”三态还需应用处理偏好保存与系统变化
2. 颜色走 token，不硬编码两套散装 hex
3. 对比度与状态色同步验收

本节总结

暗色是设计系统能力，不是最后加一个反色。

自测题

1. class 策略的好处？

参考答案

配置手动选择器后，产品可以控制暗色激活；跟随系统、持久化与首次绘制前的初始化仍需应用实现。

参考

• Tailwind v4 Dark mode
• Tailwind v3 Dark mode