从"套壳"到"原生":基于 Material Design 3 的 Android 平台设计规范——whodb 仓库 Impeccable 设计技能 Android 平台参考详解
从"套壳"到"原生":基于 Material Design 3 的 Android 平台设计规范——whodb 仓库 Impeccable 设计技能 Android 平台参考详解
本文以 whodb 仓库中 Impeccable 设计技能(
.agents/skills/impeccable)的 Android 平台参考文档 android.md 为核心骨架,结合其配套的脚本与兄弟参考文档,系统讲解"如何让一个原生 Android 应用(无论基于 Jetpack Compose、Android Views,还是 React Native、Expo、Flutter)做到真正的 Material 原生质感"。读完本文,你将掌握:Android 平台设计的最低质量线(Android slop test)、布局与导航结构、48×48 dp 触控目标、Material 字体/色彩/主题体系、组件与动效选择,以及这套规范如何被转化为可打分的自动化审计标准与跨平台适配策略。
这份文档在项目中扮演什么角色
android.md 并不是一份孤立的界面美化建议,而是 whodb 仓库内置的 Impeccable 前端设计技能(定义于 SKILL.md)所依赖的"平台规范层"之一。该技能覆盖网页、桌面端、iOS、Android 等场景,其工作流要求:当目标平台被识别为 android 时,任何设计、重构、审计、适配操作都必须先以这份规范作为评分基准。
这份规范的实际加载逻辑写在技能脚本 context.mjs 中:函数 loadNativePlatformReferences(platform) 会根据记录的平台值读取对应的平台参考文档——adaptive 会同时加载 ios.md 与 android.md,ios 或 android 则只加载各自的文档。这意味着:
- 在会话初始化阶段,脚本会通过 PRODUCT.md 的
## Platform字段判定平台(合法取值为web、ios、android、adaptive,见 context.mjs); - 平台判定为原生(
ios/android/adaptive)时,对应的平台参考会自动进入后续所有设计命令的上下文; - 在
init流程中,如果新记录的平台恰好是ios、android或adaptive,也会在进入任何设计工作之前主动加载相应规范(见 init.md)。
换言之,这份 android.md 就是"Android 原生设计是否达标"的裁判手册:下文介绍的所有布局、触控、排版、色彩、组件、动效规则,都会被 audit.native.md 逐条映射为可打分的检查项。
适用范围:哪些技术栈受这份规范约束
文档开篇明确了适用范围——所有最终运行在 Android 硬件上的原生应用:
- 原生 UI 框架:Jetpack Compose、Android Views;
- 跨平台框架:React Native、Expo、Flutter(只要最终产物部署到 Android 设备)。
一个关键的设计哲学是:在原生平台上,"访客模式"(Persuade / Operate / Read / Experience 四种模式)会收窄表达自由的边界。Material Design 3 在任何模式下都管辖结构、导航与交互;品牌只能通过 Material 的主题体系(色彩角色、字号层级、形状、动效)来表达,而不是通过推翻平台组件来表达。
对于"同时出货到 iPhone"的 Material-everywhere 跨平台应用,文档特别强调:即便你在 Android 上全面采用 Material,只要应用运行在 iPhone 硬件上,就仍然欠 iOS 一份"操作系统级保证"——安全区域 insets、Reduce Motion、边缘滑动返回。这正是 ios.md 存在的意义,也是 adaptive 平台模式下两份参考必须同时加载的原因。
Android slop test:如何一眼识别"iOS 套 Android 皮"
文档给出的验收问题是:一个熟练的 Android 用户会信任这个应用,还是会在不合规的组件前卡壳?
最常见的翻车模式(即"披着 Android 皮肤的 iOS 应用")有三个典型信号:
- 从 iPhone 照搬的底部导航:iOS 的 Tab Bar 被直接移植成 Android 唯一的导航方式;
- 忽略系统返回手势的后退箭头:应用内自制返回按钮,无视 Android 的预测性返回手势(predictive Back gesture)与返回键;
- Cupertino 形状的开关和对话框:把 iOS 风格的开关(switch)、弹窗直接搬到 Android 上。
文档给出的裁决很明确:Material 3 就是规则手册(rulebook)——跟随它的组件,并让品牌通过它来表达,而不是绕过它。
这套"slop test"在技能中被进一步系统化:audit 命令的 Platform Conformance(平台一致性)维度会直接以这份规范及其 slop test 作为打分依据(见 audit.native.md),检查项包括系统手势是否被破坏、inset 是否违规、是否存在跨平台控件移植、是否混用图标集等。
布局与结构:把 Material 导航装进正确的窗口尺寸
文档对布局与结构给出四条硬性要求:
按尺寸匹配的 Material 导航
- 紧凑宽度(compact width):使用底部导航栏(navigation bar),3~5 个目的地;
- 展开宽度(expanded width):切换为导航栏(navigation rail)或抽屉(drawer);
- 严禁把手机版底部导航栏原封不动地搬到平板上。
这与 adapt.native.md 的"Phone → Tablet"策略完全呼应:平板不是手机的放大版,必须用**窗口尺寸类(window size classes)**驱动结构切换,而不是拉伸布局。折叠屏(foldable)场景同样依赖窗口尺寸类来响应姿态与铰链变化,需要分别测试折叠、展开、桌面三种形态。
系统返回永远可用
必须尊重 Android 的预测性返回手势和返回键,绝不困住用户、绝不劫持返回手势。在 audit 中,这条对应"predictive Back hijacked"(劫持预测性返回)的违规检查。
Edge-to-edge 与窗口 insets
状态栏、导航栏、刘海/挖孔(display cutout)、输入法(IME)的 insets 必须全部正确处理,确保内容永远不会被系统栏或软键盘遮挡。
顶栏 + 单一主操作
每个屏幕用顶部应用栏(top app bar)提供屏幕上下文;当屏幕存在唯一主要操作时,配合一个 FAB(悬浮操作按钮)。
触控目标:48×48 dp 是底线不是建议
文档给出的数字非常具体:
每个触控目标的最小尺寸为 48×48 dp,相邻目标之间至少保留 8 dp 间距。
这条规范同时呼应了 layout.md 中的"即使可见标记很小,触控目标也必须可用",以及 audit.native.md 的检查项"低于 48 dp 或排列过密的触控目标"。作为对照,iOS 侧的最低标准是 44×44 pt——跨平台团队在 adaptive 模式下需要同时满足两套阈值。
排版体系:用角色说话,用 sp 呼吸
Android 平台的排版规则围绕 Material 字阶(type scale)展开:
- Material 字阶角色:Display、Headline、Title、Body、Label 五大类,每类又分 large / medium / small 三档。设计时必须把文本映射到这些角色上,禁止每个屏幕手工挑选字号;
- Roboto 是系统字体:品牌字体通过字阶体系注入,同时保证正文、标签、控件保持可读性与一致性;
- 一律使用 sp 单位,绝不使用固定 px:这样文本才能跟随系统字体大小设置缩放。
typeset.md 进一步把这条规范扩展为原生平台的一般原则:必须保留平台文本缩放能力(Android 的 sp 缩放),并单独验证"大字号下布局是否裁剪或重叠"——这正是 audit 中 Accessibility 维度的检查点之一。此外它强调字号体系要"角色最少、层级分明",用字号/字重/字距/色调的组合拉开层级,而不是只靠字号硬撑。
色彩与主题:角色 token 优先,动态取色兜底
Material 色彩角色
使用 Material 色彩角色(primary、on-primary、surface、surface-variant、secondary-container、outline、error 等)。这些角色 token 会自动解析亮/暗主题与对比度变体,而裸 hex 色值会在深浅色切换时直接失效。这条规则在 audit.native.md 中对应"硬编码颜色 / 语义色缺失"的扣分项:得分 0 的定义就是"到处硬编码"。
Dynamic Color(Material You)
在合适的场景启用动态取色:Android 12+ 上从用户壁纸推导配色方案,并且必须提供静态回退方案。audit 中的 Appearance & Theming 维度明确检查"没有静态回退方案"与"在适用场景忽略 Dynamic Color"两类问题。
暗色主题是一等公民
暗色主题是一等方案(first-class scheme),必须专门设计并测试,严禁简单反色。这与 whodb 自身 PRODUCT.md 中"暗色与亮色模式都是一等公民,不做事后主题化"的设计原则一致,可见这套平台规范与仓库自身的品质标准是同构的。
色调层级(Tonal elevation)
通过标准的 surface 色调层级(辅以适当的阴影)表达高程,禁止随手添加任意投影。这既避免了阴影系统的失控,也让"层级"拥有统一的语义。
组件与动效:标准组件、单一 FAB、Material 运动模式
组件库清单
文档明确要求使用 Material 标准组件:按钮(filled / tonal / outlined / text 四种风格)、FAB、开关(switch)、chips、snackbar、底部弹层(bottom sheets)、Material 对话框、导航栏/导航栏/抽屉。绝不移植 iOS 控件,也不要发明"等效"控件。
一条 FAB 铁律
一个屏幕只有一个 FAB,只服务于单一主要操作:禁止堆叠 FAB,禁止把 FAB 花在次要任务上。这条与布局章节的"顶栏 + 唯一主操作"严格配对。
瞬态反馈的正确容器
- Snackbar 用于瞬态反馈(必要时可带操作项),但不要用 toast 承担这个职责;
- **对话框(dialog)**只用于"必须打断用户"的决策场景。
Material 动效模式
采用 Material 运动模式:container transform、shared-axis、fade-through,配合标准缓动与时长;同时必须尊重系统级 Remove animations(移除动画)设置——检测到时应回退为交叉淡入(crossfade)或直接瞬时切换。
animate.md 对原生平台的指令与此一致:"遵循 ios.md 或 android.md 的 Motion 章节(包括平台的 Reduce Motion 行为),不要套用 web 工具"。它给出的动效时长参考(100–150 ms 即时反馈、150–300 ms 常规状态变化、300–500 ms 布局/浮层/视图切换)可以作为 Material 标准缓动的落地量化参考。
从规范到执行:规范如何变成可打分的审计与可执行的适配
这份 android.md 的价值在于它不是"仅供参考",而是被 Impeccable 技能整体转化为可执行的工程动作:
五维审计打分
audit.native.md 以平台参考(ios.md / android.md)为评分基准,从源码层面(Compose / React Native / Flutter 源码,而非浏览器工具)对原生应用做五维检查,每维 0~4 分:
| 维度 | 与 android.md 的对应检查 |
|---|---|
| 1. 无障碍(TalkBack) | 标签缺失、sp 固定字号、48 dp 触控目标、Reduce Motion 被忽略、对比度 |
| 2. 性能 | 慢启动、未虚拟化列表(缺少 LazyColumn)、主线程掉帧、Compose 多余重组 |
| 3. 外观与主题 | 硬编码 hex、暗色模式失修、Dynamic Color 无回退、自绘 material |
| 4. 平台一致性(关键维度) | 预测性返回被劫持、inset 违规、iOS 模式搬到 Android、web 形状控件、混用图标集 |
| 5. 自适应 | 平板被拉伸、横屏裁切、键盘遮挡输入、多窗口/折叠屏失效 |
总分 20 分,并按 P0(阻断)/P1(重大)/P2(次要)/P3(打磨)四级给问题定级;每个问题都必须标注违规的是哪条 Material 规则,并推荐对应的修复命令。
跨平台翻译表
adapt.native.md 给出了一张 iOS ↔ Android 的习惯翻译表,恰好是 android.md "绝不移植 iOS 控件"的正面操作清单:
| iOS | Android |
|---|---|
| Tab Bar | 导航栏 / rail / 抽屉 |
| 边缘滑动返回、返回 chevron | 预测性返回手势 / 返回键 |
| Switch、分段控件、系统选择器 | Material 开关、chips、Material 选择器 |
| Action sheet | 底部弹层 / Material 对话框 |
| SF Symbols、SF Pro、Dynamic Type | Material Symbols、Roboto、sp 缩放 |
| 语义系统色、材质 | Material 色彩角色、色调层级 |
| 系统 push/sheet 转场 | container transform、shared-axis、fade-through |
适配的正确姿势是"翻译习惯(translate idioms),而非移植控件(transplant them)":品牌的表现层(配色意图、字体强调、动效性格)应该通过目标平台的主题系统继承过去,导航和控件则必须在目标平台的语汇里重建。
一套贯穿全流程的"原生准入线"
综合来看,android.md 在技能里承担的是"原生质量准入线"的角色:
init记录平台后立即加载本规范(init.md);adapt做平台/设备适配前先读目标平台参考(adapt.native.md);layout、typeset、animate在原生场景下都以本规范为最终裁决(分别见 layout.md、typeset.md、animate.md);audit按本规范逐条打分并生成 20 分制健康报告。
结语:把"像 Android"从感觉变成检查表
android.md 这份平台参考的可贵之处,在于它把"原生感"这种模糊感受拆解成了可逐条核对的硬指标:48×48 dp 的触控目标、8 dp 间距、Material 字阶与 sp 单位、色彩角色 token、Dynamic Color 静态回退、一等公民的暗色主题、色调层级、单一 FAB、snackbar/对话框的职责边界、container transform 等 Material 动效模式、以及必须响应的系统返回与 Remove animations。对任何向 Android 硬件出货的团队(无论是 Jetpack Compose、Android Views 还是 React Native、Expo、Flutter),这份规范加上技能配套的 audit 五维打分与 adapt 翻译表,就是一套可直接落地执行的"Android 原生质量准入线"。下次再遇到"底部只有一个 Tab Bar、返回箭头无视系统手势、开关长得像 Cupertino"的应用时,你已经知道它输在哪一条了。