Give a UI-reviewing agent screens to judge against

· Maksym Lyskov

I asked an agent to review a broken settings screen with nothing to compare it to. It blocked one problem, marked four more as notes, and missed one completely. Given screenshots of two screens the app already ships, it blocked all six, and it still passed the two good screens.

I tested this on a small made-up admin app: two reference screens I was happy with, and three new screens to review.

The test

The app is a booking admin. It has a sidebar, a page title with a solid blue Save button top right, and white cards. Each card opens with a bold heading and one grey line of help text. I took screenshots of two of its screens, a customer list and a booking settings page, and used them as the references.

Then I built three new settings screens:

  • Gift cards follows the house style: same header, same Save, same cards.
  • Notifications follows it too.
  • Waivers breaks it the way a rushed change does. It has two stacked titles, Settings in dark text with Waiver settings in blue under it. Save is at the bottom left, grey, and looks disabled, with Reset and Cancel next to it. Neither card has a heading. One field reads “365” with no unit.

Each screen went to Claude Code in headless mode (claude -p) with only the Read tool, once with each of two prompts.

Prompt A, no references:

You review UI changes for a booking admin app before they merge.
Read the screenshot cands/waivers.png. List every problem you see,
one per line, each marked BLOCKING (must be fixed before merge) or
NOTE (fine to ship). End with one line: BLOCKING: <count>

Prompt B, with references:

You review UI changes for a booking admin app before they merge.
These are screens the app already ships and the team is happy with:
refs/ref-list.png and refs/ref-settings.png. Read them first, then
read the screenshot cands/waivers.png and judge it against them.
Mark a finding BLOCKING only when the screen does something
differently from how the reference screens do the same thing, with
no reason visible on the screen, or when it would make a user do the
wrong thing. Everything else is a NOTE.
List each finding on one line with its mark. End with one line:
BLOCKING: <count>

What came back

Screen Prompt A (no references) Prompt B (references)
Gift cards 0 blocking 0 blocking
Notifications 0 blocking 0 blocking
Waivers 1 blocking 6 blocking

Each cell is one run.

Without references, the one blocker was the missing unit on “365”. The reviewer noticed the grey Save button, the missing card headings, the blue subtitle and Reset sitting next to Save. It filed every one of them as a NOTE. It never mentioned that Save had moved from the top right to the bottom left, because with nothing to compare against, nothing says Save can’t sit at the bottom left.

With the references, it blocked six things: the second title level, the Save position, the grey Save, Reset and Cancel, the missing card headings, and the missing unit. Each line said what the reference does and what this screen does instead: “both references put the main action in the top-right of the header. Here Save sits at the bottom-left, below the cards.”

The good screens stayed at zero both times, but the notes changed. Without references, the reviewer said the grey dropdowns on Notifications looked disabled. Fair enough as an opinion, but every dropdown in the app looks like that. With references, it saw the same grey dropdowns on the approved settings page and called them consistent.

Picking the references

Use screens you already ship and like. Don’t use mockups or the design-system page. They show what the app was meant to look like, and users only ever see what shipped.

Cover the screen types you build: a list, a settings page, a dialog, and the phone width if you have one. I used two in the test. I’d add a dialog and a phone screen next. A settings change gets judged against the settings reference, and a new dialog against the dialog one.

Keep a screenshot of each type in the repo next to the review prompt, and update it when a screen you like changes. If you forget to update one, the reviewer will block the change you just approved.

Write the severity rule down

Prompt B changes two things: it adds the references, and it says what counts as blocking. Keep both. Without the rule, the model is free to block on any best-practice opinion it has.

The rule I use has three cases:

  1. It matches how the references do it → fine.
  2. The screen departs from the references with no reason you can see on screen, or it would make a user do the wrong thing → blocking.
  3. Everything else → a note.

A screen type you have no reference for gets judged against the closest one you do have. A new detail page gets compared with the list or settings page next to it.

References from another product are inspiration only

Screenshots of another company’s admin product are tempting as a second reference set. An agent holds new screens to whatever reference it gets, so the reviewer starts asking for that product’s layout, and an agent that builds screens starts copying it. Pages pick up saved views, a headline number with a percent change and a record timeline, none of which they have any use for.

If you keep an outside set, say so in both prompts in one sentence: these screenshots are ideas to borrow from, and no screen is judged against them. If you like something from it, build it into one of your own screens. Then it’s a reference.

Keep a few screens to re-test the prompt

You can reuse that table as a test suite. Keep two or three screens you approved and two or three you sent back, each with what was wrong. Whenever you change the review prompt or the references, run it on all of them. Approved screens should come back with zero blockers, and rejected ones should come back blocked for the reason you gave.

If a screen you approved starts getting blockers, the prompt is judging taste again. If a bad one gets through, check that your references show the thing it got wrong.

If you already have an agent reviewing UI, take your next screen change and run it twice: once as it is, once with two or three of your best screens in the prompt and the blocking rule above. Compare the two lists.