Impeccable 的 iOS 平台参考（ios.md）：把 Apple HIG 蒸馏成 AI 可执行的 native 设计规范

本文解读 Impeccable 技能包中 reference/ios.md 这份 iOS/iPadOS 平台参考文档：它是 AI harness 在做原生 iOS 设计决策时的"规则手册"，覆盖安全区与系统导航、44pt 触控目标、Dynamic Type 与 SF 字体、语义颜色与系统材质、SF Symbols 与模态层级，以及用 xcrun simctl 在 Simulator 中完成构建验证的完整流程。读完你会掌握这套 native 规范的全部要点，并理解它如何由 PRODUCT.md 的 ## Platform 字段驱动、由 context.mjs 自动内联进模型上下文的加载机制。

文档定位：native 平台的规则参考

ios.md 属于 Impeccable 单一技能（impeccable，含 23 个子命令）下的平台参考文件之一，与 android.md 并列，专门服务原生 iOS / iPadOS 应用：SwiftUI、UIKit、React Native、Expo、Flutter 等最终运行在 Apple 硬件上的技术栈。

它确立的核心原则是：HIG（Apple Human Interface Guidelines）合规性在每一种工作模式下都管辖结构、导航与交互；而品牌只通过平台留出的开放层来表达——tint（强调色）、type（字体）、motion（动效）、content（内容）。文档开头进一步定义了"visitor mode"的边界：在 native 场景下，它收窄的是表达可以覆盖的范围，而不是取代 HIG。

这份文档的来源值得注意：根据 NOTICE.md 的第三方声明，skill/reference/ios.md 与 android.md 是从 MIT 许可的 ehmo/platform-design-skills 项目蒸馏（Apple HIG 与 Material Design 3 规则）而来，并改写成 Impeccable 自身的语气。也就是说，它不是泛泛的"iOS 设计建议"，而是一份经过取舍、可直接喂给模型执行的检查清单。

文档如何被加载：Platform 字段驱动

从仓库源码结构看，这份文档不是被动躺在目录里的，而是由一套确定性的加载机制驱动的：

• 用户的 PRODUCT.md 携带一个 ## Platform 小节，取值是裸值：web / ios / android / adaptive（跨平台单一代码库同时发布双端并逐 OS 适配，如 Flutter、React Native、KMP）。字段缺失时默认 web，legacy 项目不受影响。
• 解析逻辑在 extractPlatform()：读取 ## Platform 后第一个非空行并小写化。一个值得注意的细节是，ios, android 或 ios and android 这样的双目标列表会被识别为 adaptive，而不是未识别值；任何无法识别的取值会回落到 web，同时 context.mjs 的 CLI 会打印一条 WARNING 指令，点名坏值——"工具链名或拼写错误不会静默获得 web 指导"。
• 当平台解析为 ios / android / adaptive 时，loadNativePlatformReferences() 会把对应的平台参考（adaptive 则同时读 ios 和 android 两份）直接内联进 context 输出，让 native 规范无需模型二次读文件就进入上下文。
• 命令级路由上，当 setup.platform 为 native 时，存在 native 变体的命令会改走变体文件：目前为 audit.native.md 与 adapt.native.md；而 layout、typeset、animate 这类命令则在自己的 web 文件里用一行指引把 native 场景引到 ios.md。例如 layout.md 写明"Native：follow ios.md or android.md for navigation, insets, adaptation, and touch targets"。

还有一条重要的"减法"事实：Live 模式、detect CLI 与设计 hook 都是 web-only——它们基于浏览器/HTML 规则工作，因此 SKILL.md 的路由对任何 native 项目都会跳过 live 与 detect.mjs，hook 在 PRODUCT.md 声明 native 平台时也会停止扫描（React Native 项目恰好全是被 hook 监听的 .tsx/.ts/.js 文件）。对 iOS 项目而言，这意味着验证手段只能是下一节讲的 Simulator 证据链，而不是浏览器截图检测。

The iOS slop test：一页识别"从 Web 移植来的 App"

文档用一道直觉测试作为总纲：

一个熟练的 iPhone 用户会信任这个 App，还是会在不符合规范的控件上犹豫？

破绽（tell）是"从网站移植过来的"痕迹：重造导航栏、自定义返回手势、Web 形状的按钮、依赖 hover 的交互暗示。默认做法是使用平台组件，只在"用户会感谢你"的理由下才偏离。

这条测试把后面所有细则串成一条线：安全区、系统导航、触控目标、语义颜色、SF Symbols、模态层级——它们各自都是"不 slop"的具体判据。

布局与结构

• Safe area（安全区）。 布局必须落在 safe-area insets 之内。刘海、Dynamic Island、home indicator、圆角之下不放任何控件。
• 系统导航。 2–5 个顶级分区用 Tab bar（放"分区"而非"动作"）；层级用 navigation stack；自包含任务用 sheet。禁止自定义全局导航，禁止混用隐喻（mixed metaphors）。
• 保留左缘滑回手势。 左边缘 back gesture 是肌肉记忆，永不禁用或覆盖它。
• **大标题（Large title）**用于顶层页面，滚动时塌缩为 inline；深层详情页保持 inline。

这组规则与 adapt.native.md 的告诫相呼应：跨设备类/平台适配的陷阱是"把适配当缩放"，工作是在目标平台约定内重新思考体验。

触控目标

• 每个可点控件最小 44×44 pt，相邻目标之间留足呼吸空间。

这是 HIG 的硬性底线，也是 native 与 web 检查最容易被"视觉通过但手指不通过"忽略的一条：视觉上 28pt 的图标按钮看起来没问题，实际命中区域不达标。

排版

• Dynamic Type。 使用系统文本样式（从 Large Title 到 Caption），让文字跟随用户设置的字号。禁止硬编码字号。
• San Francisco 承载 UI。 正文、标签、控件留在 SF Pro / SF Compact 上；品牌字体只允许出现在 display 时刻。
• 11 pt 下限；Body 为 17 pt。

在 Impeccable 的命令体系里，typeset 命令对 native 项目的指引同样是"follow ios.md，包括平台缩放与无障碍行为"（见 typeset.md）。

颜色与材质

• 语义系统颜色（label、secondaryLabel、systemBackground、separator、tint）。它们自动适配 Dark Mode 与高对比度；裸 hex 会在那里失效。
• Dark Mode 是一等外观（first-class appearance）。 两种模式都要设计并测试。
• 只有一种 tint 颜色驱动交互元素；装饰不是它的职责。
• **系统材质（materials）**用于栏与 sheet 背后的模糊与半透明；不要手搓玻璃拟态（hand-rolled glassmorphism）。

组件与控件

• 平台控件。 Switch、segmented control、stepper、系统 picker、action sheet、alert、context menu、swipe actions。"为了风味而重造"这些控件是最常见的 native slop。
• SF Symbols 承载图标。 基线对齐、感知 Dynamic Type、有 weight 与 scale 变体；不要混入 Web 图标集。
• 有意识的模态性（deliberate modality）。 聚焦可关闭的子任务用 sheet，沉浸用 full-screen cover。取消/完成要清晰；除非数据丢失要求保护，否则尊重下滑关闭。
• **分组/内嵌列表（grouped/inset list）**承载设置形态的内容；不要自造卡片堆叠。

动效

• 系统转场。 push 是滑动、sheet 是升起、关闭是入场动画的逆放。与导航模型对抗的自定义转场会令人迷失。
• 尊重 Reduce Motion。 用交叉淡入淡出（crossfade）替代视差与大位移。

animate 命令对 native 项目同样只做一行指引："follow the Motion section of ios.md / android.md，包括平台的 Reduce Motion 行为。不要应用 web 工具链"（见 animate.md）。这是 Impeccable v4 的一个设计取舍：平台差异足够大的内容留在平台参考里，而不是给命令文件加内联翻译注释——避免 native 运行时"为 web 内容付账"。

验证构建：Simulator 是唯一截图来源

这是文档中最具可操作性的部分，它给 AI harness 规定了 native 证据链的完整命令：

1. 截图只能来自 Simulator，绝不允许来自浏览器。 构建并运行后，用：

   xcrun simctl io booted screenshot <path>
   

   多个 Simulator 同时运行时，把 booted 换成目标设备的 UDID——从 xcrun simctl list devices booted 获取。文档特别指出：显示名可能重名，而 UDID 永远不会，所以多实例时必须用 UDID。要覆盖 App 发布的每一类设备：至少一台 iPhone，若 iPad 是目标则加一台 iPad，并把文件写到审查流程期望的位置。

2. Dark Mode 与 Dynamic Type 属于通过条件（pass 的一部分）。 翻转外观：

   xcrun simctl ui booted appearance dark
   

   多个设备在线时同样复用截图那次的 UDID；在大 Dynamic Type 尺寸下检查一次，能抓出固定布局掩盖的截断。

3. Simulator 给广度；姿态、手势、性能需要真机。 要说明证据出自哪一边。

这条证据链与 Impeccable 的审查流程严丝合缝：finish reviewer 期望的截图在 .impeccable/review/ 下，native 项目按设备类命名（phone.png、tablet.png，adaptive 时按 OS 加后缀）——见 impeccable-finish-reviewer.md。也就是说，ios.md 规定的"从哪抓图、写到哪里"直接决定下游 review 环节能否拿到有效证据。

适用前提与边界

• 本文所有细则适用于 PRODUCT.md 中 ## Platform 为 ios（或 adaptive 时与 android.md 并用）的项目；web 项目不加载这份参考，General 规则已覆盖。
• 从源码结构看，平台识别依赖 PRODUCT.md 的裸值字段；doctor 命令会把"工作区有 native 构建文件却继承了 web 记录"列为关键发现（workspace-platform-native-evidence），因为一个继承的记录无法同时承载两个平台，修复方式是在该工作区写子 PRODUCT.md——见 doctor.md。
• 该参考文件在仓库内以多份 provider 镜像同步分发（.agent/、.claude/、plugin/ 等目录下均有 skills/impeccable/reference/ios.md），源文件为 skill/reference/ios.md，各镜像内容一致。

小结

ios.md 是 Impeccable 把 Apple HIG 压缩成"模型可执行清单"的样本：slop test 定基调，布局/触控/排版/颜色/组件/动效给出六组硬性判据，xcrun simctl 命令链给出可复现的验证手段；而 extractPlatform() 与 loadNativePlatformReferences() 则保证这份规范在平台被声明的那一刻就自动进入上下文——这正是"设计语言让 AI harness 更擅长设计"在 native 场景下的落点。