A design system AI agents can actually read

Context

Brighte's component library already worked for the humans using it. But the way the team ships changed fast: engineers working with AI coding tools, PMs prototyping, and me shipping my own front-end changes in code. All of that put a new kind of user in front of the design system, a very literal one. An AI agent doesn't absorb conventions by osmosis the way a new designer does. It reads what's there, and if what's there is ambiguous, it fills the gaps by guessing.

As design-system custodian, I treated that as a design problem to solve (not a tooling one). A design system is a product judged by its users, and we had a user it was failing.

The problem

Point an AI coding agent at the system as it stood and the output was inconsistent and barely usable: wrong tokens, invented variants, structure that drifted from one attempt to the next. Essentially throwaway code that needed correcting everywhere. Most people run into that, conclude AI is overhyped, and stop. I read it differently. The model wasn't the problem. There was no reliable source of truth for an agent to work from, so it approximated.

My role

The idea was mine and I drove the work, as Product Designer and custodian of the design system, working hand in hand with engineering. I'll make the same point here I make about all shipped outcomes: the working system belongs to the team that built and uses it. What I'd claim personally is the reframe, the semantic layer's design, and the validation approach.

Approach

I started the way most people do, stuffing all the instructions into a long prompt. That got consistency, but a prompt that long is unrealistic, because no one writes a brief like that. So I took the instructions out of the prompt and built them into the system itself. That way an agent routes itself through the right context without being told to.

Concretely, that meant a context and semantic layer on top of the existing system. Every component gets a specification documenting which tokens to use, how it composes, and, critically, what an agent must never generate. Above the components, pattern rules describe how they assemble into whole layouts for a given surface. An agent reads the layers in sequence (surface rules, then pattern, then the specific components) and arrives at the same grounded output every time instead of inventing one.

The shift is from prompting the model to engineering the context it reads. I think of the first as using AI and the second as building with it.

What shipped

The semantic layer itself, live over the design system the team builds with. Code Connect in Figma, which I set up so the design system in code and the one in Figma line up. And the working habits around it. I've helped engineers upskill in working with tools like Claude Code, and helped PMs get set up to prototype effectively. I've also done a lot of the experimentation on when it's best to work from Figma, straight in code, or in a prototyping tool. The system only matters if the team works this way, so the enablement was part of the work.

Outcome

I validated it with a defined test instead of eyeballing it. The test was consistency: run the same brief through several independent AI agents in fresh sessions, no shared context, and measure how alike the outputs are. Structure, component usage, and token accuracy held across all of them. Set against the old system's throwaway output, the same prompts now produce something close to draft feature code, on-brand and working the first time, with far less rework.

The shape of that evidence is a consistency benchmark plus daily use in a shipping team. It is not a formal time-and-motion study. I cared about measuring it at all because "it felt better" isn't evidence, and a consistency threshold is.

Reflection

The lesson I carry from this work comes from a migration. We leaned too hard on AI to carry it and under-invested in investigating the existing backend behaviour up front. The UI and the migration itself went fine, but a few connecting behaviours weren't well documented, so we shipped with a list of fast-follow fixes and some stakeholder concern. The lesson was blunt: front-load the planning, investigation and documentation, because the problems you hit downstream eat the productivity the AI gave you.

What still frustrates me is that the design-side AI and the code-side AI don't yet share a source of truth. A good prototype still can't be promoted straight through to production. I expect the space to close that gap, but it's where I keep pushing.

The pattern generalises beyond components. Find where the AI is guessing, work out what context would stop it guessing, and build that context as a product. Design systems are the clearest instance because they're already supposed to be a source of truth.