dark-mode-converter

暗色模式转换器

像设计成熟的产品那样构建暗色模式：将它视为拥有独立逻辑的第二套主题，而不是简单翻转浅色主题的颜色。反转颜色行不通，因为暗色 UI 的工作方式不同——层级通过更亮的表面而非阴影来传达，饱和色在深色背景上会产生刺眼的振动感，纯黑加纯白带来的是眩光，而非对比。

工作流

1. 先进行令牌化。 清点代码库中的每种颜色。如果组件中硬编码了颜色，应先将它们提取为语义令牌，再进行转换——bg.base、surface、surface.raised、text.primary、text.muted、border、accent、状态。如果暗色模式基于原始十六进制值替换构建，下一个功能就会让它失效。（如果已有令牌，也要在同一轮检查中找出遗漏项。）
2. 设计暗色调色板，按用途遵循暗色 UI 的规律：基础色用深灰，绝不用 #000（采用 #0f1115–#1a1d23 范围，或向品牌色调偏移）；表面层级越高，颜色越亮（基础层 -> 卡片 -> 弹出层，每层亮一档）；文本用灰白色，绝不用 #fff（接近 #e8eaed，约为 87% 白），并设置多个弱化层级；强调色降低饱和度并提亮 1–2 档，避免产生振动感；边框改用低透明度白色；阴影颜色加深、范围收窄，或者完全改用表面亮度来体现层级。验证每组文本与表面的组合至少符合 WCAG AA 标准。
3. 按技术栈接入机制：Tailwind 使用 dark: 和 class 策略（v4：@variant dark），或通过 [data-theme="dark"] 块重新定义自定义属性。添加包含三种状态（浅色／深色／系统）的切换器、localStorage 持久化、prefers-color-scheme 默认设置，以及在 <head> 中添加防闪烁内联脚本，在首次绘制前设置 class。
4. 处理棘手问题——天真转换容易在这些地方失败：带有白色背景的图片和插画（替换变体、在其后添加微妙的表面底色，或在适用时用 CSS 过滤器处理徽标）；图表和数据可视化调色板（需要专属的暗色系列配色）；表单控件和 color-scheme: dark，确保原生输入框、滚动条和自动填充样式匹配；嵌入的第三方小组件（地图主题、iframe）；不会继承主题的电子邮件模板和开放图谱图片；在深色背景上会消失的焦点环。
5. 执行审查。 对关键路由逐一检查两种模式的截图（或列出路由供用户检查）：查找残留的浅色表面、阴影分隔改动后出现的双重边框、难以阅读的弱化文本，以及失去视觉力度的强调按钮。输出 dark-mode-report.md：令牌映射表（按用途列出浅色 -> 深色）、修改过的文件、对比度表，以及仍需设计人员审阅的项目。

规则

• 只使用语义令牌。将 dark:bg-gray-800 散布在 90 个组件中会产生维护负担，而非构成主题——应集中管理映射。
• 基础色绝不使用纯黑，文本绝不使用纯白。这些颜色仅用于特定场景，不可作为默认值。
• 层级表现方式要反转：浅色模式通过阴影表达“更高”，暗色模式通过更亮的表面表达。转换逻辑，而不只是颜色。
• 重新校准强调色，但不更改品牌：调整亮度／饱和度，使其适用于深色背景，同时保留品牌色调（检查品牌色在深色背景上的对比度；如果确实冲突，应提醒用户，而不是悄悄改变色调）。
• 从现在起，两种模式都是一等模式：每份报告都必须包含以下规则——新组件必须定义两种主题的令牌，否则无法通过审查。
• 实时测试系统偏好切换——system 设置必须能响应操作系统更改，无需重新加载。

快捷命令

• “将此项目转换为暗色模式”——完整工作流
• “先对我的颜色进行令牌化”——单独执行第 1 步
• “只设计暗色调色板”——基于现有令牌执行第 2 步
• “审查暗色模式”——针对现有实现执行第 5 步