#三种做法,三种代价

给一个站点加暗色模式,通常会在网上找到三种方案。

方案一:只跟随系统。

CSS
@media (prefers-color-scheme: dark) {
  body { background: #111; color: #eee; }
}

五分钟能做完,但用户没法覆盖——系统是深色你就必须是深色。对于「晚上看文档想调亮一点」这种需求,它无能为力。

方案二:根节点加 class。

CSS
.dark body { background: #111; color: #eee; }

可以手动切换,但每个选择器都要写成两份。主题越多,组合爆炸越严重。

方案三:语义化变量 + 一层切换。

CSS
:root { --bg: #fff; --text: #111925; }
[data-theme='dark'] { --bg: #0e1116; --text: #e9edf3; }
body { background: var(--bg); color: var(--text); }

组件只写一次,主题只是换一组变量值。这是唯一能长期维护的方案,也是本文的重点。

#关键不是颜色,是命名

大部分人第一次做主题会这样命名:

CSS
:root {
  --white: #ffffff;
  --gray-1: #f1f1f2;
  --gray-9: #111925;
  --yellow: #ffd000;
}

然后写 background: var(--white)。到了暗色主题,问题来了:深色背景下 --white 应该变成 #0e1116,可变量名叫 white。你等于在说谎,而且每个使用点都要重新判断该用哪个色阶。

正确的做法是按用途命名,不按色值命名:

CSS
:root {
  --bg: #ffffff;          /* 页面底色 */
  --bg-soft: #fafafa;     /* 次级区块 */
  --card: #ffffff;        /* 卡片 */
  --text: #111925;        /* 主文本 */
  --text-2: rgba(17, 25, 37, 0.85);  /* 正文 */
  --text-3: rgba(17, 25, 37, 0.65);  /* 辅助信息 */
  --text-4: rgba(17, 25, 37, 0.45);  /* 时间、计数 */
  --line: rgba(17, 25, 37, 0.07);    /* 分隔线 */
  --accent: #ffd000;
}

在暗色里,前四个色的值全换掉,但语义结构完全不变:

CSS
[data-theme='dark'] {
  --bg: #0e1116;
  --bg-soft: #14181e;
  --card: #161b22;
  --text: #e9edf3;
  --text-2: rgba(233, 237, 243, 0.86);
  --text-3: rgba(233, 237, 243, 0.62);
  --text-4: rgba(233, 237, 243, 0.42);
  --line: rgba(255, 255, 255, 0.08);
}

注意我用的不是纯白和纯黑。深色界面里 #fff 的文字在 OLED 上会「发光」,刺眼且边缘发虚;#e9edf3 这种带一点冷调的白,看起来舒服得多。同理,纯黑背景会让阴影完全失去层次,#0e1116 留了一点点亮度,卡片才能靠明度差浮起来。

#透明度比灰阶更可靠

浅色主题里的辅助文字,我原本写的是 #8a8f99 这样的具体灰。切到暗色后发现一个问题:同一个灰值在不同底色上的对比度表现完全不同。

改成 rgba(17, 25, 37, 0.65) 之后,文字会自然地「融进」底色——底色变了,混合结果自动跟着变。代价是可预测性下降(你无法一眼算出最终颜色),收益是主题切换时不用逐个微调。

一个实用的分档:

变量 透明度 用途
--text-2 0.85 长段落正文
--text-3 0.65 摘要、元信息
--text-4 0.45 时间戳、计数、占位符
--line 0.07 分隔线、边框

低于 0.4 的文字在深色背景上会开始「脏」,高于 0.9 又和主文本抢层级。0.65 这个位置几乎是万金油。

#切换时机:别让页面闪一下

最常见的问题:用户选过暗色,刷新页面时先闪一下白。

原因很直白——CSS 是异步加载的,脚本又放在 </body> 前,等主题生效时首屏已经画完了。解决办法是在 <head> 里塞一段同步脚本,在首次绘制之前把属性写好:

HTML
<script>
  try {
    var saved = localStorage.getItem('cb-theme');
    if (saved === 'dark' || (!saved && matchMedia('(prefers-color-scheme: dark)').matches)) {
      document.documentElement.dataset.theme = 'dark';
    }
  } catch (e) {}
</script>

三个要点:

  1. 放在 <head> 里,且不要加 defer;
  2. 用 try/catch 包住——Safari 无痕模式下 localStorage 会直接抛错;
  3. 判断逻辑必须是「用户选择 > 系统偏好 > 默认浅色」。

切换按钮本身只做一件事:

JavaScript
themeBtn.addEventListener('click', () => {
  const next = document.documentElement.dataset.theme === 'dark' ? 'light' : 'dark';
  document.documentElement.dataset.theme = next;
  localStorage.setItem('cb-theme', next);
});

#那些不会自动适配的东西

变量能解决 80% 的问题,剩下 20% 需要单独处理。

阴影。 浅色下 0 8px 24px rgba(0,0,0,.12) 很自然,暗色下这个阴影几乎看不见,而且会让卡片边缘发灰。我的做法是把阴影也变成变量,暗色版本加大不透明度:

CSS
--shadow-md: 0 12px 32px -16px rgba(0, 0, 0, 0.28);  /* light */
--shadow-md: 0 12px 32px -16px rgba(0, 0, 0, 0.8);   /* dark  */

图片。 截图里的白底在深色模式下像一块发光的板子。有两种缓解手段:给图片加 filter: brightness(.9)(会失真,慎用),或者给容器加一层深色描边:

CSS
.post-content img {
  border: 1px solid var(--line);
  border-radius: 6px;
}

原生控件。 滚动条、输入框、下拉箭头都是浏览器画的。一行 color-scheme 能让它们跟着变:

CSS
:root { color-scheme: light; }
[data-theme='dark'] { color-scheme: dark; }

这行几乎零成本,但少了它,暗色页面里的输入框会是刺眼的白色。

代码高亮。 代码块通常自带一套固定背景。最省事的策略是两套主题共用一套暗色代码样式——在浅色页面里,深色代码块本来就是常见设计(GitHub 也这么做),不需要为它单独做适配。

#过渡动画要克制

给 body 加 transition: background-color .2s 是加分项,但不要写成 transition: all。all 会让布局属性也参与过渡,切换主题的瞬间可能出现文字位移、边框抖动。

CSS
body {
  transition: background-color 0.2s cubic-bezier(0.22, 0.61, 0.36, 1),
              color 0.2s cubic-bezier(0.22, 0.61, 0.36, 1);
}

还有一个必须处理的边界:系统设置了「减少动态效果」的用户。

CSS
@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after { transition-duration: 0.01ms !important; }
}

#小结

三件事按重要性排序:

  1. 变量按语义命名,主题只是一组值的替换;
  2. 首屏同步脚本书写主题,否则一定有闪烁;
  3. 把阴影、图片描边、color-scheme 一起纳入主题,否则总有一两处「忘了改」。

做完这三步,暗色模式就不再是一个功能,而是设计系统里一个自然的维度。