adversarial-ios-design

对抗式 iOS 设计门禁

iOS 设计与 UX 审查门禁——通过/不通过：由单个盲审子 Agent 按照本门禁规则，以对抗性审查方式评判作品；只有每条规则均为 PASS 或 N/A 时，作品才算通过。本技能只给出判定，绝不修复作品。

门禁评判的是渲染后的用户界面，而不是源文本。采集证据——模拟器截图和交互录屏拼接成胶片条——是强制流程步骤；审查者从像素倒推：先观察采集结果，再怀疑违规之处，最后才打开代码定位问题。仅审查代码是门禁记录在案的失效模式：这会让门禁沦为一个指示从未见过的动画该如何制作的代码检查器。

这些规则是 Apple 设计审查会指出的问题中可判定的子集——每条规则都明确说明用于判定的证据，依据来自人机界面指南、WWDC 设计专题，以及 Apple 自身对应用的实测惯例。门禁针对 Agent 和经验丰富但并非专家的开发者实际会交付的失效模式进行评判：该用标签栏却用了汉堡菜单抽屉、推入式表单在滑动关闭后丢失草稿、提醒框写着“Yes”/“No”、空状态一片空白、全屏加载指示器、状态变化瞬间跳转、在内容上绘制玻璃效果，以及文字在辅助功能字号下被截断。

何时应用

• 面向用户的 SwiftUI 屏幕、功能或 PR 即将合并，需要对设计和 UX 质量作出客观的 PASS/FAIL 判定，而不是咨询式反馈。
• 某个 Agent（Claude、Codex）编写了 UI，你希望独立检查它是否遵循平台的设计规范——模态呈现、导航结构、提醒规范、反馈状态——而不是把 Web/Android 习惯翻译成 Swift。
• 某个屏幕“能用”但感觉不像原生界面，你希望列出可判定的原因及其位置，而不是主观的审美形容词。
• 某次设计润色声称达到了 Apple 级品质，你希望依据屏幕的实际渲染效果——截图和胶片条——而不是代码暗示的效果来检验这一说法。
• 之前的“润色”或门禁驱动的修复轮次让 UI 变得更繁杂——增加了动画、触觉反馈或装饰——你希望强制执行克制原则：无谓的动效不合格，每项修复都必须是最小改动，优先删除而非添加。
• 差异涉及手势或交互行为（识别器、拖动/长按/调整大小、自定义 ButtonStyle/PrimitiveButtonStyle 实现）——运行本门禁及其采集流程，并在同级架构门禁之前执行：仅审查代码无法发现识别器仲裁；一次顺利试验不构成证据（参见 references/_evidence-capture.md 中的重复试验要求）；把本门禁放在最后，正是交互回归问题伪装成已审查状态交付的原因。

不要将本门禁用于没有 SwiftUI 用户界面部分的目标——服务器端 Swift、CLI 工具、非 UI 软件包（审查者提示词的前置条件会中止，并显示 “GATE NOT APPLICABLE”）。SwiftUI 架构和更新机制（观察、视图标识、任务生命周期、列表构建）由同级的 adversarial-swift-ui 门禁负责；Swift 语言质量由 adversarial-swift 负责。本门禁无法判定的审美判断（主视觉比例、情感意图、构图）属于 ios-taste——排除项列表见 gotchas.md。补救措施需要的最低部署目标版本高于项目所用版本的规则，判为 N/A，而不是 FAIL——审查者提示词中附有版本门槛表。

审查流程

严格按以下步骤执行——本门禁的价值就在于每次审查都采用相同流程。

步骤 1 之前有两个前置条件——之所以设置这两个条件，是因为违反它们正是本门禁系列记录在案的实际失效模式（2026 年 7 月：门禁在不断变动的目标上充当清理驱动器运行，差异增长到 33 个文件时仍未产生任何判定）：

• 固定目标。 仅针对固定的引用进行派发——提交 SHA、储藏或已保存的差异——并将其记录为目标清单。如果待审查的代码仍在变化（工作区持续累积编辑，其他 Agent 也在其中操作），则不要派发。如果审查进行期间目标发生变化，本次运行即作废：应以 GATE VOID — target changed 代替裁决，并针对新的固定状态重新派发。已派发的门禁必须始终以呈现裁决、GATE NOT APPLICABLE 或记录作废告终——绝不能无声结束，因为这与“已审查”无法区分。
• 裁决，而非清理。 此门禁是对已完成工作的最终检查。“运行门禁并激进地修复所有问题”颠倒了约定，也是有据可查的范围膨胀路径：先实现，再冻结，然后执行门禁。出现 FAIL 后，调用方仅在原始目标范围内应用修复，并针对同一目标清单重新派发全新的盲审查者——各轮之间审查范围绝不扩大；新增代码意味着需要以其自己的清单启动新一轮门禁。

当其他 Agent 可能在审查期间修改工作区时，审查者应从不可变快照读取规则（例如 git archive <ref> <skill-dir> | tar -x -C "$TMPDIR"），而不是读取实时检出内容；技能目录属于只读基础设施，必须排除在所有清理或修复范围之外。

1. 确定目标。 明确界定审查对象（差异、文件集、PR、单个屏幕或完整流程），并记录引用版本和路径，确保审查针对的是明确且固定的目标。记录 Swift 工具链和最低部署目标——多项规则会根据它们进行版本判定。还要包含仓库根目录——nav-stack-per-tab、flow-onboarding-optional 和 state-launch-screen-replica 可能要求检查差异代码块之外的 App 入口点、Info.plist 和资源目录。
2. 收集渲染证据。 按照 references/_evidence-capture.md 操作：先预检截图能力（启动模拟器并截取一张临时截图——如果失败，立即记录明确的阻塞原因，不要等到审查数小时后才记录），然后在模拟器中构建并运行目标，为每个受影响的屏幕截取浅色、深色和辅助功能字号的截图，并将每次会改变结构的交互录制为 10 fps 胶片条，同时为每个主要屏幕录制一段简短的空闲视频。涉及手势的交互需要在同一次 App 会话中至少连续录制 3 次试验——一次顺利运行不足以证明识别器仲裁有效。此步骤为必需步骤——只有遇到明确记录在裁决标题中的阻塞原因时才可跳过（项目无法构建、没有模拟器运行时，或屏幕无法在没有凭据的情况下访问）。没有截图时，依赖截图的检查项标记为 N/A，动态效果规则只能报告候选问题——绝不能判定为 FAIL 或 PASS。
3. 加载规则。 阅读 references/_sections.md 和 references/ 中的所有规则文件（所有 nav-*.md、flow-*.md、layout-*.md、color-*.md、type-*.md、glass-*.md、state-*.md、motion-*.md、haptic-*.md、craft-*.md 文件）。
4. 编写审查提示词。 将规则、目标、工具链和部署信息，以及截图、录制和胶片条的绝对路径（或明确的截图阻塞原因）填入 references/reviewer-prompt.md。编写好的提示词必须完全自包含——审查者看不到任何对话历史，因此不得引用提示词之外的上下文。
5. 派发一名盲审查者。 启动一个 Task 子代理，其完整输入只能是编写好的提示词——不得附带对话上下文或其他评论。
6. 采用失败即关闭原则给出结果。 审查者的结构化输出即为裁决结果——不存在合并步骤。只有每条规则都为 PASS 或 N/A 时，总体结果才是 PASS；任何一条 FAIL 都会使检查门禁失败。绝不取平均值、权衡严重程度或豁免规则——“轻微”的 FAIL 仍是 FAIL。如果审查者返回“GATE NOT APPLICABLE”（没有 SwiftUI UI 界面），应停止并报告该结果，而不是给出裁决。
7. 生成裁决。 填写 assets/templates/verdict.md。若结果为 FAIL，将审查者提出的“达到 PASS 所缺少的内容”汇总到修复清单中，并为每项标注位置，按类别重要性排序。每条最终结果为 FAIL 的规则都必须出现在修复清单中，并且修复内容必须具体到可以直接照此应用——如果审查者的建议只是重述违规内容，则应根据规则中的 Correct 示例推导修复方案再填写。生成清单前，逐项执行最小化测试：采用能使规则结果翻转的最小改动，优先删除而非添加，且不得超出规则明确指定的补救措施添加任何内容——包括动画、触觉反馈、视图、状态或抽象。修复清单是核验材料，用于证明每项 FAIL 都能明确判定并通过改动消除，而非待办事项：修复必须限于已声明的目标范围内；审查者发现的目标清单之外的违规，应列入裁决中的范围外观察项——供未来调用检查门禁时报告，当前不得修复，也不得计入裁决结果。 如果同一条规则在对未发生变化的目标进行多次复审时反复改变判定结果，或者人工查看证据后推翻判定结果，这就是规则中的可判定性缺陷——请将其记录在 gotchas.md 中并细化规则；不要推翻门禁判定。

判定格式

审查者针对每条规则返回：PASS | FAIL | N/A、证据（file:line、引文或具名截图区域；PASS 和 FAIL 均须提供），以及每项 FAIL 对应的修复方案：应用后可使规则通过的明确变更及其位置，而不是重述违规内容。最终报告遵循 assets/templates/verdict.md。

规则类别

#	类别	前缀	涵盖内容
1	导航与信息架构	nav-	使用 TabView 而非抽屉／按钮网格；标签页用于导航而非执行操作；≤5 个标签页；标签栏保持稳定；每个标签页使用一个 NavigationStack；系统返回按钮；每个屏幕都有标题；通过系统提供的界面进行搜索
2	模态与流程规范	flow-	独立任务使用工作表；取消按钮靠前，完成按钮靠后；防止关闭有未保存更改的工作表；仅媒体／多步骤流程使用 fullScreenCover；一次仅显示一个工作表；警告框仅用于可执行操作，并使用动词按钮；有意执行破坏性操作时使用 confirmationDialog；可撤销的删除不显示确认提示；可选的引导流程，并在情境中请求权限；尽量减少情境中的设置项
3	布局与视觉层级	layout-	44×44 pt 的点击目标及其周围留白；按钮与边缘保持间距；背景延伸至安全区域外，内容遵循安全区域；动态字体文本不使用固定高度容器；嵌套圆角保持同心
4	颜色与对比度	color-	使用系统背景颜色；语义化标签层级；保留语义角色；达到数值对比度下限；绝不只通过颜色表示状态；自定义颜色和图像需提供深色模式变体；文字与图像之间使用提升可读性的图层
5	排版	type-	最小字号为 11 pt；界面文字不使用 Ultralight／Thin／Light 字重；区块标题使用标题式样
6	材质与 Liquid Glass	glass-	仅在浮动层使用玻璃材质，绝不让玻璃叠加在玻璃之上；每个栏中最多有一个着色操作；栏后不绘制底色，也不混用滚动边缘样式
7	反馈状态	state-	设计空状态；优先使用骨架屏，而非全屏加载指示器；使用确定性进度指示，避免含糊标签；错误状态说明原因并提供恢复方式；启动屏仅复刻界面框架
8	动效	motion-	以录屏为主要依据：通过逐帧检查确定是否存在突变、反馈时长过长、界面框架过冲、以滑动代替缩放以及多余装饰；使用弹簧动画而非缓动曲线，并确保 Reduce Motion 路径可由代码判定——除此之外，仅凭代码只能筛选出候选项
9	触觉反馈	haptic-	重要结果应提供成功／错误触觉反馈；不触发垃圾信息式反馈；记录不同模式的含义；标准控件不重复触发反馈
10	工艺细节	craft-	数字文本过渡使用固定宽度数字；通过文本 API 设置 SF Symbols 大小，并匹配字重／变体；不锁定外观模式

注意事项

分派审查者之前，请阅读 gotchas.md——其中预先记录了规则忠实度防护要求（字体／颜色字面值的同级门禁边界、双向删除确认规则，以及不存在单一强调色规则）、阈值依据（推导得出的 0.5 s 动效上限）、截图证据协议，以及此门禁刻意排除的判断事项。

相关技能

• adversarial-swift-ui — 用于 SwiftUI 架构和更新机制的同级把关项（观测、身份、任务生命周期、列表、动画范围）；对面向用户的 SwiftUI 工作同时运行两项；如果差异涉及手势或交互行为，则先运行此把关项。
• adversarial-swift — 用于混合工作中 Swift 语言相关问题的同级把关项。
• ios-taste（精选）— 本把关项刻意排除的判断性设计指导；先用它来设计屏幕，再用本把关项来验证可判定的部分。
• design-review（精选）— 本把关项视角对应的 Web UI 建议性评审。

参考文件

文件	描述
references/_evidence-capture.md	强制执行的捕获协议：模拟器截图、交互录制、ffmpeg 胶片条，以及如何查看它们
references/reviewer-prompt.md	供盲审员使用的独立提示词模板，涵盖版本门控、先看像素再看代码的评审顺序以及捕获协议
assets/templates/verdict.md	评审结论报告模板
references/_sections.md	类别定义和排序
metadata.json	版本和来源引用