Why coding agents fail at the design system

When coding agents like Claude Code or Cursor fail at a design system, the cause often lies less in the model than in knowledge that isn't recorded in any document.

In many product teams, the design system works because people compensate for its gaps. Retros and hallway conversations have made it common knowledge that a component has effectively been replaced, that a property has a bug, or that a color value exists but was never meant as the background of a dialog.

An agent doesn't have this knowledge. Ilya Greben of Design Systems Surf sums it up in a headline: “Every missing decision becomes an AI guess.” Every missing decision turns into a guess, because the agent delivers a result either way.

What this looks like in practice

Atlassian has described what happened when the first AI prototypes were built in its own system. The results looked plausible and were still wrong, with incorrect component imports, incorrect token names, and icons that fit the brand but don't exist (report on the Atlassian blog). The difficulty is that such errors don't stand out at first glance.

What a system needs to capture

Three measures provide a sound starting point. They follow from the problem described here and are not backed by a study:

Structured descriptions. A component's properties, allowed values, and combinations are recorded in a form that can be checked.
Tokens with a purpose. Alongside its value, a color token also contains the rule that goes with it, for example: color-danger only for actions that can't be undone.
A visible lifecycle. An agent cannot recognize a status like “unofficially replaced.” States like experimental, stable, and deprecated therefore belong in the component's description.

Documentation that appears complete is not enough for this. When reviewing your own system, it is worth asking which knowledge currently rests only with long-standing team members.

From the series “Design Systems and AI”. Next: Three design systems that have opened up to agents.