Jetpack Compose中themes.color的适用场景及使用规范

核心颜色语义定义 #

Material Design 颜色系统的核心设计目标是通过固定语义的颜色令牌，实现全局视觉一致性、无障碍对比度达标、多主题（亮色/暗色/品牌换肤）快速切换，所有颜色令牌的语义完全对应使用场景，不需要靠主观判断：

• primary：App 核心品牌主色，用于最高优先级的交互元素、核心视觉强调点
• onPrimary：放置在 primary 底色之上的内容（文字、图标、描边）专用色，默认和 primary 保持符合无障碍标准的对比度
• primaryVariant：primary 的同色系深浅变体，用于顶部 App Bar、状态栏等同色系低一级强调的场景
• secondary：次级品牌色，用于中优先级的交互元素、辅助强调点，和主色形成视觉区分
• onSecondary：放置在 secondary 底色之上的内容专用色
• secondaryVariant：secondary 的同色系深浅变体
• surface：卡片、弹窗、菜单、底部表单等悬浮类组件的底色
• onSurface：放置在 surface 底色之上的内容专用色，组件禁用状态的内容色默认取带透明度的该值
• background：页面根层级的背景底色
• onBackground：放置在根背景上的普通正文、标题等内容的默认色
• error：错误、危险操作语义的专用色（比如删除按钮、表单错误提示）
• onError：放置在 error 底色之上的内容专用色

注意：所有带on前缀的颜色永远和对应的底色配对使用，不要单独拿onPrimary这类颜色当普通组件的底色用。contentColorFor() 方法会根据传入的背景色自动匹配对应的on开头内容色，不需要手动计算对比度。

不同按钮默认颜色差异的本质原因 #

三类按钮默认背景色不同，完全是由组件的视觉优先级决定的，完全匹配上述颜色语义，对应源码逻辑如下：

// 高优先级：填充按钮，用于页面主操作（确认、提交、下一步）
// 视觉权重最高，直接用主色当背景，内容自动匹配onPrimary
@Composable
fun buttonColors(
    backgroundColor: Color = MaterialTheme.colors.primary,
    contentColor: Color = contentColorFor(backgroundColor),
    disabledBackgroundColor: Color = MaterialTheme.colors.onSurface.copy(alpha = 0.12f)
        .compositeOver(MaterialTheme.colors.surface),
    disabledContentColor: Color = MaterialTheme.colors.onSurface
        .copy(alpha = ContentAlpha.disabled)
): ButtonColors = DefaultButtonColors(
    backgroundColor = backgroundColor,
    contentColor = contentColor,
    disabledBackgroundColor = disabledBackgroundColor,
    disabledContentColor = disabledContentColor
)

// 中优先级：轮廓按钮，用于页面次要操作（取消、返回、次要选项）
// 视觉权重低于填充按钮，背景和所处层级底色保持一致，用主色做文字/描边强调
@Composable
fun outlinedButtonColors(
    backgroundColor: Color = MaterialTheme.colors.surface,
    contentColor: Color = MaterialTheme.colors.primary,
    disabledContentColor: Color = MaterialTheme.colors.onSurface
        .copy(alpha = ContentAlpha.disabled)
): ButtonColors = DefaultButtonColors(
    backgroundColor = backgroundColor,
    contentColor = contentColor,
    disabledBackgroundColor = backgroundColor,
    disabledContentColor = disabledContentColor
)

// 低优先级：文本按钮，用于页面辅助操作（查看更多、忘记密码）
// 视觉权重最低，背景完全透明，仅用主色做文字强调
@Composable
fun textButtonColors(
    backgroundColor: Color = Color.Transparent,
    contentColor: Color = MaterialTheme.colors.primary,
    disabledContentColor: Color = MaterialTheme.colors.onSurface
        .copy(alpha = ContentAlpha.disabled)
): ButtonColors = DefaultButtonColors(
    backgroundColor = backgroundColor,
    contentColor = contentColor,
    disabledBackgroundColor = backgroundColor,
    disabledContentColor = disabledContentColor
)

实际开发使用规则 #

• 所有全局通用组件、无特殊业务语义的元素，必须从MaterialTheme.colors取色，禁止硬编码十六进制颜色值，否则亮色/暗色模式切换、品牌换肤时需要逐组件修改代码，且容易出现对比度不达标问题
• 同层级、同优先级的同类型组件必须严格遵循统一颜色规范：比如所有页面的主操作填充按钮默认都使用primary作为背景，禁止同层级操作随意更换颜色，避免打乱用户对视觉优先级的判断
• 特殊语义场景可以自定义颜色，但必须遵循底色+对应on色的配对规则：比如危险操作按钮可以用error作为背景，内容色用contentColorFor(error)自动匹配，不要随意搭配底色和内容色
• 禁止跨语义用色：不要用primary作为大段普通正文的文字色，不要用onBackground作为交互组件的底色，避免破坏全局视觉一致性

内容的提问来源于stack exchange，提问作者Charles