figma-pixel-verify

Figma 像素验收

对照 Figma 持续更新的产物（Inventory + Spec）测量正在运行的 UI，并将通过／失败证据写入其 Verify 部分（或 Spec 源文件的同级文件）。对于未通过的行，在本次运行中修复并重新测量。实际值来自已完成布局的读取。不要覆盖 Figma expected。不要编辑 figma-pixel-implement 技能说明。

使用时机

• 在 figma-pixel-implement 之后（或任何留下持久化 Inventory + Spec 路径的 Figma 实现之后）
• 用户要求检查像素对齐／设计保真度／对照稿面验收
• 独立使用：用户提供 Figma URL + 正在运行的预览 URL／路由；测量前，按照相同的路径约定持久化一份最简 Inventory + Spec

输入

1. 持续更新的产物 — 来自实现阶段的文件路径。列与实现参考一致（state、mode、basis）。本次会话执行实现后，不要悄悄重建缺失的表格并声称交接已完成——判定为失败并返回 figma-pixel-implement。
2. 可运行的 UI — 文档展示界面，优先顺序如下：持续更新产物 Stories 子节中的组件工作台故事（或检测到的 Storybook 风格工作台）→ 轻量级隔离测试环境（替代主机／引擎依赖）→ 产品内预览路由 → 启动完整应用／浏览器（最繁重，最后选择）。没有计算样式 API 的界面使用 layout-probe：一条在产品实际使用的父容器中（即屏幕使用的容器）挂载控件、运行布局并打印框架信息的命令。在没有父容器的情况下对控件进行布局的命令不属于测量。
3. 正在运行的 UI 截图，适用于可打开 UI 的渠道（storybook、isolated-harness、preview、full-app）：本次运行中保存该 UI 的 png、jpg、jpeg 或 webp 文件，并注明其路径。无法打开 UI 的 layout-probe 记录 Screenshot: not-openable，不得虚构图片。图片仅作为辅助证据，不能替代数值检查。

工作流（按顺序）

1. 预检 — 按照 reference.md 中的阶梯确定测量渠道。文档 UI：Stories 子章节故事 → 检测到的组件工作台 → 产品内预览 → 完整应用启动（最后手段）。对于没有计算样式 API 的界面，或所有文档阶梯都不可用的情况：使用 layout-probe——本次运行执行的一条命令，将控件挂载到实际发布时使用的父容器中（即屏幕使用的同一容器），运行一次布局，然后输出控件的宽度、高度和子项框架。没有父容器、仅对控件进行布局的命令不算测量。如果不存在此类探针，就使用项目工具链能运行的最小探针，并运行它。如果不存在工作台，提出一条建议采用工作台的建议；如果工作台损坏，则沿阶梯转到下一个渠道并记录；在报告中声明渠道（storybook | isolated-harness | preview | full-app | layout-probe）。确认所选渠道可用。确定 Spec source（living-artifact 路径）。Inventory 与 Spec 共同构成要测量的行列表。如果本次运行已基于 Figma 实现，而文件缺失或缺少关键行：总体结果为 FAIL，返回 figma-pixel-implement 补全表格——不要臆造行并声称交接完成。如果这是独立运行（本次未执行实现）：按 implement 的路径约定持久化最小 inventory 和 spec，然后进行测量。注明主题范围（mode）和视觉 state。如果涉及多个主题，测量前先确定运行中的 UI 如何切换主题（data-theme、切换控件、系统偏好）。**浏览器渠道（质量门槛）：**在 macOS 上，如果 ego-browser skill（或其安装脚本）可用且 CLI 已可用，或者安装可在本轮完成且无需等待人员操作，则应在其他文档渠道之前使用它。如果安装仍需 GUI 引导，记录这一情况，并在本轮继续使用下一个可用的 JS-eval 或 layout-probe 渠道。不要将该产品的 TaskSpace/CLI API 复制到此 skill 中。如果操作系统不是 macOS、skill/安装路径不存在或安装受阻，则继续使用其他渠道，并记录所用渠道。缺少 ego-browser 不应中止 verify。
2. 源文件核对（门槛） — 测量前，根据 Figma 源文件以机械方式推导预期项列表（使用获取的节点树数据和/或参考导出）：每个范围内节点的位置、尺寸、字体排版集、容器属性和同级间距都应成为预期项。将其与 Spec 表核对——每个预期项都必须由某个 spec 行覆盖，或列为 out-of-scope 并说明原因；缺项必须新增为 spec 行（成为本次运行要测量的行），或明确标记为 out-of-scope。将核对表（预期项 / 已覆盖 / 新增行 / 范围外）写入 Verify 报告。核对完成前不得开始测量。如果范围内的框架缺少参考导出，总体结果为 FAIL，并退回 figma-pixel-implement。
3. 视觉检查 — 如果模型能够检查图像，则截取 UI 与 Figma 的截图并进行对比；记录明显不匹配（错误组件、缺少区块、主题偏差、图形被截断 / 叠放效果）。视觉检查属于辅助证据。如果可以运行 JS-eval 或 layout probe，仅凭视觉对比不能得出总体 PASS。在可打开的渠道中，保留运行中 UI 的文件并注明其路径。对于无法打开 UI 的 layout probe，记录 not-openable。
4. 像素差异扫描 — 将每张参考导出与本次实现的截图按相同尺寸并排比较（如果工具链允许，也生成逐像素差异图）；逐区域检查。每个发现的差异都必须成为新增测量行或记录为残差——在 spec 表之外发现差异，是此扫描应覆盖的合理结果。保存扫描产物（并排图和/或差异图），并在报告中注明其路径；对于没有扫描产物的可打开渠道，总体结果不能为 PASS。
5. 数值测量 — 对每个关键视觉行，将运行中的 UI 切换到该行的 state 和 mode（优先通过浏览器渠道使用真实指针悬停/点击/主题控件——声明式故事条目（测试 id、旋钮、自动操作）也算到达该状态——然后读取计算样式和/或边界框）。对于 layout-probe，实际值是该命令打印的框架。仅为了匹配 expected 而写入源代码字面值，不算完成测量。谨慎映射选择器；存在稳定测试 id 时优先使用。默认状态的读数不能满足悬停（或其他状态）行的要求。已发布参考交互：当任务文本包含 figma.com 或 node-id=，且同时包含 参考、match the existing 或 same as 时，读取所指现有控件为悬停、焦点、焦点内和打开或展开状态编写的规则。凡是与静止状态规则不同的属性，都应以相应 state 成为 spec 行。静止框架读数不能通过这些行。仅检查文本、可见性或项目数的探针不算测量。不同主题下按模式区分的行应分别判定。对于 out-of-scope: behavior 行，不要声称数值 PASS——将它们列为行为项，而非像素 PASS。对于范围内的每个多行文本节点，测量内容不能仅限于边界框：行数、每行墨迹起始位置（首个可见字符的渲染左边缘）、换行内容，以及任何悬挂缩进或行内偏移都要记录为行；仅读取边界框不算覆盖多行节点的对齐情况。
6. 比较 — 应用 reference.md 中的容差。为每行分配一个判定结果。未测量的关键视觉行（JS-eval 可用但跳过了该行）属于阻塞项，不能通过残差绕过并获得总体 PASS。
7. 修复循环 — 对于未通过的行，修复运行中的 UI，并在本次运行中重新测量，然后更新实际值/判定结果列。持续迭代，直至总体 PASS 或无法执行测量命令。安全上限：约 8 次迭代；达到上限则总体结果为 FAIL，并列出残差。当测得的框尺寸符合平台控件的固有尺寸而非 spec 时，下一次迭代将该控件切换为 custom-layout，并在布局过程中指定 spec 框架。不要更改 Spec 中的 expected。不要修改 figma-pixel-implement skill 文件。不要暂停并等待人员判断像素。
8. 独立复核 — 写入总体 PASS 前，必须进行独立复核：由使用全新上下文的 Agent 运行、使用不同模型，或盲目重新核对源文件（不参考作者的 Spec 表，而是从 Figma 源文件重新推导预期项列表）。在报告中以 Independent check: 行记录复核方法、复核者身份及其产物路径。如果没有可用的独立渠道，则记录尝试过的方法和不可用原因——绝不声称进行了实际未执行的复核。
9. 报告 — 将 Verify 部分写入 living artifact（或 Spec source 中指定的同级报告）。模板：reference.md。包含覆盖情况（已测量与 inventory 的对比）、渠道声明（Channel: storybook | isolated-harness | preview | full-app | layout-probe），以及在项目声明的宿主引擎版本低于工作台浏览器时，可选地注明这一差异。此说明不会影响几何 PASS，也不会增加人工步骤。依赖该引擎语法的行应在该版本下限对应的运行时或解析器中测量，否则这些行仍视为未测量，总体结果不能为 PASS。可将组件测试结果列为辅助证据。对于多主题范围，按主题分别报告。该 Verify 部分就是宿主环境要求的测量报告。只有当范围内每个关键视觉行都为 PASS 或 accepted-residual，且每个实际值都引用了本轮运行中经过布局的读数，并且存在完整的源文件核对表，并且注明了像素差异扫描产物，并且存在 Independent check: 行（或记录了尝试的方法和不可用原因）时，总体结果才为 PASS。如果有任何关键行未测量、存在 MISSING-style、未接受的 DRIFT、spec 要求 token 却出现 HARDCODED、spec 本身不完整、实际值复制自源代码字面值，或者运行中的 UI 出现以下情况，总体结果都不能为 PASS：Spec 为透明/none 时使用了臆造的纯色填充；对应单张 Assets 导出的图形被截断；使用了与实例几何不匹配的通用包装器；Spec 记录了 Figma 变量，却使用了自行臆造的文本颜色别名；可见图形仍来自远程设计 URL。如果无法运行探针命令，总体结果为 FAIL，且报告必须注明该命令。报告中的 Verify 部分必须包含 Mounted in、Measurement command、Screenshot，以及一个 ### Measurement excerpt 代码块，其中的文本包含每个通过行的实际数值和颜色。对于 storybook、isolated-harness、preview 和 full-app，Screenshot 必须是本轮保存的非空 png、jpg、jpeg 或 webp 文件路径。对于无法打开 UI 的 layout-probe，Screenshot 应为 not-openable。检查器会从报告文件所在目录解析相对路径，并拒绝缺失或为空的文件。截图文件不能替代数值通过结果。在报告 PASS 前，在此 skill 目录中运行 scripts/check-figma-verify-report.mjs 检查 living artifact。必须返回 0。

判定分类

判定	含义
PASS	在预期容差范围内，并且在正确的 state / mode 下测量
DRIFT	可测量，但超出容差范围
HARDCODED	值碰巧匹配或使用了字面值，而不是通过项目令牌/变量实现；当规范要求使用令牌时标记——前提是令牌映射属于约定内容
VARIANT	匹配的是与请求不同的已记录变体（例如悬停/深色）
MISSING-style	无法测量属性（没有节点、没有样式或通道不可用）
accepted-residual	明确冻结的偏差（负责人 + 原因）。不算相对于 Figma 预期的 PASS

工具用途（与平台无关）

用途	Agent 可使用
打开/预览 UI	通过 macOS 安装门槛后使用 Quality 通道；否则使用 Agent 已具备的其他 JS 求值/预览通道
切换视觉状态	使用真实指针悬停/点击/主题控件，然后读取样式
读取布局后的框架	在页面中执行 JS、使用类似 DevTools 的 API，或使用可打印框架的布局探测命令
截图	使用浏览器或 Figma 截图工具（当模型能查看图像时，由视觉能力检查截图）
应用修复	使用原生编辑工具，然后重新测量

Quality 通道安装成功后，请使用该通道进行测量。无法安装时，可使用其他 JS 求值路径。不要将第三方浏览器 API 复制到此技能中。

如果没有文档通道，请运行布局探测并读取其打印出的框架。如果无法执行该命令，请将数值行标记为 MISSING-style，注明缺失的命令，不要声称达到像素级 PASS。

关系

技能	边界
figma-pixel-implement	产出代码 + 持久化的 Inventory/Spec；不负责最终判定
Agent 原生的 Figma→代码指南 / MCP fetch	不能替代测量
Host PDCA 工作流	安装时强依赖；Figma UI 属于范围时调用；缺少 Verify 部分（或 Spec source sibling）会导致该验证阶段失败；spec-gap FAIL 时返回 implement 阶段
ego-browser（外部，macOS）	Quality 测量通道：技能/安装路径存在时安装；不是 frontmatter 依赖；无法安装时降级处理

注意事项

• 在可以进行测量时，仅凭截图就判定为 PASS。
• 不重新测量，陷入无限微调循环。
• 在高 DPR 下，将 ±1 CSS px 的几何误差视为失败，却不注明 DPR。
• 对蒙版 / currentColor 问题默默略过——如果实现违反了资源规则，应指出这是颜色 DRIFT 的根本原因。
• 仅测量默认主题，就将各模式行标记为 PASS——范围内的每个主题都必须在自身主题下测量。
• 根据默认状态样式将悬停行标记为 PASS。
• 关键行仅以“尚未测量”留在残差项中，却判定整体为 PASS。
• 将冻结的 18px 与 16px 差异判为 PASS，而不是 accepted-residual。
• 明明存在持续更新的产物路径，却只把报告留在聊天记录中。
• 用测量得到的实际值覆盖 Spec 中的 expected。
• 本轮实现后，Spec 丢失却默默重建，并声称交接已完成。
• 对臆造的纯色填充、堆叠叶片路径图标、通用 16/24 外壳、臆造的文本颜色别名或远程设计 URL 判定为 PASS。
• 在 macOS 上跳过可用的高质量通道 CLI，只通过较弱的文档通道进行测量。
• 在等待 GUI 引导的同时，未能在本轮使用其他通道或布局探针。
• 将与 expected 匹配的源代码字面值视为测量所得的实际值。
• 将第三方浏览器 TaskSpace / CLI API 复制到此技能中。
• 在无法安装 ego-browser 的主机上，仅因其不可用就中止验证。
• 在 JS-eval 可用时，仅凭视觉效果 / 截图就判定整体为 PASS。
• 报告判定结果时，未说明使用的测量通道。
• 将工作台 / 引擎底层说明视为拒绝判定几何项 PASS 或要求人员完成这些项的理由。
• 将未挂载正式版父级的布局命令视为测量。
• 对可打开的通道，在没有保存非空截图文件的情况下报告 PASS。
• 为无法打开 UI 的布局探针臆造图像。
• 跳过源代码对照——测量集最终只包含作者记得写下的内容。
• 在可打开的通道上，没有差异扫描产物却报告 PASS。
• 将同一上下文中的自我审查视为独立复核。
• 只测量多行文本节点的框，就声称已覆盖其对齐情况。