Core rule
If appearance is part of the requirement, the rendered result is the evidence.
Source code, DOM structure, CSS, a scene tree, a passing test suite and a clean build are not proof that something looks right. They are proof that it was described right. Those are different, and the gap between them is where almost every "finished" UI that the user immediately calls broken lives.
The loop
implement -> launch/render -> capture the actual output -> LOOK at it
-> find defects -> fix -> render again -> look again -> only then done
The second look is not optional. See verification-before-completion: evidence
must come from the final state, so a screenshot taken before the last edit
proves nothing about what ships.
First: can you actually see pixels?
"Look at the screenshot" is the easiest instruction in this pack to fake, because the honest report and the fabricated one are the same sentence. These are two different claims and only the second supports a completion claim:
a screenshot was captured <- a file exists
the agent inspected the pixels <- a model actually read the image
Settle it once per session, with a check that cannot be bluffed:
TOOLS\Test-VisionCanary.ps1 -Word <word> -Shape <shape> -Color <colour>
Open TOOLS\vision-canary\vision-canary.png first and report what is in it. The
expected answer is stored only as a hash, so reading the repository is not a
substitute for looking.
PASS - inspect rendered output before every visual completion claim.
FAIL - that is an answer, not an error. Then:
- keep the screenshot as an artifact for the user or a capable agent;
- fall back to DOM / accessibility tree / computed styles / console / network / element geometry, which catch many of the defects below;
- say "visual verification unavailable in this provider/session" and name what remains unchecked. Never write "looks good" about pixels you did not see.
What each client can do changes with its version; test, do not assume. As
measured for this pack: Claude Code reads image files directly; codex and
codex exec accept -i/--image; grok, kimi and hermes showed no image-attach
flag in their --help. An MCP server that returns an image is only useful if
the client forwards it to the model - which the canary is how you find out.
Getting the pixels
Cheapest sufficient route, in order. Do not turn on a browser stack to check a README, and do not open a full browser when a render-to-file settles it.
| what | route |
|---|---|
| web page / app | the provider's own browser capability, else Playwright (CLI or MCP), screenshot to file |
| console errors, failed requests, computed layout | Chrome DevTools MCP - web profile |
| desktop app / EXE | launch it, screenshot the window, then close it and check it actually exited (process-lifecycle-cleanup) |
| Blender / Godot / Unity | render or capture through that engine's own capability - engine-* profiles |
| generated image or asset | open the file |
Capability profiles are per project and off by default; see
capability-profiles. Enable the one this task needs, not all of them.
What to look for
AI-written UI fails in a small number of recognisable ways. Sweep for these before anything subjective:
- overlapping or clipped elements; text overflowing its container
- content hidden behind a header, footer or fixed bar; off-screen controls
- broken, missing, wrong, stretched or low-resolution images
- blank or grey preview boxes; loading placeholders left behind
- unreadable contrast; text far too small
- modal, dropdown or tooltip positioned wrong; z-index/layering wrong
- horizontal scrollbar on the page body; layout collapse at mobile widths
- default browser or OS chrome showing where custom UI was intended
- controls that do not respond when actually clicked
- empty states that were never designed
- inconsistent spacing or visual hierarchy
- materially different from the reference design or what the user asked for
Then stop. This is a closure skill, not a design system: fix correctness, usability, obvious polish defects and the user's stated requirements. Do not drift into unbounded pixel-perfection.
Interactions, not just appearance
A screenshot proves the first frame. If the requirement includes behaviour,
exercise it: click the control, submit the form, open the menu, resize to the
breakpoints that matter - then look again. Check the console for errors and the
network panel for failed requests when something is missing rather than ugly; a
grey box is usually a failed request, not a CSS bug, and guessing at CSS is how
that one gets fixed five times without being fixed. See systematic-debugging.
Failed verification is the workflow working
Finding a defect is the point. Do not suppress it, do not weaken a check to make it pass, and do not narrate a defect you have not fixed as if it were minor. Observe, fix, render, look again.
Report honestly
State which of these you did:
- rendered and inspected the actual output (say at what size/state)
- captured output but could not inspect it (say why; keep the artifact)
- verified structurally only - DOM/CSS/scene data (say what stays unverified)
"I checked the code and it should render correctly" is not any of the three.