AI coding agents struggle with visual consistency because each decision is made locally, with partial context, by a process that can’t see its own output unless you give it a way to. A single screen often comes out fine. The tenth screen, built in a different session from a slightly different prompt, uses a new shade of grey, its own card and a spacing value that isn’t on the scale. None of that is a lack of capability. It follows from how agents work, which means each cause has a matching fix.
Consistency is a whole-product property
Consistency isn’t visible in any one file. It lives in the relationship between screens: the same thing looks the same everywhere, and different things look deliberately different. An agent works through files and tasks. Unless something carries the relationships into each task, every task is a fresh, reasonable guess.
1. Every session starts from zero
Claude Code’s memory documentation is direct about it: each session begins with a fresh context window. What carries over is what you wrote down (instruction files such as CLAUDE.md) and, in Claude Code, notes the agent saves to auto memory. The corrections you gave in chat last Tuesday aren’t there. So the second session re-derives the design from the code it happens to read, and lands somewhere slightly different.
Fix: make direction persistent. The mechanics for Claude Code are in how to keep UI consistent across Claude Code sessions.
2. Long sessions forget, too
Within a session, context fills up. Claude Code’s best practices note that performance degrades as it fills, and that Claude may start “forgetting” earlier instructions. When a session compacts, the conversation is summarised: instructions in the project’s CLAUDE.md are re-read from disk, but a design decision made only in chat survives only if the summary kept it.
Fix: keep sessions to one task, and write anything that must survive into a file, not a message.
3. The agent defaults to the most likely answer
Without specific direction, models choose the most common pattern. Anthropic calls this distributional convergence. For one screen that produces something generic. Across many screens, the “most likely” answer also shifts with the wording of each prompt, so screens are generic in slightly different ways. We cover the generic part in why AI-generated interfaces look generic.
Fix: give it a point of view that doesn’t depend on the prompt: written principles and annotated references.
4. Vague words mean different things each time
“Clean”, “modern” and “premium” don’t specify anything. Each time an agent reads them it resolves them afresh, and it has no reason to resolve them the same way twice. Two people prompting the same agent with the same adjective will get two products.
Fix: replace adjectives with decisions (“secondary text is one weight lighter, not smaller”) and with references that show the quality you mean.
5. The system is optional unless it’s enforced
Styling tools make it easy to step outside a scale. Tailwind, for example, supports arbitrary values such as p-[13px], which is useful and also exactly how a scale erodes. An agent that wants a specific look will reach for the value that produces it, unless the instructions and a check say otherwise.
Fix: tokens the agent is told to use, a lint rule or review step that catches arbitrary values, and a component library it can find. See design tokens for AI coding agents.
6. Searching is cheaper than knowing
An agent finds existing components by searching the code. If the right component has an unexpected name, lives somewhere unusual or isn’t mentioned in the instructions, the agent may not find it, and building a new one is quicker than looking harder. That’s how products end up with three cards and two modals.
Fix: name the components and where they live in the instruction file, or expose them through a component server such as Storybook’s; see how to make Claude Code follow your design system.
7. It can’t see what it built
An agent writes code. Unless it opens the result in a browser, it judges the interface from the code alone, and visual inconsistencies are much easier to see than to read. Claude Code’s best practices make the general point: without a check it can run, “looks done” is the only signal available.
Fix: give the agent a browser and ask it to compare its screenshot against an existing screen, not just against the prompt. A repeatable version is in visual testing with Claude Code and Playwright.
Why it compounds
Each inconsistency becomes context for the next task. An agent that reads a file with an off-scale value and a one-off card has learned that both are acceptable here. Drift is self-reinforcing, which is why catching it early is cheaper than fixing it later. If it’s already happened, start with a design drift audit.
What actually helps
- Persistent direction: instruction files, principles and references that load every session.
- A narrow system: tokens and components that are easy to find and awkward to bypass.
- Specific language: decisions and references instead of adjectives.
- Visual checks: screenshots compared against the product, not only the prompt.
- Corrections that stick: when you correct the same thing twice, write it down.
For the team version of this, with several people and agents on one product, see how to keep AI coding agents consistent across a product.
Direction that outlives the session
The first, third and fourth causes come down to the same gap: the product’s direction isn’t anywhere the agent can read it. Attuna keeps it in one place. In Attuna, in private beta, a project holds the brief, rules to prefer or avoid, and annotated references, and every agent that connects over MCP reads the same project, in every session.