深色模式上不上，先看后台这三个数字过没过线

「能不能顺手加个深色模式」这句话，最近在改版沟通里出现得越来越多。听上去只是多一个开关，落到执行上是把整站的色彩体系重做一遍，再多养一套需要长期维护的皮肤。接需求之前花半小时做一次核算，下面三个数字有任何一个不过线，这一版就先别开工。

前置条件：三个数字，缺一个都不动手

第一个数字是深色偏好用户的真实占比。别拍脑袋估，在统计代码里加一行上报：把 window.matchMedia 检测 prefers-color-scheme 为 dark 的结果作为自定义维度传上去，连续跑满 14 天。企业官网的访客集中在工作时段、以桌面端为主，这个比例通常落在 8% 到 18% 之间；如果站点访客里手机端超过七成，比例会明显往上走。低于 12% 就意味着投入的人日只服务了不到八分之一的人，那这一版把预算放在加载速度或表单转化上，回报要实在得多。这是网站设计里少数可以用数据直接否掉的需求，不必靠主观审美争论。

第二个数字是页面模板套数。首页、列表页、详情页、产品页、单页、搜索页、表单页，八套以内的站，色值改造大约 3 到 4 个人日；如果历史上换过两三家外包，模板堆到 20 套以上、各写各的样式，工作量会直接翻到 12 人日往上，还不含回归测试。第三个数字最能说明底子——用编辑器全局搜索十六进制色值，把重复的去掉，看还剩多少个独立颜色。剩 40 个以内说明当初的网站设计留下了一套还算克制的色板，往上加一层深色是可行的；剩到七八十个，说明根本没有色板，这时候做深色等于把混乱原样复制一份，先做色值收敛才是正事。

第一步：把散落的色值收敛成语义别名

命名不要按颜色本身来，灰色一号、灰色二号这种名字换到深色下全部失效。按用途命名：页面底色、卡片底色、正文色、次要文字色、分隔线色、品牌主色、危险色、禁用色。一个中等规模的企业站，语义变量控制在 18 到 24 个就够用，超过 30 个说明拆得太碎，后面两套值要各维护一遍，成本翻倍。

校验方法很直接：改完之后在业务样式文件里全局搜索 color 和 background 后面直接跟井号的写法，剩余数量应该是 0，允许出现十六进制的只有变量定义那一个文件。搜出来的每一处都记下来，这些往往是后期最容易在深色下露馅的地方。

第二步：两套值挂在同一个属性上，别复制样式表

常见的错误做法是把整个样式表复制一份改成深色版，两份文件从此开始各自漂移，三个月后改一处按钮圆角只改了浅色那份。正确做法是在根元素上挂一个主题标记属性，标记为 light 和 dark 时各定义一遍变量值，组件样式一份都不动。这条约束要写进网站设计规范里，否则接手的人下次还会复制。

具体色值有两条经验值得直接照抄。深色底不要用纯黑，用亮度在 20 到 24 之间的深灰，比如 141618 到 1b1e24 这一档，纯黑会让边界完全消失，卡片和背景分不开层次。正文文字也不要用纯白，用 e6e8ec 附近的浅灰，纯黑配纯白的对比度接近 21 比 1，看久了字会有明显的光晕感和残影。

校验方法：手动把根元素的主题属性改成 dark，不要开切换器，逐页翻一遍。凡是仍然显示为白色或浅灰的区块，全是第一步漏掉的硬编码，一个个揪出来补进变量。这一遍至少要覆盖登录、搜索结果为空、表单校验报错这三个不常打开的状态页。

第三步：切换器做三态，重点在首屏那两百毫秒

开关做三个状态：跟随系统、强制浅色、强制深色，选择结果写进 localStorage。绝大多数站点只做两态，用户在系统里切了主题网站却不跟着变，反而要被投诉。真正的技术难点不在开关本身，而在页面加载的头两百毫秒——如果读取偏好的脚本跟着打包文件异步加载，用户会先看到一帧白底再跳成深色，那一下刺眼程度足以让人直接关掉。

做法是把读取脚本内联写在 head 里、放在所有样式表引用之前，五行以内，同步执行，不要打包、不要加 defer。校验方法：浏览器开发者工具里把网络限速到慢速 3G，录屏回放首屏，逐帧看有没有出现白底。一帧都不能有。

第四步：图片、标志、图表、阴影单独处理

白底 PNG 产品图放在深色页面上像贴了张白纸，这是深色版最容易被甲方一眼看穿的地方。两个办法：产品图统一换成透明底，或者对图片加一层亮度降到 0.9 左右的滤镜，让边界不那么扎眼。企业标志要准备深色版本，用图片元素的多源写法按系统偏好切换，不要用滤镜反色，反色会把品牌红变成青色。

数据图表要单独调一遍配色。浅色底下饱和度拉满的那套颜色，换到深色底上会产生明显的发光感，饱和度统一降 15% 到 20%，亮度提 5% 左右。阴影在深色下几乎完全不可见，别再靠阴影分层，改用底色亮度差——卡片比页面底色亮 3% 到 5%，弹层再亮 3%，层级关系就出来了。

校验方法只有一条硬指标：用对比度检测工具逐类文字量一遍，正文不低于 4.5 比 1，18px 以上的大字号不低于 3 比 1，禁用态文字不低于 3 比 1。很多网站设计稿在深色下把次要文字调到 6b7280 那一档，量出来只有 3.2 比 1，正文用就不合格，得提到 9ca3af 附近。

常见报错与处理

首屏白闪：九成是脚本没内联到 head 最前面，剩下一成是服务端渲染的页面没有把主题写进 HTML 属性，客户端补写时已经晚了一帧。处理办法是服务端读 cookie 直接输出主题属性，localStorage 只做兜底。

正文变成黑底深灰字：这是后台富文本编辑器留下的坑。运营从 Word 粘贴文章，行内样式带着写死的深灰色跟进来，浅色下看不出问题，深色下几乎读不了。处理分两步，先在深色主题下给富文本容器加一条覆盖规则，强制正文色跟随变量；再写脚本清洗历史数据里的行内颜色声明，一个几百篇文章的站，这一步大约耗时一到两小时。这类历史包袱在网站设计阶段看不见，只有换主题时才会集中爆出来。

输入框自动填充后变白底：浏览器对自动填充有一套强制样式，改背景色无效，得用内阴影覆盖的写法把底色顶回去，同时把文字色也一并指定。第三方嵌入内容不跟随：地图、在线客服、验证码这类以框架形式嵌入的模块无法被主题变量影响，可行的做法是给容器加一个亮度降低的滤镜过渡，或者干脆保留浅色但把周围留白加大，不要硬改。

打印出来是黑纸白字：这个问题几乎每个上了深色模式的站都会中一次，客户打印产品页报价直接费掉半盒墨。在打印媒体查询里强制把主题变量还原成浅色一套即可。另外还有一类隐蔽故障是图片懒加载的占位底色写死成浅灰，图片没加载出来时页面上会闪出一片片白块，把占位色也换成变量就能解决。

上线前自查项

逐条过，不打勾的不上线：业务样式文件里硬编码色值为 0；语义变量在两套主题下都有定义、没有漏项；慢速网络下首屏无白帧；系统切换主题时页面实时跟随；刷新和跳转后主题保持不变；正文对比度不低于 4.5 比 1；产品图与企业标志有深色适配；图表配色已单独降饱和；富文本历史数据的行内颜色已清洗；打印样式强制浅色。十条全过之后，再把深色模式当成一个需要长期维护的分支写进网站设计的交付文档，注明以后新增任何页面都要在两套主题下各截一次图，否则半年之后新加的板块又会是一片白。