colors.xml 颜色值必须严格为 #rrggbb 或 #aarrggbb 格式，缩写、空格、非法字符均导致编译失败；主题色与语义色应分离存放，命名需具业务含义；语义色应不透明，透明度由控件层控制；compose 不自动同步 colors.xml，需显式读取资源。
colors.xml 里写错颜色值会直接编译失败
android 要求所有 #RRGGBB 或 #AARRGGBB 格式必须严格 6 位或 8 位，少一位（比如 #RGB）或带空格、字母超范围（如 #GGGGGG）都会报 Failed to parse color 错误。gradle 不会帮你容错，也不会在预览里提示——等你运行才炸。
-
#FF0000✅ 合法，不透明红色 -
#F00❌ 编译失败，缩写不被 colors.xml 支持（只在 XML layout 的android:background等属性中支持） -
#FF0000FF✅ 合法，带 alpha 的红色（注意 AARR 顺序） -
#0000FF00❌ 错误，alpha 在前才是标准格式，这个会被当黑色 + 无效 alpha 解析
主题色和语义色别混在同一个 colors.xml 里
把 colorPrimary 和 color_error_text 都塞进 res/values/colors.xml 看似省事，实际会让样式维护变脆弱。系统主题色（colorPrimary、colorSurface）是 Material Design 主题引擎依赖的 key，一旦你手动覆盖它们又没同步更新 themes.xml，Dark Mode 切换或动态配色（Material You）就会失效。
- 推荐拆开：
res/values/colors_theme.xml（只放colorPrimary等主题键） +res/values/colors_semantic.xml（放color_success_icon、color_hint_text等业务语义色） - 语义色名必须带含义，避免用
red_1、blue_dark这类纯视觉命名——ui 改版时你根本不知道哪处用了它 - 如果项目已用 androidx Core 的
ContextCompat.getColor()，确保传入的是资源 ID（R.color.xxx），不是硬编码值，否则深色模式切换后颜色不会自动适配
透明度别靠改 alpha 值“凑”出新颜色
有人喜欢在 colors.xml 里写 #80FF0000 当“半透红”，这在浅色模式下看着没问题，但切到深色模式后，同一 alpha 值叠加在深色背景上，视觉明度可能突变，导致文字可读性崩坏。
- Material 官方建议：语义色应定义为不透明色（
#RRGGBB），透明效果统一由控件层控制（比如TextView的android:alpha或View.setAlpha()） - 如果真要多级灰阶（如 disabled 状态），用独立色值定义更可控：
color_text_disabled对应#616161（深色模式下对应#BDBDBD），而不是靠 alpha 动态算 - 注意
#AARRGGBB的 alpha 是十六进制，#80≈ 50% 透明，但人眼对亮度感知是非线性的——#40并不等于“一半再一半”，实测常需调成#33或#55才协调
Jetpack Compose 项目里 colors.xml 依然有用，但别指望它自动同步
Compose 使用 MaterialTheme.colorScheme 管理颜色，但它默认不读 colors.xml。你不能以为在 XML 里改了 colorPrimary，Compose 的 primary 就会跟着变——它俩完全解耦。
- 若用
Theme.kt手动构建ColorScheme，得显式读取资源：val primary = androidx.core.content.ContextCompat.getColor(context, R.color.colorPrimary) - 更稳妥的做法：在
colors.xml定义基础色（color_primary_base），再在themes.xml中用?attr/colorPrimary引用它；Compose 层则通过LocalContext.current拿 context 去查，保证两端源头一致 - 别在 Compose 可组合函数里硬写
Color(0xFF0000FF)——这种写法绕过所有资源管理，后续换肤、动态色、L10N 全都失效
颜色配置真正难的不是写对格式，而是让每种颜色在 Light/Dark/AMOLED/低对比度等所有场景下都保持语义稳定。很多人卡在“看着差不多”，结果一开 TalkBack 或切到 OLED 屏，才发现 color_hint_text 在深色模式下灰得看不见。