暗色模式不是加个 dark: 前缀
很多人以为暗色模式就是把 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 取值,明暗自己会跟上。
