frontend-visual-qa
Audits rendered UI, whole-site route censuses and task/object-link handoffs in web apps, decks, dashboards, design systems, Markdown/Obsidian and Electron. Uses real-browser journeys and Playwright for typography, overflow, responsive, routing, data-viz, browser-output or native-shell defects and reference comparisons. Excludes source-only citation checks, greenfield design (ui-designer) and QA setup (qa-expert).
How do I install this agent skill?
npx skills add https://github.com/daymade/claude-code-skills --skill frontend-visual-qaIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill is a sophisticated UI auditing tool for web applications, dashboards, and design systems. It uses Playwright to drive a browser and inspect rendered artifacts for layout and functional defects. The skill demonstrates high security maturity by including explicit SSRF protections in its crawler and implementing automated redaction of sensitive URL components (like OAuth tokens or path secrets) in generated reports. Findings related to dynamic execution and local dependency resolution are appropriate for its functional requirements as a developer-oriented auditing extension.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 2 issues
What does this agent skill do?
Frontend Visual 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.
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;
- whole-site census — sitemap-derived route coverage and repeatable structural errors across declared viewports, used to choose where full visual inspection is required.
For a specific task/object link handoff, select state and journey for that destination, including authoritative machine and run/job identity when titles repeat. Keep the audit bounded to the promised destination.
For an illustrated spreadsheet or fill-in grid, also read grid image forms. Judge recognizable thumbnails, readable labels and usable entry fields together; a visible-row target alone does not establish readability.
For a website/document converted to Markdown, or an illustrated transcript/note consumed in Obsidian or another named reader, load references/markdown-reader-handoff.md before judging figure readability. Compare the complete source figure with its actual document reading canvas, including HTML captions and SVG/CSS dependencies. For oversized embedded images, use its display-size recipe and test a representative long image with the adjacent text before applying the same layout to the document.
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, or to extract a design system from reference screenshots — this skill audits an already-rendered artifact, it does not derive one.
- Use this skill to test the already-rendered result, not to debug nonvisual code (logic, data, or backend correctness) that produced no visible defect.
- 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 owns rendered information hierarchy as well as geometry: whether persistent labels, explanations and repeated context help the actor's task or displace it. Do not route that question away as mere copy polish. Domain-fact correctness, terminology and persuasion still need the appropriate content or subject-matter review; a rendering pass cannot certify those claims.
Required Outcome
Prepare before taking over the target
The executing auditor resolves the latest user contract and stage-specific Skills before driving a shared browser or device. Load the Skills explicitly requested for this task from their actual entries. For numerical breakdowns or charts, also use data-visualization-discipline; for Android control, use android-automation alongside this visual audit. Add a design Skill only when the user requests it or the task changes design. Device control alone supplies no visual or business acceptance criterion.
Read the selected current Skill text and affected references, then freeze the actor's question, canonical target, affected states and observable answer. A catalog entry, remembered section label or compaction summary is a locator, not the loaded instructions. Reuse unchanged text still present in context; after compaction, reload only the needed instructions rather than rerunning completed tests.
Record this preparation in the existing scope contract: required capability, resolved owner/entry, and the acceptance evidence it supplies. Missing instructions leave the dependent judgement unverified; continue authorized independent read-only work. Finish tool/dependency preparation before a short shared-resource window, and follow the target-control owner's restoration contract when that window ends. These are auditor actions, not claims of an automatic Skill-loading guard.
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.
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
1. Establish The Audit Contract
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.
Freeze the user's requirements separately from the implementation. A complaint about clutter, redundant explanation or wasted space identifies a failure class, not just the circled element. Inspect that class across the declared full surface. Do not silently narrow the review to the last screenshot's rectangles or rewrite the requirement as “the task remains possible” after a candidate fails.
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.
2. Select The Evidence Level
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.
3. Prove Target, State And Viewport
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.
For GET-readable web resources, follow delivery verification and run the bundled manifest comparison before claiming a matched deployment. Include separately served embedded components. Its result establishes only the supplied identity checks; keep pixel inspection and the actual user journey as independent gates. For a hosted local artifact with competing current/old links, use that reference's current-entry handoff to bind the selected local content, verify every declared old link and inspect the actual recipient page; HTTP 200 or a correct redirect alone does not pass.
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 unstyled-page complaints or shared route-style changes, run the cold-entry then warm-return check before accepting a correctly styled return visit.
For a data-bearing Demo that promises existing activity but renders zero/empty, load the reference's Data-bearing Demo states recipe before judging the state.
For a loading-speed claim, read §2's performance-comparison boundary before measuring.
For hidden-page polling, read that reference's Verify polling stops in a genuinely hidden page recipe before testing; media focus emulation cannot establish that policy.
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.
4. Capture And Inspect Rendered Evidence
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.
Before reading an overflowing <pre> with horizontal wheel input, load the
fresh input-target check
and inspect the affected text positions rather than accepting scroll movement alone.
Before judging wheel-driven pan/zoom sensitivity, load the same reference's
Wheel requests are not browser-received wheel events recipe; compare movement
with received input rather than the harness request.
For a promised continuous same-map overview-to-detail interaction, load Continuous zoomable maps and exercise intermediate disclosure, reversal and the affected return paths.
Load references/history-derived-checklist.md
for the core visual/responsive defect catalog and standards-backed checks,
including complete multiline request, log and audit-table rows.
For composition or density audits, including AI-generated UI or copy complaints,
execute its Information necessity before layout check and select the matched
Established methods before fixing line breaks. Before declaring rendered UI ready for
release, complete that check's ancillary-copy inventory and dispositions across
the declared surface, including shared text and affected conditional states.
Missing coverage or unresolved task-relevant explanations leave that release
claim partial; passing geometry or finding no forbidden words cannot clear it.
The sweep's attentionInventory makes
the visible text population and exact repetitions inspectable; review the full
population against the task, not only its repetition candidates. Complete
inventory coverage is not proof that the content is necessary.
For a publication whose local checks pass but discovery or reading still feels cluttered, including feedback such as “还有 AI Slop”, use the publication journey cases to calibrate whole-path findings, including the declared controls, deks and expanded summaries, against failing and healthy cases. These supplement the existing necessity check, not a style score.
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.
Whole-Site Route Census
For a release-wide or sitemap-owned surface, enumerate canonical routes and run the bounded structural census from the audited project so it resolves that project's existing Playwright dependency:
node <skill-root>/scripts/route_census.mjs \
--url 'https://reader.example/' \
--viewport 1440x900 --viewport 390x844 \
--limit 20 --out <new-empty-directory>
Use --sitemap <url-or-file> instead of --url when the sitemap is not at the
site-root sitemap.xml. Sitemap indexes are followed recursively; canonical
routes retain sitemap order, are de-duplicated, and --limit both selects the
first N and stops discovery with discovery.truncated: true. Discovery is also
capped at 100 sitemap documents and 10,000 routes. A run accepts at most 20
viewport entries and 100 explicit probes. With no --viewport, the census uses
1440x900 and 390x844.
URL boundaries fail closed: an HTTP(S) root never follows file: children; a
local file root follows only file: children inside its own directory; canonical
routes and probes are same-origin by default. Use --allow-origin <origin> only
for an intentional cross-origin route set. Loopback, private and link-local
targets require an exact --allow-target <host> entry. Sitemap redirects are
validated hop by hop before the next fetch, and browser main-frame redirects are
intercepted and checked before continuation. The browser policy applies only to
main-frame navigations; cross-origin iframes and subresources are not blocked by
the route-origin rule. Hostnames are also resolved and rejected when they map
into restricted address space; documentation-only hosts (example.*, .test,
.invalid) are exempt for fixtures. This reduces DNS-based bypasses but cannot
eliminate DNS rebinding between validation and connection.
Each route/viewport has a 45-second hard deadline covering navigation, readiness
and evaluation; override it only with --route-timeout-ms <1000-300000>.
Use --probe <url> --probe-expected-status <status> for a deliberate probe such
as an unknown localized-404 route. Probe records carry
routeKind: "localized-404-probe" and expectedStatus; a matching 404 is an
observation, not a confirmed census error. Canonical records carry
routeKind: "canonical" and expect HTTP 200 unless the route set is explicitly
modeled another way.
It writes records.jsonl plus summary.json and checks unexpected statuses,
fatal page/navigation/deadline failures, horizontal overflow, console errors,
broken and pending viewport-visible images, missing alt text, broken same-page
hash targets, duplicate IDs, missing/duplicate visible H1, missing visible main
landmark, and empty rendered text. Path-style hash routes such as #/app and
hashbangs such as #!dashboard or #! are not treated as element anchors. Pending images
are warnings; the other listed conditions are confirmed errors. Exit 0 means no
confirmed structural error, 1 means at least one, and 2 means invalid input or
runtime/setup failure. Records retain sitemap order through routeIndex and
persist only redacted, hashed route evidence; keep any exact-route mapping local
and out of shared evidence.
The census is Level C triage and does not clear visual acceptance. It does
not inspect composition, typography, crop, focus appearance, or the user journey,
and a zero exit is not a visual pass. For every appearance claim, capture the
affected routes with visual_layout_audit.mjs or the canonical harness and
open every cited screenshot; an unopened screenshot or a clean
summary.json cannot support “looks correct.”
Run the probe regressions from a project that already provides Playwright:
node --test <skill-root>/tests/test_silent_degradation_probe.mjs
node --test <skill-root>/tests/route-census/test_route_census.mjs
node --test <skill-root>/tests/route-census/test_visual_layout_audit_regressions.mjs
5. Exercise Journeys And Outputs
For changed data-bound contribution views or multi-item reads, apply the linked journey contract's bounded-window coverage, visible contribution and mixed-result recovery checks before granting a pass. These are auditor actions through the authorized project harness, not predicates enforced by the generic sweep.
For UI refactors, category splits, or navigation changes, first apply the Refactor Preservation recipe in references/journey-and-page-contracts.md. Derive affected journeys from the immutable pre-change version, then verify them on the current target; the new navigation alone cannot define what survived. For refresh/deep-link/return checks, use that reference's Route And Addressability recipe, including default-entry and late-data controls when startup is affected, and repeated occurrences when the product promises to retain them.
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 or game-feedback lifecycle using Transient UI, 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.
For a media library, evidence/review viewer or a video-download complaint, load media playback and output cases before choosing samples. It covers poster-to-playback geometry, portrait/landscape, image notices, compatible previews, source identity, seeking and actual downloaded bytes.
Load references/journey-and-page-contracts.md when the audit includes state transitions, authorization, modes, summary-to-detail disclosure, 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.
For citation markers that promise original evidence, run that reference's Cited Source Inspection against the actual text, image or PDF and its return path. For changed long-document navigation or source sidebars, also use its Long-document reading positions recipe; a correct first screen does not verify the same controls deep in the document.
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.
6. Report, Fix, And Re-run
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.
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.
These 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.
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;
- every explicit pass condition is met, including information necessity when layout/density or release readiness is in scope; calling a violation Moderate, Minor, taste or “still usable” does not override a user's requirement;
- 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.
- scripts/route_census.mjs — sitemap-derived whole-site structural census with JSONL records, aggregate summary, documented exit codes, and no screenshot or visual-acceptance claim.
- scripts/attention_inventory.mjs — observed text/geometry, repetition and label echo inventory used by the sweep; it never certifies necessity.
- scripts/painted_text_probe.mjs — vertical text-fragment clipping used by the sweep; reports examined coverage and unsupported clipping/scroll windows.
- scripts/journey_input.mjs — non-TTY JSONL input for an already-authorized browser adapter; preserves full commands and stops dependent steps on failure.
- 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/markdown-reader-handoff.md — complete-figure comparison in the actual Markdown reader, dependency diagnosis and authorized readable-image repair.
- 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 and polling acceptance, virtual-time false negatives,--dump-domtiming (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. Source-development
cases 44–45 calibrate Goal/requirement/reply separation, exact originals,
long-text return and runtime replacement using the nested-source fixture.
From an existing Playwright project, run
node --test <skill-root>/tests/test_nested_source_return.mjs. This is synthetic calibration, not a prerequisite for ordinary audits or product acceptance.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/daymade/claude-code-skills/frontend-visual-qa">View frontend-visual-qa on skillZs</a>