Figma iOS 构建审查流程

使用本工作流从 Figma 构建或审查原生 iOS UI，并持续迭代，直至线上应用界面与设计稿完全一致。优先采用真实运行时状态，但本地 UI 验证可使用 Local Direct Harness。以 Figma 作为视觉参考依据，而非添加虚假生产环境路径的理由。

输入项

仅收集必需内容：

• Figma URL、文件密钥（file key）、节点 ID（node id）或截图。
• 目标界面表面（surface）及其状态：启动（launch）、加载（loading）、权限（permission）、空态（empty）、已填充（populated）或错误（error）。
• 目标 UIKit 文件或视图控制器（view controllers）。
• 导航路径：启动可见（launch-visible）、已提交的 Maestro 流程（committed Maestro flow）、本地路由（local route）或 Local Direct Harness。
• 所需资源（assets）及预期的资源目录（asset catalog）名称。

若仓库中存在 AGENTS.md 或本地 Figma-to-code 标准操作流程（SOP），请先阅读并以其为准，覆盖通用说明细节。

模式决策

在开始编辑前确定路径：

• 从 Figma 构建：适用于用户要求实现全新 Figma 页面、创建缺失的页面/组件/单元格，或完成从设计到 UIKit 代码的端到端转化。
• 审查现有 UI：适用于目标 UIKit 界面已存在，且用户要求比对、打磨、审计或提升 Figma 保真度（fidelity）的场景。

两条路径最终均进入相同的视觉审查循环（visual review loop）。

共用准备步骤

1. 通过 Figma MCP 读取 Figma 节点，捕获节点 ID、截图、尺寸、状态、颜色、字体排印（typography）、图标、资源及关键画框（frames）。
2. 查阅目标仓库规则、现有 UIKit/SnapKit 模式、导航风格、数据存储（data stores）及 harness 命令。
3. 若任务非 trivial 且仓库要求执行计划，则在仓库指定的规划位置新增或更新执行计划。

从 Figma 构建

适用于从零开始的实现：

1. 将 Figma 节点拆解为屏幕结构、可复用视图、单元格（cells）、控件、资源、状态及交互行为。
2. 确定目标集成点：新视图控制器、已有视图控制器、子视图、表格/集合单元格、路由或资源目录条目。
3. 基于现有 UIKit、SnapKit 或 Auto Layout、数据存储、服务、颜色辅助工具及资源命名规范进行实现。
4. 实现产品行为时，接入真实运行时状态；仅在本地 UI 验证时使用 Local Direct Harness。
5. 仅对 Maestro 流程中需点击或断言（assert）的控件，添加稳定的 accessibilityIdentifier 值。
6. 新增或更新路由逻辑，确保持久化产品界面可通过常规应用导航访问；当无需持久化路由时，使用 Local Direct Harness 进行纯本地视觉审查。
7. 若新界面引入了持久化的用户交互路径，则新增或更新已提交的 Maestro 流程。
8. 运行构建/启动门禁（build/launch gate），随后进入视觉审查循环。

审查现有 UI

适用于保真度审查或细节打磨：

1. 读取现有 UIKit/SnapKit 文件、视图模型（view models）、资源及流程 ID（flow ids）。
2. 识别与 Figma 的预期差异：安全区域（safe area）、数据差异、原生行为差异、缺失资源、动态文字压力（dynamic text pressure）等。
3. 运行构建/启动门禁，将模拟器切换至目标页面，随后进入视觉审查循环。

Local Direct Harness

当真实导航或 Maestro 会引入干扰噪声时，使用该方式聚焦于本地视觉验证：

• 创建渲染目标状态所需的模拟（mock）或固件（fixture）依赖项。
• 直接将应用窗口（app window）的 rootViewController 设置为待审查的视图控制器。
• 将入口限定在 Debug、harness 或 test 构建目标中，避免影响常规生产路径。
• 审查完成后，恢复或移除临时模拟入口、启动钩子（launch hooks）及 rootViewController 覆盖逻辑；除非该 harness 是已提交的可复用测试入口，否则不应保留。
• 在最终交付物中记录模拟依赖项、根视图控制器及清理状态。

视觉审查循环

重复以下循环，直至变更区域全部通过比对检查清单：

1. 使用仓库的启动门禁构建并启动 Debug 版应用，通常执行：

   scripts/verify.sh
   

2. 将模拟器切换至目标页面：

   • 对于启动可见（launch-visible）页面，使用最新 harness 的 launch.png。
   • 对于持久化导航，使用已提交的 Maestro 流程。
   • 对于本地 Lookin 审查，使用 .harness/tmp/ 下的临时 hold 流程；在最终 hold sentinel 前断言目标根视图或关键控件。
   • 当直接视觉验证更快时，使用 Local Direct Harness。

3. 使用 Lookin MCP 检查实时 UIKit 视图层级及其相关属性。若当前环境不可用 Lookin MCP，则改用模拟器截图加代码审查，并将缺失层级证据记录为残余风险（residual risk）。

4. 使用 Lookin 截取实时原生截图。若 Lookin 截图超时、层级过浅，或仅返回不可操作的图层数据，则使用：

   xcrun simctl io "$VERIFY_SIMULATOR_ID" screenshot .harness/tmp/.png
   

5. 将实时原生界面与 Figma 源对比，调整 UIKit/SnapKit、资源、颜色、字体排印、图标朝向、间距及动态尺寸适配。

6. 重新构建、导航回该页面，并对已变更的视觉区域重复 Lookin/截图检查。

7. 运行仓库的验证门禁（verification gates），并记录任何阻塞项（blocker）。

Maestro 与 Lookin

使用 Maestro 作为点击驱动器和持久化黑盒门禁（black-box gate）；使用 Lookin 作为原生 UIKit 检查桥接器，用于查看视图层级、属性及截图。针对聚焦式视觉审查，Local Direct Harness 可替代 Maestro 导航；但在验证持久化端到端导航、点击或断言时，应优先使用已提交的 Maestro 流程。

对于 iOS 系统权限，优先使用 Maestro 的 launchApp.permissions 或 setPermissions，以避免常规视觉审查与冒烟测试（smoke flows）依赖系统弹窗文案。当本地 Maestro/Xcode/iOS 模拟器栈在设置 usertracking: allow 后仍显示 ATT/用户追踪提示时，允许跳过 ATT/用户追踪弹窗的点击操作。仅当流程明确用于测试权限行为本身时，才将系统权限弹窗设为流程目标。

当多个 Maestro 流程面向同一模拟器时，请串行执行。单个 iOS 模拟器在同一时间仅能被一个 Maestro 进程可靠驱动，因此切勿为节省时间而并行启动多个流程命令。若仓库提供了封装脚本（如 scripts/verify-flow.sh），请优先使用该脚本——它会自动串行化已提交流程，并传入选定的模拟器 UDID。

启动第二个本地流程前，请确认此前的 maestro 或 verify-flow 进程未仍在占用同一模拟器。

已提交流程示例：

FLOW_FILE=.harness/flows/.yaml scripts/verify-flow.sh

临时 hold 流程示例：

appId: 
---
- launchApp:
    permissions:
      photos: allow
      usertracking: allow
- tapOn:
    text: "Allow"
    optional: true
- tapOn:
    id: ""
- assertVisible:
    id: ""
- extendedWaitUntil:
    visible:
      id: "__hold_for_lookin__"
    timeout: 120000

hold 流程的最终超时属预期行为。应将成功导航/断言（sentinel 前）视为有效结果，而非最终进程退出码。请勿提交 hold 流程，亦不得将其超时作为验证结果上报。

比对检查清单

在宣告审查完成前，请核查以下各项：

• 屏幕尺寸、模拟器型号、缩放比例及安全区域（safe-area）差异。
• 导航栏高度、标题位置、按钮帧（button frame）、图标尺寸、色调（tint）及方向。
• 内容起始 Y 坐标、水平边距、行/卡片高度、行间距、滚动内边距（scroll insets）及底部安全区域。
• 字体大小、字重、行高、颜色、对齐方式、截断（truncation）及动态文字压力（dynamic text pressure）。
• 背景色/背景图、卡片填充色、圆角半径、阴影、色调（tint）及不透明度。
• 图片占位槽（image slots）、占位符、内容模式（content mode）、裁剪（clipping）及资源名。
• 因 Figma 使用示例内容而可接受的运行时数据差异。

质量门槛与失败处理

仅当满足以下全部条件时，方可认定视觉审查完成：

• 在“从 Figma 构建”模式下，目标界面已被实现、可通过任一认可的导航方式访问，且已连接至真实运行时状态，或已文档化其模拟/固件验证状态。
• Figma 源与实时原生界面均已检查。
• 实时页面已通过任一认可的导航方式抵达：启动可见状态、真实应用导航、已提交 Maestro 流程、本地 hold 流程或 Local Direct Harness。
• 至少完成一次使用 Lookin MCP 的实时层级检查。
• 已通过 Lookin 或模拟器截图回退方案完成实时截图检查。
• 所有视觉差异均已修复，或明确记录为可接受的原生/运行时数据差异。
• 仓库相关启动门禁与流程门禁均已通过；若存在阻塞项，则需准确记录对应命令及产物路径。

常见失败情形的处理方式如下：

• 若 Figma MCP 无法读取节点，请索取截图或具备访问权限的节点，而非凭猜测推断设计尺寸。
• 若无已提交 Maestro 流程可抵达该页面，则可在 .harness/tmp/ 下创建本地 hold 流程，或使用 Local Direct Harness 进行检查；仅当该交互应成为持久化门禁时，才建议提交正式流程。
• 若 Lookin 层级检查失败，请重启 Debug 应用，确认应用处于前台，并在 Lookin 仍无法连接时记录阻塞项。
• 若 Lookin 仅返回浅层层级或不可操作的图层数据，请保留任何有用证据，并改用模拟器截图回退方案进行视觉比对。
• 若 Lookin 截图失败但层级检查正常，请使用模拟器截图回退方案，并记录该回退行为。
• 若页面仅在特定真实运行时配置下可达，请记录生成该审查状态的路由及配置条件。
• 若运行时数据与 Figma 示例内容不同，请保留真实应用数据，并比对布局韧性（layout resilience），而非硬编码 Figma 内容。
• 若验证无法执行，请勿宣称审查完成；须报告被跳过的命令、原因及残余风险。

硬性规则

• 禁止为匹配 Figma 而添加虚假的生产环境路由、服务或数据存储（stores）。
• Local Direct Harness 代码必须限定于 Debug、harness 或 test 构建目标，并在审查后清理临时入口。
• 当真实应用的数据存储（app stores）自主管理数据时，禁止硬编码 Figma 示例行（sample rows）。
• 当需要稳定视觉数据时，应使用固件数据（fixture data）或来自应用外部的现有 harness 设置。
• 仅对 Maestro 流程中需点击或断言的控件，添加稳定的 accessibilityIdentifier 值。
• 禁止提交 DerivedData、构建输出、模拟器录制、harness 运行产物、本地 hold 流程、截图或 Lookin dump。
• 当 Figma 与 iOS 原生安全区域或平台行为冲突时，优先采用原生行为，并记录该决策。

验证与交付

运行相关本地门禁，常见命令如下：

git diff --check
scripts/verify-docs.sh
scripts/verify.sh
scripts/verify-flow.sh

请串行运行流程门禁。若需执行多个特定流程，请依次调用，或使用仓库提供的封装脚本（该脚本会自动串行化流程列表）；并行 Maestro 运行会争夺唯一可用模拟器，导致误报失败。

在最终总结或执行计划中，需记录以下内容：

• Figma 节点/源及所作假设。
• 模拟器型号及实时屏幕尺寸。
• 所用导航方式或 harness，包括 Local Direct Harness 的模拟依赖项、根视图控制器及清理状态（如适用）。
• 用于抵达页面的运行时路由/配置条件（如适用）。
• 在任意本地 hold sentinel 前断言的根视图/关键控件 accessibility ID。
• Lookin 结果及是否启用截图回退方案。
• 所做 UI 更改及有意保留的运行时数据差异。
• 验证命令及其通过/失败状态。