The design problem is not that an AI coding agent cannot produce an attractive section. It is that each section can be attractive for a different reason. One gets a new radius, another invents a tighter type scale, and a third solves spacing with values that appear nowhere else. The page looks assembled rather than directed.
Asking for “more polish” usually makes the drift worse. The agent needs a smaller decision space, not more permission to decorate.
Visual drift starts as an information problem
A coding agent sees the files, prompt, and context available to the current task. If the repository has a clear design system, it can reuse concrete decisions. If those decisions exist only in a designer’s memory or scattered screenshots, the agent has to infer them.
Inference is local. The agent may inspect the nearest card and reproduce it accurately while missing the broader rule that separates editorial cards from pricing cards. It may create a fluid headline that works on the current screen but competes with the established heading hierarchy elsewhere.
The result is not random. It is the predictable output of incomplete constraints.
Audit the system before the screens
Do not begin by collecting every small visual mismatch. First identify whether the project has one source of truth for each layer:
- color roles, including text, surfaces, borders, action, success, and focus;
- typography roles and their responsive behavior;
- spacing rhythm and container widths;
- radii, borders, and shadows;
- button, link, form, table, and disclosure states;
- common page compositions;
- image treatment and icon rules;
- reduced-motion and forced-color behavior.
A token list alone is not a design system. Tokens provide ingredients. Components and compositions show how those ingredients form recognizable interface patterns.
In the Brief & Ship marketing-site example, the editorial layer did not introduce another palette. It reused the existing Carbon, Linen, lavender action color, Open Runde typeface, border weights, pill controls, and reading measure. The new work was primarily compositional: article headers, a contents rail, source lists, related cards, and a restrained CTA.
Give tokens semantic jobs
Raw values make reuse possible. Semantic roles make reuse likely.
An agent choosing between #6b6c75 and #6f707a has no reason to understand why one should carry secondary body text and the other should carry compact metadata. Names such as --text-muted and --text-quiet explain purpose, especially when the documentation includes contrast requirements and examples.
The same applies to spacing. A catalog of numeric increments does not explain section rhythm, card padding, or the distance between a heading and its deck. Record both the scale and the common compositions.
Semantic tokens do not mean a new variable for every component. That creates a brittle translation layer. Keep the set small enough that a reviewer can see when the agent is using the wrong role.
Turn recurring layouts into compositions
Agents drift when every page begins from an empty component. Create stable compositions for the patterns the site actually repeats:
- a marketing section with eyebrow, heading, deck, and content;
- a reading layout with article measure and optional rail;
- a hub introduction with category context and featured paths;
- a comparison table with preserved header semantics;
- a related-content group;
- a contextual product transition.
These are not rigid page templates. They are structural starting points. The visible content can vary in density, heading rhythm, tables, examples, and narrative while alignment and spacing remain coherent.
Do not create a component for a pattern that has occurred once and may never repeat. Premature primitives add vocabulary without reducing decisions.
Scope the agent’s design brief
A useful design instruction names both the allowed materials and the review objective:
- Reuse tokens from `src/styles/global.css`.
- Extend the existing hairline card treatment; do not add another shadow scale.
- Keep article text within the established reading measure.
- Preserve table headers on narrow screens. Horizontal scrolling is acceptable.
- Do not add a client framework for presentation-only behavior.
- Show any new token or primitive explicitly in the final diff summary.
That final line matters. Novel decisions deserve attention. If the agent adds a color, breakpoint, radius, or animation, the reviewer should not have to discover it while scanning a large stylesheet.
The AGENTS.md website guide explains where these instructions belong and how to route deeper design documentation without turning the root file into an encyclopedia.
Review at three distances
Component review catches optical alignment, focus treatment, wrapping, and state behavior. Page review catches hierarchy, repetition, pacing, and responsive composition. Site review catches cross-route drift: two different card languages, inconsistent navigation, changing container widths, or calls to action that do not share a recognizable family.
Run all three. A screenshot of one viewport cannot cover them.
For an agency, this review model supports handoff and margin control. A clear system reduces the number of subjective fixes that return late in delivery. The agency workflow treats that consistency as an operating concern, not just a designer preference.
Do not confuse sameness with coherence
A coherent site still needs variation. A research page should not read like a pricing page. A technical guide may need code, while an audience page may work through commercial scenarios. The system should keep typography, spacing, interaction, and brand decisions recognizable while allowing the composition to serve the job.
This is where generic “SEO templates” fail. They standardize the visible article so aggressively that every topic inherits the same rhythm and persuasion pattern. Brief & Ship uses one editorial shell but varies structure and voice by content family.
Responsive behavior is part of the design language
Desktop consistency can hide mobile improvisation. An agent may preserve colors and radii while inventing a different collapse strategy in every section. One grid wraps, another turns into a carousel, a table loses its headers, and navigation disappears to make the header fit.
Document responsive behavior at the level of content priority:
- which groups become one column;
- which information may scroll horizontally;
- which controls remain visible;
- how reading order changes;
- where text is allowed to wrap;
- which decorative elements can disappear;
- how target size and focus visibility hold up on touch screens.
Avoid device-name breakpoints in the instructions. A rule such as “switch when the content no longer fits at the minimum readable width” survives new screens better than “tablet layout at 768 pixels.” The implementation can still use a fixed breakpoint once the design has established why it exists.
Tables deserve special restraint. Replacing headers with generated CSS labels may look elegant and still weaken semantic associations for assistive technology. Horizontal scrolling is often the more honest mobile behavior for a dense comparison, provided the region remains operable and the header cells stay in the document.
Include states, not just static surfaces
Design drift often appears after the default screenshot: focus rings, hover treatment, open disclosures, validation messages, disabled controls, long labels, empty results, and reduced motion. If the system documents only pristine cards and buttons, an agent will invent the rest under deadline pressure.
For each interactive primitive, define the states that actually exist and the browser behavior to preserve. A link needs a recognizable focus state and readable visited behavior where history matters. A disclosure should use native semantics unless custom interaction has earned its complexity. A disabled purchase control should explain what the user can do next instead of looking active and refusing input.
Accessibility belongs inside this state model. Contrast tokens, focus colors, motion preferences, table semantics, and error association are design decisions with technical consequences. They should not appear as a final audit layer after the page has already established incompatible patterns.
Use an acceptance checklist that exposes novelty
Before merging a design change, review these questions:
- Did the change add a color, type role, radius, shadow, breakpoint, or motion pattern?
- Could an existing component or composition carry the requirement without a new variant?
- Does the page preserve hierarchy at narrow, wide, zoomed, and text-expanded states?
- Are interactive states and keyboard focus visible against every surface used?
- Does the component still make sense with real long content rather than a short placeholder?
- Is the new decision documented where the next agent will find it?
The right answer is not always “no new decisions.” Art direction needs room to evolve. The goal is to make novelty deliberate, named, and reusable when it genuinely becomes part of the system.
Make regression expensive to hide
Documentation guides the agent. Code review and checks make drift visible. Useful controls include:
- a single token source;
- scoped global selectors;
- visual regression snapshots for stable components;
- contrast checks for text roles;
- generated-page review at narrow and wide viewports;
- a rule that new primitives need a demonstrated repeated use;
- a release summary that names design-system changes.
Not every visual defect can be reduced to a test. The goal is to reserve human attention for art direction and judgment instead of spending it rediscovering which gray or radius the project already chose.
The wider production-readiness diagnosis applies the same principle to architecture, SEO, performance, and deployment: important decisions should live in durable project context, and verifiable rules should have executable checks.