跳到正文

暗色模式不是加个 dark: 前缀

设计约 7 分钟3 次阅读

很多人以为暗色模式就是把 bg-white 改成 bg-white dark:bg-gray-900,一路加下去就完事了。

我给这个博客做暗色模式的时候,踩到五个坑,没有一个是「忘了加 dark: 前缀」。它们都指向同一件事:暗色模式暴露的不是配色问题,是你的样式有没有单一事实来源。

一、内联样式没有 dark: 可加

<time style={{ fontSize: 12, color: "#bbb" }}>{formatDay(date)}</time>

归档页的时间戳是这么写的。#bbb 在浅色背景上是恰当的次级灰,在深色背景上几乎不可见。

问题是你没法补救——dark: 是 Tailwind 的变体,作用于 class,对 style 属性完全无效。想修就只能重写。

这类代码在项目里有几十处:style={{ color: "#999" }}、style={{ background: "#1890ff" }}、style={{ borderLeft: "2px solid #e8e8e8" }}。它们当初被写成内联,多半是因为「就一个值,懒得起 class 名」。代价是整个暗色模式无从谈起。

结论:内联样式写颜色,等于放弃了这个元素的主题能力。

二、第三方 prose 类会把正文颜色写死

后台编辑器用的是 TipTap,内容区挂了这么一串 class:

class: "prose prose-gray max-w-none min-h-[400px] focus:outline-none px-6 py-4"

@tailwindcss/typography 的 prose-gray 会设置一堆 --tw-prose-* 变量,其中正文色是 gray-700。深色背景配 gray-700 文字——几乎读不了。

我一开始没发现,因为浅色模式下它完全正常。是切到深色截图时才看出来「正文比标题暗一大截」。用 getComputedStyle 一测,亮度只有 40% 左右。

修法不是加 dark:prose-invert,而是换掉它:

class: "post-prose max-w-none min-h-[400px] focus:outline-none px-6 py-4"

post-prose 是前台文章页用的那套 token 驱动排版。换过来之后一举两得——对比度正常了(亮度 96.5%),而且编辑区和最终发布的文章共用同一套排版规则,真正的所见即所得。

结论:第三方排版类是个黑盒,它对颜色的假设未必是你的假设。自己有设计系统的时候,别把正文交给它。

三、嵌入的第三方组件有自己的主题概念

评论用的是 giscus,配置里写着:

script.setAttribute("data-theme", "preferred_color_scheme");

看起来很合理——跟随系统。但它跟随的是操作系统,不是我的站点开关。

于是:系统是浅色、用户在站内手动切到深色 → 整页变暗,评论区还是刺眼的一大块白。

修法是让它跟着 resolvedTheme 走,并且用 postMessage 热更新,不重建 iframe:

iframe.contentWindow?.postMessage(
  { giscus: { setConfig: { theme: resolvedTheme === "dark" ? "dark" : "light" } } },
  "https://giscus.app"
);

这里还有个时序坑:主题同步的 effect 如果在 iframe 创建前跑,postMessage 没有接收方。所以注入脚本要等 resolvedTheme 有值之后再执行,并且用一个 ref 把主题值传进注入逻辑——不能直接进依赖数组,否则每次切主题都会把评论区整个重建一遍。

结论:任何 iframe / 第三方 widget 都要单独接线,它们不在你的 CSS 作用域里。

四、批量替换会制造反色陷阱

后台有几十个文件要从 gray-* 迁到 token,我写了脚本批量替换。其中一条规则是:

bg-gray-900 → bg-ink

看起来天经地义:gray-900 是最深的灰,--ink 是墨色。

但深色模式下 --ink 是近白色。原本的 bg-gray-900 text-white(深底白字)被替换成了 bg-ink text-white——深色模式下就是白底白字,元素直接消失。

中招的有三处:编辑器工具栏的激活按钮、AI 面板的模式切换、聊天气泡。

正确的写法是 bg-ink text-bg:

  • 浅色模式:--ink 近黑,--bg 近白 → 黑底白字
  • 深色模式:--ink 近白,--bg 近黑 → 白底黑字

两边都自动反色。

结论:语义 token 的值会随主题翻转,所以前景和背景必须成对指定。批量替换只能处理单个 class,处理不了这种配对关系——替换完必须人工过一遍所有 text-white / text-black。

五、有些东西不应该跟随主题

代码块我最后决定固定深色,不跟随皮肤:

.post-prose pre {
  background: oklch(0.19 0.008 265);
  color: oklch(0.88 0.005 265);
  border: 1px solid oklch(0.27 0.01 265);
}

理由很简单:语法高亮的配色方案是为深色背景设计的,硬塞进浅色底会难看且难读。GitHub、Stripe 文档、很多技术博客都是这么做的。

同理,AI 面板里表示增删的红绿 diff 标记也保留了红绿语义,只是补了暗色变体(bg-green-500/15),而不是换成主题色——红加绿表示增删是跨产品的通用约定,改掉只会让人困惑。

结论:一致性是手段不是目的。当「跟随主题」会损害可读性或打破用户既有认知时,就该破例——但要明确写下理由,否则下一个人会以为是漏改。

真正的判据

做完这一轮,我的体会是:暗色模式做得好不好,不取决于你写了多少 dark:,而取决于一个问题——

这个颜色,全站有几个地方定义它?

如果答案是「一个」,暗色模式就是改那一个地方的事。 如果答案是「几十个」,那你做的不是暗色模式,是打地鼠。

改造之后,.post-prose 的 .dark 补丁从 50 多行降到 0 行。不是因为我删掉了暗色支持,而是因为正文样式现在只从 token 取值,明暗自己会跟上。

分享