AI-written UI can pass review yet break at 320px, in empty and error states, and by keyboard. Five checks to run before you merge.
If the UI your AI agent wrote looks fine in the diff but breaks in the browser, the diff was the wrong place to judge it. Layout, states, keyboard behavior and accessible names are hard to judge from the text of a diff and show up when the page runs, so run a short set of checks: a narrow screen, empty and failing data, a keyboard with no mouse, an accessibility scan, and a person for what a scan cannot judge.
Disclosure: we build TLM Forge, a process layer for Claude Code, so weigh the product section accordingly. Most of this post applies with or without us.
Why a clean diff proves so little about UI
A diff shows what changed in the text. What a page does depends on things the diff does not contain: the viewport, the data the server returns, and the input device. A flex row that reads fine in code breaks at 320 pixels. A list component looks finished until the list is empty. A button looks right until someone tries to reach it without a mouse.
One GitHub feature request, filed by a single user in December 2025, says that on frontend work Claude Code "operates blind": it can read and write CSS, HTML and JSX but "cannot see the rendered result". That is one person's account, not a measurement. It matches Anthropic's best-practices page, which says "Claude stops when the work looks done" and that without a check that comes back pass or fail, "that makes you the test suite". The page names a "browser screenshot next to the mockup" as one such check, and says /verify, which has Claude build and run the app and look at the result, "catches the kind of problem that tests and typechecks miss". The broader failure of agents declaring victory early is covered in Claude Code Said It's Done. It Wasn't..
Sources: anthropics/claude-code issue 13762, Claude Code docs: Best practices
What the research measured, and what it cannot tell you
Layout failures follow screen size
A cross-environment study of AI-generated webpages (Guo et al., on arXiv) built pages from reference screenshots with eight generators, including Cursor and v0, and rendered them in nine browser and device combinations. Of the 203 generated pages it analyzed, 139 (68 percent) had at least one compatibility issue. Human-written pages under the same setup failed 24 times in 60 (40 percent). The failures followed screen size: 67.5 percent of generated pages failed only when moved from a desktop to a phone-sized viewport, and 1.0 percent failed only across browsers. Among the failing pages, 46.0 percent had a missing or misused viewport meta tag and 29.5 percent had flex or grid containers without wrapping, even though a keyword scan found at least one responsive construct, such as flex, grid or a Tailwind breakpoint prefix, in 97.5 percent of the generated instances.
Sources: Guo et al., Does It Render Everywhere? (arXiv 2608.12518)
What this cannot tell you: the pages were single static HTML files built from screenshots, with layouts that depend on interactive behavior, such as collapsible menus, filtered out. They were not features an agent built inside your app with a browser to hand, and the tools are the ones the paper names, not Claude Code. The human baseline failed 40 percent of the time, so this is hard for people too.
Sources: Guo et al., Does It Render Everywhere? (arXiv 2608.12518)
Accessibility failures hide in attributes that say nothing
A CHI extended abstract (Calò, Gurita and De Russis) analyzed 300 interfaces generated by three frontier models, named in the paper as claude-sonnet-4, gemini-2.5-flash and gpt-4o. LLM judges flagged 541 semantic accessibility violations, nearly two per interface, led by generic button labels (27 percent) and vague link text (26 percent), then poor alt text (20 percent). The point is that an image with alt="image" passes automated checks and tells a screen reader user nothing. The human validation was small, and the authors call it preliminary. A separate comparison of GPT-4o and Qwen2.5-Coder-32B against human-written code found the models often did better on basics such as color contrast and alt text, but struggled with ARIA attributes. Both tested the models they name, so results for yours may differ.
Sources: Calò, Gurita and De Russis, Measuring the Semantic Accessibility Gap in LLM-Generated Web UIs (CHI Extended Abstracts), Suh et al., Human or LLM? A Comparative Study on Accessible Code Generation Capability (arXiv 2503.15885)
People fail these checks too, and scans see only part
WebAIM's annual Million report, in its February 2026 scan of the top one million home pages, detected WCAG 2 failures on 95.9 percent of them, averaging 56.1 errors per page. Low contrast text (83.9 percent of pages), missing alt text (53.1) and missing form labels (51) led. Pages using ARIA averaged 59.1 detected errors against 42 without it, though the report cautions that this does not necessarily mean ARIA caused them, since those pages were also more complex.
Sources: WebAIM: The WebAIM Million
Deque's analysis of more than 13,000 pages and page states and nearly 300,000 issues found that 57.38 percent were identified by automated tests built on axe-core. That is a vendor's own data and it counts by volume: contrast alone is about 30 percent of the issues in its table. Playwright's accessibility guide says "many accessibility problems can only be discovered through manual testing".
Sources: Deque: The Automated Accessibility Coverage Report, Playwright docs: Accessibility testing
Five checks that catch what the diff hides
Each check can be scripted and each leaves a step for a person. The snippets use Playwright, which Claude Code can run from the terminal like any test command.
1. A narrow window and a device profile
WCAG 2.2 criterion 1.4.10, Reflow, asks that content work without scrolling in two dimensions at a width equivalent to 320 CSS pixels, with exceptions such as maps and data tables. In a test, call page.setViewportSize({ width: 320, height: 640 }) and check document.documentElement.scrollWidth > document.documentElement.clientWidth. True means overflow. If it fails, look first at display: flex rows: MDN says the default flex-wrap: nowrap keeps items on a single line that may overflow the container.
Sources: W3C: Web Content Accessibility Guidelines (WCAG) 2.2, MDN: flex-wrap
A desktop window may not exercise the viewport tag. Under Playwright's devices['iPhone 13'] profile, a page we built without the tag reported a window.innerWidth of 980. With <meta name="viewport" content="width=device-width">, the form MDN shows, it reported 390, in both Chromium and WebKit. Run the overflow check in a 320 pixel desktop window and under a device profile, and assert that innerWidth does not exceed the device width.
Sources: MDN: meta name viewport, Playwright docs: Emulation
2. Every state, not only the one where data arrives
The diff usually shows the path where data comes back fine. Check an empty list, a failed request, a slow response and content longer than the example. Playwright's network docs show route.fulfill for answering an endpoint: use route.fulfill({ json: [] }) for empty and route.fulfill({ status: 500, body: 'boom' }) for failure, and wait inside the handler before route.continue() for slow.
Sources: Playwright docs: Network, Playwright docs: Route
Assert something a user could see or hear: a message for the empty list, role="alert" for the failure and role="status" for loading. WCAG 4.1.3, Status Messages, says status messages must be programmatically determinable through role or properties, so assistive technologies can present them without receiving focus.
Sources: W3C: Web Content Accessibility Guidelines (WCAG) 2.2
3. A pass with only the keyboard
Press Tab from the top and watch. WCAG 2.1.1 requires all functionality to be operable through a keyboard interface, and 2.4.7 that any keyboard operable interface has a mode where the focus indicator is visible. Search generated code for outline: none with no replacement, which W3C technique F78 lists as a failure, and for click handlers on div or span. On our toy page, Tab skipped a clickable div entirely. W3C's guidance on ARIA is to use a native element when one already has the semantics and behavior you need, so use a button.
Sources: W3C: Web Content Accessibility Guidelines (WCAG) 2.2, W3C: Technique F78, W3C: Using ARIA
In a test, press Tab, assert toBeFocused() on the expected control and read its computed outline or box-shadow. That shows an indicator exists, not that a person can see it. F78 also lists outlines or borders that hide the indicator.
Sources: W3C: Technique F78
4. Names, roles and meaning
WCAG 4.1.2 requires that the name and role of interface components can be programmatically determined. An icon-only delete button with no label fails it. A role locator doubles as a name check: page.getByRole('button', { name: 'Remove card' }) finds nothing if the button has no accessible name. By default Playwright matches the name as a case-insensitive substring, so add exact: true when you mean the whole name. Playwright also says role locators "do not replace accessibility audits and conformance tests".
Sources: W3C: Web Content Accessibility Guidelines (WCAG) 2.2, Playwright docs: Locators
Meaning needs a reader. Across the 300 generated interfaces in the CHI paper, generic button labels such as "Submit" and vague links such as "Read more" were the two most common semantic faults its LLM judges flagged, and the authors note that alt="image" passes every automated check. In our own axe run (axe-core 4.14.0), a Submit button, a Click here link and an alt="image" image produced no violations. Read every generated label, link and alt string as if it were all a person could perceive.
5. An axe scan, with its limits in mind
Add @axe-core/playwright: new AxeBuilder({ page }).withTags(['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa']).analyze(), then assert that violations is an empty array. Playwright's guide uses those tags to match the WCAG A and AA rules, and notes that automated testing cannot detect all types of WCAG violations. Scans cover some failure types far better than others: in Deque's table, 83.11 percent of contrast issues were found automatically, against 54.42 percent of name, role and value issues, 2.49 percent of keyboard issues and 0 percent of focus visible issues.
Sources: Playwright docs: Accessibility testing, Deque: The Automated Accessibility Coverage Report
Keep screenshots for human eyes first. If you later turn them into toHaveScreenshot baselines, Playwright warns that rendering can vary with the host OS, settings, hardware and headless mode, and says to run tests where the baselines were generated.
Sources: Playwright docs: Visual comparisons
What the checks caught on a deliberately broken page
We built one toy page with seven planted defects and ran the checks with Playwright 1.64.1, @axe-core/playwright 4.14.0 (axe-core 4.14.0) and headless Chromium 156. It is a single hand-made page, not a benchmark. The defects: a row that overflows at 320 pixels, no viewport tag, a removed focus outline, a clickable div, an icon-only button with no name, low-contrast text, and no handling of empty, failed or slow loads.
- axe, run with the four WCAG tags, flagged two of the seven: the unnamed icon button and the low-contrast text. It did not flag the other five.
- The 320 pixel overflow check caught the row in a desktop window (scrollWidth 500 against clientWidth 320) and missed it under the iPhone 13 profile, where the page laid out at 980 pixels. The innerWidth check caught the missing tag.
- Pressing Tab moved focus to the unnamed button and then out of the document. The clickable div never took focus.
- The role locator with the expected name failed on the unnamed button, and the empty, 500 and slow mocks each failed on a page that never handled them.
- After the fixes, the whole suite passed, apart from one test that skips itself on the desktop profile.
Each tool saw a slice. The slices add up to coverage only when you run all of them and keep a person for the rest.
Which check finds what
| Check | What it catches | Automate with | Still needs a person |
|---|---|---|---|
| Narrow window | Sideways scroll, clipped content | setViewportSize at 320 and a scrollWidth check | Judging whether the layout is usable |
| Device profile | Missing viewport tag, desktop layout shrunk onto a phone | A profile such as iPhone 13 and an innerWidth check | Trying it on a real phone |
| States | Empty, failed and slow loads with nothing on screen | page.route mocks and assertions on text and roles | Deciding what each message should say |
| Keyboard | Controls Tab never reaches, focus that is not visible | Tab presses, toBeFocused, a computed outline check | Whether the order makes sense and the indicator can be seen |
| Names and meaning | Controls with no accessible name | getByRole with a specific name | Whether labels and alt text mean anything |
| Rules scan | Contrast and many attribute errors | axe through @axe-core/playwright | Everything scans miss, including a screen reader pass |
Letting the agent run the checks
- Playwright from the terminal. Claude Code runs
npx playwright testlike any test command. The best-practices page lists a test file among checks Claude can run, and says to ask for evidence: "the command it ran and its output, or the screenshot". - Claude in Chrome. The docs describe design verification, web app testing and live debugging. It needs the extension, a direct Anthropic plan and a
/loginsign-in; with an API key Claude Code keeps it off, and it is not available through providers such as Amazon Bedrock. /verify. It builds and runs the app and looks at the result. The docs warn that its inferred launch gets unreliable when a project needs a database, an env file, a graphical session or a multi-step build.- Playwright MCP. The README gives
claude mcp add playwright npx @playwright/mcp@latest. The server works through "structured accessibility snapshots, bypassing the need for screenshots or visually-tuned models" and offers--viewport-sizeand--deviceoptions. Our reading is that a snapshot of roles, names and text helps with the names check but says little about how the page looks, so ask for screenshots too.
Prompt to paste, adapted to your page: "Add Playwright checks for the /cards page in tests/ui.spec.ts. Check for no horizontal scroll at 320 pixels wide. Under the iPhone 13 profile, check that window.innerWidth does not exceed the device width. Mock the cards API three ways (empty list, status 500, slow response) and assert an empty message, an alert role and a status role appear. Tab to the remove button and assert it is focused with a visible outline, found with getByRole and its exact name. Add an axe scan with the wcag2a, wcag2aa, wcag21a and wcag21aa tags. Run npx playwright test and paste the output. Do not change application code until I have seen the failures."
Then read the output. The tests Claude writes for a page can be as hollow as any others, and How to Test AI-Generated Code Properly covers tautological and over-mocked tests, which apply here too. Add these checks to your Definition of Done for AI-Generated Code so that done for a UI change includes evidence from a browser.
A pre-merge checklist for UI changes
- No sideways scroll at 320 CSS pixels, in a desktop window and under a device profile.
- A viewport meta tag on every page template.
- Empty, failed, slow and long-content states each show something sensible.
- Tab reaches every control in order, with a visible focus indicator and no outline removed without a replacement.
- Every control, link and image has a specific accessible name or alt text, never a bare "Submit", "Click here" or "image".
- axe scan clean with the WCAG tags, remaining findings written down, and screenshots opened by a person.
Where TLM Forge fits, and where it does not
TLM Forge sizes each task Light, Medium or Deep. Light gets no review agents, so a change sized Light gets none of the reviews below. When a Medium or Deep change touches UI, a ux-reviewer joins the final review wave next to the other reviewer agents, and Deep work is verified on a real running environment. See Catch accessibility and design slips on changed screens and New features are tested on a real system, not fakes.
The limits are plain. The ux-reviewer is an LLM agent, so it can miss things, and a review wave does not replace testing on real devices or a designer's eye. The checks in this post are yours to write and run.
Frequently asked questions
01Why does AI-generated CSS work on desktop but break on mobile?
In one study of AI-generated pages, most failures appeared only when the page moved from desktop to a phone-sized viewport, not across browsers. Common causes were a missing or misused viewport meta tag, flex containers that never wrap, and hard-coded dimensions. Test at 320 CSS pixels and under a mobile device profile instead of trusting the desktop view.
02Can Claude Code check its own UI changes in a browser?
Yes, in several ways. It can run Playwright tests from the terminal, use the Claude in Chrome extension if you have a direct Anthropic plan and sign in with login, or run the verify command to build and run the app. Ask for the command output and screenshots as evidence.
03Does a clean axe scan mean AI-written UI is accessible?
No. Deque audit data found automated tests identified 57.38 percent of issues by count, and Playwright documentation says many problems can only be found by manual testing. An image with the alt text image passes a scan yet tells a screen reader user nothing. Add a keyboard pass and a screen reader pass.
04How do I test empty, error and loading states?
Intercept the API request in your test and answer it yourself: an empty list, a server error and a delayed response. Then assert what a user would see or hear, such as a message, an alert role for failures and a status role for loading. Playwright route mocking does this without changing the app.
05What should a human still check after automated UI tests pass?
Tab through the whole flow without a mouse, zoom the browser to 400 percent (WCAG treats that on a 1280 pixel window as 320 CSS pixels wide), read every label and alt text for meaning, run one screen reader pass, and open the app on a real phone. Scripts cannot judge those.