Design Systems

Why AI agents make ugly UI

Most bad AI-generated interfaces come from missing visual context, not weak code generation.

April 25, 20267 min read

Generic in, generic out

AI coding agents generate UI by drawing on patterns learned during training. When a model is trained on millions of open-source React components and Tailwind-based interfaces, it learns the statistical center of that distribution: the most common card margin, the most common button color, the most common heading size, the most common empty state message. These defaults are not wrong — they represent correct, functional UI patterns. But they are generic by definition. They reflect what most products do, not what your product should do. When you ask an agent to build a dashboard without giving it your design system, it builds the most average version of a dashboard it knows. When you ask for a settings page without a visual spec, you get the most common settings page layout. The output is correct but interchangeable — it could belong to any product, which means it belongs to none of them.

The five root causes of ugly AI UI

Five specific causes account for most bad AI-generated UI. First: no color context. The agent uses safe neutrals and a generic accent color because it has no product color information. Second: no spacing rhythm. The padding and margin values are internally consistent within a single component but arbitrary across the product — 16px in one card, 20px in another, 14px somewhere else — because there is no spacing scale in the context. Third: no hierarchy signal. Without a type scale, heading sizes are guessed rather than calculated, producing inconsistent visual weight across pages. Fourth: no density instruction. The agent defaults to a comfortable medium density that is right for consumer apps but wrong for data tools or operational products. Fifth: no state design. Empty states, loading states, and error states are afterthoughts — either missing or filled with placeholder copy — because the agent had no specification for how those states should look.

Missing hierarchy

Visual hierarchy is the invisible structure that makes a page easy to scan. When AI-generated UI lacks hierarchy, it typically fails in three predictable ways. The first is heading parity: every heading on the page has the same visual weight because the agent did not have a type scale that distinguishes h1 from h2 from h3. The result is a page that feels flat and hard to navigate. The second is action parity: multiple buttons on the same screen have similar visual prominence, so the user cannot tell which action is primary and which is secondary. The third is density inconsistency: some sections have too much padding relative to others, creating a visual rhythm that is uneven rather than intentional. All three of these hierarchy failures can be addressed with a type scale, a button hierarchy rule, and a spacing system in DESIGN.md. The agent does not fail at hierarchy because it lacks the capability — it fails because it was not given the information.

The pattern repetition problem

A subtler cause of poor AI-generated UI is pattern repetition without purpose. Agents tend to reuse the patterns they applied most recently in a session. If a session starts with a marketing-style hero section, subsequent pages may inherit hero-like patterns: large headings, centered layouts, background fills, and decorative spacing. If the session starts with a dense data table, subsequent components may inherit table-like density even in contexts where a lighter layout would be more appropriate. This pattern repetition is not intentional; it is a side effect of the agent using recent context as its design reference. DESIGN.md breaks this cycle by giving the agent a stable visual reference that is independent of what was built most recently. Instead of inheriting patterns from the last component, the agent can check the spec and apply the appropriate pattern for each new surface.

Fix

The fix for ugly AI-generated UI is not to write a longer prompt or to complain more specifically about what looks wrong. The fix is to give the agent a DESIGN.md file before the first line of UI code is generated. A DESIGN.md that takes two hours to write will save dozens of follow-up correction sessions over the life of the project. The file should answer the five questions that address the five root causes: what are the colors and what do they mean, what is the spacing system, what is the type scale, what is the appropriate density for this product surface, and what do empty states and error states look like. Include screenshots or links to visual references where abstract rules are hard to express in text alone. Ask the agent to summarize the design constraints before building to surface any rules it found ambiguous. That pre-build step is where misinterpretations are caught cheaply before they become implemented components.

Building lasting visual memory

A one-time DESIGN.md is useful. A maintained DESIGN.md is powerful. The goal is not to write a perfect spec once but to grow a reliable visual memory that reflects the product as it evolves. Every time an AI agent generates UI that requires a correction, ask: was this because a rule was missing, or because a rule was unclear? If the rule was missing, add it. If it was unclear, rewrite it with more specific values. Over time, the file accumulates the exact set of rules that prevent the mistakes that actually happen in this specific codebase. After three to six months of maintenance, agents working with a well-maintained DESIGN.md will produce UI that requires only product-level review rather than visual cleanup. That is the end state: generated code that is architecturally correct and visually consistent, leaving reviewers to focus on whether the product behavior is right rather than whether the spacing is off.

Use DESIGN.md with a real product reference

Browse curated DESIGN.md examples from product teams, design systems, developer tools, SaaS dashboards, and AI-native apps. Use them as references before your agent builds the next screen.

Browse directory Submit DESIGN.md

Related guides

Design Systems7 min read