Android 深色主题与设计令牌

深色主题不是把所有颜色反转。文字层级、品牌色、分割线、图片和系统栏都需要在不同外观下保持对比度与一致语义。若业务布局直接写入大量颜色值，切换主题会变成逐页修补。更可维护的方式是先建立语义化设计令牌，再由不同主题提供具体值。

一、颜色名称表达语义

相比 gray_333，text_primary、surface_page 和 status_warning 更能表达用途。具体颜色变化时，业务布局无需修改。

<resources>
    <color name="surface_page">#FFFFFF</color>
    <color name="surface_card">#F5F6F8</color>
    <color name="text_primary">#1A1A1A</color>
    <color name="text_secondary">#666666</color>
</resources>

夜间资源目录提供同名值：

<resources>
    <color name="surface_page">#121212</color>
    <color name="surface_card">#1C1C1E</color>
    <color name="text_primary">#F2F2F2</color>
    <color name="text_secondary">#B3B3B3</color>
</resources>

具体色值应来自项目设计规范，示例只说明资源组织方式。

二、优先通过主题属性引用

公共组件可以引用主题属性，让不同业务主题覆盖实现：

<TextView
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:textColor="?attr/colorTextPrimary"
    android:textSize="16dp" />

文本宽高使用 wrap_content，字号使用 dp，并通过父布局约束可用空间，符合项目适配规则。

主题属性应集中定义，不在各模块重复声明语义相近的名称。

三、处理状态颜色

按钮、输入框和列表项通常有按下、禁用、选中等状态。状态选择器应同时考虑浅色与深色主题，不能只替换默认颜色。

禁用状态不应仅通过降低透明度处理，如果叠加在不同背景上会得到不可控结果。优先使用设计规范中明确的禁用前景与背景令牌。

四、避免运行时遍历修改颜色

主题切换后遍历视图树并手动替换颜色，容易遗漏弹窗、自定义控件和后创建视图。资源与主题机制能够在创建或重建界面时统一解析颜色，更适合大规模页面。

只有画布绘制、动态图表等无法直接使用普通资源的场景，才需要监听主题并更新画笔。

fun updateColors() {
    linePaint.color = resolveThemeColor(R.attr.colorChartLine)
    textPaint.color = resolveThemeColor(R.attr.colorTextPrimary)
    invalidate()
}

五、图片和图标也要适配

纯色图标优先使用可着色资源，从主题获取颜色。包含阴影、渐变和照片的图片不能简单着色，需要由设计提供适合深色背景的版本或容器处理方案。

透明图片在深色背景上可能出现白边，启动图和空状态插画尤其需要真机检查。

六、同步系统栏与弹窗

状态栏、导航栏图标的明暗应与背景匹配。应用内弹窗、底部面板和浮层也必须继承正确主题，避免深色页面弹出浅色且文字不可读的窗口。

相关系统 API 存在版本差异，应使用项目现有兼容控制器，不直接调用超出最低兼容版本的能力。

七、响应主题变化

跟随系统模式时，配置变化可能触发页面重建。页面状态应由 ViewModel 和保存状态恢复，不要为了避免重建而让每个控件手动处理所有资源。

视频播放、编辑草稿等确实需要特殊保持的页面，可以沿用项目配置变化方案，但仍要确保资源重新解析。

八、WebView 与混合页面

混合页面的原生容器和 H5 内容需要约定主题参数与切换时机。原生只传递语义模式，不应向页面发送大量具体色值。页面内部使用自身设计令牌完成渲染。

主题更新消息要与页面生命周期对齐，避免页面尚未准备时丢失首次状态。

九、检查对比度与层级

深色背景下，纯白大面积文字可能过于刺眼，次级文字又容易对比不足。重点检查：

• 正文、辅助文字和占位文字。
• 品牌色文字与按钮。
• 涨跌、警告和成功状态。
• 分割线与卡片边界。
• 禁用和按压状态。
• 截图、图表和第三方页面。

颜色不能是唯一的信息表达方式，状态还应有文本、图标或形状差异。

十、建立主题回归测试

可为核心组件建立浅色和深色视觉基准，并在小屏、长文本和不同业务状态下检查。自动截图能发现大面积遗漏，人工验证则关注对比度、图片质量和系统窗口一致性。

总结

深色主题的关键是语义化颜色体系。业务布局引用主题令牌，不直接绑定具体色值，状态、图标、系统栏和混合页面都使用同一语义。通过资源机制响应外观变化，再用完整状态矩阵验证，主题维护才能从逐页修补变成系统能力。