pixel-perfect

pixel-perfect

一项用于根据截图、图片、Figma 预览/导出内容、可交互演示或实时网站，尽可能精确地复现 UI 的技能。

最终成果不只是代码，还包括：

• 基于测量结果制定的实现计划
• 详细的视觉规范
• 实现该规范的代码
• 持续迭代验证，直到渲染结果与参考内容高度一致

此技能用于精确复刻，而非获取灵感、重新设计、清理、规范化或风格化诠释。

何时使用此技能

当用户希望执行以下操作时，请使用此技能：

• 精确复制设计
• 根据截图复现界面
• 准确克隆 Figma 网站或演示
• 详细匹配间距、内边距、颜色、排版和布局
• 将设计移植到其他框架，同时保持外观不变

当用户希望执行以下操作时，请勿使用此技能：

• 重新设计
• 评审设计
• 实现一个大致类似的版本
• 改善 UX，而非复刻设计

前提条件

• MCP 服务：
  • Chrome DevTools MCP（首选）或 Playwright MCP（备用）
• 命令行工具：
  • jq
  • awk
  • ImageMagick：magick（v7）或 convert + compare + identify（v6）

如何使用此技能

请严格按照以下循环执行：

1. 测量一次参考内容，并制定具体规范
2. 根据该规范进行实现
3. 对照参考素材进行验证
4. 仅修改不匹配的部分
5. 再次验证

重复步骤 3 至 5，直到所有必需的问题都已解决（fixed、accepted_by_user 或 renderer_only_drift），并且通过验证关卡。

核心规则

1. 以参考内容为准。
2. 不要重新设计。
3. 不要简化。
4. 不要“改进”设计。
5. 除非用户明确要求，否则不要用取整后的值或更美观的值替代测量值。
6. 不要用主题默认值替代测得的颜色、字号、间距、圆角或阴影。
7. 如果可以检查源内容，就对其进行测量。
8. 最后务必进行基于截图的视觉验证。
9. 如果仍有明显差异，不要以“足够接近”为由停止。
10. 保真度优先于框架惯例。

规范术语

• MUST 和 MUST NOT 表示硬性要求。
• SHOULD 表示强烈建议的默认做法，仅可在报告中给出明确理由后覆盖。

优先级顺序

需要权衡时，请按以下顺序优先处理：

1. 整体布局结构
2. 外边距和区块间距
3. 内边距和间隔
4. 排版、字号、字重、行高
5. 颜色、边框、圆角、阴影
6. 字体和图标的素材一致性
7. 图标尺寸和位置
8. 交互状态和细节

输入优先顺序

接受的输入类型按优先级排序如下：

1. 可检查的 Figma 源文件
2. 实时网站
3. 可交互演示
4. 图片导出文件
5. 截图

规则：

• 使用优先级最高的可用来源作为主要测量来源
• 仅在需要时使用较低优先级的来源辅助视觉确认
• 如果 Figma 未体现行为和状态的细节，则使用运行时来源进行确认
• 如果只提供一个来源，则使用该来源

必需输出

执行期间，此技能必须产出以下四项：

1. 简短的执行计划
2. 基于测量结果的详细 UI 规范
3. 代码实现
4. 验证结果，以及尚未解决的差异（如有）

Agent 必须先编写规范，不得直接开始编码。

使用 references/report-template.md 中的报告标题结构。

使用两种报告模式：

• iteration 模式：用于迭代优化循环（简要摘要投影，仅包含有变更或失败的项目）
• final 模式：用于完成交接时（完整报告）

不要强制限制 token 数量。通过投影产物，而不是重复完整报告内容，来保持中间输出简洁。

当 Agent 认为任务已完成时，必须向用户提供最终验证交接，其中包括以下所有内容：

1. 明确说明其认为实现已完成
2. 并排显示视觉对比，其中包括：
   • 一张参考图／设计图
   • 一张实际渲染的应用截图
3. 直接请求用户验证，并询问是否还有任何遗漏
4. 明确提示用户：如果不批准，请列出遗漏的细节

参考资料

详细执行指南请参阅以下资料：

• references/report-template.md
• references/responsive-scope-playbook.md
• references/measurement-playbook.md（索引）
• references/measurement-chrome-devtools.md
• references/measurement-image.md
• references/measurement-figma.md
• references/specification-playbook.md
• references/validation-playbook.md

工作流

阶段 1：识别来源类型

确定以下哪一种情况适用：

• 可通过实时方式检查的来源
• 可通过 Figma 检查的来源
• 仅有静态视觉来源

如果存在可通过实时方式检查的来源，请将其用作主要测量来源。 如果存在可通过 Figma 检查的来源，请将 Figma 检查数据用作主要测量来源。 如果只有图像，请使用基于截图的测量方式。

来源选择必须遵循输入优先级顺序。 只有在没有更高优先级来源可用时，才应将较低优先级来源用作辅助确认。

阶段 2：选择响应式验证范围

必须在开始实现前选择所需视口。 请遵循 references/responsive-scope-playbook.md 中的确定性范围与分类规则。

最低要求：

• 如果用户指定了视口或设备，必须严格使用这些视口或设备
• 否则，对来源进行分类，并根据指南手册选择默认视口集合
• 必须在计划中记录来源分类、选定的视口集合及选择理由
• 在选定集合中的每个必需视口上，验证都必须通过
• 如果偏离默认设置，必须在报告中明确说明理由

阶段 3：检查与测量

模式 A：可通过实时方式检查的来源

使用 Chrome DevTools MCP 等浏览器工具直接检查渲染后的 UI。 严格遵循 references/measurement-chrome-devtools.md 中的测量顺序。

测量并记录：

• 视口尺寸
• 页面宽度和可见内容宽度
• 安全区域或浏览器内边距（如相关）
• 关键元素的边界框
• 相对于父级和视口的 x、y 位置
• 区块和控件的宽度与高度
• 四侧内边距
• 四侧外边距
• 同级元素之间的布局间距
• 计算后的字体系列
• 计算后的字体大小
• 计算后的字体粗细
• 计算后的行高
• 字间距（如相关）
• 文本颜色
• 背景颜色
• 渐变
• 边框宽度
• 边框颜色
• 边框圆角
• 盒阴影
• 不透明度（如使用）
• 图标尺寸
• 对齐规则
• 滚动行为
• 粘性或固定定位（如有）

还需截取以下内容：

• 完整视口
• 每个主要区块
• 每个视觉细节密集的区域

如果可以检查 DOM，请勿先凭截图估算数值。 先进行测量。

模式 B，仅有截图或图像

如果设计仅以图像形式提供，请推断其结构并进行视觉测量。 使用 references/measurement-image.md 中的纯截图流程。

确定：

• 目标视口尺寸，或估算其尺寸
• 主要布局容器
• 各区块之间的相对间距
• 卡片和容器内部的内边距
• 文本层级
• 可能的字号比例
• 大致的圆角半径
• 大致的图标尺寸
• 从像素中采样颜色
• 可见时的渐变色标
• 对齐模式和网格节奏

实施过程中反复对比截图，以微调不确定的数值。

模式 C，Figma 源文件

如果源文件是 Figma 预览或可访问检查数据的文件，请根据 Figma 检查数据进行测量。 使用 references/measurement-figma.md 中的 Figma 流程。

首先根据检查数值进行测量，然后使用导出或捕获的画面图像进行视觉确认。

第四阶段，编写执行计划

编写详细规格之前，先写一份简洁的执行计划。

计划 MUST 包含：

• 源类型
• 测量方法
• 实施目标
• 验证方法
• 已知风险或不确定因素

示例：

Source: clickable demo
Measurement: Chrome DevTools MCP DOM inspection plus screenshots
Target: React Native screen on iPhone-sized viewport
Validation: simulator screenshots matched against reference
Risk: native font rendering may differ slightly from browser rendering

计划应简短。这是执行计划，不是完整规格。

第五阶段，编写详细实施规格

开始编码前，先制定一份基于测量数据的 UI 规格。

规格必须具体到足以让其他工程师无需查看原始参考即可实现该屏幕。 使用 references/specification-playbook.md 中的字段级架构和质量检查项。

第五阶段的目标：

• 在开始编码之前，制定完整、以测量数据为依据的实施约定

必需章节：

1. 屏幕元数据：定义目标环境和全局布局行为。
2. 组件层级：定义结构树，以及实施和验证中使用的命名。
3. 分区测量：定义各主要区块的几何尺寸、间距、对齐方式和表面样式。
4. 字体排版规格：定义关键文本元素的精确文本渲染规则。
5. 调色板：定义屏幕使用的具体颜色值和渐变。
6. 边框和圆角规格：定义边框、圆角和分隔线样式。
7. 图标规格：定义图标资源、尺寸、位置和样式细节。
8. 资源一致性与用户决策：记录字体和图标的可用情况，以及用户批准的回退方案。
9. 交互和状态说明：定义依赖可见状态的样式和布局行为。
10. 平台转换说明：记录渲染器转换限制，不进行重新设计。

每个章节所需字段和示例输出，请参阅 references/specification-playbook.md。 实施开始前，所有 10 个必需的规格章节 MUST 全部齐备。

第六阶段，验收约定（实施前的强制要求）

实施开始前，报告 MUST 包含一份验收约定，其中包括：

• 必须匹配项列表：标注不可妥协的设计决策
• 忽略项列表：明确允许存在的差异
• 允许的平台适配偏差：仅允许渲染器导致的偏差

规则：

• 未记录此约定前，MUST NOT 开始实施
• 如果提供了用户标注的对比截图，这些标注 MUST 反映在 必须匹配项列表 中
• 如果屏幕由数据驱动，除非文案差异会影响布局、间距、溢出或换行，否则 SHOULD 排除文案/内容差异
• 所有排除项 MUST 在 忽略项列表 中明确列出

第 7 阶段：根据规范实现

以规范为唯一事实来源编写代码。

规则：

• 一次实现一个章节
• 使用明确的值
• 避免使用会改变外观的框架默认值
• 不要将任意测量值归一化到间距刻度
• 不要用相近的主题颜色替换实际颜色
• 不要将字体大小改成“更标准”的值
• 不要让按钮看起来更均衡或更现代
• 不要删除或增加细节
• 如果缺少精确资源，不要自动选择备用字体或图标包
• 只有在规范中记录了用户的明确批准后，才能实现备用资源
• 如果参考图使用了明显不同的图标系列，你必须采用该图标系列，或在大量实现之前获得用户的明确批准

如果源文件使用了 23px 或 18px 这类看似不寻常的值，请保留这些值。

第 8 阶段：运行并截图

在正确的目标环境中运行实现。

使用执行计划中定义的环境设置。验证期间不要切换目标环境。

运行检查清单：

• 确认计划中的目标类型（web、react-native 或其他已声明的目标）
• 以适合截图捕获的稳定运行模式启动目标
• 确保目标字体和图标资源符合已批准的资源一致性决策
• 在可能的情况下，于截图捕获前禁用动画和过渡效果，以减少帧间差异
• 按计划中的声明精确设置每个所需视口
• 为每个视口捕获所有所需截图

对于所选视口集中的每个所需视口，捕获以下截图：

• 全屏
• 每个主要章节
• 与参考图在视觉上存在差异的任何区域

每轮都使用计划中声明的精确视口尺寸。 视口尺寸必须与计划完全一致。 必须捕获每个视口所需的截图。

产物输出要求：

• 对于每个视口，将截图产物和验证输入文件保存到磁盘
• 对于每个视口，运行 ./scripts/validate-visual.sh 并保存 JSON 输出（例如 validation/<viewport>.json）
• 将验证器 JSON 产物视为数值的唯一事实来源

阶段 9：视觉验证

针对每个必需的视口，将实现截图与参考图进行比较。

请重点检查：

• 顶部间距
• 页面水平内边距
• 卡片宽度
• 区块间距
• 卡片内部内边距
• 字号差异
• 字重差异
• 行高差异
• 颜色不正确
• 圆角过大或不足
• 阴影不匹配
• 按钮高度不匹配
• 图标位置不匹配
• 行密度不匹配
• 对齐偏差

同时运行客观的差异检查，并记录数值结果。 使用 references/validation-playbook.md 中的验证流程和报告格式。 对于面向 LLM 的更新，先使用 ./scripts/summarize-validation.sh 将验证器产物整理为精简摘要。

验证配置：

• lenient（仅在明确说明理由时允许）
• portable（跨渲染器工作时的默认配置）
• strict（同一渲染器工作时的默认配置）
• ultra（仅选择启用，绝不作为默认配置）

配置选择规则：

• 当源和目标使用实际上相同的渲染器和字体栈时，默认使用 strict
• 当源和目标的渲染方式不同时（例如从浏览器到 React Native），默认使用 portable
• 仅当用户明确要求且条件受控时，才使用 ultra（相同的渲染器版本、操作系统、DPR、字体和截图流程）
• 仅当硬性约束阻碍更高保真度匹配时，才使用 lenient；记录具体阻碍，以及无法实现更高配置级别的原因

portable 的解释：

• portable 必须仅允许渲染器级别的偏差
• portable 不得放宽 Must-match list 中标注的设计决策

标注问题的处理：

• 每个标注问题必须且只能以以下一种状态结束：fixed、accepted_by_user 或 renderer_only_drift
• 验证报告必须为每个标注问题包含一项是／否检查
• 验证报告必须包含组件属性表，列包括：component、property、desired value、actual value、drift、result、reason
• 每行的结果必须为：good、bad 或 bad_with_reason
• renderer_only_drift 必须附带简要原因
• 除非所有标注问题都具有规定的状态，否则报告不得声称已验证
• 如果报告未在最近一次视觉修改后更新，则不得声称已验证

每次运行时，必须先报告所选配置及其选择原因，再报告指标。 每次运行时，必须报告每个必需视口的视口级指标。

LLM 输入投影规则：

• 在迭代循环中，仅向模型提供投影摘要（失败的检查、主要偏差、差异和后续操作）
• 不要重新输入完整的验证 JSON，除非需要特定切片来解决某个具体不匹配
• 需要更多详细信息时，仅加载针对性的切片（单个视口、单个问题 ID 或特定检查类型）

阶段 10：细化

调整代码，消除明显的差异。

如果差异表明规范不完整或有误，请更新规范。

重复以下步骤：

• 实现
• 运行
• 截图
• 比较
• 细化

直到明显差异消失，或遇到阻碍完美复现的平台限制。

最后一次实质性 UI 编辑后，必须至少完成一轮完整的 capture -> compare -> fix -> re-capture 循环。 细化循环必须至少运行一次，且不得超过 10 次。

如果运行 10 轮后仍有未解决的差异，报告必须包含详细的未解决问题部分，其中包括：

• 每个未解决的问题
• 当前期望状态与实际状态
• 已尝试的方法
• 问题难以修复的原因
• 问题可能仅由渲染器、资源、数据还是实现限制导致
• 针对每个未解决问题建议的下一步操作

如果遇到阻碍，请记录限制和剩余差异。

迭代报告规则：

• 每轮细化都必须根据投影输出生成一个 iteration 报告块
• iteration 报告应只包含状态有变化的项目和未通过的行
• 只有在交付时的 final 报告模式下，才需要完整报告章节和详尽表格

完成定义

仅当以下条件全部满足时，技能才算完成：

1. 已制定简洁的执行计划。
2. 已编写详细且基于测量的 UI 规范。
3. 已通过代码实现 UI。
4. 已将渲染结果与参考图进行视觉比较。
5. 已按照配置文件选择规则选定验证配置文件，并在报告中记录。
6. 已记录客观验证指标，且所选配置文件的所有必需阈值均已通过。
7. 如果使用 lenient，必须明确记录阻碍因素及原因。
8. 已记录字体和图标的资源一致性状态；任何回退方案的使用都必须有明确的用户批准记录。
9. 已制定验收约定，其中包含“必须匹配项列表”“忽略项列表”和“允许的跨平台差异”。
10. 如果用户提供了标记过的对比截图，则必须将其作为主要验证材料。
11. 每个标记的问题都必须标记为 fixed、accepted_by_user 或 renderer_only_drift，并附上原因。
12. 最新视觉改动后，已更新验证报告。
13. 最后一次实质性 UI 编辑后，至少运行过一轮完整的 capture -> compare -> fix -> re-capture 循环。
14. 验证报告包含组件属性表，列出每个已验证属性的期望值、实际值、差异和结果。
15. 所选视口集合中的所有必需视口均已通过验证。
16. 间距、字体排印、颜色、边框圆角、对齐方式或区块尺寸方面均无明显差异。
17. 最终回复明确包含“我认为这已经完成”的表述。
18. 最终回复包含参考图与实际应用截图的并排对比，供用户查看。
19. 最终回复请用户验证是否完成；如果尚未完成，请说明遗漏之处。

“差不多相似”不算完成。 “够好了”不算完成。 “符合框架惯例但略有不同”不算完成。

应避免的失败模式

请勿执行以下操作：

• 仅快速浏览设计，就凭记忆进行实现
• 跳过规范制定
• 因为觉得合适，就到处使用通用的 16 间距
• 使用看起来接近的默认字号
• 用主题色替换测量得出的颜色
• 未经用户批准就自动选择字体或图标回退方案
• 使用最新视觉改动之前的旧报告来声称验证已完成
• 忽略标记的对比截图问题，而不将其解决为 fixed、accepted_by_user 或 renderer_only_drift
• 擅自进行主观的 UX 改进
• 只完成第一轮
• 不进行截图比较就宣称成功
• 结束时未明确请求用户验证，也未询问是否遗漏了细节

调用示例

Use pixel-perfect to copy this screen exactly
Use pixel-perfect to recreate this Figma preview in React Native
Use pixel-perfect to clone this clickable demo without redesigning it
Use pixel-perfect to port this web design into native while preserving the look

预期行为摘要

此技能会将“照着这个设计做”之类的模糊提示转化为严格的流程：

• 检查源
• 测量源
• 编写计划
• 编写详细规范
• 根据规范实现
• 运行目标
• 截取屏幕截图
• 与参考进行比较
• 持续改进，直至匹配

此技能不要求 Agent 发挥创意，而是要求 Agent 做到精准。