Agentic Design System

Where this starts

The design system overhaul rebuilt the system for people. This is the question that came next: what happens when the consumer is not a person.

Two agentic workflows were emerging at the same time, and the design system sat between them. Engineering was beginning to generate implementations from designs. Designers were beginning to prototype in code. Both were reaching for the same system, neither was getting it right, and the explanations on offer were guesses.

So I ran it as research, with our lead front-end engineer, rather than arguing about it in the abstract.

The experiment

Three things made it a test rather than a demo:

• Figma MCP as the connection between the design file and the model, so the model was reading the real design rather than a description of one.
• Prompt pipelines with controlled variation, so a difference in the output could be traced to a difference in the input instead of to the weather.
• The design system as the variable. Same design, same prompt, different amounts of structure exposed to the model.

The question was deliberately narrow. Given a design and a design system, can a model produce an implementation that actually uses the system.

What the first tests told us

No. Not without being told how.

A model reads a design perfectly well. It sees layout, spacing, color, hierarchy, and the relationships between elements. What it cannot do is look at a rectangle with a label and know that it is your Button, let alone know the rules for using your Button correctly.

Handed a design and a system, it would:

• rebuild components from scratch instead of reaching for the ones that already existed
• hardcode the values it could see rather than the tokens that produced them
• assemble combinations the system deliberately does not allow

None of that is the model being careless. It is the model being handed a picture and asked to infer a contract. The information was not missing from the design system. It was missing from what the model could reach.

Inference vs lookup: the same design, twice

Full screen

That reframed the whole project. The problem was never model capability. It was that a design system communicates through convention, apprenticeship and review, and none of those survive contact with a machine consumer.

What Code Connect is actually for

This is the thing I understood only by testing it: Code Connect exists to solve exactly this problem. It is not a documentation convenience. It is the link that lets a design point at its implementation, so the model stops inferring and starts looking it up.

Fix 1: Tokens the agent can reason about

Raw values are the first thing that breaks. Hand a model #008b8b and it will cheerfully hardcode that hex in forty places. The moment you rebrand, every one of them is wrong, and no amount of prompting reliably stops it.

• Primitives are raw values: teal-500: #008b8b, space-4: 16px. The agent should never see these. If it does, it hardcodes them.
• Semantics are intent-named aliases: color/action/primary, color/danger/background. This is the only layer the agent reads and writes. The name describes the job, not the value, so a rebrand updates one alias and everything downstream follows.
• Component tokens are optional: button/background/default → color/action/primary. Skip them until you are doing multi-brand work.

Fix 2: Component metadata

Most component documentation is written in prose, for humans. An agent needs a contract with explicit keys, explicit values, no ambiguity. The emerging consensus (surfaced across talks from Indeed, GitHub, and others at the AI Design Systems Conference 2026) is JSON metadata per component, covering four things:

• Props: the states and variants that already exist in Figma. Five states in Figma, five states in the metadata. No interpretation.
• Relationships: what the agent must know before placing the component. Is it a form child? A toolbar item? What can it not sit next to? This is the context a human infers and an agent cannot.
• Tokens: which semantic tokens the component consumes. Load-bearing in an agentic system, not decorative.
• Usage: what it is for, and the anti-patterns. Not the obvious ones ("don't put two primary buttons side by side"), but the specific ones only your team knows.

An agent can auto-generate the first draft of this metadata, but it comes back about 80% right and 20% generic. It will list the obvious anti-patterns and miss the ones that actually bite: "never use a destructive button in onboarding," "loading state shows after 200ms, not immediately." The 20% is the part that encodes what your team learned the hard way, and it is the part a person has to write.

Fix 3: One source of truth

The fix is architectural, not editorial. Pick one canonical source: for us, the design system components linked to Figma via Code Connect (or rich component descriptions, which do the same job without enterprise tooling).

Everything else derives from it or maps to it:

• The Figma library
• The docs site
• The token files

None of them are independent truth. They are all projections of the one contract.

What it changed

No more hardcoded values creeping into forty places the moment a token changes. No more agent guessing which source to trust: the Figma library, the docs site, and the token files all resolve to one contract instead of competing.

The larger change is what it made possible. Once the system could be read by a machine, the handoff itself could be rebuilt around that, which became the design skills infrastructure and took spec production from days to under 30 minutes.

What I'd do next

• Measure it properly. The tests told us what broke and why, but a standing benchmark would tell us whether the system is getting more legible over time or just differently broken.
• Push the metadata upstream, so a component that ships without its usage contract fails review the way a component without an accessible name would.