AI UI review checklist: test generated interfaces before you ship

Do not begin by clicking around and collecting impressions. First define what this review is allowed to prove. Without that contract, reviewers tend to invent requirements, treat personal taste as a defect, or accept an attractive screen whose main task never completes.

• User task: State the outcome in user terms, such as "invite a teammate and see confirmation," rather than "review the settings page."
• Product requirements: List the approved actions, permissions, data, validation rules, confirmations, cancellation behavior, and recovery paths that apply.
• Design authority: Name the exact DESIGN.md, token set, theme file, component guidance, reference kit, or approved design that governs the interface.
• Delivery artifacts: Record how those decisions reach the project, such as CSS variables, Tailwind theme values, DTCG tokens, a shadcn registry item, or generated files.
• Platforms and viewports: Include only the browsers, devices, container widths, and color modes the product supports.
• Content fixtures: Prepare realistic short, typical, long, empty, invalid, and restricted examples where relevant.
• Required states: Name the idle, loading, success, empty, error, disabled, focus, selected, open, and permission states that the task can actually reach.
• Exclusions: Record work that is outside this release so its absence is not mistaken for a defect.

A generated interface can pass one kind of review and fail another. Keep the evidence separate so a strong visual result cannot hide a broken task, and a working task cannot excuse an inaccessible or fragile implementation.

Start from the user outcome and work through every required branch. A passing test describes observable behavior, not an impression.

• The primary action is visible or discoverable at the point where the user needs it.
• Labels describe the resulting action rather than a vague intention.
• Navigation preserves the user's context where the requirement says it should.
• Validation identifies the affected field or action and gives the user a possible next step.
• Success produces the required confirmation or changed state.
• Cancellation leaves data and navigation in the expected condition.
• Permission restrictions prevent the action and explain what the user can do next.
• Loading, empty, failure, retry, and recovery paths work when they are in scope.
• Keyboard interaction can reach and operate the task controls where keyboard use is supported.

Write acceptance criteria as observations. For example: "Submitting a valid invitation disables duplicate submission, shows progress, returns a success message containing the invited address, and adds the pending member to the list." That can be checked. "The invitation flow feels intuitive" cannot.

Trace visible decisions back to the declared authority. Check semantic colors, typography roles, spacing, layout, motifs, component treatments, and mode behavior. Record unexplained values, but do not assume every difference is wrong. A local exception may be intentional, stale, or absent from the system.

• Semantic roles: Components use roles such as background, foreground, primary, border, ring, success, warning, and destructive for their intended meanings.
• Typography: Heading, body, label, data, and mono roles use the declared families, weights, sizes, line heights, and casing rules.
• Spacing: Repeated gaps follow the documented scale unless an approved exception exists.
• Layout: Page width, grid, alignment, density, and responsive transitions match the declared rules.
• Components: Buttons, inputs, cards, tables, navigation, overlays, and feedback treatments use the intended variants and states.
• Modes: Light and dark values retain the same semantic meaning, and mode-specific exceptions are documented.
• Motifs: Decorative treatments appear only where the authority permits them and do not interfere with meaning or interaction.
• Hardcoded values: One-off colors, font declarations, radii, shadows, and spacing values have a documented reason or are routed for correction.

Replace placeholder content with fixtures that stress the real layout. Review the same task across required viewports and states instead of judging separate screenshots as isolated compositions.

• Use realistic names, dates, prices, statuses, descriptions, and data density.
• Test long labels and translated-length text without changing the intended meaning.
• Check narrow and wide layouts at the supported container or viewport sizes.
• Verify wrapping, truncation, overflow, sticky regions, overlays, and scroll behavior.
• Increase zoom or user text spacing and record clipping, overlap, loss of content, or blocked controls.
• Use every declared color mode and any supported forced-color setting.
• Inspect focus, hover, active, selected, disabled, open, loading, empty, error, and success states that the task can reach.
• Repeat the task with slow or failed data where the product supports those conditions.

Forced-colors mode deserves its own observation when it is supported. Browsers may replace authored colors with a user-selected palette, so meaning that exists only in a custom fill, border, or shadow can disappear. Record what remains perceivable rather than assuming the ordinary theme predicts the result.

Use this review to identify concerns and collect evidence, but keep the claim bounded. Visual inspection, token conformance, automated checks, and AI critique can each find problems. None of them alone certifies accessibility.

• Record keyboard order, focus visibility, control operation, and focus behavior around overlays.
• Check that control names, visible labels, instructions, errors, and state changes are understandable in context.
• Verify that information is not conveyed by color or visual position alone.
• Observe reflow, zoom, and user text-spacing behavior on required surfaces.
• Test relevant content and controls in supported high-contrast or forced-color settings.
• Send semantic markup, assistive-technology behavior, contrast measurements, and formal conformance questions to the appropriate evidence-backed review track.

Choose surfaces from the product you are reviewing. A landing page may need navigation, a form, and feedback. An application may also need data views, detail views, overlays, and permission states. Omit surfaces the product does not use.

1. 1

   Select a user task

   Name one outcome and the exact start condition. Keep the task narrow enough to repeat.

2. 2

   Select a representative surface and state

   Choose the navigation, form, data view, detail view, overlay, or feedback state that carries the highest consequence or exposes a distinct system rule.

3. 3

   Apply a fixed fixture

   Record the viewport, mode, content, account or permission state, and data condition. Reuse that fixture after changes.

4. 4

   Write the expected result before inspection

   Cite the requirement or design rule and describe the observable result. If no authority exists, stop and route the gap.

5. 5

   Capture the observation and evidence

   Record what happened, where it happened, and the smallest screenshot, recording, DOM observation, console output, or test result needed to reproduce it.

6. 6

   Assign severity, owner, and disposition

   Choose pass, revise, or block. Route the cause to the correct layer instead of assigning every issue to the generated implementation.

Review ID: UI-REVIEW-____
Build or revision: ____
Reviewer: ____
Date: ____

User task: ____
Start condition: ____
Required outcome: ____
Surface: ____
Required state: ____
Viewport or container: ____
Color mode: ____
Input and content fixture: ____
Permission or account fixture: ____

Requirement authority: ____
Design-system authority: ____
Delivery artifact: ____
Expected rule or behavior: ____
Observed result: ____
Evidence reference: ____

Evidence track:
  - task completeness: pass | fail | not tested
  - design-system conformance: pass | fail | not tested
  - resilience: pass | fail | not tested
  - accessibility: pass | concern | not tested

Finding route: requirement | design system | delivery mapping | implementation | fixture
Severity: low | medium | high | release blocking
Owner of next decision: ____
Known limitation: ____
Disposition: pass | revise | block
Retest required: yes | no
Retest result: ____

A visible defect is often downstream of the place that needs to change. Fixing the nearest CSS rule may make one screen pass while preserving the same failure for the next generation.

• Product-requirement gap: The intended behavior, permission, content rule, confirmation, cancellation, or recovery path is missing or contradictory. Example: nobody has decided whether removing a member needs confirmation. Next owner: product decision maker.
• Design-system-source gap: The requirement is clear, but the authoritative system lacks a role or rule needed to express it consistently. Example: warning and destructive actions have no distinct documented treatment. Next owner: design-system owner.
• Delivery or mapping gap: The source contains the correct decision, but the exported token, framework mapping, registry item, theme file, or installed artifact loses or misassigns it. Example: the source defines a focus ring role, but the delivered theme maps the component to a border role. Next owner: artifact or integration owner.
• Generated implementation defect: Requirements and delivered rules are sufficient, but the generated interface ignores, overrides, or incorrectly implements them. Example: a button hardcodes a color instead of using the delivered destructive role. Next owner: implementation owner or coding agent operator.
• Invalid review fixture: The expectation uses unsupported data, an excluded platform, the wrong account state, a stale build, or a surface outside the release contract. Example: a reviewer expects an admin action while testing a read-only account. Next owner: reviewer or test owner.

If more than one layer contributed, name the earliest authoritative failure as the primary route and list downstream defects separately. That prevents a local patch from hiding a missing decision.

Inspection shows whether the current snapshot looks connected to its system. A controlled change tests whether that connection still works. Change one bounded decision in the declared authority, propagate it through the normal delivery route, and check both the intended update and unrelated values.

1. 1

   Choose one semantic decision

   Use a reversible, tightly scoped role such as the warning background, focus ring, heading weight, or compact spacing step. Do not combine several edits.

2. 2

   Record the before state

   Capture the authoritative value, delivered value, intended consumers, representative fixture, and a few nearby values that must remain unchanged.

3. 3

   Change the declared authority

   Make the change where the team says the decision belongs. Editing the rendered component directly does not test propagation.

4. 4

   Run the normal delivery path

   Regenerate, export, install, or apply the artifact in the same way the project normally receives design decisions.

5. 5

   Verify the chain

   Confirm that the authority, delivery artifact, and intended interface consumer contain the new decision.

6. 6

   Check for unrelated drift

   Compare the recorded neighboring roles and representative surfaces. Any unexplained change fails the test even if the target changed correctly.

7. 7

   Restore or approve the test value

   Treat the change as a test unless the responsible owner approves it as the new design decision. Record the final state in the review.

• Pass: Every required task and representative state meets its observable criteria; conformance differences are explained; required resilience checks have evidence; accessibility limitations are explicit; no unresolved release-blocking finding remains.
• Revise: The authority is clear and the defect is bounded, reproducible, owned, and safe to retest before release. The record names the failing fixture and expected result.
• Block: A required task fails; a destructive or irreversible action behaves ambiguously; permissions are wrong; recovery is unavailable where required; the governing requirement or design authority is unresolved; evidence is missing for a release-critical state; or the controlled change reveals broken propagation or unrelated drift.

Severity should describe consequence, not visual prominence. A subtle permission error can block release. A conspicuous spacing mismatch may be low severity if it does not impair the task and the design owner accepts it.

Identity Forge can provide declared inputs for this process: semantic light and dark color tokens, typography, spacing and layout guidance, motifs, usage rules, DESIGN.md, and delivery formats such as Tailwind, DTCG, and shadcn-oriented artifacts. These inputs reduce ambiguity when you ask whether generated UI follows a chosen system.

They do not supply product requirements, finished component behavior, a completed UI audit, or proof that an interface is accessible or ready for production. They also do not decide whether a difference is an approved exception. That judgment remains with the people responsible for the product, design system, implementation, and release.

If a project has no declared design authority, establish one before claiming conformance. The related guides on design systems for AI coding agents, DESIGN.md, and semantic color tokens explain possible inputs. The review method itself remains tool-independent.

• The reviewed user task, start condition, and required outcome are written down.
• Requirements and design-system authorities are named and versioned or otherwise identifiable.
• Delivery artifacts and supported platforms are recorded.
• Representative content, permissions, modes, viewports, and required states are fixed.
• Primary, cancellation, confirmation, error, and recovery paths pass where required.
• Semantic colors, typography, spacing, layout, component treatments, motifs, and modes trace to the declared authority or an approved exception.
• Long content, narrow layouts, zoom or text spacing, keyboard operation, and relevant non-default states have evidence.
• Accessibility concerns and untested areas are explicit; no visual or AI review is presented as certification.
• Each finding is routed to requirements, the design-system source, delivery mapping, implementation, or fixture.
• One controlled authoritative change reaches its intended artifact and consumer without unrelated drift.
• Every unresolved issue has severity, an owner of the next decision, and a retest condition.
• The release record ends with pass, revise, or block rather than a vague approval comment.

For the next review, choose one release-critical task and complete the record before inspecting the rest of the interface. If the expected behavior or design authority cannot be named, stop there and route that gap. More screenshots will not resolve a missing decision.

• 7-point checklist to review any AI-generated UI: The captured article explains that polished AI-generated screens can conceal weak logic and missing product decisions, so visual finish should not be treated as readiness.
• AI Generated UI Quality Checklist: The checklist recommends reviewing hierarchy, system consistency, real content, responsive behavior, mobile layouts, and non-default states before shipping generated UI.
• AI design review assistant for modern designers: Figma presents design review as a contextual feedback and iteration workflow, including reviews of selected frames, components, and flows.
• A pre-ship design review checklist for AI-generated UI: The captured article separates mechanically checkable problems from qualitative design review and covers palette, typography, layout, spacing, states, focus, and motion.
• forced-colors CSS media feature: MDN documents that forced-colors mode lets the browser impose a user-selected color palette and can alter several CSS color-related properties.
• Identity Forge: Identity Forge provides design kits with semantic tokens, typography, layout rules, DESIGN.md guidance, and delivery routes for coding-agent workflows.
• How to generate a DESIGN.md (and what it is): A DESIGN.md can document design intent, color and type systems, layout and spacing rules, component treatments, motifs, and explicit usage constraints for a coding agent.
• Semantic color tokens explained: Semantic color tokens name colors by their interface roles and allow components to refer to stable roles across light and dark themes.
• Shadcn design system generators: do you need a theme, a system, or an agent handoff?: The article distinguishes a visual theme from a broader design system and recommends inspecting token meaning, component mappings, typography, layout guidance, installation routes, and known gaps.