impeccable 原生 Android 设计参考全解Material Design 3 守则、组件边界与 adb 真机验收实战【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable导读impeccable是一个让 AI 前端设计代理产出“非平庸设计”的技能库它对不同交付平台维护了不同的平台守则。本文以仓库中的平台参考文档 skill/reference/android.md同名文件同时存在于 .cursor/skills/impeccable/reference/android.md 等各模型提供商的分布式技能目录中为核心系统讲解面向 Jetpack Compose、Android Views、React Native、Expo、Flutter 等原生 Android 应用的设计约束从 Material Design 3 的布局、触控、字体、色彩、动效规范到“Android slop 测试”再到用adb在模拟器与真机上截图、切换深色主题、放大字体做交付前验收的完整命令链。读完本文你能掌握一套可直接执行的“Android 界面是否可信”检查清单并理解这些规则在 impeccable 路由、审计、评审流程中的落地方式。一、这份文档在 impeccable 中扮演什么角色1.1 平台轴Platform Axis是独立于模式Mode的第二维在 impeccable 中用户可见的技能是一个名为impeccable的单一技能内含 23 个命令craft、shape、init、audit、polish 等。CLAUDE.md 明确指出技能同时维护两条互相正交的轴模式ModePersuade / Operate / Read / Experience回答“访客来这个界面做什么”平台Platformweb / ios / android / adaptive回答“交付目标是什么、套用哪套原生惯例”。android.md正是android平台值所对应的规则手册内容定位是“Material Design 3 的蒸馏版”distilled。除 web 外的每个平台都有专属参考文件平台触发条件加载的参考文档web默认值无需额外规则书技能本体 General 规则ios原生 iOS / iPadOS 应用skill/reference/ios.mdandroid原生 Android 应用skill/reference/android.mdadaptive同一套代码同时交付 iOS 与 AndroidFlutter、React Native、KMP且按系统自适应同时加载 ios.md 与 android.md需要特别强调的是 adaptive 的判定标准一个“Material-everywhere”的跨平台应用这正是 Flutter 的默认形态如果两端长得一模一样在 impeccable 里不被视为 adaptive它只取单一平台通常按 Material 处理的约束。只有真正“按系统自适应”的跨平台应用才需要同时吃进两套平台守则。1.2 文档如何进入 AI 的执行上下文从 CLAUDE.md 的实现说明可以还原这条加载链路项目根目录的PRODUCT.md中记录## Platform字段取值只有裸值web/ios/android/adaptive技能启动脚本skill/scripts/context.mjs通过extractPlatform()底层复用通用的extractSectionValue()解析该字段字段缺失时默认回退为web保证老项目不受影响当解析结果是ios、android或adaptive时context.mjs会把对应平台参考文档直接内联进它的输出也就是说平台惯例无需模型二次读取文档即可进入上下文当用户在原生平台项目上初始化init时skill/reference/init.md 会在确认平台后自行加载对应平台参考文档见其“Step 3/Step 4”描述因为新项目在写入 PRODUCT.md 之前context.mjs无从得知平台init 是唯一能学到答案的地方如果一个工作区携带原生构建文件、却继承了指向 web 的根 PRODUCT.mdskill/reference/doctor.md 会把它登记为最重要的workspace-platform-native-evidence类漂移问题修复方式是给该工作区补一份子 PRODUCT.md因为“一份继承来的记录无法同时承载两个平台”。此外NOTICE.md 记录了文档出处skill/reference/ios.md与skill/reference/android.md由 ehmo 的 MIT 许可项目platform-design-skillsApple Human Interface Guidelines 与 Material Design 3 规则蒸馏而来并以 impeccable 的语气重写。1.3 适用边界哪些技术栈算“Android”文档第一句就把覆盖范围写得很清楚面向原生 Android 应用具体包括 Jetpack Compose、Android Views传统 View 体系、React Native、Expo、Flutter——即凡是“最终运送到 Android 硬件上”的界面。这里的关键限定是“原生”二字如果是纯浏览器里跑的移动端 Web 页面它走的是 web 平台的通用规则而不是这套 Material 守则同样CLAUDE.md 说明 live 模式、detectCLI 与设计钩子全部是 web-only 工具对任何原生ios/android/adaptive项目都会被路由跳过。1.4 每条规则都带可寻址的规则 ID值得注意的一个仓库细节是skill/reference/android.md里每条规范行末都带!-- rule:android-* --形式的 HTML 注释例如rule:android-layout-adaptive-nav、rule:android-touch-target-48dp、rule:android-color-dynamic-color、rule:android-verify-emulator-capture等。这些稳定的规则标识让指南中的每一条都能被工具链精确定位、被测试与钩子引用而不是只靠自然语言匹配。二、原生模式的表达边界品牌只能借 Material 的壳表达文档给出一句贯穿全文的原则性陈述On native, the visitor mode narrows what expression may override. Material Design 3 governs structure, navigation, and interaction in every mode; brand expresses through Materials theming (color roles, type scale, shape, motion).翻译成设计语言就是在原生平台无论你的模式是 Persuade转化页、Operate工具型 App还是 Read文档型内容Material Design 3 都接管结构、导航与交互品牌只能通过 Material 的换肤系统来表达——即色彩角色color roles、字体字号阶梯type scale、形状shape与动效motion。这等同于宣告结构层不可自创表达层才是品牌发挥的空间。同时文档保留了一条“平台债务”提醒一个 Material-everywhere 的跨平台应用哪怕也装到了 iPhone 上只要跑到 iOS 硬件上就仍然欠 iOS 那套操作系统级保障——安全区 inset、Reduce Motion、边缘右滑返回。这正是 adaptive 平台值要求“两端参考文件都加载”的原因。三、The Android slop test一眼识破“穿 Android 皮的 iOS 应用”这是 Android 平台上最核心的验收提问Would a fluent Android user trust this app, or trip on off-spec components?一个资深的 Android 用户能否信任这款应用还是会被不合规格的组件绊倒文档指出最常见的破绽恰恰是“穿了 Android 皮的 iOS 应用”典型症状包括照抄 iPhone 的纯底部导航iOS 的 Tab Bar 习惯被直接搬成唯一的底部导航条无视系统 Back 手势的返回箭头界面里画一个自造的返回箭头却让系统级预测性返回predictive Back失效或冲突Cupertino 造型的开关与对话框开关、弹窗沿用 iOS 的圆润形态iOS 风格 switch、alert 样式而没有 Material 化。结论只有一句话Material 3 就是规则书rulebook。要用它的组件再通过它的主题机制把品牌织进去而不是绕过组件另起炉灶。四、Layout structure布局与结构四原则文档的布局与结构部分给出四条硬性要求每条都可落到 Material 3 的标准组件名上。4.1 Material 导航必须匹配屏幕宽度rule:android-layout-adaptive-nav紧凑宽度compact width手机竖屏使用底部导航条Material 3 的 NavigationBar承载 3–5 个目的地destination扩展宽度expanded width平板/大屏切换为导航抽屉栏NavigationRail或抽屉NavigationDrawer。最不能容忍的行为是“把一个手机底部导航条原封不动搬到平板上”never ship a phone bottom-bar untouched on a tablet。平板横向空间充裕底部栏会浪费大量可读宽度且不符合 Material 的响应式导航规范。4.2 系统返回永远可用rule:android-layout-system-back必须响应 Android 的**预测性返回手势predictive Back gesture**与 Back 键永远不要困住用户也不要劫持该手势例如把 Back 手势改造成收起键盘之外的其他自定义语义而拦截系统返回。从 Android 13 起的预测性返回还要求应用预览即将返回的目标界面这更意味着返回栈必须交给系统管理。4.3 真正 edge-to-edge处理全部窗口 insetrule:android-layout-window-insets内容要延伸到屏幕边缘但必须正确应用以下 inset避免内容被遮挡状态栏status barinset导航栏navigation barinset刘海/挖孔display cutoutinset输入法IMEinset——软键盘弹出时输入框不能被键盘盖住。在 Compose 中这对应WindowInsets体系statusBars、navigationBars、displayCutout、ime与Modifier.windowInsetsPadding(...)在传统 View 体系则对应setOnApplyWindowInsetsListener/WindowInsetsCompat。用对了 insets深色沉浸式底栏、全面屏手势条与键盘弹起才不会“吃”掉内容。4.4 顶部应用栏提供屏幕语境单一主操作配 FABrule:android-layout-top-app-bar每个屏幕用 Top App Bar 说明“我在哪”screen context当该屏幕存在唯一的主操作时用一个 FABFloating Action Button与之配对。没有主操作就不要硬塞 FAB。五、Touch targets48×48 dp 的触控底线48×48 dp minimumfor every touch target, with at least 8 dp between them.文档规定每一个触控目标最小 48×48 dp相邻目标之间至少留8 dp间距。这是 Material 无障碍规范的核心数字接近 44pt 的 iOS 对应值但更大直接决定拇指能否可靠点中目标、以及误触概率。值得注意的是 48 dp 是“可点击热区”而非视觉尺寸实践中常通过扩大可点击区域实现视觉更紧凑、热区仍达标的布局8 dp 间距则是防误触的间隔底线。这条对应的规则 ID 是rule:android-touch-target-48dp也是审计时会真实检查的硬指标。六、Typography交给 Material 字体阶梯字号只用 sp6.1 用 Material type scale 映射文本角色rule:android-typo-type-scale文本必须映射到 Material 的字体角色阶梯Display大标题展示仅用于品牌化首页大字号场景Headline屏级标题Title区块与列表标题Body正文Label控件内文字、说明文字以上每个角色又分 large / medium / small 三档。规则是“给文本先定角色、再从阶梯取样式”绝不允许在具体屏幕上逐个手选字号never hand-pick sizes per screen。手选字号的直接后果就是字号体系失序、层级混乱。6.2 系统字体是 Roboto品牌字体经由阶梯注入rule:android-typo-system-fontRoboto 是 Android 的系统字体。如果要引入品牌字体正确的做法是把它作为阶梯的替换字体通过主题注入Compose 中即定义Typography并把品牌 face 挂到各角色上并保证正文、标签与控件仍然清晰、一致。而不是在个别组件里混用字体制造割裂。6.3 只用 sp绝不用固定 pxrule:android-typo-scalable-sp字号必须使用spscaled pixels单位让文字跟随系统字体缩放设置。用户把系统字体调大界面文字随之放大若用 dp 或 px 写死字号就会在辅助功能字体缩放下出现截断或错位。这也是后文“验收”环节要专门检查 font scale 的原因。七、Color theming用角色令牌换肤不用裸 hex7.1 Material 色彩角色是唯一合法的取色方式rule:android-color-role-tokens文档给出必须使用的 Material 色彩角色清单primary、on-primary、surface、surface-variant、secondary-container、outline、error。要点在于Role tokens resolve light/dark and contrast variants automatically; raw hex breaks there.角色令牌会自动解析浅色/深色/高对比度下的正确取值直接写死的裸十六进制颜色在这些变体里必然失效。主题换肤、深色模式、无障碍对比度增强全靠“代码只引用角色、角色解析最终色值”这一层抽象才能自动工作。7.2 Dynamic ColorMaterial You按需启用rule:android-color-dynamic-color在合适的场景使用动态取色Android 12 上从用户壁纸派生整个配色方案scheme同时必须准备一个静态配色作为回退static fallback——因为不是所有设备、所有 Android 12 版本都支持动态取色品牌化程度高的界面也应保守使用。7.3 深色主题是一等公民不是快速反相rule:android-color-dark-theme深色主题必须被设计并测试为一套正式的方案绝不允许一键“quick invert”把颜色粗暴反相。正确做法仍是通过角色令牌自动解析深色变体并在深色下人工校准表面色、文字对比与图形化强调。7.4 色调化层级表达高度rule:android-color-tonal-elevation用 Material 标准的 **surface 色调层级tonal elevation**来传达“抬升感”必要时才叠加阴影禁止随手加任意 drop shadow。也就是说卡片浮起的高度变化应当体现在 surface 色彩的明暗层级上而不是靠自定义投影。八、Components motion原生组件 单 FAB Material 动效8.1 只用 Material 组件禁止移植 iOS 控件rule:android-components-material文档列出的合法组件集合Buttonsfilled实心/ tonal色调/ outlined描边/ text文字四种样式FAB浮动操作按钮Switches开关、chips筛选/输入片、snackbars、bottom sheets、Material dialogsMaterial 风格对话框Navigation bar / rail / drawer底部导航条/侧栏/抽屉。硬性禁令是绝不移植 iOS 控件也绝不自行发明等价物never port iOS controls or invent equivalents。iOS 的 switch、alert、tab bar 造型出现在 Android 应用里就是上文 slop test 中“Cupertino 形状开关和对话框”的直接扣分项。8.2 一个 FAB 只能对应一个主操作rule:android-components-single-fab永远只放一个FAB且它只服务屏幕的主操作。禁止堆叠多个 FAB也禁止把 FAB 浪费在次要任务上。8.3 瞬时反馈用 Snackbar打断性决策才用 Dialogrule:android-components-snackbarSnackbar承载转瞬即逝的反馈操作成功、已删除等可含“撤销/重试”类操作但不要用 Toast 承担这个职责Dialog只用于必须打断用户的决策破坏性确认、需要立即表态的选择。这个区分对应 Android 的模态层级常规反馈走轻量 Snackbar真正需要用户停下做决定才提升到模态对话框。8.4 Material 动效模式并尊重系统“移除动画”设置rule:android-motion-material-and-reduce动效必须遵循 Material 的三种过渡模式Container transform容器变换元素在两种形态间以同一容器形变过渡Shared-axis共享轴父子页面沿同一轴滑动Fade-through淡入贯穿层级切换时淡出淡入。并统一使用 Material 标准缓动曲线与时长。同时必须响应系统的Remove animations移除动画无障碍设置——检测到该设置开启时用交叉淡入crossfade或直接硬切instant cut代替大段位移动效。九、Verifying the build用 adb 完成交付前验收这是文档中实操性最强的一节也是 native 平台与 web 平台验收方式的分水岭原生截图必须来自模拟器或真机绝不来自浏览器。因为 impeccable 的 finish reviewer 等工作流依赖真实设备截图来评估还原度浏览器渲染无法代表 Android 的渲染管线。9.1 截图构建安装后用 screencap 采集流程是先完成构建并安装到目标再执行adb exec-out screencap -p path当同时连接了多台设备时必须用-s serial指定目标设备adb -s serial exec-out screencap -p path截图覆盖范围必须与 App 实际交付的设备形态一致至少一台手机如果平板是交付目标则至少再补一台平板。截图文件要写入评审流程review flow约定的位置——按 plugin/agents/impeccable-finish-reviewer.md 的约定原生平台的评审截图放在.impeccable/review/且使用设备形态命名如phone.png、tablet.pngadaptive 平台再按 OS 加后缀这与 web 平台的desktop.png/mobile.png命名约定不同。9.2 深色主题与字体缩放必须进入验收流程两件最容易掩盖布局问题的状态必须纳入截图清单切换深色主题adb shell cmd uimode night yes放大字体到 1.3 倍检查是否有标签被截断固定布局最容易暴露此问题adb shell settings put system font_scale 1.3验收结束后恢复默认字体缩放adb shell settings put system font_scale 1.0当多台目标设备同时连接时上述命令同样要加上捕获用的-s serialadb -s serial shell cmd uimode night yes adb -s serial shell settings put system font_scale 1.3font_scale 1.3正是对前文“sp 单位、绝不用 px”规则的实证字号真的跟随系统设置放大后凡是写死尺寸的标签、按钮就会原形毕露。9.3 证据来源要诚实模拟器管广度真机管手感文档最后一条验收纪律是Emulators give breadth; gestures, refresh rates, and performance need hardware. Say which one produced the evidence.模拟器emulator的价值是“广度”快速覆盖多机型、多系统版本、多屏幕形态真机的价值是“手感”返回手势、刷新率表现、真实性能只能靠硬件验证产出证据时必须说明截图来自模拟器还是真机say which one produced the evidence不冒充、不混用。这条规则 ID 为rule:android-verify-hardware-honesty也是一条诚信要求评审方必须知道证据的生成环境才能判断其可信度。十、这些守则如何融入 impeccable 的完整工作流android.md不是孤立文档仓库里有多个命令与代理会引用它的内容理解这条引用网络有助于在实际使用时“对号入座”原生代码级审计当平台为原生时audit命令走 plugin/skills/impeccable/reference/audit.native.md——这是直接从源码SwiftUI / UIKit / Compose / React Native / Flutter打的代码级审计不适用浏览器工具评分标准即 ios.md / android.mdadaptive 两端都读并要求在评分前先读完平台参考文档。原生适配adapt命令的原生变体 plugin/skills/impeccable/reference/adapt.native.md 明确警告“把适配当成缩放是陷阱”跨设备形态、方向或平台的迁移必须在目标平台文档的惯例内重新思考体验。动效/排版/布局命令animate、typeset、layout的参考文档各自声明“原生场景请遵循平台文档的 Motion / 排版 / 布局与无障碍缩放章节”不套用 web 工具链。完工评审评审代理 plugin/agents/impeccable-finish-reviewer.md 接收父流程截图原生平台即phone.png/tablet.png等结合方向契约与 PRODUCT.md 做最终的 fidelity 复核。原生项目的工具豁免live 变体模式、detect检测 CLI 与设计钩子都是 web-only当 PRODUCT.md 声明原生平台时钩子会跳过对.tsx/.ts/.js文件的扫描因为 React Native 项目恰恰就是由这些文件构成的按 web 规则扫描会产生误报。结语用一份守则回答“Android 用户会信任它吗”回到文档开头那个问题一个熟练的 Android 用户会不会信任这款应用android.md给出的答案路径是清晰的——结构上导航匹配屏幕宽度、系统 Back 永远可用、edge-to-edge 正确处理 insets、顶栏FAB 给出语境规格上48×48 dp 触控、sp 字号、Material 角色令牌、一等公民的深色主题、单一 FAB 的组件纪律动效上容器变换/共享轴/淡入贯穿并尊重系统移除动画设置而这一切最终都要靠模拟器与真机上的adb截图验收来落地。配合adb shell cmd uimode night、adb shell settings put system font_scale这两组开关把深色模式与字体缩放真正跑进截图里再诚实标注证据来源一套可靠的 Android 交付验收闭环就成立了。对使用者而言这份文档最大的价值在于它把“Material 3 蒸馏规则”压缩成了一张可直接对照的检查表而对阅读仓库的人来说skill/reference/android.md 中逐条规则携带的rule:android-*标识也为将来把每条规范接入自动化检查提供了天然的锚点。【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考