结论先行:深色模式工程化的现代答案是「语义 token + light-dark() + color-scheme」三件套:颜色只定义一次,light-dark(浅色值, 深色值) 按当前配色方案自动取值;color-scheme 告诉浏览器页面支持哪些方案,让滚动条、表单控件等原生 UI 同步变色;手动切换只需改根元素的 color-scheme,不再需要给每个组件写 .dark 覆盖。light-dark() 已是基线能力(Chrome 123+、Safari 17.5+、Firefox 120+,2024 年三大引擎齐备)。本文给出完整 token 架构、跟随系统与手动切换的实现、图片与阴影的处理,以及旧浏览器降级。
为什么 .dark 类方案越写越累
传统深色模式是「双份样式」:每个组件写一遍浅色,再在 .dark 作用域下覆盖一遍。组件库有一百个组件就有两百份颜色声明,新增组件忘写深色覆盖就出「白块事故」,设计改一个灰阶要同步改两处。更隐蔽的问题是原生 UI:滚动条、input 默认样式、select 下拉、日期选择器不理会你的类名,深色页面里一条亮白滚动条格外刺眼,表单控件的白底也像一块块补丁。根源在于「主题」被实现成了样式覆盖,而不是颜色系统的输入参数。工程化的方向是把主题收敛为少数几个语义变量,组件只消费变量,切换主题只改变量。
color-scheme:被低估的地基
color-scheme 声明元素支持的配色方案,浏览器据此渲染原生控件与画布默认色。根元素写 color-scheme: light dark; 表示两种都支持,具体用哪种由系统偏好决定;写 color-scheme: dark; 则强制深色。它同时是 light-dark() 的开关——没有正确设置 color-scheme,light-dark() 永远返回浅色值,这是最常见的「不生效」原因。color-scheme 还可以声明在局部元素上:页面整体浅色,但某个代码展示区强制深色,给该区域单独写 color-scheme: dark 即可,区域内的原生控件与 light-dark() 取值都会跟随局部声明,做「深色终端窗口」「深色预览区」这类混合界面非常顺手。meta 标签 <meta name='color-scheme' content='light dark'> 可以让浏览器在 CSS 加载前就用对底色,避免白屏闪烁。表单控件、滚动条、默认按钮从此自动跟随,不需要任何额外样式。
light-dark():一个 token 两种取值
light-dark() 接受两个颜色参数,按当前 color-scheme 返回其一。语义 token 全部用它定义,组件层完全不知道主题的存在:
:root {
color-scheme: light dark;
--bg: light-dark(#ffffff, #16161d);
--bg-soft: light-dark(#f5f5f7, #22222c);
--text: light-dark(#1a1a22, #ececf2);
--text-muted: light-dark(#6b6b76, #9a9aa6);
--border: light-dark(#e5e5ea, #33333e);
--brand: light-dark(#5b47ff, #8f7fff);
--brand-soft: light-dark(#f0edff, #2b2547);
}
body {
background: var(--bg);
color: var(--text);
}
.goods-card {
background: var(--bg-soft);
border: 1px solid var(--border);
}
.price { color: var(--brand); }
.coupon { background: var(--brand-soft); }注意深色模式的品牌色不是照搬浅色值:#5b47ff 在深底上对比度不足,提到 #8f7fff 才能保证可读性。深色主题也不是「颜色反转」,背景用带一点色相的深灰而非纯黑,文字用柔白而非纯白,层次靠明度差而不是阴影,直接反转浅色值会得到一个刺眼且层次混乱的页面。这些决策全部收敛在 token 层,组件代码一行不改。token 的命名也建议按语义而非色值:--bg-soft 表达「柔和表面」,而不是 --gray-100,后者在深色模式下会名不副实——深色主题里它其实是深灰,名字却写着浅灰,维护者读起来处处别扭。语义命名让 token 在两个主题下都自洽。
跟随系统 + 手动切换
产品通常要三档:跟随系统、强制浅色、强制深色。实现只需操作根元素的 color-scheme,light-dark() 自动响应:
const root = document.documentElement;
function applyTheme(mode) {
if (mode === 'system') {
root.style.colorScheme = 'light dark';
} else {
root.style.colorScheme = mode;
}
localStorage.setItem('theme-mode', mode);
}
applyTheme(localStorage.getItem('theme-mode') || 'system');@media (prefers-color-scheme: dark) {
:root { --hero-img: url('/hero-dark.png'); }
}跟随系统时 color-scheme 写 light dark,浏览器按 prefers-color-scheme 自动选边;强制模式写单值即可覆盖系统,用户的选择优先于系统偏好,这也是三档设计的语义基础。选择持久化到 localStorage,并在首屏尽早执行(内联脚本或 meta 配合),避免「先浅后深」的闪烁。需要监听系统变化做额外逻辑时用 matchMedia('(prefers-color-scheme: dark)') 的 change 事件,但纯颜色切换不需要——light-dark() 自己会响应。图片类资源无法用颜色函数切换,用媒体查询换 background-image,或准备两套 img 用 CSS 显隐;照片本身通常不需要深色版本,需要处理的是带白底的插画与图标,以及嵌在内容里的截图类素材。
阴影、遮罩与第三方内容
深色模式里阴影的表现力下降,层次改用「更亮的表面色」表达:弹层背景比页面背景亮一档,边框比背景再亮一档,必要时保留弱阴影。遮罩统一用半透明黑,两种主题通用。第三方内容(iframe 嵌入、富文本详情)不受你的 token 控制,深色模式下给它们包一层浅色底或加 filter 反色都是权衡方案,建议优先保留浅色底并明确边界,避免反色把商品图片也处理掉。验收时用真实页面过一遍对比度:正文至少 4.5:1,大字号 3:1,深色模式下的次要文字最容易不达标。
兼容与降级
light-dark() 支持面为 Chrome/Edge 123+、Safari 17.5+、Firefox 120+,2024 年成为基线,如今覆盖率很高。旧浏览器降级有两条路:一是每个 token 先写浅色静态值再写 light-dark(),旧浏览器保留浅色值,整站呈现浅色主题,功能无损;二是用 prefers-color-scheme 媒体查询为旧浏览器保留一份深色覆盖,代价是回到双份样式,只建议在深色是硬需求且旧浏览器占比可观时做。color-scheme 本身支持极早,可放心写。检测可用 CSS.supports('color', 'light-dark(#fff, #000)')。无论哪条路,组件层都只消费语义 token,降级方案被隔离在 token 定义层,这是架构上最重要的收益。
结合 api工厂:商城深色模式一次到位
H5 商城的深色模式涉及商品卡、价格、优惠券弹层、订单列表等大量组件,用语义 token 架构可以把改动收敛到一处。基于 api工厂(https://www.it120.cc/)开发时,商品、Banner、CMS 文章都由后台维护,前端渲染结构消费 token 即可;开源项目 vueMinishop、uni-app-mall(大全 https://www.it120.cc/help/uq920k.html)的组件样式按本文模式改造后,深色模式就是「定义一组 light-dark() 变量」的工作量。运营上传的 Banner 图建议预留深色版本位,用媒体查询切换。数据与主题彻底解耦,后续再加品牌主题、节日皮肤,都是 token 层的增量,而不是全站样式的重写。
深色模式的设计原则
工程架构之外,深色主题本身有几条设计原则值得固化。第一,不用纯黑做背景:纯黑与亮色文字对比过强,长文阅读易疲劳,带一点色相的深灰(如偏品牌色相的深底)更舒适,也更容易表达层次。第二,层次靠明度而非阴影:深色底上阴影几乎不可见,弹层、卡片、悬浮态用「更亮的表面」区分,定义 surface-0 到 surface-3 的明度阶梯比调阴影参数有效得多。第三,饱和度要降:高饱和色在深底上会产生「光晕感」,品牌色与状态色在深色模式里适当降色度、提明度,OKLCH 让这一步变成调整两个分量的确定性操作。第四,图片与插画单独处理:白底插画在深色页面里像补丁,准备深色版本或加柔和的底托;照片通常保持原样。这些原则写进 token 注释,比口头约定可靠。
防闪烁与首屏时序
深色模式最影响体验的细节是「先浅后深」的闪烁:HTML 先按默认浅色渲染,脚本执行后才切深色,用户看到一次刺眼的白屏。解法是把主题决策提前到首帧之前。推荐组合:head 里放 meta color-scheme 声明支持双色;紧跟一段内联脚本读取 localStorage 并设置根元素 color-scheme,这段脚本必须同步执行且足够小;CSS 里的 light-dark() 随后自然取到正确值。注意脚本要放在样式表之前或至少不依赖外部资源,任何异步加载都会留下闪烁窗口。服务端渲染的项目可以更彻底:把主题偏好写进 Cookie,服务端直接输出带 color-scheme 内联样式的 html 标签,首帧即正确。跟随系统档不需要脚本干预,浏览器自己按 prefers-color-scheme 处理,这也是默认档推荐跟随系统的原因之一。
多主题扩展:不止深浅两档
light-dark() 只表达两个值,但架构可以支撑更多主题。思路是把「主题」抽象为一组语义 token 的取值集合:深浅两档用 light-dark() 内联表达,品牌主题、节日皮肤则用根元素的 data-theme 属性加属性选择器覆盖 token。组件层永远只消费 var(--bg)、var(--brand),不关心主题数量。需要注意 light-dark() 与属性覆盖的优先级关系:属性选择器里重新定义 --brand 即可覆盖 light-dark() 的结果,因为自定义属性的层叠发生在取值之前。主题切换的持久化、首屏防闪烁逻辑与深浅模式完全复用,只是 mode 的取值从两个变成多个。这个架构的边界也要清楚:主题数量上去之后,对比度验收矩阵会成倍增长,建议把验收工具化,每新增主题自动跑一遍 token 组合检查,而不是人工走查。
验收清单
上线前按清单走查:两种主题下正文对比度达标,次要文字与禁用态单独检查;原生控件(滚动条、输入框、下拉)颜色跟随,没有亮白残留;图片、插画、第三方嵌入在深色下不刺眼;主题切换无闪烁,刷新与跨页导航保持选择;跟随系统档在系统切换时实时响应;localStorage 不可用(隐私模式)时优雅退回跟随系统;旧浏览器降级为完整浅色主题而非半深半浅。七条全过,深色模式才算工程化完成,而不是「看起来变黑了」。
文章标签
相关产品
api工厂是面向开发者的开放 SaaS 平台:开箱即用的后台管理系统 + 全端 SDK,只需前端开发即可构建小程序、App、H5 与网站。