一只捡星星的熊

4.1 基本概念#

Material 3 使用 color scheme 表达界面颜色。一个 color scheme 不是调色板截图，而是一组有语义的颜色角色。

Material 3 的颜色系统有两个关键点：

• 颜色是角色，不是固定值。
• 前景色和背景色要成对使用。

也就是说，设计和开发时不应该先问“这个按钮是什么蓝色”，而应该先问“这个按钮是不是主操作”。如果它是主操作，通常使用 primary 作为容器或文字角色；如果它只是普通页面内容，就应该回到 surface 体系。

常见角色：

Material 3 中颜色角色可以分成几组：

命名规律：

• onXxx 表示放在某个背景色上的前景色。
• XxxContainer 表示一个强调程度较低、适合大面积容器的颜色。
• surface 系列用于承载内容，不应该被 primary 大面积替代。

4.2 Primary、Secondary、Tertiary#

primary 是最重要的强调色，通常用于关键操作、选中态、品牌识别和最重要的交互入口。它不应该被用作所有标题、所有图标或整页背景。

secondary 用于辅助强调。它适合表达次级操作、补充状态或与 primary 形成层级关系，但不应该和 primary 抢夺注意力。

tertiary 是第三强调色，可以用于更灵活的补充场景，例如特殊标签、扩展品牌色、图表辅助色或某些独立模块。

如果一个页面里 primary 到处都是，等于没有任何地方真正重要。Material 3 的强调色要节制使用，把注意力留给真正关键的操作。

4.3 On colors：前景色不是手写黑白#

onXxx 表示放在某个背景色上的前景色。比如：

• onPrimary 放在 primary 上。
• onPrimaryContainer 放在 primaryContainer 上。
• onSurface 放在 surface 上。
• onError 放在 error 上。

这个命名解决的是对比度和主题适配问题。浅色模式下，onSurface 可能接近黑色；深色模式下，它可能接近白色。开发者不应该手写 Color.Black 或 Color.White 去猜。

正确搭配示例：

Compose 示例：

1
Button(
2
    onClick = onSave,
3
    colors = ButtonDefaults.buttonColors(
4
        containerColor = MaterialTheme.colorScheme.primary,
5
        contentColor = MaterialTheme.colorScheme.onPrimary
6
    )
7
) {
8
    Text("保存")
9
}

很多 Material 组件已经内置了合理的颜色组合，只有在确实需要表达产品语义时才手动覆盖。

4.4 Surface 和 Container#

surface 是 Material 3 中非常核心的概念。页面、卡片、sheet、dialog、菜单等都可以理解为不同层级的 surface。它们承载内容，而不是像 primary 那样表达强强调。

常见 surface 角色：

Surface 系列适合表达层级，不适合全部替换成灰色。浅色模式下，surface 层级可能是细微的明度变化；深色模式下，surface 层级对可读性和空间关系更重要。

典型用法：

• 页面背景：surface
• 普通卡片：surfaceContainerLow 或组件默认值
• 弹层、dialog：更高层级的 surface container
• 分隔和轮廓：outline / outlineVariant

不要用重阴影解决所有层级问题。Material 3 更强调用容器色、边框、间距和 tonal elevation 共同表达层级。

4.5 Error 和状态色#

error 用于表达错误、失败、危险或破坏性操作。但错误状态不能只靠颜色表达，因为颜色对色弱用户不一定可靠，也可能在动态主题下不够明显。

错误状态应同时包含：

• 错误色，例如 error 或 errorContainer。
• 明确文字，例如“邮箱格式不正确”。
• 靠近出错位置的提示。
• 必要时提供恢复操作，例如“重试”。
• 可访问语义，让辅助技术能读出状态。

表单错误示例：

1
OutlinedTextField(
2
    value = email,
3
    onValueChange = onEmailChange,
4
    label = { Text("邮箱") },
5
    isError = emailError != null,
6
    supportingText = {
7
        if (emailError != null) {
8
            Text(
9
                text = emailError,
10
                color = MaterialTheme.colorScheme.error
11
            )
12
        }
13
    }
14
)

危险操作不一定直接用大面积 error 背景。很多时候 TextButton + 错误色文字 + 确认对话框，比一个大红按钮更合适。

4.6 浅色和深色 Color Scheme#

Material 3 应同时考虑浅色和深色主题。只调浅色模式是不完整的主题设计。

浅色和深色主题不是简单取反：

Compose 中通常分别定义：

1
private val LightColorScheme = lightColorScheme(
2
    primary = Color(0xFF3F5F90),
3
    onPrimary = Color.White,
4
    surface = Color(0xFFFAF8FF),
5
    onSurface = Color(0xFF1A1B20)
6
)
7

8
private val DarkColorScheme = darkColorScheme(
9
    primary = Color(0xFFA8C7FA),
10
    onPrimary = Color(0xFF0A305F),
11
    surface = Color(0xFF121318),
12
    onSurface = Color(0xFFE3E2E9)
13
)

实际项目里建议用 Material Theme Builder 或设计工具生成完整色板，再在真实页面里验证，而不是手工只填几个颜色。

4.7 Dynamic Color#

Dynamic Color 是 Material 3 的代表特性之一。Android 12+ 可以从用户壁纸提取颜色，生成应用 color scheme。

Compose 中常见写法：

1
@Composable
2
fun AppTheme(
3
    darkTheme: Boolean = isSystemInDarkTheme(),
4
    dynamicColor: Boolean = true,
5
    content: @Composable () -> Unit
6
) {
7
    val colorScheme = when {
8
        dynamicColor && Build.VERSION.SDK_INT >= Build.VERSION_CODES.S -> {
9
            val context = LocalContext.current
10
            if (darkTheme) dynamicDarkColorScheme(context) else dynamicLightColorScheme(context)
11
        }
12
        darkTheme -> darkColorScheme()
13
        else -> lightColorScheme()
14
    }
15

16
    MaterialTheme(
17
        colorScheme = colorScheme,
18
        typography = AppTypography,
19
        content = content
20
    )
21
}

使用建议：

• 系统级 Android 应用、个人工具、内容消费类应用适合 dynamic color。
• 品牌强约束产品可以关闭 dynamic color，使用固定品牌色。
• 不要直接把品牌色硬塞进所有组件；应先生成完整 color scheme，再让组件读取角色色。

Dynamic Color 的核心收益是个性化，但它也会带来品牌一致性和测试复杂度问题。是否开启要看产品类型。

动态色开启后仍要检查：

• 主按钮是否足够明显。
• 错误状态是否清晰。
• 深色模式是否可读。
• 品牌标识是否被弱化。
• 图表、状态色、业务颜色是否被主题色干扰。

4.8 Compose 中使用 ColorScheme#

页面中应优先从 MaterialTheme.colorScheme 读取颜色：

1
Surface(
2
    color = MaterialTheme.colorScheme.surface
3
) {
4
    Text(
5
        text = "Material 3",
6
        color = MaterialTheme.colorScheme.onSurface
7
    )
8
}

组件默认颜色通常已经符合 Material 3。比如 Button 默认使用 primary 和 onPrimary，TextField 默认处理 focused、error、disabled 等状态。只有在默认语义不符合产品需要时，才通过 colors 参数覆盖。

封装组件时可以把颜色策略集中起来：

1
@Composable
2
fun DangerButton(
3
    text: String,
4
    onClick: () -> Unit
5
) {
6
    TextButton(
7
        onClick = onClick,
8
        colors = ButtonDefaults.textButtonColors(
9
            contentColor = MaterialTheme.colorScheme.error
10
        )
11
    ) {
12
        Text(text)
13
    }
14
}

这样业务页面只写 DangerButton("删除任务")，不需要每次都手写 error 色。

4.9 颜色检查清单#

设计或实现完一套 color scheme 后，可以按下面检查：

• 浅色和深色模式是否都完整。
• primary 是否只用于关键操作和品牌强调。
• 页面大面积背景是否使用 surface 系列。
• 所有文字是否使用对应的 onXxx 角色。
• 错误状态是否有颜色、文字和语义提示。
• disabled、selected、focused、pressed 状态是否清晰。
• 动态色开启后是否仍有足够对比度。
• 卡片、sheet、dialog 是否能区分层级。
• 边框和分隔线是否使用 outline / outlineVariant。
• 是否存在散落的 hex 色值或 Color.Black / Color.White。

4.10 常见颜色错误#

5.1 排版角色#

可以按下面方式理解这些角色：

Display 要慎用。很多应用界面并不需要 display 级别文字，尤其是工具类、后台类、表单类页面。过大的标题会挤压真正需要处理的信息，降低扫描效率。

5.2 层级选择#

选择文字样式时，先判断文字承担的职责，而不是先看它“应该多大”。

常见选择：

排版层级要和页面结构配合。一个页面里如果到处都是 headline，用户会失去判断主次的依据。反过来，如果所有文字都是 body，页面会显得平，没有扫描路径。

5.3 中文排版注意点#

中文界面不能完全照搬英文排版直觉。中文字符密度高、词边界不靠空格表达，字号、字重和行高的选择会直接影响可读性。

中文排版建议：

• 正文行高要充足，通常不要让行高接近字号。
• 长正文避免过宽，一行过长会显著降低阅读效率。
• 中文界面里过粗字重容易显得压迫，标题常用 medium / semibold 即可。
• 字号层级不要过多，常用 3-5 个层级就够。
• 按钮文案尽量短，但不能为了短牺牲动作含义。
• 不要依赖英文大小写来表达层级，中文没有同样的视觉机制。

如果应用同时有中英文，要检查英文单词变长、中文无空格换行、数字和单位混排等情况。尤其是按钮、Tab、Chip、列表 trailing 区域，最容易出现文字溢出。

5.4 Compose 中定义 Typography#

Compose 中通常在 ui/theme/Type.kt 定义应用排版，再通过 MaterialTheme 注入。

1
val AppTypography = Typography(
2
    headlineLarge = TextStyle(
3
        fontWeight = FontWeight.SemiBold,
4
        fontSize = 32.sp,
5
        lineHeight = 40.sp
6
    ),
7
    bodyLarge = TextStyle(
8
        fontSize = 16.sp,
9
        lineHeight = 24.sp
10
    )
11
)

如果需要统一字体族，可以把 fontFamily 放到各个样式中：

1
val AppFontFamily = FontFamily(
2
    Font(R.font.noto_sans_sc_regular, FontWeight.Normal),
3
    Font(R.font.noto_sans_sc_medium, FontWeight.Medium),
4
    Font(R.font.noto_sans_sc_semibold, FontWeight.SemiBold)
5
)
6

7
val AppTypography = Typography(
8
    titleLarge = TextStyle(
9
        fontFamily = AppFontFamily,
10
        fontWeight = FontWeight.SemiBold,
11
        fontSize = 22.sp,
12
        lineHeight = 28.sp
13
    ),
14
    bodyLarge = TextStyle(
15
        fontFamily = AppFontFamily,
16
        fontWeight = FontWeight.Normal,
17
        fontSize = 16.sp,
18
        lineHeight = 24.sp
19
    ),
20
    labelLarge = TextStyle(
21
        fontFamily = AppFontFamily,
22
        fontWeight = FontWeight.Medium,
23
        fontSize = 14.sp,
24
        lineHeight = 20.sp
25
    )
26
)

页面中使用时，应优先读取 MaterialTheme.typography：

1
Text(
2
    text = "任务详情",
3
    style = MaterialTheme.typography.titleLarge,
4
    color = MaterialTheme.colorScheme.onSurface
5
)

不要在业务页面里到处写 TextStyle(fontSize = 17.sp)。如果某个样式反复出现，它应该进入 typography token 或组件封装。

5.5 排版和颜色的关系#

文字层级不只由字号决定，也由颜色角色决定。Material 3 中常见做法是：

不要手写 Color.Black 或 Color.White。这样会破坏深色模式、动态颜色和可访问性。颜色应来自 MaterialTheme.colorScheme，并和背景色成对使用。

5.6 可访问性和字体缩放#

排版必须支持系统字体缩放。很多界面在默认字号下看起来正常，但用户把字体调大后，按钮、Tab、列表项、输入框就会溢出或裁切。

检查重点：

• 按钮文字变长或字体放大后是否仍能完整显示。
• TopAppBar 标题过长时是否有省略或合理换行。
• TextField 的 label、输入内容、错误文字是否互相遮挡。
• 列表项 supporting text 增多后高度是否稳定。
• 只靠小号灰字表达的重要信息是否仍然可读。

可访问性不是简单把字号调大。真正要做的是保证布局能承受字体缩放，并且重要信息不会因为空间不足被裁掉。

5.7 常见排版错误#

使用建议汇总：

• 页面标题用 headline，不要在卡片里使用 display。
• 按钮文字通常使用 label。
• 长正文优先保证 line height 和可读性。
• 不要用字号表达所有层级；颜色、间距、容器、图标也能表达层级。

6.1 Shape token#

常见规模：

可以按下面方式理解 shape token：

圆角越大，通常越柔和、越轻松；圆角越小，通常越紧凑、越正式。这个规律不是绝对的，但在产品气质上很有影响。

6.2 Shape 和组件语义#

不同组件对 shape 的需求不同。操作型组件强调可点击边界，内容型组件强调分组关系，弹层组件强调层级。

Shape 不应该独立决定层级。一个高层级 dialog 通常还需要 surface container、tonal elevation、遮罩和间距共同表达。

6.3 Compose 中定义 Shapes#

Compose 中可通过 Shapes 定义：

1
val AppShapes = Shapes(
2
    small = RoundedCornerShape(8.dp),
3
    medium = RoundedCornerShape(12.dp),
4
    large = RoundedCornerShape(16.dp)
5
)

如果项目需要更完整的 shape 体系，可以在主题外扩展自己的 shape token：

1
object AppShape {
2
    val chip = RoundedCornerShape(8.dp)
3
    val card = RoundedCornerShape(12.dp)
4
    val dialog = RoundedCornerShape(28.dp)
5
    val bottomSheet = RoundedCornerShape(
6
        topStart = 28.dp,
7
        topEnd = 28.dp,
8
        bottomStart = 0.dp,
9
        bottomEnd = 0.dp
10
    )
11
}

使用时应优先走主题或封装组件：

1
Card(
2
    shape = MaterialTheme.shapes.medium
3
) {
4
    Text("Card content")
5
}

如果某个 shape 反复出现，就不应该散落在业务页面里。把它抽成 token 或组件默认值，后续调整产品风格时更可控。

6.4 品牌气质和圆角策略#

Shape 会明显影响产品气质。

圆角不是越大越现代。过大的圆角会让列表、表单和后台界面显得松散，尤其在信息密度高的页面中，会降低扫描效率。

6.5 局部圆角#

有些组件不是四个角都一样。例如 bottom sheet 通常只有顶部圆角，因为它从屏幕底部升起，底部贴合屏幕边缘。

1
val BottomSheetShape = RoundedCornerShape(
2
    topStart = 28.dp,
3
    topEnd = 28.dp,
4
    bottomStart = 0.dp,
5
    bottomEnd = 0.dp
6
)

局部圆角常见场景：

• Bottom sheet：顶部圆角，底部贴边。
• 顶部图片卡片：图片顶部跟随卡片圆角，底部与内容区相接。
• 分段控件：首尾项有外侧圆角，中间项无圆角。
• 组合输入框：多个字段视觉上属于一组时，外层容器统一圆角。

局部圆角要服务于结构关系，不要为了视觉花样随意改变某一个角。

6.6 Shape、裁剪和点击区域#

在 Compose 中，shape、clip、background、clickable 的顺序会影响视觉和点击反馈。常见问题是背景看起来有圆角，但点击水波纹或内容裁剪没有跟随圆角。

一般原则：

• 组件自带 shape 参数时，优先使用组件参数。
• 需要自定义容器时，注意 clip(shape) 和 background(color, shape) 的配合。
• 可点击区域不应该因为视觉圆角太大而变得难点。
• 图片放在圆角卡片里时，要确认图片也被正确裁剪。

示例：

1
Box(
2
    modifier = Modifier
3
        .clip(MaterialTheme.shapes.medium)
4
        .background(MaterialTheme.colorScheme.surfaceContainer)
5
        .clickable(onClick = onClick)
6
        .padding(16.dp)
7
) {
8
    Text("Clickable container")
9
}

如果使用 Card(onClick = ...)，通常不需要自己组合 clip 和 clickable，因为组件已经处理了 shape、container 和交互反馈。

6.7 自适应中的 Shape#

Shape 也要考虑屏幕尺寸和信息密度。手机上适中的圆角可以增强触控友好感；大屏上如果所有容器都过度圆润，页面会显得零散。

自适应建议：

• compact 宽度下，卡片和按钮可以保持较明显圆角。
• expanded 宽度下，大面积内容区可以更克制，避免每个区域都像独立卡片。
• 大屏 list-detail 中，左侧列表通常不需要每一项都卡片化。
• Dialog、sheet 这类浮层可以保持较大 shape，用来强调层级。

不要为了适配大屏而简单放大圆角。shape 应该和容器尺寸、内容密度一起调整。

6.8 常见 Shape 错误#

设计建议汇总：

• 同一产品中圆角要有规律，不要每个组件随意设置。
• 操作型组件和内容容器可以有不同圆角。
• 企业后台、工具类产品通常不需要过度圆润。
• 游戏、儿童、娱乐类产品可以更大胆。

7.1 Surface 的作用#

Surface 不应该被理解成“灰色背景块”。它是 Material 主题系统中的内容承载面，颜色、形状、边框、间距和 elevation 会一起决定它的视觉层级。

7.2 Surface 颜色角色#

Material 3 中常见 surface 相关颜色：

这些角色的目的，是让不同承载面在浅色和深色主题下都有稳定关系。不要手写一组灰色去模拟它们，否则动态色、深色模式和可访问性都容易失控。

7.3 Surface、Container、Background#

在 Material 3 里，surface 和 container 经常一起出现。

• surface 更像基础承载面，例如页面、主内容区。
• container 更像组件或区域自己的背景，例如卡片、按钮、输入框、弹层。
• background 在旧设计体系里常被频繁使用，但 Material 3 更强调 surface 体系。

典型关系：

不要把 primary 当成通用背景色。大面积 primary 会让页面过重，也会抢走真正关键操作的注意力。

7.4 Compose 中的 Surface#

Compose Material3 提供了 Surface 组件，用来统一处理颜色、内容颜色、形状、边框、阴影和 tonal elevation。

1
Surface(
2
    color = MaterialTheme.colorScheme.surface,
3
    contentColor = MaterialTheme.colorScheme.onSurface
4
) {
5
    Text("页面内容")
6
}

普通内容容器可以这样写：

1
Surface(
2
    shape = MaterialTheme.shapes.medium,
3
    color = MaterialTheme.colorScheme.surfaceContainer,
4
    tonalElevation = 1.dp
5
) {
6
    Column(
7
        modifier = Modifier.padding(16.dp)
8
    ) {
9
        Text(
10
            text = "账户信息",
11
            style = MaterialTheme.typography.titleMedium
12
        )
13
        Text(
14
            text = "用于显示用户资料和状态。",
15
            style = MaterialTheme.typography.bodyMedium
16
        )
17
    }
18
}

如果使用 Card、Dialog、NavigationDrawer 这类组件，通常不需要自己再包一层 Surface，因为这些组件本身已经带有 container、shape 和 elevation 语义。

7.5 Surface 和 Card 的区别#

Surface 更基础，适合构造自定义承载面；Card 是更具体的内容容器组件，带有更明确的 Material 组件语义。

如果只是普通卡片内容，优先使用 Card。如果要构造一个应用自己的面板样式，再考虑 Surface。

7.6 深色模式下的 Surface#

深色模式中，surface 的作用更明显。因为阴影在深色背景上不容易被看见，层级更多依赖 surface container、tonal elevation、边框和间距。

深色模式检查重点：

• onSurface 是否足够可读。
• surface 和 surfaceContainer 是否能区分层级。
• 卡片、dialog、sheet 是否能从背景中分离。
• outline 是否过亮或过暗。
• 错误、选中、禁用状态是否仍然清晰。

不要简单把浅色主题取反当作深色主题。深色主题需要单独检查可读性和层级。

7.7 常见 Surface 错误#

8.1 Shadow elevation 和 tonal elevation#

Shadow elevation 更像“光照下产生的投影”。Tonal elevation 更像“同一套主题中，越高层的 surface 会带有不同的色调”。在深色模式下，tonal elevation 往往比 shadow 更重要。

8.2 Elevation 的使用场景#

Elevation 应该用于解释空间关系，而不是装饰。一个元素如果没有必要浮起，就不应该为了“更好看”加很重的阴影。

8.3 Compose 中的 elevation#

Material3 组件通常暴露 elevation 或 tonalElevation 参数。不同组件 API 不完全一致，但目标都是表达层级。

Surface 示例：

1
Surface(
2
    tonalElevation = 3.dp,
3
    shadowElevation = 1.dp,
4
    shape = MaterialTheme.shapes.medium
5
) {
6
    Text(
7
        text = "Elevated surface",
8
        modifier = Modifier.padding(16.dp)
9
    )
10
}

Card 示例：

1
ElevatedCard(
2
    elevation = CardDefaults.elevatedCardElevation(
3
        defaultElevation = 2.dp,
4
        pressedElevation = 4.dp
5
    ),
6
    onClick = onClick
7
) {
8
    Text(
9
        text = "可点击卡片",
10
        modifier = Modifier.padding(16.dp)
11
    )
12
}

不要给每个容器都手动设置 elevation。很多 Material 组件默认已经有适合的层级。

8.4 状态和 elevation#

Elevation 可以随着交互状态变化。例如按下、拖拽、滚动、展开时，组件的层级可能发生变化。

常见状态：

状态变化要克制。频繁或夸张的 elevation 动画会让界面显得不稳定。

8.5 Elevation、Outline 和间距#

层级不一定都要靠 elevation。很多时候 outline 和间距更清晰。

如果一个后台页面里到处都是投影，信息密度会下降，也会显得嘈杂。工具类页面通常更适合用 outline、间距和 surface container 表达层级。

8.6 深色模式中的 elevation#

深色模式下，阴影不容易看见，tonal elevation 更重要。一个浮层如果只靠阴影，可能会和背景融在一起。

检查方式：

• 在深色模式下打开 dialog、menu、bottom sheet。
• 看浮层是否能从背景中分离。
• 检查 surface container 是否过亮或过暗。
• 检查 outline 是否抢注意力。
• 检查 pressed / selected 状态是否仍然明显。

8.7 常见 Elevation 错误#

使用建议：

• 不要依赖重阴影表达所有层级。
• 卡片、sheet、dialog 可以通过 surface container、outline、间距、tonal elevation 共同表达。
• 深色模式下投影不明显，tonal elevation 更重要。

9.1 Motion 的作用#

Motion 的目标是解释变化，而不是制造变化。没有信息意义的动画，通常应该删掉或弱化。

9.2 常见 Motion 类型#

Ripple 是最基础的反馈，表示“用户点到了这个东西”。它不应该被随意禁用，除非有更清晰的替代反馈。

9.3 Duration 和 Easing#

动效有两个基础参数：持续时间和缓动曲线。

常见经验：

• 小范围状态反馈要快。
• 页面级转场可以稍慢，但不能阻塞操作。
• 进入动画通常可以比退出动画稍明显。
• 高频操作的动画要克制。
• 数据密集型工具页面不适合大量装饰性动效。

Compose 中可以用 tween、spring 等方式控制动画：

1
val alpha by animateFloatAsState(
2
    targetValue = if (visible) 1f else 0f,
3
    animationSpec = tween(durationMillis = 180),
4
    label = "contentAlpha"
5
)

9.4 Compose 中常见动效 API#

示例：空状态和内容切换：

1
AnimatedVisibility(
2
    visible = tasks.isEmpty()
3
) {
4
    EmptyState(
5
        title = "暂无任务",
6
        actionText = "新建任务",
7
        onAction = onAddTask
8
    )
9
}

动效要跟状态绑定，而不是单独存在。比如 visible、expanded、selected、loading 这些状态变化，才是动画触发的依据。

9.5 页面转场#

页面转场要表达导航关系。

转场方向要稳定。用户从列表进入详情，再返回列表，动画方向应该能让人理解“回到原来的地方”。

9.6 减少动效和可访问性#

系统可能开启“减少动效”设置。应用应尊重这类偏好，避免长时间、强位移、循环播放或闪烁动画。

需要特别谨慎的动效：

• 大面积快速移动。
• 闪烁或高频变化。
• 自动循环播放。
• 和阅读内容同时发生的装饰动效。
• 阻塞操作的过长转场。

动效不应该成为理解界面的唯一方式。即使关闭动画，页面结构、状态文案和操作反馈也应该清楚。

9.7 常见 Motion 错误#

10.1 组件状态#

常见组件状态：

状态应该组合使用。例如提交按钮可以同时是 enabled = false 和 loading = true；输入框可以同时是 focused = true 和 error = true。

10.2 State layer#

State layer 是 Material 组件在表面叠加的一层状态反馈，用来表达 hover、focus、pressed、dragged 等交互状态。它不是单独的装饰，而是和组件颜色、形状、ripple 一起工作。

很多 Material 组件已经内置 state layer，不需要手动实现。自定义可点击容器时，要确保点击反馈、焦点反馈和语义状态都完整。

10.3 页面状态#

页面不只有“正常内容”一种状态。真实应用至少要考虑：

页面状态应集中建模，不要散落成多个布尔值。例如：

1
sealed interface TaskListUiState {
2
    data object Loading : TaskListUiState
3
    data object Empty : TaskListUiState
4
    data class Content(val tasks: List<Task>) : TaskListUiState
5
    data class Error(val message: String) : TaskListUiState
6
}

这样 UI 可以根据一个明确状态渲染，而不是同时判断 isLoading、tasks.isEmpty()、errorMessage != null。

10.4 Loading 状态#

Loading 要说明系统正在处理。根据范围不同，可以分成页面级、局部级和按钮级。

Loading 时要避免重复提交。按钮提交中通常应该禁用，并显示明确反馈。

1
Button(
2
    onClick = onSubmit,
3
    enabled = !submitting
4
) {
5
    if (submitting) {
6
        CircularProgressIndicator(
7
            modifier = Modifier.size(16.dp),
8
            strokeWidth = 2.dp
9
        )
10
    } else {
11
        Text("保存")
12
    }
13
}

10.5 Empty 和 Error#

Empty state 不是错误。它表示系统正常工作，但当前没有内容。Error state 表示系统无法完成用户预期，需要解释原因和恢复路径。

错误状态不要只写“出错了”。更好的表达是具体、可行动的，比如“任务加载失败，请检查网络后重试”。

10.6 Selected 和 Focused#

selected 和 focused 很容易混淆。

• selected 表示这个项在业务上被选中，例如当前导航目的地、已选筛选项。
• focused 表示当前键盘、遥控器或辅助技术焦点停在这个控件上。

一个元素可以 selected 但没有 focused，也可以 focused 但没有 selected。比如底部导航中“首页”是 selected，用户用键盘 Tab 到“设置”时，“设置”是 focused，但不一定 selected。

状态表达要同时考虑视觉用户和辅助技术用户。选中状态不要只靠颜色，最好有图标、指示器、文字或语义属性辅助。

10.7 Disabled 状态#

Disabled 表示当前不可操作，但它应该有理由。用户看到禁用按钮时，需要知道为什么不能点。

常见策略：

• 表单不完整时禁用提交按钮。
• 提交中禁用按钮，防止重复请求。
• 权限不足时禁用操作，并在附近说明原因。
• 不要把所有错误都表现成 disabled，有些情况更适合显示错误提示。

禁用状态的可访问性要特别注意。过浅的 disabled 文本可能不可读；完全隐藏操作则可能让用户不知道这个能力存在。

10.8 Compose 中的状态管理#

Compose UI 应该由状态驱动。状态变化后，UI 重新组合并呈现对应界面。

简单状态：

1
var selected by rememberSaveable { mutableStateOf(false) }
2

3
FilterChip(
4
    selected = selected,
5
    onClick = { selected = !selected },
6
    label = { Text("已完成") }
7
)

复杂页面状态建议放到 ViewModel，由 UI 层订阅：

1
val uiState by viewModel.uiState.collectAsStateWithLifecycle()
2

3
when (val state = uiState) {
4
    TaskListUiState.Loading -> LoadingState()
5
    TaskListUiState.Empty -> EmptyState()
6
    is TaskListUiState.Content -> TaskList(tasks = state.tasks)
7
    is TaskListUiState.Error -> ErrorState(message = state.message)
8
}

状态命名要表达业务含义。isRed、showThing 这类名字通常不如 hasError、isSubmitting、selectedTaskId 清楚。

10.9 常见 State 错误#

实践原则：

• 状态先建模，再写 UI。
• 状态反馈要靠近触发位置。
• 加载、错误、空状态都应有明确 UI。
• 操作反馈要快，尤其是按钮、列表项、导航项。
• 状态不能只靠颜色表达。

11.1 布局的基本职责#

布局的第一原则是稳定。按钮 hover、文本变化、错误提示出现、加载状态切换时，页面不应该大幅跳动。固定格式的元素，例如工具栏、列表项、导航项和操作区，应尽量有稳定高度、宽度或最小尺寸。

11.2 常用布局容器#

普通 Column 适合少量静态内容；大量数据应使用 LazyColumn。列表项如果会增删改，应尽量提供稳定 key，避免滚动位置和动画状态混乱。

11.3 间距与内容宽度#

Material 3 界面里的间距要表达分组关系。相关内容之间距离更近，不相关内容之间距离更远。不要只靠分割线区分所有内容。

常见间距策略：

• 页面外边距保持统一，例如 compact 宽度下常用 16dp 左右边距。
• 列表项内部间距稳定，避免每个 item 根据内容随意变化。
• 表单字段之间保持一致间距，错误文字贴近对应字段。
• 大屏正文要设置最大宽度，避免一行文字过长。
• 卡片之间用间距和容器色共同表达层级，不要依赖重阴影。

Compose 示例：

1
LazyColumn(
2
    modifier = Modifier.fillMaxSize(),
3
    contentPadding = PaddingValues(16.dp),
4
    verticalArrangement = Arrangement.spacedBy(12.dp)
5
) {
6
    items(
7
        items = tasks,
8
        key = { it.id }
9
    ) { task ->
10
        TaskListItem(task = task)
11
    }
12
}

11.4 常见布局问题#

• 把所有内容都放进一个大 Column，没有页面骨架和滚动策略。
• 页面横向拉伸后，正文过宽、阅读困难。
• 每个区域都做成卡片，导致信息层级变碎。
• 错误提示出现时把按钮挤到屏幕外。
• 按钮文案变长后宽度变化，操作区来回跳动。
• 列表项高度不稳定，扫描效率低。

12.1 Window Size Class#

Window Size Class 是自适应布局的判断入口。它不是直接告诉你“这是什么设备”，而是把当前可用窗口宽度和高度归类，让界面根据空间做结构变化。

实现时不要把 Window Size Class 当成硬编码设备判断。用户可能在平板上分屏，也可能在桌面上缩小窗口，因此应根据窗口可用尺寸决定布局，而不是根据设备型号决定布局。

Compose 中常见判断方式是先取得窗口尺寸分类，再把它转成应用自己的布局策略：

1
enum class AppLayoutType {
2
    BottomNavigation,
3
    NavigationRail,
4
    PermanentDrawer
5
}

这样业务页面只关心 AppLayoutType，不用到处直接判断 compact、medium、expanded。

12.2 List-detail 和 supporting pane#

List-detail 是大屏最常见的内容组织方式。手机上通常是“列表页 -> 详情页”两级跳转；大屏上可以把列表和详情同时显示。

List-detail 的关键不是多放一栏，而是减少来回跳转。用户在左侧切换对象，右侧保持上下文显示详情，适合高频浏览、比较和编辑。

Supporting pane 更适合辅助信息，例如筛选条件、属性面板、上下文建议、评论区。它不应该抢走主内容焦点，也不应该变成另一个完整页面。

设计注意：

• 左右两栏都要有稳定宽度，避免内容随着选择项频繁跳动。
• compact 宽度下应退回单页导航。
• expanded 宽度下不要让正文无限变宽，长文本需要最大宽度限制。
• 空详情状态要明确，例如“选择一个任务查看详情”。

13.1 Scaffold：页面骨架#

Scaffold 是页面级布局组件，用来组织 Material 页面中最常见的结构：顶部栏、底部栏、内容区、浮动操作按钮和 snackbar。它不负责业务内容本身，而是负责给业务内容提供稳定的页面框架。

Compose 中最容易忽略的是 innerPadding。Scaffold 会根据 top bar、bottom bar、FAB 等区域计算内边距，内容区如果不用它，列表或表单就可能被遮挡。

1
Scaffold(
2
    topBar = {
3
        TopAppBar(title = { Text("Tasks") })
4
    },
5
    floatingActionButton = {
6
        FloatingActionButton(onClick = onAdd) {
7
            Icon(Icons.Default.Add, contentDescription = "添加任务")
8
        }
9
    }
10
) { innerPadding ->
11
    LazyColumn(
12
        modifier = Modifier.padding(innerPadding)
13
    ) {
14
        items(tasks) { task ->
15
            Text(task.title)
16
        }
17
    }
18
}

常见问题：

• 忘记把 innerPadding 传给内容区。
• 把所有页面都塞进一个巨大 Column，导致 top bar、snackbar、FAB 之间没有统一管理。
• FAB 承载多个并列操作，削弱页面主操作。
• 页面级 loading、empty、error 没有统一放在内容区处理。

13.2 TopAppBar：页面标题与操作入口#

TopAppBar 表达当前页面的身份和页面级操作。它不是普通标题栏，而是导航层级、标题和操作区的组合。

常见变体：

结构理解：

• navigationIcon 通常放返回、关闭、打开 drawer 等导航动作。
• title 放当前页面标题，不应该塞过长说明。
• actions 放页面级高频操作，例如搜索、分享、删除。
• 低频操作适合放入 overflow menu，而不是全部展开成图标。

顶级页面通常不放返回按钮；详情页、编辑页、二级页面通常需要返回按钮。这个规则不是视觉偏好，而是在表达页面层级。

1
TopAppBar(
2
    title = { Text("任务详情") },
3
    navigationIcon = {
4
        IconButton(onClick = onBack) {
5
            Icon(
6
                Icons.AutoMirrored.Filled.ArrowBack,
7
                contentDescription = "返回上一页"
8
            )
9
        }
10
    },
11
    actions = {
12
        IconButton(onClick = onDelete) {
13
            Icon(Icons.Default.Delete, contentDescription = "删除任务")
14
        }
15
    }
16
)

13.3 Text 与 Icon：基础信息表达#

Text 是文字信息的最终承载者。Material 3 中不要只从字号理解文本，而要从 typography role 理解文本。标题、正文、标签、按钮文字都应使用不同的排版角色。

常用 typography：

Icon 需要区分“装饰图标”和“操作图标”：

• 装饰图标：contentDescription = null。
• 操作图标：contentDescription 应描述用户动作，而不是机械写图标名称。

错误示例是把删除按钮描述成 "Delete icon"；更好的描述是 "删除任务"。屏幕阅读器用户关心的是动作结果，不是图标长什么样。

13.4 Button：操作强度#

Material 3 的按钮不是只换外观，而是在表达操作优先级。按钮选型应先问“这个操作在当前区域有多重要”。

原则：

• 一个区域内通常只有一个最主要按钮。
• 删除、重置等危险操作不要只靠颜色区分，最好配合文案和确认。
• 按钮文字要表达动作，例如“保存”“创建项目”，不要写“确定”“提交”“下一步”泛化一切的抽象结果。

按钮状态：

• enabled = false 表示当前不可操作。
• loading 状态应阻止重复点击。
• 危险操作不应只靠红色表达，还应结合文案、确认和上下文。

1
Button(
2
    onClick = onSave,
3
    enabled = !isSaving
4
) {
5
    if (isSaving) {
6
        CircularProgressIndicator(
7
            modifier = Modifier.size(16.dp),
8
            strokeWidth = 2.dp
9
        )
10
    } else {
11
        Text("保存")
12
    }
13
}

13.5 Card：内容容器#

Card 表达一个相对独立的内容单元。它适合承载文章摘要、任务项、商品、设置分组、详情片段，但不适合把页面每个区域都包起来。

常见变体：

Card 的关键不是“圆角”，而是容器关系。一个页面里如果所有内容都被卡片包裹，用户反而难以判断哪些内容是主要信息，哪些只是辅助信息。

使用原则：

• 卡片不是万能容器，不要把页面所有区域都卡片化。
• 卡片内部标题通常用 titleMedium 或 titleLarge，不要随便用 display 级别文字，不应该使用过大的 headline。
• 可点击卡片要给整个卡片清晰点击区域，要有明确反馈和语义。
• 卡片之间用间距表达分组，不要依赖重阴影。
• 卡片背景应来自 surface / surfaceContainer 体系，而不是随手写灰色。

13.6 ListItem：稳定列表结构#

ListItem 是列表信息的标准结构，常用于任务列表、设置项、联系人、消息、搜索结果。它提供了稳定的信息槽位。

ListItem 的优势是信息密度稳定，适合大量重复内容。不是所有列表项都需要卡片；普通列表用 ListItem + Divider 往往更清晰。

常见问题：

• trailing 区域塞多个按钮，导致点击目标太小。
• supporting 文本过长，列表高度不稳定。
• 选中态只靠颜色表达，没有图标、文字或语义辅助。
• 列表项点击区域过小，只能点文字。

13.7 TextField：输入与校验#

TextField 不是单纯的输入框，它同时包含字段名称、输入内容、提示、错误、辅助说明和交互状态。

核心概念：

label 和 placeholder 不是一回事。label 告诉用户字段是什么；placeholder 只是输入示例或临时提示。如果只用 placeholder，当用户开始输入后，字段含义可能消失。

常用状态：normal focused error disabled read-only

1
OutlinedTextField(
2
    value = email,
3
    onValueChange = onEmailChange,
4
    label = { Text("邮箱") },
5
    placeholder = { Text("name@example.com") },
6
    isError = emailError != null,
7
    supportingText = {
8
        if (emailError != null) {
9
            Text(emailError)
10
        }
11
    },
12
    singleLine = true
13
)

原则：

• 错误状态要有文字说明,不要只用 snackbar 或 toast 报错,，否则用户需要自己猜哪一项错了。
• label、placeholder、supportingText 不是一回事。
• 表单要考虑键盘、焦点顺序和提交动作。

13.8 NavigationBar、NavigationRail、NavigationDrawer：全局导航#

导航组件表达信息架构。选哪个组件，取决于顶级目的地数量、屏幕宽度和层级复杂度。

全局导航只放顶级目的地，比如首页、搜索、收藏、设置。返回、筛选、排序、详情页操作不属于全局导航。

导航项通常包含：

• 图标。
• 文案。
• selected 状态。
• 目标 route 或 destination。

原则：

• 导航组件表达的是信息架构，不是装饰。
• 顶级目的地不应频繁变化。
• 当前选中项必须清晰可见，用户应该能从导航状态判断“我现在在哪个主区域”。

13.9 Dialog、BottomSheet、Snackbar：临时反馈与决策#

这三类组件都属于临时 UI，但职责不同。

Snackbar 不应该承载复杂决策；Dialog 不应该用于所有提示；BottomSheet 不应该变成另一个完整页面。

删除、重置、退出编辑这类危险操作通常需要确认。确认文案要具体，例如“删除任务”比“确定”更清楚。

13.10 ProgressIndicator 与状态页面#

真实页面必须处理非理想状态。Material 3 组件不仅用于展示正常内容，也要表达加载、空数据、错误、离线、禁用、提交中等状态。

加载状态不要只显示空白页面。错误状态不要只写日志。用户需要知道发生了什么、能不能重试、下一步该做什么。

13.11 Selection controls：选择与设置#

选择类控件要根据数据关系选型。

Switch 适合“打开/关闭通知”这种立即生效的设置，不适合“删除账号”这种需要确认的危险操作。Slider 适合音量、亮度、字号这类连续值，不适合需要精确输入的金额或数量。

设置项文案要表达结果，而不是只写技术名。例如“自动同步”比“sync_enabled”更适合界面。

13.12 Adaptive components：自适应组件#

自适应不是把组件拉宽，而是根据窗口宽度改变导航、内容密度和信息结构。Material 3 通常把窗口分为 compact、medium、expanded。

典型变化：

• 手机上列表和详情分成两个页面。
• 平板上可以左侧列表、右侧详情同时显示。
• 大屏上导航从 bottom bar 变成 rail 或 drawer。
• 内容宽度要有限制，不能无限拉伸正文。

自适应组件要和业务信息结构一起设计。如果只改导航，不改内容组织，大屏仍然会显得空和散。

13.13 常用组件选型速查#

选择组件时要回到三个问题：

1. 这个组件表达什么信息层级？
2. 它在当前页面里是不是最合适的交互形式？
3. 它的 loading、disabled、error、selected 等状态是否完整？

14.1 依赖#

Gradle 示例：

1
dependencies {
2
    implementation("androidx.compose.material3:material3:1.4.0")
3
}

如果使用 Compose BOM，版本通常由 BOM 统一管理：

1
dependencies {
2
    implementation(platform("androidx.compose:compose-bom:<version>"))
3
    implementation("androidx.compose.material3:material3")
4
}

14.2 最小页面骨架#

1
@OptIn(ExperimentalMaterial3Api::class)
2
@Composable
3
fun HomeScreen() {
4
    Scaffold(
5
        topBar = {
6
            TopAppBar(title = { Text("Material 3 Notes") })
7
        },
8
        floatingActionButton = {
9
            FloatingActionButton(onClick = { /* TODO */ }) {
10
                Icon(Icons.Default.Add, contentDescription = "Add")
11
            }
12
        }
13
    ) { innerPadding ->
14
        LazyColumn(
15
            modifier = Modifier
16
                .padding(innerPadding)
17
                .fillMaxSize(),
18
            contentPadding = PaddingValues(16.dp),
19
            verticalArrangement = Arrangement.spacedBy(12.dp)
20
        ) {
21
            items(sampleItems) { item ->
22
                ElevatedCard(onClick = { /* open */ }) {
23
                    ListItem(
24
                        headlineContent = { Text(item.title) },
25
                        supportingContent = { Text(item.subtitle) }
26
                    )
27
                }
28
            }
29
        }
30
    }
31
}

要点：

• Scaffold 负责处理系统化页面结构。
• 内容区要使用 innerPadding，避免被 top bar、bottom bar、FAB 遮挡。
• 尽量让组件读取 MaterialTheme，不要到处硬编码颜色。

14.3 Theme 结构#

1
@Composable
2
fun MyAppTheme(
3
    darkTheme: Boolean = isSystemInDarkTheme(),
4
    content: @Composable () -> Unit
5
) {
6
    val colorScheme = if (darkTheme) {
7
        darkColorScheme()
8
    } else {
9
        lightColorScheme()
10
    }
11

12
    MaterialTheme(
13
        colorScheme = colorScheme,
14
        typography = AppTypography,
15
        shapes = AppShapes,
16
        content = content
17
    )
18
}

组织建议：

1
ui/theme/
2
  Color.kt
3
  Type.kt
4
  Shape.kt
5
  Theme.kt

14.4 Design Token 落地#

Design Token 是把视觉决策变成可复用变量的方式。Material 3 已经提供了颜色、排版、形状等基础 token；应用自己的主题应该在这些 token 之上扩展，而不是在业务页面里散落硬编码值。

常见 token 类型：

Material 3 没有内置统一 spacing token，但项目里通常需要自己维护一套间距规则，例如：

1
object AppSpacing {
2
    val xSmall = 4.dp
3
    val small = 8.dp
4
    val medium = 16.dp
5
    val large = 24.dp
6
    val xLarge = 32.dp
7
}

这样页面写的是 AppSpacing.medium，而不是到处散落 16.dp。好处是后续调整密度、适配平板或统一设计规范时，不需要逐个页面查找。

Token 落地原则：

• 业务页面不直接写品牌色 hex 值。
• 普通文本优先使用 MaterialTheme.colorScheme.onSurface。
• 主操作优先使用 primary，不要把 primary 当页面背景色滥用。
• 间距、圆角、字号一旦形成规律，就应沉淀成 token。
• token 命名表达用途或层级，不表达偶然数值，例如 screenPadding 比 padding16 更稳定。

14.5 基础组件封装#

组件封装不是为了把 Material 组件重新包一遍，而是为了沉淀产品自己的语义和默认策略。封装后的组件应减少重复参数，并让页面代码更接近业务含义。

适合封装的内容：

示例：

1
@Composable
2
fun PrimaryButton(
3
    text: String,
4
    onClick: () -> Unit,
5
    modifier: Modifier = Modifier,
6
    enabled: Boolean = true,
7
    loading: Boolean = false
8
) {
9
    Button(
10
        onClick = onClick,
11
        modifier = modifier,
12
        enabled = enabled && !loading
13
    ) {
14
        if (loading) {
15
            CircularProgressIndicator(
16
                modifier = Modifier.size(16.dp),
17
                strokeWidth = 2.dp
18
            )
19
        } else {
20
            Text(text)
21
        }
22
    }
23
}

封装边界要克制。不要为了“统一”把所有参数都藏起来，也不要把业务规则塞进通用 UI 组件。一个好的封装应该满足：

• 默认样式统一。
• 常见状态内置，例如 loading、disabled、error。
• 仍允许调用方传入必要 modifier 和内容。
• 不依赖具体业务数据模型。
• 名称表达产品语义，而不是只是 MyButton、CommonCard。

15.1 基本原则#

• 颜色对比度足够。
• 点击区域足够大。
• 文字支持系统字体缩放。
• 图标按钮有 contentDescription。
• 状态不能只靠颜色表达。
• 表单错误有文字说明。
• 动效不过度，尊重减少动效设置。
• TalkBack 顺序符合视觉和业务顺序。

可以把可访问性理解成四个层面：

15.2 语义和 contentDescription#

屏幕阅读器依赖语义树理解界面。Compose 中很多 Material 组件已经带有基础语义，但自定义组件、图标按钮、图片和复杂容器仍然需要手动检查。

图标要区分两类：

• 装饰图标：只增加视觉氛围，不提供额外信息，contentDescription = null。
• 操作图标：用户可以点击或它表达重要状态，必须提供可理解描述。

Compose 常见写法：

1
IconButton(onClick = onBack) {
2
    Icon(
3
        imageVector = Icons.AutoMirrored.Filled.ArrowBack,
4
        contentDescription = "返回"
5
    )
6
}

如果图标只是装饰，可以设置 contentDescription = null；如果图标是操作入口，必须提供可理解的描述。

描述应该表达“用户动作”或“信息含义”，不要机械描述图标形状。

15.3 触控目标和交互区域#

可点击区域必须足够大。用户点击的是控件，不是像素级图标。Material 组件通常已经处理了最小触控目标，但自定义 Row、Box、Icon 时容易做得太小。

常见要求：

• 图标按钮不要只让图标本身可点，应使用 IconButton。
• 列表项如果整体可点，应让整个 item 可点，而不是只让文字可点。
• 紧挨着的多个操作要留足间距，避免误触。
• 小屏、单手操作、字体放大后都要检查点击区域。

推荐：

1
ListItem(
2
    headlineContent = { Text(task.title) },
3
    supportingContent = { Text(task.description) },
4
    modifier = Modifier.clickable(onClick = onOpenTask)
5
)

不要只给 Text(task.title) 加 clickable，这样触控区域太小，也不符合用户对列表项的预期。

15.4 颜色对比和非颜色表达#

颜色不能作为唯一状态表达。错误、成功、选中、禁用、警告等状态，都应尽量结合文字、图标、容器、边框或语义。

常见做法：

Material 3 的 onXxx 颜色角色就是为了保证前景和背景有合理对比。不要手写 Color.Gray、Color.Black、Color.White 去覆盖组件默认颜色。

15.5 字体缩放和文本溢出#

用户可能开启系统字体放大。UI 必须在大字号下仍然可用，而不是只在默认字号截图里好看。

重点检查：

• 按钮文字是否被裁切。
• TopAppBar 标题是否过长。
• Tab、Chip、NavigationBarItem 是否文字溢出。
• TextField 的 label、placeholder、supportingText 是否重叠。
• 列表项高度变化后是否仍然可扫描。
• 错误文案是否能完整显示。

布局上应避免硬编码过小高度。固定高度容器如果包住可缩放文字，很容易在字体放大后裁切。

15.6 表单和错误提示#

表单错误要靠近对应字段，并且用明确文案说明怎么修复。

1
OutlinedTextField(
2
    value = email,
3
    onValueChange = onEmailChange,
4
    label = { Text("邮箱") },
5
    isError = emailError != null,
6
    supportingText = {
7
        if (emailError != null) {
8
            Text(emailError)
9
        }
10
    },
11
    singleLine = true
12
)

不要只用 snackbar 或 toast 提示表单错误。用户需要知道具体哪个字段错了，以及怎么改。

错误文案建议：

15.7 焦点顺序和 TalkBack#

TalkBack 顺序应符合视觉顺序和业务顺序。自定义布局中，如果视觉上是从上到下、从左到右，语义顺序也应尽量一致。

需要检查的场景：

• 自定义 Row/Column 嵌套很深。
• 多个 IconButton 连在一起。
• 列表项里同时有点击项和 trailing 操作。
• Dialog、BottomSheet 打开后焦点是否进入浮层。
• 关闭浮层后焦点是否回到合理位置。

复杂组件可以通过 Compose semantics 调整语义：

1
Modifier.semantics {
2
    contentDescription = "任务已完成"
3
    selected = true
4
}

但不要滥用 semantics 覆盖组件默认语义。优先使用 Material 组件的内置语义，只有自定义组件表达不清楚时再手动补充。

15.8 动效和减少动效#

动效要尊重系统减少动效设置。对于运动敏感用户，大面积移动、快速缩放、闪烁、循环动画都可能造成不适。

建议：

• 动效服务于理解，不做无意义装饰。
• 避免长时间循环动画。
• 避免大范围快速位移。
• loading 动画不应影响用户阅读主要内容。
• 即使关闭动效，状态变化也要能通过布局、文案和状态表达理解。

15.9 Compose 可访问性检查点#

Compose 页面可以按下面清单检查：

• 所有可点击图标都有清晰 contentDescription。
• 装饰图标使用 contentDescription = null。
• 可点击区域足够大。
• 重要状态不只靠颜色表达。
• 表单错误有字段级说明。
• loading、empty、error、disabled 状态都有明确 UI。
• 字体放大后文本不裁切、不重叠。
• TalkBack 朗读顺序符合视觉和业务顺序。
• Dialog / BottomSheet 的焦点行为合理。
• 动效不过度，并尊重减少动效偏好。

15.10 常见 Accessibility 错误#

16.1 Theme Builder 解决什么问题#

手工配色容易出现几个问题：

• 只选了一个品牌色，没有完整 light/dark scheme。
• 前景色和背景色对比度不稳定。
• primary、surface、error 等角色语义混乱。
• 深色模式只是简单取反。
• 设计稿和代码里的颜色无法对应。

Theme Builder 的作用是把“品牌核心色”变成“可落地的主题系统”。它生成的不是装饰色板，而是一套应用主题 token。

典型用途：

• 设计阶段快速探索品牌色。
• 生成 light/dark color scheme。
• 验证颜色角色，而不是手工拍脑袋配色。
• 交付设计 token 给工程实现。

16.2 输入和输出#

Theme Builder 的输入通常包括：

输出通常包括：

不要只复制某几个颜色。真正有用的是完整 color scheme，因为 Material 组件依赖的是一组角色关系。

16.3 核心色选择#

核心色选择会影响整个主题气质。选色时要考虑品牌、产品类型、使用场景和可访问性。

选择建议：

• 品牌已有明确主色时，优先使用品牌主色作为 primary seed。
• 专业工具不要选过于高饱和的主色，否则界面容易疲劳。
• 内容阅读类产品的主色应克制，避免干扰正文。
• 金融、安全、医疗、工业类产品要优先考虑可信和清晰。
• 娱乐、生活方式产品可以更大胆，但仍要检查对比度。

不要用纯黑、纯白或过亮荧光色作为核心色。它们生成的色板往往难以在浅色和深色模式里保持稳定。

16.4 生成后检查什么#

Theme Builder 生成结果后，不要只看色板是否好看，要放到真实界面里验证。

检查重点：

验证方式：

1. 放到真实首页、列表页、表单页、详情页中看。
2. 同时检查浅色和深色模式。
3. 检查按钮、输入框、错误状态、选中态、禁用态。
4. 开启动态颜色时再检查一次。
5. 用真实中文文案和真实数据测试。

16.5 导出到 Compose#

Theme Builder 可以帮助生成 Android 或 Compose 主题代码。落地时通常会放到 ui/theme/Color.kt 和 Theme.kt。

典型结构：

1
ui/theme/
2
  Color.kt
3
  Type.kt
4
  Shape.kt
5
  Theme.kt

Color.kt 中保存 light/dark scheme 需要的颜色：

1
private val LightColorScheme = lightColorScheme(
2
    primary = Color(0xFF3F5F90),
3
    onPrimary = Color(0xFFFFFFFF),
4
    primaryContainer = Color(0xFFD5E3FF),
5
    onPrimaryContainer = Color(0xFF001B3D),
6
    surface = Color(0xFFFAF8FF),
7
    onSurface = Color(0xFF1A1B20)
8
)
9

10
private val DarkColorScheme = darkColorScheme(
11
    primary = Color(0xFFA8C7FA),
12
    onPrimary = Color(0xFF0A305F),
13
    primaryContainer = Color(0xFF274777),
14
    onPrimaryContainer = Color(0xFFD5E3FF),
15
    surface = Color(0xFF121318),
16
    onSurface = Color(0xFFE3E2E9)
17
)

Theme.kt 中根据深色模式和 dynamic color 策略选择 scheme：

1
@Composable
2
fun AppTheme(
3
    darkTheme: Boolean = isSystemInDarkTheme(),
4
    dynamicColor: Boolean = false,
5
    content: @Composable () -> Unit
6
) {
7
    val colorScheme = when {
8
        dynamicColor && Build.VERSION.SDK_INT >= Build.VERSION_CODES.S -> {
9
            val context = LocalContext.current
10
            if (darkTheme) dynamicDarkColorScheme(context) else dynamicLightColorScheme(context)
11
        }
12
        darkTheme -> DarkColorScheme
13
        else -> LightColorScheme
14
    }
15

16
    MaterialTheme(
17
        colorScheme = colorScheme,
18
        typography = AppTypography,
19
        shapes = AppShapes,
20
        content = content
21
    )
22
}