Impeccable 原生 Android 设计基准：用 Material 3 约束 AI 产出可信 Android 体验的完整指南

Impeccable 原生 Android 设计基准：用 Material 3 约束 AI 产出可信 Android 体验的完整指南

【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable

导读

android.md是 Impeccable 设计技能中面向原生 Android 平台的一张"规则参考卡"：它定义了当 AI（或你）为一个会真正安装到 Android 设备上的应用做设计、重设计、审计或改造时，必须遵守的 Material Design 3 基线——从导航结构、触控目标、字体排印、颜色主题到构建验证的 adb 截图取证方法。读完本文，你将掌握 Impeccable 如何把"原生可信"翻译成可执行的规则（含每条规则的机器可读锚点），并能在真机/模拟器上按规范完成截图取证与暗色、字体缩放检查。相关参考文档位于.rovodev/skills/impeccable/reference/android.md（skill 目录下有同源副本 skill/reference/android.md）。

1. 这份文档在 Impeccable 体系中的角色

在 Impeccable 技能中，参考文档按平台拆分：web、ios.md、android.md，以及自适应场景两者都读。android.md是一个**"什么时候会被载入"的强制约束**，而不是可选项：

• 运行context.mjs做会话初始化时，如果加载到原生平台指导，会遵循其指令载入本文件；
• init.md 在把平台记录为ios/android/adaptive之后，"before any design work" 就要加载对应的平台参考（这是唯一能学到平台答案的地方）；
• audit.native.md 明确说它按平台参考打分："Score against the platform reference(s): ios.md / android.md"，并在 0–4 的评分标准里把0=Web port（没有任何原生特征）列为最差档；
• adapt.native.md 做跨上下文适配前要求先读目标平台的参考；
• animate.md 规定原生平台动效必须遵循 ios.md/android.md 的 Motion 一节，包括平台级的 Reduce Motion 行为，而不是套用 web 那套工具。

换句话说，android.md 是原生 Android 任务的"准入规则书"：web 检测器（detect.mjs 等）只读 HTML/CSS，"对原生代码没有裁决权"，所以这份文档连同 finish-reviewer 的底限检查，是 Android 上唯一的 slop 闸门（见 new-work.md 中关于 native 平台跳过后台检测器的说明）。

1.1 文档的适用范围界定

For native Android apps: Jetpack Compose, Android Views, React Native, Expo, Flutter shipping to Android hardware.

适用范围覆盖所有"真实运行在 Android 硬件上"的技术栈：Jetpack Compose、传统 Android Views、React Native、Expo、Flutter。移动端 Web（mobile web）不属于这里——那是 web 参考的领域；用原生壳包一个网站也不会让你的设计语言变成原生。

1.2 三条总纲

1. On native, the visitor mode narrows what expression may override.Impeccable 的 visitor mode（Persuade / Operate / Read / Experience，见 SKILL.src.md）在原生平台上只决定"品牌表达能在哪些层发挥"，不能推翻平台自身的结构约定。
2. Material Design 3 governs structure, navigation, and interaction in every mode.无论哪种模式，结构、导航、交互都由 Material 3 统辖；品牌通过 Material 的主题体系来表达——color roles（颜色角色）、type scale（字体尺度）、shape（形状）、motion（动效）。
3. 跨平台仍要对每块硬件负 OS 责任。一个"Material 无处不在"的跨平台应用如果同时发布到 iPhone，在 iOS 硬件上依然欠它 iOS 的系统保证：safe-area insets、Reduce Motion、edge-swipe back。这与 ios.md 的规则互为镜像。

2. Android slop 测试：一眼识别"套着 Android 皮的 iOS 应用"

文档给出了一个非常实用的自检问题：

Would a fluent Android user trust this app, or trip on off-spec components?

一个熟练的 Android 用户会信任这个应用，还是会在一堆不符合规范的组件上绊倒？最常见的"tell"（露馅信号）恰恰是一个披着 Android 皮肤、内核却是 iOS 的应用：

• 从 iPhone 照搬过来的仅底部导航；
• 无视系统 Back 手势的自绘返回箭头；
• Cupertino 形状的开关和对话框。

结论直截了当：Material 3 就是规则书（rulebook）——跟着它的组件走，再通过它去主题化品牌。对照 audit.native.md 的评分，只要出现"3–4 种违规"就属于 Heavy violations，说明 fluent 用户已经无法信任界面。

3. 布局与结构（Layout & structure）

3.1 Material 导航，匹配窗口宽度

绝不要把一个手机底部栏原封不动搬到平板上。平板改用 rail/drawer，这是 Material 3 响应式导航的标准决策，不是口味问题。

3.2 系统 Back 必须始终有效

尊重预测性返回手势（predictive Back gesture）和 Back 按钮。应用永远不能困住用户（trap the user），也不能劫持（hijack）这个手势。这是 Android 手势导航的肌肉记忆，改写它的代价是信任崩塌。

3.3 Edge-to-edge 与窗口 insets

内容必须正确应用以下 insets，保证不被系统元素遮挡：

• status bar（状态栏）
• navigation bar（导航栏）
• display cutout（刘海/打孔屏）
• IME insets（软键盘弹出时）

否则输入法弹起时表单被键盘盖住、内容藏在系统栏后面，都属于文档明确禁止的状态。

3.4 Top app bar + 单一主操作 FAB

每个屏幕用top app bar交代屏幕上下文；当且仅当屏幕有一个主要动作时，配合一个FAB（Floating Action Button）。

这些条目在副本 skill/reference/android.md 中以 HTML 注释锚点标注为可机器读取的规则：android-layout-adaptive-nav、android-layout-system-back、android-layout-window-insets、android-layout-top-app-bar。

4. 触控目标（Touch targets）

48×48 dp 是每个触控目标的最小尺寸，目标之间至少间隔 8 dp。

48dp 是 Material 触控目标的物理下限（约 7–10mm，对应指尖的稳定命中区域），8dp 间距防止相邻目标误触。低于此值的按钮、图标按钮、列表项、chip 都是需要修复的违规项——这正是 audit.native.md 会抓取的 "touch target" 类技术缺陷。对应规则锚点：android-touch-target-48dp。

5. 字体排印（Typography）

5.1 Material type scale：按角色映射，绝不逐屏手挑字号

Material 3 的类型尺度包含 Display、Headline、Title、Body、Label 五组角色，每组又有 large / medium / small。正确做法是：

• 把文本映射到角色上（这篇是 Body large、那个统计数字是 Headline medium……）；
• 永远不要为了某个屏幕单独手挑字号。

角色体系保证整个应用的层级和节奏一致，也让主题替换（换品牌字体）自动传导到每一处。

5.2 Roboto 是系统脸，品牌脸通过 type scale 进入

Roboto 是 Android 系统字体。品牌字体应以"brand face"的身份经由 type scale 主题化进入界面，同时保持正文、标签和控件可读、一致。

5.3 用 sp，绝不用固定 px

字号必须使用sp（scalable pixels），这样文字会跟随系统的字号设置（font scale）缩放；固定 px 会让大字模式下的界面直接截断或溢出——后文"构建验证"一节正是用来抓这种毛病的。

对应规则锚点：android-typo-type-scale、android-typo-system-font、android-typo-scalable-sp。

6. 颜色与主题（Color & theming）

6.1 Material color roles 取代裸 hex

文档点名的角色：primary、on-primary、surface、surface-variant、secondary-container、outline、error。这些角色令牌（role tokens）会自动解析亮色/暗色（light/dark）以及对比度变体；而直接写死的原始 hex 会在这些自适应场景里失效——因为同样的 hex 在暗色主题、高对比度下并不会自动变换。

6.2 Dynamic Color（Material You）

在合适的产品上使用Dynamic Color：Android 12+ 可以从用户壁纸推导出配色方案（dynamic color scheme），同时必须准备静态回退（static fallback）——因为并非所有设备、所有启动器都启用壁纸取色。

6.3 暗色主题是一等公民

Dark theme is a first-class scheme. Design and test it; never a quick invert.

暗色不是把亮色反相（invert）就完事，必须专门设计和测试。

6.4 色调高程（Tonal elevation）

通过标准 surface 色调层级来表达高程（Material 3 中抬高的 surface 用更浅的 surface 色调而非阴影），必要时才辅以阴影；禁止任意自定义投影。

对应规则锚点：android-color-role-tokens、android-color-dynamic-color、android-color-dark-theme、android-color-tonal-elevation。

7. 组件与动效（Components & motion）

7.1 用 Material 组件，禁止移植 iOS 控件或自创替代品

• 按钮体系：filled / tonal / outlined / text 四种；
• FAB、switch、chip、snackbar、bottom sheet、Material dialog；
• 导航：navigation bar / rail / drawer。

绝不要移植 iOS 控件（比如 Cupertino switch、iOS 风格弹窗），也不要凭空发明等价物。这是整份文档反复强调的最常见 native slop 来源。对应锚点android-components-material。

7.2 一个 FAB = 一个主操作

永不堆叠 FAB（不搞 FAB 组），也不要把一个 FAB 花在次要任务上。锚点android-components-single-fab。

7.3 瞬态反馈用 Snackbar，打断式决策才用 Dialog

• Snackbar用于瞬态反馈，需要时可附带 action（如 Undo）；
• 文档特别指出：不要用toast承担这类职责；
• Dialog只用于"必须打断用户"的决策。

锚点android-components-snackbar。

7.4 Material 动效模式 + 遵循系统"移除动画"设置

动效采用 Material 的标准模式：container transform、shared-axis、fade-through，配标准缓动与时长。同时必须尊重系统的 Remove animations（移除动画）设置——用 crossfade 或瞬时切换来替代空间位移动效。这与 animate.md 对原生平台"遵循平台 Reduce Motion 行为"的要求一致。锚点android-motion-material-and-reduce。

8. 构建验证（Verifying the build）：截图取证必须来自真机/模拟器

原生验证与 web 最大的不同：截图来自模拟器或连接的真机，绝不来自浏览器。

8.1 截图命令

构建并安装后，用 adb 抓屏：

adb exec-out screencap -p > <path>

多个设备同时连接时，用-s <serial>指定目标：

adb devices # 先列出 serial adb -s emulator-5554 exec-out screencap -p > phone.png

覆盖应用发布到的每一个设备类别：至少一部手机；平板在目标范围内时，至少一部平板。文件应写到审核流程（review flow）期望的位置——按 impeccable-finish-reviewer.md 的约定，原生截图放在.impeccable/review/，命名按设备类别如phone.png、tablet.png（adaptive 场景按 OS 追加后缀）。

8.2 暗色主题与字体缩放必须进入本轮验证

两个命令组合使用：

adb shell cmd uimode night yes # 切到暗色 adb shell settings put system font_scale 1.3 # 放大字号 # ... 抓屏 ... adb shell settings put system font_scale 1.0 # 验完恢复 1.0 adb shell cmd uimode night no # 恢复亮色

字号放到 1.3 倍正是为了暴露固定布局下被截断的标签——只在默认字号下截图永远发现不了这类问题。多设备场景下，这些命令同样要带-s <serial>。

对应锚点：android-verify-emulator-capture、android-verify-theme-and-scale。

8.3 诚实交代证据来源：模拟器 vs 硬件

Emulators give breadth; gestures, refresh rates, and performance need hardware. Say which one produced the evidence.

• 模拟器擅长覆盖广度（多设备类别、系统版本、暗色/缩放），成本低、可并行；
• 手势手感、刷新率、性能必须靠真实硬件验证；
• 报告里必须说清楚证据来自哪一种。

这也呼应 SKILL.src.md 的验证纪律：完整构建 → 一次批量检查（覆盖所发布的所有设备类别）→ 按检查结果一次性修复 → 至多再确认一轮 → 停止打磨。证据缺失与证据错误同样致命——finish-reviewer 会先校验截图存在性与有效性（无黑屏/空白、内容与文件名一致），缺失的 viewport "a viewport nobody captured is a viewport nobody inspected"，直接判不通过。

9. 与 iOS 参考的对照：两个平台的规则如何协同

同为原生参考，android.md 与 ios.md 结构镜像但内容各归其位：

对于adaptive平台（同一产品按 OS 真正适配设计语言），两份参考都要读；而一个跨平台应用在 iOS 硬件上仍须履行 iOS 的 safe-area / Reduce Motion / edge-swipe back 承诺——这正是文档第 5 行那句"still owes iOS its OS guarantees on that hardware"的含义。

结语

.rovodev/skills/impeccable/reference/android.md与 skill/reference/android.md 是一份可执行、可审计、可被机器读取（每条规则都带<!-- rule:android-* -->锚点）的 Android 原生设计基线。它没有给"好看"留模糊空间，而是把原生可信落到 Material 3 的具体规则上，并用 adb 截图取证闭环保证每一次设计决策都经过真实渲染的检验。对任何要让 AI 产出、或自行校验 Android 原生 UI 的团队，这份参考都可以直接作为设计评审与代码审计的 checklist 使用。

【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable