frontend-visual-qa

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Frontend Visual QA

前端视觉QA

Audit the interface the user can actually see. Treat build success, DOM presence, and uninspected screenshot files as supporting signals, never as visual proof.

Default to audit-only. Do not edit implementation, add tests, install dependencies, or update snapshots unless the user explicitly asks to fix or change the UI. Permission to fix source does not authorize rebuilding, restarting, or deploying any target.

对用户实际可见的界面进行审计。将构建成功、DOM存在性和未检查的截图文件视为辅助信号，而非视觉验证依据。

默认采用仅审计模式。除非用户明确要求修复或修改UI，否则不得编辑实现代码、添加测试、安装依赖或更新快照。修复源码的权限并不授权重建、重启或部署任何目标产物。

Scope And Routing

范围与路由

Use this skill only after a rendered artifact exists. Select the smallest audit profile that covers the request:

core visual — composition, typography, spacing, wrapping, clipping, images;
responsive — breakpoints, reflow, mobile alternatives, scroll ownership;
state and journey — conditional branches, transitions, recovery, routes;
browser output — download, share, clipboard, popup, file dialog, print, PDF;
native shell — Electron or hybrid chrome, permissions, drag regions, IPC UI;
page contract — dashboard/admin, landing/deck, design-system artifact, browser tool/game, map/GIS, or review tool;
reference parity — comparison with a named screenshot, product, or tier;
data visualization — chart hierarchy, tokens, semantics, and accessibility.

Combine profiles only when the changed surface or the user requests a broad release review. Do not force a local line-break review through unrelated auth, map, export, and native-shell checks.

Use adjacent skills by stage:

Use ui-designer, frontend-design, or another design skill to derive or create a visual direction.
Use this skill to test the already-rendered result.
Use qa-expert for a full test strategy, defect program, and release metrics.
Use both this skill and qa-expert only when rendered visual evidence is one part of a broader QA gate.
This skill audits whether an artifact renders correctly, not whether it communicates. A page can pass every check here while its labels are opaque internal abbreviations and its numbers contradict each other between sections. Route copy, terminology and audience fit to a content/writing-discipline skill, and never let a green visual pass be reported as "a first-time reader can follow this" — that is a different question, answered by a reader, not by a rendering.

仅在渲染产物已存在时使用本技能。选择能覆盖需求的最小审计配置文件：

核心视觉 — 布局、排版、间距、换行、裁剪、图片；
响应式 — 断点、回流、移动端替代方案、滚动控制权；
状态与流程 — 条件分支、过渡效果、恢复机制、路由；
浏览器输出 — 下载、分享、剪贴板、弹窗、文件对话框、打印、PDF；
原生外壳 — Electron或混合浏览器外壳、权限、拖拽区域、IPC UI；
页面约定 — 控制台/管理面板、落地页/演示文稿、设计系统产物、浏览器工具/游戏、地图/GIS或评审工具；
参考一致性 — 与指定截图、产品或层级进行对比；
数据可视化 — 图表层级、标记、语义化及可访问性。

仅当变更范围较大或用户要求进行全面发布评审时，才组合多个配置文件。不得通过无关的权限验证、地图、导出和原生外壳检查，强制进行局部换行评审。

按阶段使用相关技能：

使用ui-designer、frontend-design或其他设计技能来推导或创建视觉方向。
使用本技能测试已完成渲染的结果。
使用qa-expert技能制定完整的测试策略、缺陷管理方案和发布指标。
仅当渲染后的视觉证据是更广泛QA关卡的一部分时，才同时使用本技能和qa-expert技能。
本技能审计的是产物是否正确渲染，而非是否能有效传递信息。页面可能通过所有检查，但标签可能是晦涩的内部缩写，各部分数据也可能相互矛盾。文案、术语和受众适配相关问题应转交给内容/写作类技能，绝不能将视觉检查通过报告为“首次阅读者可理解内容”——这是另一个问题，需由读者判断，而非渲染结果。

Required Outcome

必备输出

Produce all of the following:

A scope contract naming the artifact, actor, job, target kind and canonical target identity, conditional state, viewports, affected journeys, reference/SSOT, and authorization.
A verification status: verified, partial, or blocked.
Findings tied to visible evidence, impact, state, viewport, and reproduction.
A list of what was actually exercised and what remains unverified.
When freshness or deployment is claimed, a separate delivery status and its identity evidence; when target mutation is explicitly authorized, identity before/after, a same-target/state/viewport re-run, and a regression guard.

Never downgrade the user's real objective to whatever evidence was easiest to collect.

需生成以下所有内容：

一份范围约定，明确产物、角色、任务、目标类型和标准目标标识、条件状态、视口、受影响的流程、参考/单一可信源（SSOT）及授权信息。
验证状态：已验证、部分验证或受阻。
与可见证据、影响、状态、视口和复现步骤绑定的问题发现。
实际执行的检查项及未验证项列表。
当涉及新鲜度或部署验证时，需单独提供交付状态及其标识证据；当明确授权修改目标时，需记录修改前后的标识、在相同目标/状态/视口下重新运行，并添加回归防护。

绝不能将用户的真实目标降级为最易收集的证据。

Workflow

工作流程

Track this checklist for nontrivial audits:

- [ ] 1. Establish the audit contract and authorization
- [ ] 2. Select the required evidence level and canonical harness
- [ ] 3. Prove the target, state, data, viewport, and claimed freshness
- [ ] 4. Capture and inspect macro, local, and responsive evidence
- [ ] 5. Exercise the affected journeys and recipient outputs
- [ ] 6. Report findings; fix and re-run only when authorized

针对非 trivial 审计，遵循以下检查清单：

- [ ] 1. 确立审计约定与授权
- [ ] 2. 选择所需的证据级别和标准测试环境
- [ ] 3. 验证目标、状态、数据、视口及声称的新鲜度
- [ ] 4. 捕获并检查全局、局部及响应式证据
- [ ] 5. 执行受影响的流程和接收端输出
- [ ] 6. 报告问题发现；仅在获得授权时进行修复并重新运行

1. Establish The Audit Contract

1. 确立审计约定

Read the project instructions, design-system SSOT, tokens, approved assets, launcher/test SOP, and the changed code. Then write a falsifiable contract:

Artifact/page type:
Actor and job:
Target kind + canonical identity:
  web = exact in-browser URL (query/fragment included) + named environment
  single file/image = canonical path + content hash + rendering scheme
  multi-resource artifact = canonical entry + dependency/manifest digest + renderer
  native = installed artifact fingerprint + build/version + process/window + renderer route
Conditional state:
Delivery identity/status, only when freshness/deployment is claimed:
Reference or design-system SSOT:
Relevant viewport/device matrix:
Intended projection/canvas size, if any:
Affected interactions and outputs:
Audit profiles:
Source authorization: audit-only | fix-and-verify
Interaction/action authority: read-only navigation | fixture-safe state changes | <named actions>
Target mutation authority: none | isolated diagnostic | local target | deploy <named environment>
Anti-goals / must-not-become:
Pass condition:

Name the correct state before judging pixels. Logged-out, onboarding, empty, permission-denied, seeded, populated, loading, and feature-flag branches can look like different products. A clean screenshot of the wrong branch is invalid. When authorization is in scope, signed-in-but-role-less is a distinct branch; logged-out or fully privileged evidence cannot stand in for it.

Use the actor's task as the success target. “The chart exists” or “the tab switches” is not enough when the user needs to decide severity, finish a review, or recover from an error.

When the pass condition names a visual reference — a screenshot, another product's page, a "make ours look like theirs" — load references/reference-parity-decomposition.md before judging the implementation, and in fix-and-verify mode before writing the next fix round. This does not widen the skill's after-implementation scope: the decomposition is the first act of the audit, applied to the reference artifact (which always already exists), and each parity fix round is implementation happening inside this skill's fix-and-verify authority. If the same request also needs a visual direction created from scratch, that part still belongs to a design skill — hand the finished inventory over rather than re-deriving it there. The contract's first deliverable is the measured structural inventory of the reference, and the parity verdict is a per-relationship diff against that inventory. Fixing only the delta the user's latest screenshot complains about, round after round, converges only by exhausting the user — a real five-round case is decomposed in that file. It also governs two traps that outlive the inventory: your own geometry assertions are Level D for parity (they encode your reading of the reference, and stay green through a misreading), and a user's veto on an effect ("never crop the image") indicts the structural premise that forces the effect, not the parameter that picks its flavor. For a reporting-grade data page compared against a tier reference, that file and references/data_viz_tier_and_token_audit.md divide the work: decomposition governs page structure, the tier benchmark governs data-presentation parameters — load both.

阅读项目说明、设计系统单一可信源（SSOT）、标记、已批准资源、启动器/测试标准操作流程（SOP）及变更代码。然后编写可证伪的约定：

产物/页面类型：
角色与任务：
目标类型 + 标准标识：
  网页 = 精确的浏览器URL（包含查询参数/片段） + 指定环境
  单个文件/图片 = 标准路径 + 内容哈希 + 渲染方案
  多资源产物 = 标准入口 + 依赖/清单摘要 + 渲染器
  原生应用 = 已安装产物指纹 + 构建/版本 + 进程/窗口 + 渲染器路由
条件状态：
交付标识/状态（仅当声称新鲜度/部署时）：
参考或设计系统单一可信源（SSOT）：
相关视口/设备矩阵：
预期投影/画布尺寸（如有）：
受影响的交互与输出：
审计配置文件：
源码授权：仅审计 | 修复并验证
交互/操作权限：只读导航 | 安全状态变更 | <指定操作>
目标修改权限：无 | 独立诊断 | 本地目标 | 部署<指定环境>
反目标/禁止事项：
通过条件：

在判断像素之前，先确认正确的状态。未登录、引导流程、空状态、权限拒绝、预填充、加载中及功能分支可能看起来像完全不同的产品。错误分支的清晰截图是无效的。当涉及权限验证时，已登录但无角色是一个独立分支；未登录或完全权限的证据不能替代它。

以角色的任务作为成功目标。当用户需要判断严重程度、完成评审或从错误中恢复时，“图表存在”或“标签页可切换”是不够的。

当通过条件指定视觉参考（截图、其他产品页面、“让我们的页面看起来和他们的一样”）时，在判断实现之前（若处于修复并验证模式，则在编写下一轮修复之前）加载references/reference-parity-decomposition.md。这不会扩大本技能在实现后的适用范围：分解是审计的第一步，应用于已存在的参考产物，每一轮一致性修复都在本技能的修复并验证权限内进行。如果同一需求还需要从头创建视觉方向，那部分仍属于设计技能的范畴——将完成的清单移交即可，无需重新推导。约定的第一个交付物是参考产物的结构化测量清单，一致性结论是针对该清单的逐项差异对比。仅修复用户最新截图中抱怨的差异，一轮又一轮地迭代，只会耗尽用户精力——该文件中记录了一个真实的五轮迭代案例。它还规定了两个在清单完成后仍需注意的陷阱：你自己的几何断言属于一致性检查的D级（它们编码了你对参考的解读，即使解读错误也会显示为通过），而用户对某个效果的否决（“绝不裁剪图片”）意味着强制该效果的结构前提存在问题，而非选择效果类型的参数存在问题。对于与层级参考对比的报告级数据页面，该文件和references/data_viz_tier_and_token_audit.md分工明确：分解负责页面结构，层级基准负责数据展示参数——需同时加载这两个文件。

2. Select The Evidence Level

2. 选择证据级别

Use the strongest level required by the claim:

Level	Evidence	Claims it can support
A	Real visible Chrome/browser or canonical native-app window, driven through the user journey	Browser/OS chrome, downloads, clipboard, popup blocking, file pickers/dialogs, print preview, permissions, native shell, actual visible-window complaints
B	Same-state browser DevTools or project E2E/Playwright run with representative data	DOM geometry, routes, focus, overlays, interaction states, repeatable responsive behavior
C	Fresh headless mechanical sweep from the bundled script	Overflow, wrapping, images, basic layout heuristics, screenshot candidates
D	Source, lint, build, unit tests, or static DOM reasoning	Hypotheses and regression support only

Do not promote a lower level into a stronger conclusion:

A screenshot path that was never opened has no visual evidence value.
A fresh headless empty state cannot verify the user's populated state.
A renderer URL cannot verify an Electron/native shell.
A handler call cannot verify Chrome print preview, popup, or download UI.
A pointer cursor, hover style, or "click to X" badge cannot verify the click does anything: a signifier without a working handler is a dead click, confirmed only by triggering it (step 5).
Device emulation is an approximation; use a real device when device-specific behavior is material.

If the required Level A surface is unavailable or another session owns the GUI, continue only with evidence that does not pretend to replace it. Report the exact missing evidence and mark the affected claim partial or blocked.

根据声明选择所需的最高级别证据：

级别	证据	可支持的声明
A	真实可见的Chrome/浏览器或标准原生应用窗口，按用户流程操作	浏览器/OS外壳、下载、剪贴板、弹窗拦截、文件选择器/对话框、打印预览、权限、原生外壳、实际可见窗口相关问题
B	相同状态下的浏览器DevTools或项目E2E/Playwright运行，使用代表性数据	DOM几何信息、路由、焦点、覆盖层、交互状态、可重复的响应式行为
C	内置脚本执行的全新无头模式扫描	溢出、换行、图片、基础布局启发式检查、截图候选
D	源码、代码检查、构建、单元测试或静态DOM推理	仅用于假设和回归支持

不得将低级别的证据升级为更强的结论：

从未打开过的截图路径不具备视觉证据价值。
全新无头模式下的空状态无法验证用户的填充状态。
渲染器URL无法验证Electron/原生外壳。
处理器调用无法验证Chrome打印预览、弹窗或下载UI。
指针光标、悬停样式或“点击执行X”标识无法验证点击是否有效：没有工作处理器的标识是无效点击，只有通过触发操作才能确认（步骤5）。
设备模拟是近似值；当设备特定行为至关重要时，使用真实设备。

如果所需的A级界面不可用，或其他会话占用了GUI，则仅使用无法替代该界面的证据继续。报告确切缺失的证据，并将受影响的标记为部分验证或受阻。

3. Prove Target, State And Viewport

3. 验证目标、状态与视口

Read project-authoritative status before launching anything. Use the canonical launcher only when each side effect fits its own authority: lifecycle permission covers rebuild/restart/deploy, while seed or transactional data changes require interaction/action authority. Never infer one from the other. An authorized isolated diagnostic server is labeled non-target.

Keep an exact web URL in browser memory, but persist only a redacted structural URL plus a stable digest/query-key list. Single files/images use path, content hash, and renderer; multi-resource HTML/decks require an authoritative resource manifest or dependency-closure digest. Native UI needs an installed-artifact fingerprint/code signature plus build, process/window, and renderer route. A renderer dev URL is diagnostic only. Treat raw screenshots as temporary local sensitive evidence; share/commit only a minimal redacted derivative.

When a claim concerns a source change, freshness, or deployment, additionally close the source-to-target chain:

take the expected identity from the target's release contract, not local HEAD unless that target is supposed to run HEAD;
read project-authoritative runtime build/image/release status;
map browser/data-plane evidence to that expected artifact—a hashed filename alone proves nothing unless an expected manifest maps it;
prove the intended route, actor, data, conditional state, and viewport.

Without identity mapping, a freshness/deployment claim is unprovable; when neither is claimed, use not applicable. Current pixels remain independently verifiable. If a source fix and target differ, its closure stays partial — source fixed, verification target stale. Audit-only work continues inspecting the live target without mutation. Source fix authority alone does not permit a target lifecycle; with separately authorized target mutation, record identity before the action, run only the named canonical lifecycle, re-prove identity, and repeat the same target/state/viewport. If lifecycle ownership is unresolved, that mutation path is blocked.

Prefer a cache-disabled reload/fresh context. Change the query only when the project declares it semantically inert, preserve existing query/fragment, and run final evidence on the original URL. The detailed page-state probe,

file://

boundary, cache rules, redirects, and viewport comparison are in references/browser-driving-and-observation-traps.md §2–§5. Record the final URL and dimensions before CSS diagnosis, then restore the user's expected viewport when finished.

For a scripted sweep, first prove the target state is reproducible with one of:

the project's fixture/storage-state/setup path;
one or more required rendered markers passed with repeated --require flags;
a direct deep link whose refresh restores the same state.

Otherwise label the run a fresh-session diagnostic, not a pass.

When the audit must sign in to a SPA, when scripted login fails or bounces back to the auth route, or when the target runs on localhost behind shell proxies, load references/auth-session-and-environment-traps.md before filing any login/network finding — those failures are usually the driving harness or the environment impersonating a product defect.

After authentication, do not drive from remembered sidebar labels or assume the target navigation is already mounted. Record the final URL, a short visible body excerpt, and the currently available links/buttons; then follow the canonical entry the rendered landing page actually exposes. If an expected locator is absent, treat navigation-contract or harness drift as the leading diagnosis until the target route/state is independently proven.

在启动任何操作之前，读取项目权威状态。仅当每个副作用符合其自身权限时，才使用标准启动器：生命周期权限涵盖重建/重启/部署，而种子或事务性数据变更需要交互/操作权限。绝不能从一个权限推断另一个权限。授权的独立诊断服务器标记为非目标。

在浏览器内存中保留精确的网页URL，但仅保存经过编辑的结构化URL加上稳定的摘要/查询键列表。单个文件/图片使用路径、内容哈希和渲染器；多资源HTML/演示文稿需要权威资源清单或依赖闭合摘要。原生UI需要已安装产物指纹/代码签名加上构建版本、进程/窗口和渲染器路由。渲染器开发URL仅用于诊断。将原始截图视为临时本地敏感证据；仅分享/提交最小化的编辑后版本。

当声明涉及源码变更、新鲜度或部署时，需额外完成源码到目标的链路验证：

从目标的发布约定中获取预期标识，而非本地HEAD，除非目标本应运行HEAD版本；
读取项目权威的运行时构建/镜像/发布状态；
将浏览器/数据层面的证据映射到该预期产物——仅哈希文件名无法证明任何事情，除非有预期清单进行映射；
验证预期路由、角色、数据、条件状态和视口。

如果没有标识映射，新鲜度/部署声明是无法验证的；如果未声明，则标记为不适用。当前像素仍可独立验证。如果源码修复与目标不符，则链路状态为部分验证——源码已修复，验证目标过时。仅审计工作继续检查实时目标，不进行修改。仅修复源码的权限不允许修改目标生命周期；如果有单独授权的目标修改权限，记录操作前后的标识，仅运行指定的标准生命周期，重新验证标识，并在相同目标/状态/视口下重复检查。如果生命周期所有权未解决，则该修改路径受阻。

优先选择禁用缓存的重新加载/全新上下文。仅当项目声明查询参数在语义上无意义时，才修改查询参数；保留现有查询参数/片段，并在原始URL上获取最终证据。详细的页面状态探测、

file://

边界、缓存规则、重定向和视口对比在references/browser-driving-and-observation-traps.md§2–§5中说明。在进行CSS诊断之前记录最终URL和尺寸，完成后恢复用户预期的视口。

对于脚本化扫描，首先通过以下方式验证目标状态可复现：

项目的固定数据/存储状态/设置路径；
一个或多个通过重复--require标志传递的必填渲染标记；
刷新后可恢复相同状态的直接深层链接。

否则将运行标记为全新会话诊断，而非通过。

当审计必须登录到SPA，脚本化登录失败或跳回授权路由，或目标在shell代理后的localhost上运行时，在提交任何登录/网络问题之前加载references/auth-session-and-environment-traps.md——这些失败通常是测试环境或环境模拟产品缺陷导致的。

认证后，不要根据记忆中的侧边栏标签进行操作，也不要假设目标导航已挂载。记录最终URL、简短的可见正文摘录以及当前可用的链接/按钮；然后遵循渲染落地页实际展示的标准入口。如果预期定位器缺失，在独立验证目标路由/状态之前，将导航约定或测试环境漂移作为首要诊断方向。

4. Capture And Inspect Rendered Evidence

4. 捕获并检查渲染证据

Capture the whole visible composition before zooming into the defect, then the affected component, relevant responsive widths, and lower sections. Open every screenshot with an image viewer and record what you saw; an uninspected file is not evidence.

Calibrate the capture before trusting it. Falsify apparent clipping against DOM geometry, pin device scale where supported, wait for fonts/network/animation, and use the engine the recipient actually views. DOM evidence explains pixels; it does not replace them.

The full capture-calibration protocol and minimum inspection set are in references/browser-driving-and-observation-traps.md §12. Extent and device-emulation traps specific to headless capture are catalogued in the same reference at §4–§5.

Load references/history-derived-checklist.md for the core visual/responsive defect catalog and standards-backed checks.

Some defects produce no diagnostic anywhere: a global reset outranking a component's own styles, a library renaming its internal DOM classes so whole rule groups match nothing, a font family declared but never shipped, geometry written into theme config where source scans cannot see it, a new design token reusing a name the file already spent, a property that cannot apply because the rule never set the layout mode it presupposes, and per-element compliance that still reads as "no design system" in aggregate. Source review, type checks and geometry assertions are structurally blind to these — the artifacts are valid and simply do nothing. When a page looks cheap while every gate is green, that combination is the signature. Load references/silent-degradation-and-evidence.md for the detection method per class, and probe the two highest-yield ones mechanically:

node <skill-root>/scripts/silent_degradation_probe.mjs font \
  --url http://127.0.0.1:5173/ --weight 700 \
  --family "Brand Sans" --family "Fallback Sans"

node <skill-root>/scripts/silent_degradation_probe.mjs class \
  --css path/to/bridge.css --library-css node_modules/<lib>/dist/<lib>.css

Pass every family in the stack and the weight the page really uses. Interpret all five verdicts exactly; platform generics are healthy, while only host-provided-only and broken asset are defects. The reference explains why computed family names,

document.fonts.check()

, unloaded candidates, and CJK-only width probes otherwise create false conclusions.

Run the bundled sweep from the audited project so it can resolve the project's existing Playwright dependency:

node <skill-root>/scripts/visual_layout_audit.mjs \
  --url 'http://127.0.0.1:5173/?state=fixture#/ready' \
  --page-type app \
  --require "Expected state marker" \
  --screenshot-sections

Use --file <artifact.html> for a local HTML artifact. Run node <skill-root>/scripts/visual_layout_audit.mjs --help for all flags. For a contracted canvas, pass one or more exact viewports; custom viewports replace the default responsive matrix:

node <skill-root>/scripts/visual_layout_audit.mjs \
  --file deck.html --page-type deck --viewport 1920x1080 \
  --screenshot-sections

For a long page whose evidence depends on below-the-fold covers or thumbnails, add --scroll-visible-media. It visits rendered media rows before capture so lazy loading can start, while excluding CSS-hidden responsive alternatives. Without that flag, offscreen lazy media is reported as deferred coverage rather than a broken asset. In either mode, inspect the screenshots: “not requested,” “still loading,” and “request completed but undecodable” are different states.

Use repeated --forbid patterns only for project-specific stale names or rendered terms that the current product contract explicitly prohibits. Do not encode generic taste preferences as forbidden regexes.

The script exits:

0 when no mechanical errors remain;
1 when errors remain, or warnings remain with --fail-on-warning;
2 for invalid input, missing prerequisites, or runtime/setup failure.

The script writes screenshots and its JSON report to a unique temporary run directory; explicit --out must be new or empty. It is a Level C sweep, not the final verdict. Never commit/share raw evidence: reports hash rendered labels and redact target-derived values, while derivative screenshots need identifying pixels redacted. Its target-string fingerprint and single-file byte hash do not compute a multi-resource closure/native identity; supply the project contract.

Do not mutate the audited project merely to run the sweep. Reuse its package manager and canonical browser harness. If Playwright is absent, continue with available Level A/B evidence and report the omitted Level C sweep; install a dependency only when dependency changes are authorized.

Pass headers through

--header-env "Name: ENV_NAME"

; argv contains only the header/env names, never the value. Raw

--header

is disabled. Values stay on the target origin; TLS stays enabled except for an explicitly trusted self-signed origin.

Run the probe regressions from a project that already provides Playwright:

bash

node --test <skill-root>/tests/test_silent_degradation_probe.mjs

在放大缺陷之前，先捕获整个可见布局，然后捕获受影响的组件、相关响应式宽度和下方区域。使用图片查看器打开每个截图并记录所见内容；未检查的文件不是证据。

在信任捕获结果之前进行校准。对照DOM几何信息验证明显的裁剪问题，在支持的设备上固定缩放比例，等待字体/网络/动画加载完成，并使用接收端实际使用的引擎。DOM证据用于解释像素，但不能替代像素。

完整的捕获校准协议和最小检查集在references/browser-driving-and-observation-traps.md§12中说明。无头捕获特有的范围和设备模拟陷阱在同一参考文档的§4–§5中列出。

加载references/history-derived-checklist.md获取核心视觉/响应式缺陷目录及基于标准的检查项。

有些缺陷无法通过任何诊断发现：全局重置优先级高于组件自身样式、库重命名内部DOM类导致整个规则组无匹配、声明了字体族但未部署、几何信息写入主题配置导致源码扫描无法发现、新设计标记重用了文件已使用的名称、属性因规则未设置预设布局模式而无法生效、每个元素都合规但整体看起来“无设计系统”。源码评审、类型检查和几何断言对这些问题是盲目的——产物有效但完全不起作用。当页面看起来粗糙但所有检查都通过时，这种组合就是特征。加载references/silent-degradation-and-evidence.md获取各类问题的检测方法，并自动检测两个最高收益的问题：

node <skill-root>/scripts/silent_degradation_probe.mjs font \
  --url http://127.0.0.1:5173/ --weight 700 \
  --family "Brand Sans" --family "Fallback Sans"

node <skill-root>/scripts/silent_degradation_probe.mjs class \
  --css path/to/bridge.css --library-css node_modules/<lib>/dist/<lib>.css

传入栈中的所有字体族及页面实际使用的字重。准确解读所有五个结论；平台通用字体是正常的，仅宿主提供字体和损坏资源属于缺陷。参考文档解释了为什么计算字体族名称、

document.fonts.check()

、未加载候选字体和仅CJK宽度探测会导致错误结论。

从被审计项目中运行内置扫描，使其能解析项目现有的Playwright依赖：

node <skill-root>/scripts/visual_layout_audit.mjs \
  --url 'http://127.0.0.1:5173/?state=fixture#/ready' \
  --page-type app \
  --require "Expected state marker" \
  --screenshot-sections

对于本地HTML产物，使用--file <artifact.html>。运行node <skill-root>/scripts/visual_layout_audit.mjs --help查看所有标志。对于约定的画布，传入一个或多个精确视口；自定义视口将替换默认的响应式矩阵：

node <skill-root>/scripts/visual_layout_audit.mjs \
  --file deck.html --page-type deck --viewport 1920x1080 \
  --screenshot-sections

对于证据依赖于折叠下方封面或缩略图的长页面，添加--scroll-visible-media。它在捕获前访问渲染的媒体行，以便懒加载启动，同时排除CSS隐藏的响应式替代方案。如果没有该标志，屏幕外懒加载媒体将被报告为延迟加载，而非损坏资源。无论哪种模式，都要检查截图：“未请求”、“仍在加载”和“请求完成但无法解码”是不同的状态。

仅对项目特定的过时名称或当前产品约定明确禁止的渲染术语使用重复的--forbid模式。不要将通用品味偏好编码为禁止正则表达式。

脚本退出状态：

0：无机械错误；
1：存在错误，或使用--fail-on-warning时存在警告；
2：输入无效、缺少先决条件或运行时/设置失败。

脚本将截图和JSON报告写入唯一的临时运行目录；显式指定的--out必须是新目录或空目录。这是C级扫描，而非最终结论。绝不要提交/分享原始证据：报告对渲染标签进行哈希处理并编辑目标衍生值，编辑后的截图需要隐藏标识像素。其目标字符串指纹和单个文件字节哈希无法计算多资源闭合/原生标识；需提供项目约定。

不要仅为了运行扫描而修改被审计项目。重用其包管理器和标准浏览器测试环境。如果缺少Playwright，继续使用可用的A/B级证据，并报告省略的C级扫描；仅当依赖变更获得授权时才安装依赖。

通过

--header-env "Name: ENV_NAME"

传递请求头；argv仅包含请求头/环境变量名称，绝不包含值。禁用原始

--header

。值仅保留在目标源；除非是明确信任的自签名源，否则保持TLS启用。

从已提供Playwright的项目中运行探测回归测试：

bash

node --test <skill-root>/tests/test_silent_degradation_probe.mjs

5. Exercise Journeys And Outputs

5. 执行流程与输出

A visible signifier is not proof of behavior — trigger every relevant control whose side effects fit the explicit action authority, confirm the response, and mark the rest unverified. Pointer/hover/button styling can be a false affordance: the handler is absent or stale, while screenshots and plausible source both pass. Only a real Level A/B trigger verifies behavior. Prioritize late-added lightboxes, thumbnail grids, and copy actions. Assert the resulting state—not dispatch—and rule out delegation, hydration timing, or trusted-gesture gates before calling a dead click (browser-driving-and-observation-traps.md trap 1). A missing visible cue around working behavior is the inverse failure in the silent-degradation reference.

Exercise only the relevant transition matrix:

entry -> ready -> active -> processing -> success/error -> recovery -> ready

Also verify, when applicable:

click -> URL/state -> refresh -> deep link -> back/forward;
drawer/modal/popover open, focus, background interaction, close, and mobile;
transient notification lifecycle with observation armed before the trigger;
advanced mode -> visible current mode and trigger owner -> one-step return to default;
provider/model/runtime status -> selected configuration and current status evidence;
download -> completed file -> opened recipient artifact;
share -> copied/opened URL -> refreshed recipient state;
file picker/dialog -> visible open/cancel/select path -> recovered app state;
print/PDF -> real Chrome preview -> nonblank pages;
Electron/native -> canonical app process/window -> native controls and shell.

Load references/journey-and-page-contracts.md when the audit includes state transitions, authorization, modes, provider/model/runtime truth, routes, transient states, overlays, browser outputs, native shells, landing/deck/browser tool/game artifacts, dashboards, design-system artifacts, GIS/maps, or review tools.

Load references/data_viz_tier_and_token_audit.md only for reporting-grade data pages, named tier/reference comparisons, chart token audits, or categorical palettes.

Before reporting a nontrivial audit, re-walk the primary path as a tired user without debugger context. Look first for unclear trigger or mode ownership, hidden return-to-default, blocked recovery, misleading runtime labels, raw machine language, unreachable controls, avoidable manual work, and the missing guard that would let the same defect recur. This is a falsification pass, not an excuse to expand a local visual-only audit into every profile.

**可见标识并非行为的证明——触发所有符合明确操作权限的相关控件，确认响应，并标记其余未验证项。**指针/悬停/按钮样式可能是虚假的功能提示：处理器缺失或过时，而截图和看似合理的源码都通过了检查。只有真实的A/B级触发才能验证行为。优先测试后期添加的灯箱、缩略图网格和复制操作。断言最终状态——而非调度操作——并在判定为无效点击之前排除委托、 hydration 时机或可信手势限制（browser-driving-and-observation-traps.md陷阱1）。有效行为周围缺少可见提示是静默退化参考文档中的反向故障。

仅执行相关的转换矩阵：

入口 -> 就绪 -> 活跃 -> 处理中 -> 成功/错误 -> 恢复 -> 就绪

此外，在适用时验证：

点击 -> URL/状态 -> 刷新 -> 深层链接 -> 前进/后退；
抽屉/模态框/弹出层的打开、焦点、背景交互、关闭及移动端适配；
触发前已启用观察的临时通知生命周期；
高级模式 -> 当前可见模式及触发所有者 -> 一键返回默认模式；
提供者/模型/运行时状态 -> 所选配置及当前状态证据；
下载 -> 完成的文件 -> 打开的接收端产物；
分享 -> 复制/打开的URL -> 刷新的接收端状态；
文件选择器/对话框 -> 可见的打开/取消/选择路径 -> 恢复的应用状态；
打印/PDF -> 真实Chrome预览 -> 非空白页面；
Electron/原生应用 -> 标准应用进程/窗口 -> 原生控件和外壳。

当审计包含状态转换、权限验证、模式、提供者/模型/运行时真实性、路由、临时状态、覆盖层、浏览器输出、原生外壳、落地页/演示文稿/浏览器工具/游戏产物、控制台、设计系统产物、GIS/地图或评审工具时，加载references/journey-and-page-contracts.md。

仅当审计报告级数据页面、指定层级/参考对比、图表标记审计或分类调色板时，加载references/data_viz_tier_and_token_audit.md。

在报告非 trivial 审计之前，以疲惫用户的身份重新走一遍主路径，不使用调试器上下文。首先查找不清晰的触发或模式所有权、隐藏的返回默认机制、受阻的恢复流程、误导性的运行时标签、原始机器语言、无法访问的控件、可避免的手动操作以及会导致同一缺陷复发的缺失防护。这是一次证伪检查，而非将局部视觉审计扩展到所有配置文件的借口。

6. Report, Fix, And Re-run

6. 报告、修复与重新运行

Every appearance claim ships with the pixels that show it. A reader who cannot see the defect cannot decide anything about it, and cannot check whether the finding is even real. Crop to the affected element with just enough surrounding context to locate it — a full-page screenshot proves nothing about a 14px misalignment, and prose alone ("the buttons look cheap") is unactionable no matter how accurate.

scripts/silent_degradation_probe.mjs shot

crops one element plus padding for exactly this.

Four rules that decide whether the evidence survives contact with a reader: comparisons must be scale-matched (two full-width regions placed side by side shrink until the 3px difference under discussion vanishes — crop both to the same component at the same width instead); dimensions are reported in CSS px, never device px (a DPR-2 capture has twice the pixel count, and quoting that as page height has produced a false "20 screens long" finding); a capture taken before a fix is labeled with the commit it shows rather than presented as current; and findings resting on a code count rather than a photograph are marked as such, so the reader knows which parts of the list are equally evidenced.

Separate impact from category. Follow the project's severity taxonomy when one exists. Otherwise use:

Blocker — false success, destructive/misleading action, or primary journey cannot complete without a safe workaround;
Major — core task, recipient output, recovery, route, or critical control is unusable;
Moderate — comprehension or operation is materially degraded but a safe workaround exists;
Minor — polish defect with little task impact.

Use categories such as layout, responsive, state, route, accessibility, browser-output, native-shell, intent, or taste. Taste and Intent are not severity levels.

Report with this compact schema:

Current-render status: verified | partial | blocked
Delivery status: matched | mismatched | unprovable | not applicable
Fix-closure status: verified | partial | blocked | not applicable
Target: <web: redacted requested/final + target-string fingerprint/query keys/redirects | single-file/image: redacted canonical path + content hash + renderer | multi-resource: entry + authoritative manifest/dependency-closure digest + renderer | native: installed-artifact fingerprint/signature + build/version + process/window + renderer route>
Environment: <verified name or unverified>
Delivery identity: <expected; observed before -> after; evidence>
Actor/job; reference/pass condition; affected journeys:
Authorization: <source scope; interaction/action scope; target-mutation scope>
Scope: <state, viewports, profiles>

Findings:
- Major · browser-output · PDF action · desktop
  Impact/state/viewport/reproduction:
  Evidence artifact/crop:
  Evidence: clicking the visible control opens about:blank; print preview has no page.
  Fix: use a user-gesture-safe print path and re-test the recipient preview.

Reference-parity inventory (parity audits only):
- <relationship -> matched | deliberately diverged (derivation) | not yet, one line each>

Verified:
- <journey/state/viewport + concrete evidence>

Not verified:
- <missing surface/evidence and why>

In audit-only mode, continue read-only evidence gathering but make no source or target mutation. In fix-and-verify mode:

Fix the root cause rather than hiding overflow, shrinking all type, changing selectors to evade the detector, or removing a feature.
Preview subjective alternatives live before committing a shared visual token.
Update a target only under its separate named mutation authority; otherwise report source-fixed/target-unverified without expanding scope.
Re-run the same canonical target and re-prove identity, route, state, viewport, journey, and recipient output.
Add or update the smallest regression guard that would catch the confirmed failure class.

Three habits keep the fix pass from manufacturing its own defects — each has produced one:

Shoot the "before" while the defect still exists. After the rebuild it is unreproducible, and a closure report can then only assert the improvement. Reuse the identical crop window for the after-shot so the pair differs by one variable.
Grep a new shared name before introducing it. A token named after a word the file already spent (
```
rail
```
,
```
bar
```
,
```
card
```
) silently overrides or gets overridden depending on definition order, changing two subsystems at once (silent-degradation class 1f).
Prove the repaired assertion can fail. Reintroduce the defect, watch it go red with the expected magnitude, then remove it. An assertion that stayed green through the whole bug does not become a guard by being rewritten.

**每个外观声明都需附带展示该声明的像素。**无法看到缺陷的读者无法做出任何决策，也无法检查发现是否真实。裁剪到受影响的元素，仅保留足够的周围上下文以定位——全页截图无法证明14px的对齐问题，仅文字描述（“按钮看起来很粗糙”）无论多么准确都无法执行。

scripts/silent_degradation_probe.mjs shot

正是为此裁剪单个元素及周围边距。

决定证据是否能被读者接受的四条规则：对比必须比例匹配（两个全宽区域并排会缩小到讨论的3px差异消失——改为将两者裁剪到相同宽度的同一组件）；尺寸以CSS px报告，绝不使用设备px（DPR-2的捕获像素数是两倍，将其引用为页面高度会产生“长达20屏”的错误结论）；修复前的捕获需标记其对应的提交，而非作为当前状态展示；基于代码计数而非图片的发现需标记为代码计数，以便读者知道列表中哪些部分的证据级别相同。

将影响与类别分开。如果项目有严重程度分类标准，则遵循该标准。否则使用：

阻塞 — 错误的成功提示、破坏性/误导性操作，或主流程无安全 workaround 无法完成；
严重 — 核心任务、接收端输出、恢复流程、路由或关键控件无法使用；
中等 — 理解或操作受到实质性影响，但存在安全 workaround；
轻微 — 抛光缺陷，对任务影响极小。

使用布局、响应式、状态、路由、可访问性、浏览器输出、原生外壳、意图或品味等类别。品味和意图不是严重程度级别。

使用以下紧凑格式报告：

当前渲染状态：已验证 | 部分验证 | 受阻
交付状态：匹配 | 不匹配 | 无法验证 | 不适用
修复完成状态：已验证 | 部分验证 | 受阻 | 不适用
目标：<网页：编辑后的请求/最终URL + 目标字符串指纹/查询键/重定向 | 单个文件/图片：编辑后的标准路径 + 内容哈希 + 渲染器 | 多资源：入口 + 权威清单/依赖闭合摘要 + 渲染器 | 原生应用：已安装产物指纹/签名 + 构建/版本 + 进程/窗口 + 渲染器路由>
环境：<已验证名称或未验证>
交付标识：<预期；观察到的修改前 -> 修改后；证据>
角色/任务；参考/通过条件；受影响的流程：
授权：<源码范围；交互/操作范围；目标修改范围>
范围：<状态、视口、配置文件>

问题发现：
- 严重 · 浏览器输出 · PDF操作 · 桌面端
  影响/状态/视口/复现步骤：
  证据产物/裁剪图：
  证据：点击可见控件打开about:blank；打印预览无页面。
  修复方案：使用用户手势安全的打印路径，并重新测试接收端预览。

参考一致性清单（仅一致性审计）：
- <关系 -> 匹配 | 故意偏离（推导） | 未完成，每项一行>

已验证项：
- <流程/状态/视口 + 具体证据>

未验证项：
- <缺失范围/证据及原因>

在仅审计模式下，继续只读证据收集，但不修改源码或目标。在修复并验证模式下：

修复根本原因，而非隐藏溢出、缩小所有字体、修改选择器以规避检测或移除功能。
在提交共享视觉标记之前，实时预览主观替代方案。
仅在获得单独的指定修改权限时更新目标；否则报告“源码已修复/目标未验证”，不扩大范围。
重新运行相同的标准目标，并重新验证标识、路由、状态、视口、流程和接收端输出。
添加或更新最小的回归防护，以捕获已确认的故障类型。

三个习惯可避免修复过程中产生新缺陷——每个习惯都曾解决过一个问题：

**在缺陷仍存在时拍摄“修复前”截图。**重建后缺陷无法复现，完成报告只能断言改进。对“修复后”截图使用相同的裁剪窗口，以便两张截图仅一个变量不同。
**在引入新共享名称之前进行搜索。**文件已使用的名称（
```
rail
```
、
```
bar
```
、
```
card
```
）命名的标记会根据定义顺序静默覆盖或被覆盖，同时改变两个子系统（静默退化类别1f）。
**证明修复后的断言可失效。**重新引入缺陷，观察其按预期程度变为失败状态，然后移除缺陷。在整个缺陷过程中始终显示通过的断言，即使重写也无法成为防护。

Completion Gate

完成关卡

Call current-render status verified only when:

the canonical target kind/identity, final target, data, and actor state are proven;
delivery is matched, mismatched, or unprovable when freshness is claimed, otherwise not applicable;
every screenshot cited in the report was opened and inspected;
relevant viewports and lower sections were covered;
affected interactions and outputs were exercised at the required evidence level;
no unresolved Blocker/Major finding contradicts the pass;
remaining limitations are explicit.

Call fix-closure status verified only after an authorized fix is rechecked against the same canonical target/state/viewport; otherwise use partial or blocked.

Otherwise report partial or blocked. Never ask the user to perform a check the available agent tools can perform.

仅当满足以下所有条件时，才将当前渲染状态标记为已验证：

标准目标类型/标识、最终目标、数据和角色状态已验证；
当声称新鲜度时，交付状态为匹配、不匹配或无法验证，否则为不适用；
报告中引用的每个截图都已打开并检查；
已覆盖相关视口和下方区域；
已按所需证据级别执行受影响的交互和输出；
没有未解决的阻塞/严重问题与通过结论矛盾；
剩余限制已明确说明。

仅当授权修复后，针对相同标准目标/状态/视口重新检查通过，才将修复完成状态标记为已验证；否则使用部分验证或受阻。

否则报告为部分验证或受阻。绝不要让用户执行可用代理工具可完成的检查。

Bundled Resources

内置资源

scripts/visual_layout_audit.mjs — Playwright-powered mechanical viewport, layout, and media-state sweep with screenshots and JSON evidence.
references/history-derived-checklist.md — core visual/responsive defect catalog plus standards-backed checks.
references/journey-and-page-contracts.md — state, route, overlay, browser-output, native-shell, and page-type contracts.
references/auth-session-and-environment-traps.md — authenticated-SPA login and post-login navigation driving traps plus environment hijack diagnostics (proxy, CSP entry point, server-log triangulation).
references/data_viz_tier_and_token_audit.md — conditional data-viz, reference-tier, token, and palette audit.
references/reference-parity-decomposition.md — the reference-parity profile's method: measured structural inventory of the named reference before judging or fixing, per-relationship parity verdicts with match criteria, why self-authored assertions are Level D for parity, veto-premise analysis, asset fidelity, relationship (not value) translation, and the pre-report confirmation list.
references/browser-driving-and-observation-traps.md — the auditor's own failure modes: misread clicks, stale caches,
```
file://
```
limits, viewport-vs-page screenshots, width-resize vs device emulation, states a default screenshot cannot show, hidden-tab media deferral, virtual-time false negatives,
```
--dump-dom
```
timing (and the title-encoded interaction probe done right), and Range-server media stalls. Read it before driving a real browser, and whenever an observation surprises you.
evals/evals.json and evals/trigger-evals.json — behavior and routing regression cases; excluded from packaged runtime content.

scripts/visual_layout_audit.mjs — 基于Playwright的自动化视口、布局和媒体状态扫描，生成截图和JSON证据。
references/history-derived-checklist.md — 核心视觉/响应式缺陷目录及基于标准的检查项。
references/journey-and-page-contracts.md — 状态、路由、覆盖层、浏览器输出、原生外壳和页面类型约定。
references/auth-session-and-environment-traps.md — 已认证SPA登录和登录后导航操作陷阱，以及环境劫持诊断（代理、CSP入口点、服务器日志三角测量）。
references/data_viz_tier_and_token_audit.md — 条件数据可视化、参考层级、标记和调色板审计。
references/reference-parity-decomposition.md — 参考一致性配置文件的方法：在判断或修复之前对指定参考进行结构化测量清单，逐项关系一致性结论及匹配标准，为什么自写断言属于一致性检查的D级，否决前提分析，资源保真度，关系（而非值）转换，以及报告前确认清单。
references/browser-driving-and-observation-traps.md — 审计人员自身的失败模式：误读点击、过期缓存、
```
file://
```
限制、视口与页面截图、宽度调整与设备模拟、默认截图无法显示的状态、隐藏标签页媒体延迟、虚拟时间假阴性、
```
--dump-dom
```
时机（以及正确的标题编码交互探测），以及范围服务器媒体停滞。在操作真实浏览器之前，以及每当观察结果出乎意料时，都要阅读该文档。
evals/evals.json和evals/trigger-evals.json — 行为和路由回归案例；不包含在打包运行时内容中。