The Screenshot Is the Spec
A field note on turning a code-correct interactive explainer into a visually clear training asset by pairing a developer pass with a UX review pass.
The page improved only after visual review rejected what automated checks accepted.
A developer agent made focused changes. A UX reviewer judged rendered screenshots.
If the visual flow is the product, screenshots are not decoration. They are proof.
The situation
The page worked in code, but the diagram did not explain the idea.
A team had built an interactive training document from a technical concept. The page had hover states, motion, responsive layout, and recreated diagrams. The first technical checks passed: the page loaded, the text did not overflow, and the interactions fired.
But the important thing was still wrong. The main diagram looked like separate boxes placed over animated lines. The code had a map. The reader did not have a clear flow.
What looked fine to the code
- The HTML rendered.
- The hover state changed text.
- The desktop layout avoided obvious overflow.
- The mobile layout kept elements inside the viewport.
What looked wrong to a human
- The flow lines felt decorative instead of directional.
- The hover panel crowded the diagram.
- The key node did not feel meaningfully more important.
- Mobile spacing made separate boxes feel connected in the wrong way.
The misconception
Passing layout checks does not mean the design is communicating.
A browser can tell you whether text overflowed. It cannot tell you whether a diagram feels like an explanation. That difference matters for AI-generated interfaces because the model often knows where every element should go in code, while missing what the eye actually reads first.
The fix was not to ask for a prettier page. The fix was to make the review loop judge the rendered artifact, not the intention behind it.
The loop
We split the work into maker and checker roles.
-
Capture the actual screen
The review started from screenshots of the rendered page. This kept the critique anchored to what a reader would see.
-
Reject by visual defect, not preference
The UX pass named concrete defects: crowded hover treatment, weak directional flow, unclear hierarchy, and mobile node collision.
-
Make one focused developer pass
The developer pass changed the diagram structure, reduced arrow noise, made the primary node stronger, and moved the hover information out of the visual path.
-
Render again before claiming done
The page was checked again on desktop and mobile. The reviewer approved only after the screenshots matched the intended explanation.
Before and after
The workflow changed the definition of done.
Before
The page loads. The hover works. No text overflow appears. Therefore the diagram is acceptable.
This is a code-centered standard. It catches broken implementation, but it misses weak communication.
After
The screenshot shows the flow. The reviewer can name the hierarchy. Mobile keeps separate ideas separate. Therefore the diagram is teaching.
This is an operator-centered standard. It treats the rendered artifact as the thing the audience will actually use.
The reusable system
Use this loop for any AI-generated interface where meaning is visual.
1. Define the visual job
Name what the page must make obvious: flow, priority, status, ownership, risk, or next action.
2. Generate the first version
Let the developer role build the page, but do not let it mark the page done by itself.
3. Review screenshots
Use rendered desktop and mobile screenshots as the review surface. Do not review only the source.
4. Reject with acceptance criteria
The checker should name the visual defect and the condition that would prove it fixed.
5. Limit the loop
Keep the loop bounded. Three focused passes is usually enough to separate real defects from taste drift.
6. Save the rule
When a failure repeats, turn the fix into a reusable QA rule so the team does not rediscover it next week.
What this teaches
AI interface work needs two kinds of evidence.
The first kind is technical evidence: the page loads, the controls work, and the layout does not break. The second kind is human evidence: the screenshot communicates the concept without someone explaining the code behind it.
Most teams stop after the first kind. The better standard is simple: when the page is supposed to teach, the screenshot has to teach too.