原生应用技术审计指南使用 Impeccable audit 对 iOS / Android 应用执行五维代码级质量审查【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable本文档系统讲解 Impeccable 技能套件中/impeccable audit命令的原生平台变体如何对 iOS、Android 以及跨平台adaptive原生应用执行代码级技术质量审计覆盖无障碍、性能、外观与主题、平台符合性、自适应性五个维度并产出带 0-4 分量化评分、P0-P3 严重度分级与修复命令建议的完整报告。读完本文你将掌握这套只记录、不修复的审计工作流能依据 ios.md 与 android.md 两份平台参考为你的原生项目建立可重复、可评分、可追踪改进的质量基线。audit 命令的双轨路由Web 与 Native 分道扬镳在 Impeccable 的 Commands 表中audit [target]被归类为 Evaluate评估命令官方描述是技术质量检查无障碍、性能、响应式并明确标注了 Web 与原生两个入口reference/audit.mdWeb与 reference/audit.native.mdNative。SKILL.md 的命令表中audit一行写作Technical quality checks (a11y, perf, responsive) | audit.md · native: audit.native.md这是全仓库唯二存在原生变体的命令之一另一个是adapt。这套机制在 CLAUDE.md 中有明确说明当命令的原生指导与 Web 版本差异过大、无法共用同一文件时就为它建立native variantreference/command.native.md。当setup.platform为原生平台时路由会用原生变体替代 Web 文件一个变体同时覆盖 ios、android、adaptive 三种平台各操作系统特有的细节则保留在平台参考文档中由 Setup 阶段统一加载。原生变体与 Web 版本必须保持报告骨架一致——修改audit.native.md时必须同步修改 audit.md 的报告骨架。这条路由不是纸上谈兵而是有测试背书的。在 tests/skill-behavior/scenarios.test.mjs 中测试明确验证当 fixture 的平台是 ios 时agent 必须加载audit.native.md而不是只读audit.md即Commands 表把 audit.native.md 列为原生变体、审计必须到达 audit.native.md。行为场景清单 tests/skill-behavior/README.md 也记录了同一条路由约定。原生审计与 Web 审计的本质差异原生变体在开篇就划清了两条边界这是代码级审计code-level audit不是设计批评design critique。审计的原料是源码——SwiftUI / UIKit / Compose / React Native / Flutter——而不是渲染结果。不适用任何浏览器工具链impeccable detect在此不生效。因为原生的无障碍、主题、自适应能力无法用浏览器里的 DOM 检测器衡量只能从平台框架的代码模式中取证。docs/CLI-CONTRACT.md 在讨论 CLI 契约时也专门引用了这条约定原生场景下no browser tooling or detect.mjs applies。评分标准则锚定平台参考ios 项目对照 ios.mdSwiftUI/UIKit/React Native/Expo/Flutter 发布到 Apple 硬件android 项目对照 android.mdJetpack Compose/Android Views/React Native/Expo/Flutter 发布到 Android 硬件adaptive 项目两份都读。如果 Setup 阶段还没有加载这些平台参考audit 开始前必须先读它们再评分。审计的立场只记录不修复audit.native.md的第一句话就是工作原则Run systematictechnicalquality checks ... Dont fix issues; document them for other commands to address.系统性技术质量检查并生成报告不修复问题而是记录问题供其他命令处理。审计产出的是证据和行动清单修复工作交给后续的命令按优先级执行——这也正是报告末尾Recommended Actions存在的意义。诊断扫描五个维度的检查点与评分标准原生审计在五个维度上逐项扫描每个维度按 0-4 分打分总分 20 分。下面按维度展开完整检查点与评分锚点。1. AccessibilityVoiceOver / TalkBack针对 iOS 的 VoiceOver 与 Android 的 TalkBack 检查以下方面缺失标签Missing labels可交互元素没有无障碍标签、trait/role、或状态播报state announcements阅读与焦点顺序Reading and focus order遍历顺序不合逻辑、控件无法到达、导航后焦点丢失文本缩放Text scaling固定 point size 破坏了 iOS Dynamic Type或 Android 用 px 而非 sp大字号下布局被裁剪或重叠触摸目标Touch targets低于 iOS 44 pt / Android 48 dp或目标之间没有间距、排列拥挤忽视 Reduce Motion视差和大滑块动画没有提供淡入淡出crossfade的替代方案对比度Contrast文字在浅色或深色外观中任一下不满足对比度要求评分锚点0-4分数含义0屏幕阅读器完全不可用1重大缺口控件无标签、无缩放2部分达标有标签但顺序或缩放有问题3良好少量缺口4优秀有标签、顺序正确、可缩放、尊重 Reduce Motion2. Performance性能启动缓慢Slow startup首帧渲染前在启动阶段做了大量重活未虚拟化列表Unvirtualized lists长内容没有使用 FlatList / LazyColumn / List 回收机制主线程卡顿Main-thread jank滚动或手势路径中的同步工作60/120 Hz 下掉帧浪费的渲染Wasted renderingReact Native 不必要的重渲染、Compose 不必要的重组缺少 memoization/keys图片处理Image handling缩略图直接解码全尺寸图片、没有缓存应用体积App weight臃肿的 JS bundle 或二进制、未使用的依赖评分锚点0-40处处卡顿1重大问题列表未虚拟化、启动慢2部分达标3良好尚有小的优化空间4优秀启动快、滚动流畅、体积精简。3. Appearance Theming外观与主题硬编码颜色Hard-coded colors用原始 hex 而非语义系统色iOS/ Material 色彩角色Android/ 设计令牌深色外观损坏Broken dark appearance缺少深色变体、深色下对比度差、粗暴的反色处理Dynamic ColorAndroid 12没有静态回退方案或在适合的场景中忽略了 Material You 动态取色非平台材质Off-platform materials在系统材质system materials或色调抬升tonal elevation应当出现的场景手工实现视觉材质评分锚点0-40一切硬编码1令牌极少2部分有令牌但使用不一致3良好少量硬编码值4优秀全语义化两种外观一等公民。4. Platform Conformance平台符合性CRITICAL这一维被标记为CRITICAL按已加载的平台参考含其中的 slop 测试评分系统手势损坏Broken system gesturesiOS 禁用边缘右滑返回、Android 劫持预测式返回predictive Back安全区违规Inset violations内容被刘海、灵动岛Dynamic Island、Home 指示条、状态栏或键盘遮挡非平台导航Off-platform navigation自定义全局导航、过载的标签栏、iOS 模式套在 Android 上或反之Web 形态控件Web-shaped controlsHTML 风格按钮、自定义开关、依赖 hover 的交互暗示图标漂移Icon drift混用图标集而不是统一使用 SF Symbols / Material Symbols系统漂移System drift与产品、平台或既定设计系统冲突的重复性快捷键或装饰模式评分锚点0-40Web 移植毫无原生感1严重违规3-4 类2存在 1-2 处明显问题3基本符合细微问题4完全原生熟练用户信任每个屏幕。5. Adaptivity自适应性手机布局拉伸Stretched phone layouts平板/iPad 渲染放大版手机 UI而不是使用 size classes / 窗口尺寸类方向破坏Orientation breakage横屏内容被裁剪、被忽略或无故锁定方向键盘/IME 处理输入框被键盘遮挡、没有 inset 调整多任务MultitaskingiPad Split View / Android 多窗口破坏布局折叠屏FoldablesAndroid 姿态变化posture change时折痕感知缺失评分锚点0-40只支持一种屏幕尺寸1重大破坏横屏或平板损坏2部分3良好少量边缘情况4优秀跨尺寸、方向与分屏自适应。平台参考的核心检查基线五个维度中的许多检查点都指向平台参考文档中的硬性规则。两份参考各自定义了slop 测试slop test——一个快速判断这是原生应用还是网站移植的直觉测试。iOS 基线ios.mdiOS slop test熟练的 iPhone 用户会信任这个应用还是在不符合规范的控件前停下来从网站移植的典型迹象是重新发明的导航栏、自定义返回手势、Web 形状的按钮、依赖 hover 的交互暗示安全区所有内容在 safe-area insets 内不得有控件位于刘海、灵动岛、Home 指示条或圆角之下系统导航2-5 个顶级分区用标签栏放 section 而非 action层级用导航栈独立任务用 sheet禁止自定义全局导航边缘右滑返回必须存活绝不能禁用或覆盖触摸目标每个可点控件最小 44×44 pt相邻目标之间留出呼吸空间Dynamic Type使用系统文本样式Large Title 到 Caption字体随用户阅读字号缩放禁止硬编码 point size正文 Body 为 17 pt11 pt 为下限语义系统色label、secondaryLabel、systemBackground、separator、tint 等随深色模式与增强对比度自动适配raw hex 会在此失效整个应用只有一个 tint 色驱动交互元素系统材质栏与 sheet 的模糊和半透明用系统材质禁止手工玻璃拟态平台控件与 SF SymbolsSwitch、分段控件、步进器、系统选择器、action sheets、alert、context menu、swipe actions 都该用系统组件图标统一 SF Symbols不得混入 Web 图标集动效系统转场push 滑动、sheet 升起、dismiss 逆向尊重 Reduce Motion用淡入淡出替代视差和大滑块Android 基线android.mdAndroid slop test最常见迹象是穿着 Android 皮肤的 iOS 应用——从 iPhone 抄来的底部导航、无视系统 Back 手势的返回箭头、Cupertino 形状的开关和对话框。Material Design 3 是规则书品牌通过它的 theming 表达Material 导航随宽度变化紧凑宽度用底部导航栏3-5 个目的地扩展宽度用导航 rail 或 drawer绝不在平板上原样使用手机底部栏系统 Back 始终可用尊重预测式返回手势和返回按钮绝不困住用户或劫持手势Edge-to-edge 窗口 insets应用状态栏、导航栏、显示裁切display cutout与 IME insets内容不藏在系统栏或键盘后面触摸目标每个触摸目标最小 48×48 dp之间至少 8 dpMaterial 字体尺度Display / Headline / Title / Body / Label 角色各分 large/medium/small文本映射到角色而不是逐屏手选字号sp 单位而非固定 px跟随系统字号设置Material 色彩角色primary、on-primary、surface、surface-variant、secondary-container、outline、error 等角色令牌自动解析明暗与对比度变体Android 12 的 Dynamic ColorMaterial You从壁纸取色必须有静态回退深色主题是头等方案绝不是快速反色色调抬升tonal elevation用标准 surface tonal 层级表达层级感外加适当的阴影禁止随意投影Material 组件与动效filled/tonal/outlined/text 按钮、FAB、开关、chip、snackbar、bottom sheet、Material 对话框、导航组件一个屏幕一个 FAB 一个主操作snackbar 用于瞬时反馈对话框只用于必须打断的决策动效遵循 container transform、shared-axis、fade-through 模式并尊重系统移除动画设置平台化的截图验证工作流两份平台参考都给出了真机证据的采集方法审计与修复后的复查都依赖它iOS截图必须来自 Simulator用xcrun simctl io booted screenshot path采集多台模拟器运行时用xcrun simctl list devices booted拿到目标 UDID 替换booted。xcrun simctl ui booted appearance dark切换深色外观还需在大号 Dynamic Type 下检查一次。至少覆盖一款 iPhone若面向 iPad 再覆盖一款 iPadAndroid截图来自模拟器或真机用adb exec-out screencap -p path采集多设备时用adb -s serial指定。adb shell cmd uimode night yes切换深色主题adb shell settings put system font_scale 1.3放大字号检查裁剪用后恢复1.0。至少覆盖一款手机面向平板则再加一款平板两条平台参考都强调同一原则模拟器/仿真器给广度手势、刷新率与性能需要真机——报告必须说明证据来自哪种载体生成报告从评分表到行动清单审计的最终交付物是报告audit.native.md给出了从骨架到细节的完整模板。Audit Health Score健康分表报告开头的核心表格#DimensionScoreKey Finding1Accessibility?[最严重的无障碍问题或 --]2Performance?3Appearance Theming?4Platform Conformance?5Adaptivity?Total??/20[Rating band]Rating bands 分级区间等级含义18-20Excellent只需细微打磨14-17Good需要修补薄弱维度10-13Acceptable需要大量工作6-9Poor需要重大重构0-5Critical存在根本性问题Platform Conformance Verdict平台符合性裁决模板明确标注Start here——这一节要最先写。核心问题是这读起来像原生应用还是像网站移植列出具体的违规项并且be brutally honest要极其诚实。它是整个审计的定性结论健康分表是它的量化总结。Executive Summary执行摘要Audit Health Score??/20评级带问题总数按 P0/P1/P2/P3 严重度计数Top 3-5 关键问题建议的下一步Detailed Findings by Severity按严重度分级的问题明细每条问题必须打上P0-P3 严重度标签P0 Blocking阻碍任务完成立即修复P1 Major造成显著困难或违反平台指南发布前修复P2 Minor令人烦恼、存在变通方案下个迭代修复P3 Polish锦上添花、无实质用户影响有空再修每条问题需完整记录 7 项[P?] 问题名称、Location屏幕、文件、行号、CategoryAccessibility / Performance / Theming / Conformance / Adaptivity、Impact如何影响用户、Guideline违反的 HIG / Material 规则如有、Recommendation如何修复、Suggested command建议用哪条命令修复。Patterns Systemic Issues模式与系统性问题识别反复出现的问题——它们指向系统级缺口而非一次性失误例如硬编码颜色出现在 15 个屏幕中应改用语义色触摸目标在标签栏和列表行的全部场景中持续低于 44 ptPositive Findings正面发现记录做得好的部分——值得保持和复制的良好实践。模板提醒celebrate what works。Recommended Actions把发现映射到修复命令建议命令必须按优先级排序P0 优先然后 P1、P2且只能从官方白名单中选择/impeccable adapt、/impeccable animate、/impeccable audit、/impeccable bolder、/impeccable clarify、/impeccable colorize、/impeccable critique、/impeccable delight、/impeccable distill、/impeccable document、/impeccable harden、/impeccable layout、/impeccable onboard、/impeccable optimize、/impeccable overdrive、/impeccable polish、/impeccable quieter、/impeccable shape、/impeccable typeset格式示例[P0]/impeccable adapt修复平板端放大的手机布局问题具体上下文[P1]/impeccable optimize为长列表引入 LazyColumn 回收具体上下文规则将每条发现映射到最合适的命令如果有任何修复被建议必须以/impeccable polish作为最后一步收尾。这些命令在白名单与 Impeccable 的 Commands 表中一一对应可从 SKILL.md 与 crates/context/src/command-metadata.json 查到各自的官方描述——例如audit在元数据中被描述为跨无障碍、性能、主题、响应式与反模式运行技术质量检查生成带 P0-P3 严重度评级和可执行计划的分级报告。展示完行动清单后必须原样告诉用户You can ask me to run these one at a time, all at once, or in any order you prefer.Re-run/impeccable auditafter fixes to see your score improve.这形成了一个闭环审计 → 分级 → 映射命令 → 修复 → 复查审计健康分成为可追踪的改进指标。审计纪律NEVER 清单与实操要点audit.native.md末尾给出了审计者必须遵守的纪律防止报告变成噪音不要只报告问题而不解释影响为什么它对用户重要不要给出泛泛的建议要具体、可执行不要跳过正面发现肯定有效的实践不要忘记优先级不可能所有问题都是 P0不要未经验证就上报误报report false positives without verification最后一条尤为重要P0-P3 中 P3 级别的问题过多就是噪音Too many P3 issues creates noise审计的目标是Be thorough but actionable——详尽但可执行聚焦真正重要的事。如何在你的原生项目中运行审计确认平台项目平台为ios/android/adaptive时审计自动路由到本文描述的原生流程Web 项目则走 audit.md前置准备先运行impeccable context完成 SetupSKILL.md 要求在每次会话中运行一次由它加载 PRODUCT.md、DESIGN.md 以及匹配的平台参考如果审计开始前平台参考尚未加载先读 ios.md / android.md 再评分从源码取证直接审计 SwiftUI / UIKit / Compose / React Native / Flutter 源码逐维度打 0-4 分汇总 ??/20 健康分并给出评级带先写裁决再写明细Platform Conformance Verdict 先行随后是执行摘要、P0-P3 问题明细、系统性模式、正面发现给出优先级行动清单只推荐白名单命令末尾用/impeccable polish收尾并转述可逐个、可批量、可任意顺序执行与修复后重跑 audit 看分数提升的引导语修复后用平台化方式复查iOS 用xcrun simctl截图并测深色外观与大字号 Dynamic TypeAndroid 用adb截图并测深色主题与font_scale 1.3记得在报告中注明证据来自模拟器/仿真器还是真机【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
原生应用技术审计指南：使用 Impeccable audit 对 iOS / Android 应用执行五维代码级质量审查
原生应用技术审计指南使用 Impeccable audit 对 iOS / Android 应用执行五维代码级质量审查【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable本文档系统讲解 Impeccable 技能套件中/impeccable audit命令的原生平台变体如何对 iOS、Android 以及跨平台adaptive原生应用执行代码级技术质量审计覆盖无障碍、性能、外观与主题、平台符合性、自适应性五个维度并产出带 0-4 分量化评分、P0-P3 严重度分级与修复命令建议的完整报告。读完本文你将掌握这套只记录、不修复的审计工作流能依据 ios.md 与 android.md 两份平台参考为你的原生项目建立可重复、可评分、可追踪改进的质量基线。audit 命令的双轨路由Web 与 Native 分道扬镳在 Impeccable 的 Commands 表中audit [target]被归类为 Evaluate评估命令官方描述是技术质量检查无障碍、性能、响应式并明确标注了 Web 与原生两个入口reference/audit.mdWeb与 reference/audit.native.mdNative。SKILL.md 的命令表中audit一行写作Technical quality checks (a11y, perf, responsive) | audit.md · native: audit.native.md这是全仓库唯二存在原生变体的命令之一另一个是adapt。这套机制在 CLAUDE.md 中有明确说明当命令的原生指导与 Web 版本差异过大、无法共用同一文件时就为它建立native variantreference/command.native.md。当setup.platform为原生平台时路由会用原生变体替代 Web 文件一个变体同时覆盖 ios、android、adaptive 三种平台各操作系统特有的细节则保留在平台参考文档中由 Setup 阶段统一加载。原生变体与 Web 版本必须保持报告骨架一致——修改audit.native.md时必须同步修改 audit.md 的报告骨架。这条路由不是纸上谈兵而是有测试背书的。在 tests/skill-behavior/scenarios.test.mjs 中测试明确验证当 fixture 的平台是 ios 时agent 必须加载audit.native.md而不是只读audit.md即Commands 表把 audit.native.md 列为原生变体、审计必须到达 audit.native.md。行为场景清单 tests/skill-behavior/README.md 也记录了同一条路由约定。原生审计与 Web 审计的本质差异原生变体在开篇就划清了两条边界这是代码级审计code-level audit不是设计批评design critique。审计的原料是源码——SwiftUI / UIKit / Compose / React Native / Flutter——而不是渲染结果。不适用任何浏览器工具链impeccable detect在此不生效。因为原生的无障碍、主题、自适应能力无法用浏览器里的 DOM 检测器衡量只能从平台框架的代码模式中取证。docs/CLI-CONTRACT.md 在讨论 CLI 契约时也专门引用了这条约定原生场景下no browser tooling or detect.mjs applies。评分标准则锚定平台参考ios 项目对照 ios.mdSwiftUI/UIKit/React Native/Expo/Flutter 发布到 Apple 硬件android 项目对照 android.mdJetpack Compose/Android Views/React Native/Expo/Flutter 发布到 Android 硬件adaptive 项目两份都读。如果 Setup 阶段还没有加载这些平台参考audit 开始前必须先读它们再评分。审计的立场只记录不修复audit.native.md的第一句话就是工作原则Run systematictechnicalquality checks ... Dont fix issues; document them for other commands to address.系统性技术质量检查并生成报告不修复问题而是记录问题供其他命令处理。审计产出的是证据和行动清单修复工作交给后续的命令按优先级执行——这也正是报告末尾Recommended Actions存在的意义。诊断扫描五个维度的检查点与评分标准原生审计在五个维度上逐项扫描每个维度按 0-4 分打分总分 20 分。下面按维度展开完整检查点与评分锚点。1. AccessibilityVoiceOver / TalkBack针对 iOS 的 VoiceOver 与 Android 的 TalkBack 检查以下方面缺失标签Missing labels可交互元素没有无障碍标签、trait/role、或状态播报state announcements阅读与焦点顺序Reading and focus order遍历顺序不合逻辑、控件无法到达、导航后焦点丢失文本缩放Text scaling固定 point size 破坏了 iOS Dynamic Type或 Android 用 px 而非 sp大字号下布局被裁剪或重叠触摸目标Touch targets低于 iOS 44 pt / Android 48 dp或目标之间没有间距、排列拥挤忽视 Reduce Motion视差和大滑块动画没有提供淡入淡出crossfade的替代方案对比度Contrast文字在浅色或深色外观中任一下不满足对比度要求评分锚点0-4分数含义0屏幕阅读器完全不可用1重大缺口控件无标签、无缩放2部分达标有标签但顺序或缩放有问题3良好少量缺口4优秀有标签、顺序正确、可缩放、尊重 Reduce Motion2. Performance性能启动缓慢Slow startup首帧渲染前在启动阶段做了大量重活未虚拟化列表Unvirtualized lists长内容没有使用 FlatList / LazyColumn / List 回收机制主线程卡顿Main-thread jank滚动或手势路径中的同步工作60/120 Hz 下掉帧浪费的渲染Wasted renderingReact Native 不必要的重渲染、Compose 不必要的重组缺少 memoization/keys图片处理Image handling缩略图直接解码全尺寸图片、没有缓存应用体积App weight臃肿的 JS bundle 或二进制、未使用的依赖评分锚点0-40处处卡顿1重大问题列表未虚拟化、启动慢2部分达标3良好尚有小的优化空间4优秀启动快、滚动流畅、体积精简。3. Appearance Theming外观与主题硬编码颜色Hard-coded colors用原始 hex 而非语义系统色iOS/ Material 色彩角色Android/ 设计令牌深色外观损坏Broken dark appearance缺少深色变体、深色下对比度差、粗暴的反色处理Dynamic ColorAndroid 12没有静态回退方案或在适合的场景中忽略了 Material You 动态取色非平台材质Off-platform materials在系统材质system materials或色调抬升tonal elevation应当出现的场景手工实现视觉材质评分锚点0-40一切硬编码1令牌极少2部分有令牌但使用不一致3良好少量硬编码值4优秀全语义化两种外观一等公民。4. Platform Conformance平台符合性CRITICAL这一维被标记为CRITICAL按已加载的平台参考含其中的 slop 测试评分系统手势损坏Broken system gesturesiOS 禁用边缘右滑返回、Android 劫持预测式返回predictive Back安全区违规Inset violations内容被刘海、灵动岛Dynamic Island、Home 指示条、状态栏或键盘遮挡非平台导航Off-platform navigation自定义全局导航、过载的标签栏、iOS 模式套在 Android 上或反之Web 形态控件Web-shaped controlsHTML 风格按钮、自定义开关、依赖 hover 的交互暗示图标漂移Icon drift混用图标集而不是统一使用 SF Symbols / Material Symbols系统漂移System drift与产品、平台或既定设计系统冲突的重复性快捷键或装饰模式评分锚点0-40Web 移植毫无原生感1严重违规3-4 类2存在 1-2 处明显问题3基本符合细微问题4完全原生熟练用户信任每个屏幕。5. Adaptivity自适应性手机布局拉伸Stretched phone layouts平板/iPad 渲染放大版手机 UI而不是使用 size classes / 窗口尺寸类方向破坏Orientation breakage横屏内容被裁剪、被忽略或无故锁定方向键盘/IME 处理输入框被键盘遮挡、没有 inset 调整多任务MultitaskingiPad Split View / Android 多窗口破坏布局折叠屏FoldablesAndroid 姿态变化posture change时折痕感知缺失评分锚点0-40只支持一种屏幕尺寸1重大破坏横屏或平板损坏2部分3良好少量边缘情况4优秀跨尺寸、方向与分屏自适应。平台参考的核心检查基线五个维度中的许多检查点都指向平台参考文档中的硬性规则。两份参考各自定义了slop 测试slop test——一个快速判断这是原生应用还是网站移植的直觉测试。iOS 基线ios.mdiOS slop test熟练的 iPhone 用户会信任这个应用还是在不符合规范的控件前停下来从网站移植的典型迹象是重新发明的导航栏、自定义返回手势、Web 形状的按钮、依赖 hover 的交互暗示安全区所有内容在 safe-area insets 内不得有控件位于刘海、灵动岛、Home 指示条或圆角之下系统导航2-5 个顶级分区用标签栏放 section 而非 action层级用导航栈独立任务用 sheet禁止自定义全局导航边缘右滑返回必须存活绝不能禁用或覆盖触摸目标每个可点控件最小 44×44 pt相邻目标之间留出呼吸空间Dynamic Type使用系统文本样式Large Title 到 Caption字体随用户阅读字号缩放禁止硬编码 point size正文 Body 为 17 pt11 pt 为下限语义系统色label、secondaryLabel、systemBackground、separator、tint 等随深色模式与增强对比度自动适配raw hex 会在此失效整个应用只有一个 tint 色驱动交互元素系统材质栏与 sheet 的模糊和半透明用系统材质禁止手工玻璃拟态平台控件与 SF SymbolsSwitch、分段控件、步进器、系统选择器、action sheets、alert、context menu、swipe actions 都该用系统组件图标统一 SF Symbols不得混入 Web 图标集动效系统转场push 滑动、sheet 升起、dismiss 逆向尊重 Reduce Motion用淡入淡出替代视差和大滑块Android 基线android.mdAndroid slop test最常见迹象是穿着 Android 皮肤的 iOS 应用——从 iPhone 抄来的底部导航、无视系统 Back 手势的返回箭头、Cupertino 形状的开关和对话框。Material Design 3 是规则书品牌通过它的 theming 表达Material 导航随宽度变化紧凑宽度用底部导航栏3-5 个目的地扩展宽度用导航 rail 或 drawer绝不在平板上原样使用手机底部栏系统 Back 始终可用尊重预测式返回手势和返回按钮绝不困住用户或劫持手势Edge-to-edge 窗口 insets应用状态栏、导航栏、显示裁切display cutout与 IME insets内容不藏在系统栏或键盘后面触摸目标每个触摸目标最小 48×48 dp之间至少 8 dpMaterial 字体尺度Display / Headline / Title / Body / Label 角色各分 large/medium/small文本映射到角色而不是逐屏手选字号sp 单位而非固定 px跟随系统字号设置Material 色彩角色primary、on-primary、surface、surface-variant、secondary-container、outline、error 等角色令牌自动解析明暗与对比度变体Android 12 的 Dynamic ColorMaterial You从壁纸取色必须有静态回退深色主题是头等方案绝不是快速反色色调抬升tonal elevation用标准 surface tonal 层级表达层级感外加适当的阴影禁止随意投影Material 组件与动效filled/tonal/outlined/text 按钮、FAB、开关、chip、snackbar、bottom sheet、Material 对话框、导航组件一个屏幕一个 FAB 一个主操作snackbar 用于瞬时反馈对话框只用于必须打断的决策动效遵循 container transform、shared-axis、fade-through 模式并尊重系统移除动画设置平台化的截图验证工作流两份平台参考都给出了真机证据的采集方法审计与修复后的复查都依赖它iOS截图必须来自 Simulator用xcrun simctl io booted screenshot path采集多台模拟器运行时用xcrun simctl list devices booted拿到目标 UDID 替换booted。xcrun simctl ui booted appearance dark切换深色外观还需在大号 Dynamic Type 下检查一次。至少覆盖一款 iPhone若面向 iPad 再覆盖一款 iPadAndroid截图来自模拟器或真机用adb exec-out screencap -p path采集多设备时用adb -s serial指定。adb shell cmd uimode night yes切换深色主题adb shell settings put system font_scale 1.3放大字号检查裁剪用后恢复1.0。至少覆盖一款手机面向平板则再加一款平板两条平台参考都强调同一原则模拟器/仿真器给广度手势、刷新率与性能需要真机——报告必须说明证据来自哪种载体生成报告从评分表到行动清单审计的最终交付物是报告audit.native.md给出了从骨架到细节的完整模板。Audit Health Score健康分表报告开头的核心表格#DimensionScoreKey Finding1Accessibility?[最严重的无障碍问题或 --]2Performance?3Appearance Theming?4Platform Conformance?5Adaptivity?Total??/20[Rating band]Rating bands 分级区间等级含义18-20Excellent只需细微打磨14-17Good需要修补薄弱维度10-13Acceptable需要大量工作6-9Poor需要重大重构0-5Critical存在根本性问题Platform Conformance Verdict平台符合性裁决模板明确标注Start here——这一节要最先写。核心问题是这读起来像原生应用还是像网站移植列出具体的违规项并且be brutally honest要极其诚实。它是整个审计的定性结论健康分表是它的量化总结。Executive Summary执行摘要Audit Health Score??/20评级带问题总数按 P0/P1/P2/P3 严重度计数Top 3-5 关键问题建议的下一步Detailed Findings by Severity按严重度分级的问题明细每条问题必须打上P0-P3 严重度标签P0 Blocking阻碍任务完成立即修复P1 Major造成显著困难或违反平台指南发布前修复P2 Minor令人烦恼、存在变通方案下个迭代修复P3 Polish锦上添花、无实质用户影响有空再修每条问题需完整记录 7 项[P?] 问题名称、Location屏幕、文件、行号、CategoryAccessibility / Performance / Theming / Conformance / Adaptivity、Impact如何影响用户、Guideline违反的 HIG / Material 规则如有、Recommendation如何修复、Suggested command建议用哪条命令修复。Patterns Systemic Issues模式与系统性问题识别反复出现的问题——它们指向系统级缺口而非一次性失误例如硬编码颜色出现在 15 个屏幕中应改用语义色触摸目标在标签栏和列表行的全部场景中持续低于 44 ptPositive Findings正面发现记录做得好的部分——值得保持和复制的良好实践。模板提醒celebrate what works。Recommended Actions把发现映射到修复命令建议命令必须按优先级排序P0 优先然后 P1、P2且只能从官方白名单中选择/impeccable adapt、/impeccable animate、/impeccable audit、/impeccable bolder、/impeccable clarify、/impeccable colorize、/impeccable critique、/impeccable delight、/impeccable distill、/impeccable document、/impeccable harden、/impeccable layout、/impeccable onboard、/impeccable optimize、/impeccable overdrive、/impeccable polish、/impeccable quieter、/impeccable shape、/impeccable typeset格式示例[P0]/impeccable adapt修复平板端放大的手机布局问题具体上下文[P1]/impeccable optimize为长列表引入 LazyColumn 回收具体上下文规则将每条发现映射到最合适的命令如果有任何修复被建议必须以/impeccable polish作为最后一步收尾。这些命令在白名单与 Impeccable 的 Commands 表中一一对应可从 SKILL.md 与 crates/context/src/command-metadata.json 查到各自的官方描述——例如audit在元数据中被描述为跨无障碍、性能、主题、响应式与反模式运行技术质量检查生成带 P0-P3 严重度评级和可执行计划的分级报告。展示完行动清单后必须原样告诉用户You can ask me to run these one at a time, all at once, or in any order you prefer.Re-run/impeccable auditafter fixes to see your score improve.这形成了一个闭环审计 → 分级 → 映射命令 → 修复 → 复查审计健康分成为可追踪的改进指标。审计纪律NEVER 清单与实操要点audit.native.md末尾给出了审计者必须遵守的纪律防止报告变成噪音不要只报告问题而不解释影响为什么它对用户重要不要给出泛泛的建议要具体、可执行不要跳过正面发现肯定有效的实践不要忘记优先级不可能所有问题都是 P0不要未经验证就上报误报report false positives without verification最后一条尤为重要P0-P3 中 P3 级别的问题过多就是噪音Too many P3 issues creates noise审计的目标是Be thorough but actionable——详尽但可执行聚焦真正重要的事。如何在你的原生项目中运行审计确认平台项目平台为ios/android/adaptive时审计自动路由到本文描述的原生流程Web 项目则走 audit.md前置准备先运行impeccable context完成 SetupSKILL.md 要求在每次会话中运行一次由它加载 PRODUCT.md、DESIGN.md 以及匹配的平台参考如果审计开始前平台参考尚未加载先读 ios.md / android.md 再评分从源码取证直接审计 SwiftUI / UIKit / Compose / React Native / Flutter 源码逐维度打 0-4 分汇总 ??/20 健康分并给出评级带先写裁决再写明细Platform Conformance Verdict 先行随后是执行摘要、P0-P3 问题明细、系统性模式、正面发现给出优先级行动清单只推荐白名单命令末尾用/impeccable polish收尾并转述可逐个、可批量、可任意顺序执行与修复后重跑 audit 看分数提升的引导语修复后用平台化方式复查iOS 用xcrun simctl截图并测深色外观与大字号 Dynamic TypeAndroid 用adb截图并测深色主题与font_scale 1.3记得在报告中注明证据来自模拟器/仿真器还是真机【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
