Impeccable 的 Android 平台设计规范在 Jetpack Compose 与跨端框架上践行 Material 3 原生体验【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable本指南以 Impeccable 技能库中的 Android 平台参考文档plugin/skills/impeccable/reference/android.md为骨架系统讲解如何为 Jetpack Compose、Android Views、React Native、Expo、Flutter 等所有最终运行在 Android 硬件上的应用执行原生设计。你将掌握 Material 3 语境下的布局、触摸目标、排版、色彩主题与动效规范以及用adb从模拟器或真机取证验证构建结果的完整流程同时了解 Impeccable 如何把这份规范注入到设计 Agent 的上下文加载与原生审计audit评分中。一、为什么原生 Android 需要一份独立的平台规范Impeccable 为web、ios、android、adaptive四种平台分别维护设计上下文。当项目的PRODUCT.md声明平台为android时impeccable context会加载对应的平台参考文档并注入设计流程当声明为adaptive跨平台同时发布到 iOS 与 Android时两份原生参考会一并加载。从源码结构看这一机制实现在 crates/context/src/context_cli.rs 的load_native_platform_references中函数根据PRODUCT.md中## Platform字段的值决定加载哪些参考——Some(adaptive)同时返回[ios, android]Some(android)只返回[android]其余情况不加载原生参考。平台字段的解析逻辑在 crates/context/src/context.rs 的extract_platform合法的单值只有web、ios、android、adaptive如果写的是“ios android”这类组合函数会把同时包含 ios 与 android 的 token 列表归一化为adaptive。如果写了一个无法识别的值context 会给出WARNING并暂时按web处理同时提示“命名应用渲染的设计语言而不是工具链”。另外crates/context/src/staleness.rs 提供了反向的证据检测当项目存在android/build.gradle、android/build.gradle.kts等文件却被标成web时检测器会提示“Web 指导被应用到了原生代码库iOS 与 Android 参考永远加载不到”并询问是否应把## Platform改为android。这也解释了平台参考在 Impeccable 工作流中的地位平台规范不是装饰性 checklist而是决定上下文加载路径的路由键。在这份规范中一条总纲贯穿始终在原生平台上“访问者模式”会收窄表达可以覆盖的范围。Material Design 3 在所有模式下都约束结构、导航与交互品牌只能通过 Material 的主题化通道颜色角色、类型尺度、形状、动效表达即便一个“Material everywhere”的跨平台应用同时发布到 iPhone它在该硬件上仍然欠 iOS 一份 OS 层面的保证安全区 insets、Reduce Motion、边缘滑动返回。二、Android slop 测试先学会识别“穿着 Android 皮囊的 iOS 应用”文档给出一个开箱即用的鉴别标准一个流畅的 Android 用户会信任这个应用还是会被不符合规范的无件绊倒最常见的翻车信号slop tell恰恰是“一个穿着 Android 皮肤的应用实际上是个 iOS 应用”从 iPhone 照搬的纯底部导航bottom-only navigation无视系统返回手势的返回箭头back arrow ignores system Back gestureCupertino 形状的开关与对话框switch 与 dialog 的圆角、描边、动效全是 iOS 腔调。结论是硬性的Material 3 就是规则手册rulebook。遵循它的组件体系然后通过它来表达品牌——而不是绕过组件体系去“复刻”iOS 外观。这份判断也被 plugin/skills/impeccable/reference/audit.native.md 的“Platform Conformance平台一致性”维度固化为评分标准0 分是“Web 移植品毫无原生感”1 分是“重度违规3~4 种”2 分是“存在 1~2 处明显问题”3 分是“基本合规细微瑕疵”4 分才是“完全原生流畅用户信任每一个界面”。三、布局与结构导航、返回、边到边与顶栏Material 导航要与尺寸匹配。紧凑宽度compact width用底部导航栏Navigation bar3~5 个目的地展开宽度expanded width改用导航 rail 或抽屉drawer。永远不要把一个手机版底部栏原封不动地摆到平板上。这条原则与 plugin/skills/impeccable/reference/adapt.native.md 的“Phone → Tablet”策略一致平板上的失败模式就是“缩放放大手机 UI”正确做法是用 window size classes 切换结构底部栏 → rail/drawer。系统返回永远可用。必须尊重预测式返回手势predictive Back gesture与返回按钮绝不困住用户、绝不劫持手势。这与 iOS 侧“edge-swipe back 必须存活”是对称的肌肉记忆保护。边到边edge-to-edge 窗口 insets。应用状态栏、导航栏、刘海/打孔display cutout与 IME insets保证内容永远不会藏在系统栏或键盘后面。审计脚本会把“内容被键盘遮挡、未做 inset 调整”列为 IME 处理缺陷。顶栏Top app bar提供屏幕语境当屏幕只有一个主操作时配一个 FAB。四、触摸目标48×48 dp 与 8 dp 间距规范给出的数字是绝对下限每个触摸目标至少 48×48 dp目标之间至少留 8 dp。这与 iOS 侧 44×44 pt 形成平台对照。在 plugin/skills/impeccable/reference/audit.native.md 的“Accessibility”维度里低于 48 dpAndroid或被塞得没有间距的目标会被记为无障碍缺陷并给出“Touch targets consistently below 48 dp throughout the tab bar and list rows”这类模式化发现示例。五、排版Material 类型尺度、Roboto 与 sp 单位Material 类型尺度。每个角色都是 Display / Headline / Title / Body / Label 五种角色 × large / medium / small 三种规格。文本必须映射到角色上绝不按屏幕手工挑字号。Roboto 是系统字体。品牌字体通过类型尺度主题化进入系统保证正文、标签与控件的可读性和一致性——品牌字体出现在展示性场景而不是接管 UI。必须用 sp永远不要固定 px。这样字号才会跟随系统字体大小设置。审计维度同样以“用 px 而不是 sp”为扣分项与 iOS 侧“固定 pt 击败 Dynamic Type”对应。六、色彩与主题角色 token、Dynamic Color 与一等公民的深色主题Material 色彩角色。使用 primary、on-primary、surface、surface-variant、secondary-container、outline、error 等角色 token。角色 token 会自动解析浅色/深色与对比度变体裸 hex 在这里会断掉。审计的“Appearance Theming”维度里0 分定义就是“全部硬编码”推荐做法是语义色贯穿、两种外观都一等公民。Dynamic ColorMaterial You用在合适处。Android 12 从用户壁纸推导 color scheme同时必须有静态回退方案static fallback。审计检查“没有静态回退方案或在合适处被忽略”。深色主题是一等公民 scheme。要专门设计与测试绝不允许快速反色quick invert。色调高度Tonal elevation。用标准 surface 色调层级表达高度必要时配合阴影不用随意的手工 drop shadow。七、组件与动效Material 组件、单一 FAB 与标准动效模式只用 Material 组件。按钮filled / tonal / outlined / text、FAB、开关、chips、snackbar、bottom sheet、Material dialog、导航栏/rail/抽屉。绝不移植 iOS 控件或自造等价物。一个 FAB一个主操作。绝不堆叠 FAB也不把一个 FAB 花在次要任务上。瞬态反馈用 Snackbar有用时可带操作但绝不用 toast 承担这个职责对话框只用于必须打断的决策。Material 动效模式。Container transform、shared-axis、fade-through配合标准缓动与时长同时尊重系统的“Remove animations”设置降级为 crossfade 或瞬时切换。这与 iOS 侧“Honor Reduce Motion”是对称要求审计在“Reduce Motion ignoredparallax and large slides with no crossfade alternative”上对两端一视同仁。八、验证构建截图必须来自模拟器或真机绝不允许浏览器这是 Android 平台规范中最具操作性的部分也是它区别于 Web 审核的关键——浏览器截图在原生审核里无效。8.1 采集截图先构建并安装应用然后用adb采集adb exec-out screencap -p path当有多台设备连接时用-s serial指定设备adb -s serial exec-out screencap -p path覆盖应用发布到的每一个设备类别至少一部手机平板在发布目标中时还要一部平板。截图文件必须写到审核流程review flow期望的目录中。8.2 深色主题与字体缩放必须纳入本轮验收# 切换深色主题 adb shell cmd uimode night yes # 放大字体到 1.3 倍验收后恢复 1.0 adb shell settings put system font_scale 1.3 adb shell settings put system font_scale 1.0文档特别提醒1.3 倍字体缩放专门用来暴露固定布局fixed layout藏起来的被截断标签。多台设备连接时-s serial同样要加到这些命令上。8.3 模拟器给广度真机给真相模拟器提供广度breadth多设备类别、多系统版本、多外观与字体配置可以低成本铺开但手势、刷新率与性能必须靠硬件。文档要求汇报证据时必须说明证据来自哪一类设备模拟器 or 真机。这与 plugin/skills/impeccable/reference/audit.native.md 的“Adaptivity”维度呼应——多窗口multi-window、折叠屏铰链姿态foldable hinge posture这类问题模拟器往往覆盖不全。九、与相邻工作流的衔接Android 平台参考不是孤立的审美建议它被 Impeccable 的多个原生命令引用为评分基准原生审计/impeccable auditaudit.native明确写着“按平台参考评分iOS 用 ios.mdAndroid 用 android.mdadaptive两者都用”并在读取前先读它们诊断扫描的五个维度Accessibility、Performance、Appearance Theming、Platform Conformance、Adaptivity都从这里取阈值例如 48 dp 触摸目标、sp 单位、Dynamic Color 静态回退、预测式返回被劫持、折叠屏姿势适配等。原生适配/impeccable adaptadapt.native在规划阶段要求“先读目标平台的参考”并把 iOS ↔ Android 的惯用法映射做成翻译表——Tab bar ↔ 导航栏/rail/drawer、Edge-swipe back ↔ 预测式返回手势/按钮、Action sheet ↔ Bottom sheet / Material dialog、SF Symbols ↔ Material Symbols、系统颜色与材质 ↔ Material 色彩角色与色调高度、系统转场 ↔ Container transform / shared-axis / fade-through。翻译惯用法而不是移植惯用法。上下文加载一旦## Platform声明为android或adaptive这些参考会由impeccable context的load_native_platform_references自动注入无需人工翻阅——这也是为什么把PRODUCT.md的平台字段写对如此重要。十、实践清单一次完整的 Android 原生审核迭代综合上述规范一个可复制的落地流程是确认PRODUCT.md的## Platform为android或adaptive让 context 自动加载 android.md用 slop 测试快速过一遍导航是底部栏还是 rail/drawer返回手势有没有被劫持开关和对话框是不是 Cupertino 形状逐项核对48×48 dp 触摸目标、sp 单位、Material 色彩角色无裸 hex、Dynamic Color 带静态回退、深色主题专项测试、单一 FAB、标准 Material 动效并尊重“移除动画”设置构建安装用adb exec-out screencap -p采集手机平板截图跑adb shell cmd uimode night yes与font_scale 1.3补深色与放大字体两轮证据标注证据来源模拟器 or 真机并把发现交给/impeccable audit的评分框架量化为 0-4 分驱动后续修复。这份 Android 平台规范的本质是把“原生感”从模糊的品味判断变成可核对的工程标准结构交给 Material 3品牌通过它的主题通道表达而验收必须来自真实 Android 硬件上的证据。当你在 Jetpack Compose、Android Views 或跨端框架上为 Android 用户打磨界面时它就是你与“Android 皮囊的 iOS 应用”之间的那道分界线。【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考