color-mode-and-theme

色彩模式与主题

决策：浅色、深色，还是两者兼有

色彩模式是品牌与使用场景的选择，而非个人偏好。请慎重决定。

浅色（白色设计）

基调： 开放、可信、以内容为主、易于访问、专业
适用： 营销网站、电商、编辑出版、受众多元的 SaaS、消费类产品，以及内容为重点的 B2B 工具

对于大多数产品，浅色模式是更稳妥的默认选择。它在明亮环境下表现更好，开箱即用的无障碍支持也更全面。

深色（深色设计）

基调： 高端、专注、沉浸、技术感强、高对比度数据
适用： 交易平台、开发者工具、创作工具（视频／音频编辑器）、可视化内容密集的数据仪表盘、娱乐、游戏

深色模式可减轻用户在低光照环境下长时间使用时的眼部疲劳。它还能让色彩丰富的数据可视化（图表、热力图）在深色背景上更加醒目。

注意： 深色模式更难做好。文字对比度过低、品牌色过于饱和、界面表面之间的区分度不足，都是常见问题。如果团队无法妥善维护，浅色模式也胜过效果不佳的深色模式。

两者兼有（系统默认 + 手动切换）

遵循 prefers-color-scheme，让操作系统设置默认模式。提供切换开关，供希望手动覆盖默认设置的用户使用。对于大多数拥有回访用户的产品而言，这是现代标准。

@media (prefers-color-scheme: dark) {
  :root { /* dark tokens */ }
}
@media (prefers-color-scheme: light) {
  :root { /* light tokens */ }
}
[data-theme="dark"] { /* manual override */ }
[data-theme="light"] { /* manual override */ }

---

何时在界面中加入主题选择器

主题选择器是一种界面控件——它会占用空间并增加复杂度。只有当用户控制权确实重要时才添加。

使用场景	是否需要主题选择器？
营销网站、落地页	不需要——选定一种模式并坚持使用
面向大众的消费级 SaaS	两者兼有（系统默认 + 切换开关）
开发者工具、技术类产品	需要——开发者会期待提供此功能
交易平台、金融仪表盘	需要——用户使用时间长，常在低光照环境下操作
B2B 企业工具（ERP、分析工具）	需要——高级用户使用时间长，个人偏好各异
电商店铺	通常不需要——默认浅色，也可采用系统默认
创作工具（设计、视频、音频）	需要——用户通常偏好深色，但也会期待提供切换开关

原则： 如果用户每天会在工具中花费数小时，就应让他们自行选择。如果产品用于交易或偶尔使用，就选择适合品牌的模式即可。

将主题切换开关放在页眉（右上角、账户区域附近）或用户设置中，不要放在主导航里。

---

品牌基调与色彩模式

品牌现有的视觉形象应影响默认模式的选择。

品牌基调	默认模式
简洁、极简、可信、开放	浅色
高端、独特、大胆、沉浸	深色
技术感强、数据密集、精准	深色
活泼、多彩、充满活力	浅色（深色模式更难与鲜艳的品牌色搭配）
中性、企业化、实用	浅色，搭配系统默认切换开关

如果品牌采用非常深的主色（藏青、深绿、近黑色），深色模式能自然地衬托它。如果品牌以明亮鲜艳的主色为核心，浅色模式则能让主色更好地展现。

---

深色模式令牌原则

主题切换器是第二套调色板，而不是一个开关。 每种语义颜色在每种模式下都需要经过验证的值，而不是用算法翻转一个值。能在浅色模式下通过的对比度，在深色模式下往往会失败；饱和度和层次感的呈现也会有所不同。实现成本不低，也因此除非确有必要，否则不应构建（见上文）。

深色模式不只是反转颜色。常见错误包括：

• 不要使用纯黑色（#000000）作为基础表面——使用非常深的中性色（#0A0A0F、#111827）来营造层次感
• 深色模式下的表面层级依靠明度，而非阴影——基础表面、+1、+2 表面应逐级变亮，而不是阴影逐渐加深
• 略微降低品牌色的饱和度——深色背景上的鲜艳颜色可能显得过于刺眼；降低 10–15% 的饱和度可让它们更易读
• 提高反色文本的字重——深色背景上的浅色文本，通常比浅色模式下相同字重的文本显得“更细”。将字重提高一个级别（例如从常规提高到中等，或从中等提高到半粗体），以保持易读性。
• 主动验证文本对比度——深色表面上的浅色文本并不会自动符合 WCAG；请检查所有组合

与令牌值相同的字面量就是那个令牌。 当硬编码颜色恰好与当前主题下令牌解析出的值相同时，这并非巧合，也不是局部选择：它就是那个令牌，只是以一种无法跟随主题变化的形式写出。问题随后会以相反的形式显现，而不是缺失。被固定为深色模式值的表面，在浅色模式下不只是看起来不对；它还会颠倒与相邻表面的关系，原本下沉的表面会变得凸起，原本退后的表面则会向前突出。布局仍能正常渲染，也不会抛出错误，唯一的反馈可能只是有人说某个屏幕感觉不太对。不要把这件事交给自律来解决，因为按定义，任何令牌审计都无法发现字面量。把它变成机械流程：用 grep 搜索标记中的字面颜色值，把数量作为有明确数字的技术债，并在数量降到零后阻止构建中出现新的字面量。任何经过 grep 检查后仍保留的字面量，都必须有书面理由；而“它反正和令牌值相同”是唯一绝不成立的理由。

/* Dark mode surface scale */
--color-surface:         #0A0A0F;  /* base */
--color-surface-raised:  #141419;  /* cards */
--color-surface-overlay: #1E1E26;  /* modals, popovers */
--color-border:          rgba(255,255,255,0.08);
--color-text:            #F0F0F5;
--color-text-secondary:  #8A8F98;

---

审查清单

• 颜色模式的选择是否经过深思熟虑，并基于品牌调性和使用场景？
• 如果采用组合模式：prefers-color-scheme 是否设置了默认模式？
• 如果构建了主题选择器：是否将它放在不显眼但易于访问的位置？
• 在深色模式下：表面是否通过明度阶梯区分，而不只是依靠阴影？
• 在深色模式下：是否略微降低了品牌色的饱和度，以避免视觉上的刺眼感？
• 是否在两种模式下验证了所有文本/背景的对比度（WCAG 2.2 AA）？
• 反色文本（浅色文本置于深色背景上）的字重是否提高了一个级别，以保持视觉上的易读性？
• 是否避免将纯黑色（#000000）用作深色模式的基础表面？