pixel-audit

像素审查

将一个页面与其事实来源进行审查，修复不匹配项，并在声称“已验证”之前，证明每项修复都落实到具体元素。/design-system 会在项目启动时通过预览检查整个组件库一次；此技能则在功能开发期间检查一个产品页面——引用项目的组件库，切勿在此处重建组件。

输入

根据请求推断；仅针对缺失的信息进行询问：

• TARGET PROJECT-CODE — 完整的 Project Matrix 代码；用于确定技术栈惯例和 UI 库。
• SCOPE — 要审查的单个页面/路由及其状态（列表/详情、模态框、表单、空/错误/加载状态、响应式断点，以及来源中包含的浅色/深色等主题变体）。范围是严格边界——绝不编辑其他页面、路由或步骤。
• SOURCE OF TRUTH — 通过 Figma MCP companion 获取的 Figma 节点，或在没有 Figma 时使用参考屏幕/参考实现。在产物中注明使用的是哪种来源。如果两者都没有，请停止并询问——绝不可凭记忆进行审查。
• 登录/环境 — 仅在页面需要身份验证时提供本地凭据。

首先加载

• 目标项目的约束上下文：GLOSSARY.md（旧版 CONTEXT.md）以及按页面/主题定位或由决策链接的 ADR；只阅读相关 ADR。
• 在设计系统文档或 AGENTS.md 中指定的项目 UI 技能；如果未注册，则查找 *-ui-coding 技能。**复用其组件；绝不可内联实现。**如果没有此类技能，则从设计系统文档或项目代码中查找设计令牌、组件库和预览。

流程

1. 梳理页面

查找路由、视图/模板/组件文件、局部模板、范围内状态、数据，以及页面应使用的设计系统组件。如果有组件预览（例如 /ui/preview/all），请打开。

2. 追踪资源管线

确定构建/资源管线、缓存和容器/服务，弄清类名/样式/组件变更如何实际应用到页面。

3. 记录像素清单

编辑前记录事实来源。对每个节点/区域（框架、面板、卡片、行、筛选器、标签页、模态框、字段、按钮，以及每种空/错误/加载/响应式变体），都要以完整尺寸捕获，包括首屏以下内容——绝不可只依赖一张完整页面截图。记录精确的 x/y、尺寸、间距、内边距、间隔、字体、颜色、边框、圆角、填充、图标尺寸、对齐方式、不透明度、阴影和变体。预期值：Figma MCP 节点元数据/变量（精确值），或从参考屏幕测量并标记为近似值——此时检查关卡验证的是相对对齐和一致性，而非绝对像素值。按来源划分的捕获调用见：references/evidence-capture.md。

4. 审查预期与实际结果

对每个节点/状态，按以下类别标记每项不匹配：

• MISSING — 应有的来源项/状态在应用中缺失或有误。
• EXTRA — 应用中存在来源未包含的项/状态。额外 UI 属于缺陷——报告并等待决策（规则见“修复”部分）。

缺陷列表产物

解析 <artifacts-root>：如果存在 *.code-workspace 目录，则使用该目录；否则使用各上下文的根目录（仓库根目录中的 GLOSSARY-MAP.md；旧版为 CONTEXT-MAP.md）；否则使用仓库根目录。文件名按 PROJECT-CODE 命名，避免两个项目中同名页面发生冲突：

<artifacts-root>/specs/pixel-audit/<TARGET-PROJECT-CODE>-<page-slug>-defects.md

清单和截图放在其旁边：<TARGET-PROJECT-CODE>-<page-slug>-inventory.md 和 shots/<TARGET-PROJECT-CODE>-<page-slug>/。在两个 Markdown 产物中都包含零归因规则。

每个缺陷占一行：

# Pixel Audit — <page-slug> (<TARGET-PROJECT-CODE>)

Zero attribution: never add or leave co-author, AI, or tool attribution in any output.

Source of truth: <Figma node(s) URL | reference screens/impl — name it>
Scope: <route + states audited>

| # | Node | URL / State | File / Component | Mismatch | Expected | Actual | Kind | Evidence | Status |
| - | ---- | ----------- | ---------------- | -------- | -------- | ------ | ---- | -------- | ------ |
| 1 | Filter bar, Search field | /assets · list | components/search-field | height off | 34px | 40px | MISSING | rect=…, computed=… | open |
| 2 | Row actions, extra "Delete" | /assets · list | pages/assets/index | not in source | — | delete icon present | EXTRA | ref=…, screenshot | open |

Evidence 必须按照验证关卡的要求落实到具体元素。Status 按 open → awaiting verification → verified 流转；如果验证关卡未通过，则为 reopened。重新运行时，将旧的 fixed 行视为待验证；这些行必须通过完整的验证关卡。

修复

• 每次只处理一个节点／页面／状态。 不要批量处理无关的修复。
• 需要调整行为、数据或界面的 MISSING 缺陷属于一个切片，而非样式修复。 记录该行，将其转交给 /to-tickets，不要在此处实现（这就是 /polish-batch 设定的边界）。
• 复用项目 UI 库的组件。 除非有充分理由并记录在案，否则不要创建一次性 UI（遵循已注册项目 UI 技能中的复用与新增规则）。
• 如果必须修改共享组件，建议通过 /design-system 扩展该库、预览和已注册的项目 UI 技能；绝不要按页面局部修改，也不要自动串联操作。 先征求用户确认。其他页面也会使用该组件，而此页面的框架可能是个例。在获得单独授权之前，将该行留在 Needs user 下并标记为 open，然后继续；绝不要擅自改写共享组件。
• 严格限定在 SCOPE 范围内。 其他页面或流程的外观细节应通过 /polish-batch 记录，绝不要在此处修复。
• 对 EXTRA 只报告，不做决定： 对于应用中存在、但来源中没有的任何图标／按钮／字段／操作，应提交给用户决定，不要默默保留、移除或重新设置样式。

验证门槛

“已验证／已完成／已修复”是需要针对每项修复举证的结论。

• 说明环境： 主机／URL 和浏览器／会话，或本地应用构建及模拟器／设备。
• 通过构建流水线： 每次更改后都要重新构建／刷新，并确认页面或应用实际加载的资源中包含已更改的类／样式／组件，而不只是源文件中存在。
• 为每项修复提供元素级证据： 选择器／引用、getBoundingClientRect()、相关的计算样式、DOM，以及在对齐至关重要时提供裁剪后的截图。原生应用需要提供本地模拟器中等效的检查器几何信息、解析后的样式、渲染树和截图。整页截图只能用于概览。如果无法使用所需的自动化工具，列出待进行的手动检查，不要凭假设将任何一行标记为 verified。
• 以下情况均视为失败： 元素隐藏、尺寸为零、折叠、被裁切、未对齐、尺寸错误、类未生效，或相较于第 3 步的采集结果出现新的控制台错误。
• 声明已验证前先尝试证伪： 主动排查修复可能出错的情况（错误的断点、过期资源、类未应用、元素位于屏幕外），并排除这些可能性。
• 只有满足以下所有条件，才能说“已验证／已完成／已修复”： 已说明环境 · 已通过构建流水线 · 已加载的资源包含更改 · 已采集元素证据 · 已采集完整尺寸的来源 · 已比较预期与实际结果 · 已检查所有范围内的状态。未尝试的行保持 open；未通过门槛的已更改行标记为 reopened。
• 最终检查： 提交最终报告前，在最终构建上为每一行 verified 重新采集一次元素证据。发生偏差的行标记为 reopened。

规则

• 禁止归属声明：绝不要在提交、PR、问题评论、发行说明、生成的文档、设置或代码注释中添加或保留共同作者、AI 或工具归属声明。
• 只建议，绝不自动串联操作。 审计结束后，建议执行 /code-review；只有在交付内容中的每一行已更改项都通过验证时，才建议执行 /commit-push-close／/commit-push-pr；如果有已重新打开的更改项，建议先解决该项。然后停止。
• 决策是产物——清单和缺陷列表应保存在磁盘上，而非聊天中。
• 始终在所有地方使用 Project Matrix 中完整的 PROJECT-CODE；绝不要将某个项目的约定、令牌或组件混入另一个项目。
• 仅限本地。 使用本地凭据、本地浏览器，不使用云端 Agent。
• 子 Agent：对于相互独立的工作，自动分派本地工作通道——绝不使用云端 Agent；分派时宣布通道数量，并在每个通道完成时报告。工作通道仅执行第 1 步（映射页面）；修复、综合和验证门槛由主 Agent 负责。
• 每次阶段转换时输出 Stage / Found / Next / Needs user——每个字段占一行。阶段：mapped → inventory captured → audited → fixing → verified。

输出

完成范围内的修复后：

Stage: pixel-audit — audited <page-slug> (<TARGET-PROJECT-CODE>) vs <source of truth>; wrote specs/pixel-audit/<TARGET-PROJECT-CODE>-<page-slug>-defects.md.
Found: <N> defects (<M> MISSING, <E> EXTRA); <V> verified, <R> reopened; <U> EXTRA items awaiting your decision.
Next: <resolve reopened changed rows; otherwise /code-review, then /commit-push-* for verified changes>. Untouched open rows and EXTRA decisions stay for the next pass.
Needs user: <EXTRA items to decide (keep/remove/restyle), or blocked states, or "none">.

Suggested next skills (optional):
- /code-review: eyeball the in-scope diff before shipping.
- /commit-push-pr (or /commit-push-close): only when every changed row included in the shipment is verified.

不要继续执行建议之外的操作。

完成标准

• 缺陷列表已创建，路径为 <artifacts-root>/specs/pixel-audit/<TARGET-PROJECT-CODE>-<page-slug>-defects.md，并注明了其事实来源和范围，每个缺陷占一行
• <TARGET-PROJECT-CODE>-<page-slug>-inventory.md 和 shots/<TARGET-PROJECT-CODE>-<page-slug>/ 已在其旁边创建
• 每行的 Status 均为 verified、open 或 reopened，没有任何待验证项；每个 verified 行的 Evidence 单元格都包含元素级证据
• 回复以 Suggested next skills (optional) 页脚结尾，后面不得有任何内容