Most AI-assisted design work runs the same play: a designer prompts a model, the model produces screens, tokens, copy. The AI makes things for you, once, and then the output sits there — a system that can’t look after itself.

We tried the inverse. Instead of asking an agent to design our product, I rebuilt the design system so an agent could work inside it — auditing tokens, catching drift, correcting components, keeping Figma and code telling the same story. The same jobs I’d hand a designer with a spare Thursday.

The hypothesis

A design system stopped being documentation for developers the day an agent could read it. If it’s now instructions for a machine, three things have to be true: the tokens must be semantically layered, every component must describe itself in a way a machine can parse, and the naming must carry enough meaning that an agent can make a judgment call without me in the room.

Worth testing on something real, not a demo with two buttons and a colour ramp. This system runs 26 components, dark mode, a state matrix that covers overdue payments and half-filed returns, and 412 tokens that all have to stay coherent while an agent works on them.

Three layers. Primitives hold raw values — hex, scales, font stacks — and no component is allowed to touch them. Semantic tokens alias primitives by intent: --color-text-primary, --color-status-critical. Component tokens scope to a single pattern — the savings figure, the payment schedule, the badge that says an accountant is acting on a client’s behalf.

The layering is what makes it machine-readable. An agent that meets --color-status-critical doesn’t need taste; it follows the chain — semantic to primitive to raw value — and lands somewhere defensible. Rename a primitive and nothing downstream notices. That indirection is the entire trick.

Here’s the chain the agent walks when it audits us. Flip the theme and watch the semantic column re-point while the component column sits perfectly still.

Dark mode is the cheapest honesty test a token architecture can take. If components only ever reference semantic tokens, dark mode is one attribute on the root element. If anything is holding a raw hex, it gets caught red-handed the moment the lights go down.

Storybook found ours. Two components had hardcoded near-black text — a statement label and an icon caption — invisible in dark mode and invisible in review, because nobody clicks every story. The agent found them by reading the stylesheet, not by looking at pixels.

The second structural bet, and the one that changed how my team worked. Figma MCP reads component descriptions — so those descriptions stopped being a sentence for a designer browsing the library and became a spec for something that has to rebuild the component from words alone.

“A card that shows a client’s tax position” is true and completely useless. What an agent needs is the surface token, the border token, the elevation, every prop and its accepted values, and what happens on hover. Write that down once and the agent stops guessing.

An agent will never leave a gap empty. Skip the disabled state and it will invent one — usually 50% opacity on everything, including the text you spent a week getting legible. Skip the error state on a payment row and it will reach for the nearest red it can find.

So the state matrix became non-negotiable: every component ships with every state drawn and bound to a token, including the awkward ones this product can’t avoid — a payment that’s overdue, a return that’s part-filed, a client an accountant hasn’t been authorised for yet. Completeness is what keeps the agent from improvising.

Two canonical files, deliberately split. One holds tokens — variables, text styles, the primitive and semantic collections. The other holds components and their machine-readable descriptions. The split isn’t tidiness: it means an agent asked about a colour queries one file, and an agent asked about a component queries the other, instead of trawling both and picking wrong.

With the structure in place I handed the agent four real maintenance jobs — the unloved kind that slip for a quarter because there’s always something shipping. Each one worked because the naming and the layering carried the context.

The part that matters: none of these followed a script. For the drift audit I asked one question — whether the stylesheet and the Figma variables still agreed. The agent decided on its own to enumerate the custom properties, pull the Figma collections, diff them, sort the gaps by whether anything consumed them, and hand back a list I could action. Structure gave it enough context to make those calls.

And a quieter one, from years of leading design teams: briefing an agent well is the same skill as briefing a designer well. Clear intent, honest constraints, and the humility to let whoever’s executing make calls inside them. The teams taught me that long before the tools did.

The design system is no longer just documentation for developers. It’s instructions for a machine — and the designer’s job is to make those instructions worth following.