Tailwind CSS 深色模式

本篇讲深色模式。Tailwind v4 用 CSS-first 方式定义深色变体，再用 dark: 前缀给元素配置暗色样式，最后在 HTML 里切换 .dark 类即可。

定义深色变体

在 @import "tailwindcss"; 之后，用 @custom-variant 声明深色策略。类策略写法如下。

@import "tailwindcss";

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

这行意思是：当元素自身或祖先带有 .dark 类时，dark: 前缀的工具类生效。这就是常见的「手动切换」方案，用户在页面上点一下就切换全站暗色。

媒体策略

如果想跟随系统设置自动切换，可以用 prefers-color-scheme 媒体查询。

@custom-variant dark (&:where([data-theme="dark"], [data-theme="dark"] *));

或者基于系统偏好：

@custom-variant dark (@media (prefers-color-scheme: dark) { &:where(...) });

本篇以更可控的类策略为主。

使用 dark: 前缀

声明之后，任何工具类前加 dark: 就会在深色模式下覆盖基础样式。

<body class="bg-white text-gray-900 dark:bg-gray-900 dark:text-gray-100">
  <h1 class="text-xl font-bold">标题</h1>
  <p class="text-gray-600 dark:text-gray-400">正文内容</p>
</body>

亮色时白底深字，深色时深底浅字。注意 dark: 要配合前面定义的 .dark 类出现才生效。

在 HTML 切换 .dark 类

深色变体取决于祖先是否有 .dark。给一小段 JS，在按钮点击时切换 <html> 上的类，并记住用户选择。

<button id="themeBtn" class="px-3 py-2 border rounded">切换主题</button>

<script>
  const btn = document.getElementById('themeBtn');
  btn.addEventListener('click', () => {
    document.documentElement.classList.toggle('dark');
    const isDark = document.documentElement.classList.contains('dark');
    localStorage.setItem('theme', isDark ? 'dark' : 'light');
  });

  if (localStorage.getItem('theme') === 'dark') {
    document.documentElement.classList.add('dark');
  }
</script>

document.documentElement 就是 <html>。切换类后，所有 dark: 样式立即生效，并写入 localStorage 记住偏好。

结合 @theme 让深色色板生效

如果自定义了主题色板，深色模式同样可以基于 @theme 的令牌来写，保持配色一致。

@import "tailwindcss";

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

@theme {
  --color-brand: #2563eb;
  --color-brand-dark: #1e40af;
}

<button class="bg-brand text-white dark:bg-brand-dark px-4 py-2 rounded">
  品牌按钮
</button>

亮色用 --color-brand，深色用 --color-brand-dark，通过 dark: 切换，主题色在全模式下都协调。

实战：可切换的卡片

综合上面内容，做一个点击切换深色的卡片。

<div class="bg-white dark:bg-gray-800 text-gray-900 dark:text-gray-100 p-6 rounded shadow max-w-sm mx-auto transition-colors">
  <h2 class="text-lg font-bold">深色模式演示</h2>
  <p class="mt-2 text-gray-600 dark:text-gray-400">点右上角按钮切换主题。</p>
  <button class="mt-4 bg-blue-500 hover:bg-blue-600 text-white px-3 py-2 rounded" onclick="document.documentElement.classList.toggle('dark')">
    切换
  </button>
</div>

transition-colors 让背景和文字颜色切换时有平滑过渡。

小结

深色模式三步：用 @custom-variant dark 定义策略，用 dark: 前缀写暗色样式，在 HTML 切换 .dark 类。可结合 @theme 统一管理色板。下一篇讲 @theme 主题定制，深入调整全站设计令牌。