Building an Agentic Design System

Hypothesis

Two readers, not one

For most of its life, a design system has one real reader. A designer opens Figma. A developer opens the component library. Both bring judgment to the gaps — an ambiguous name, an undocumented edge case, a token that doesn't quite fit a screen. They fill it in and move on, usually without noticing they did it.

AI reading and acting on the same system doesn't fill gaps with judgment. It fills them with a plausible guess — generates something that looks right, invents a variant that doesn't exist, hardcodes a value the system already had a token for. The system was never actually ambiguous to a human. It just relied on a person being there to quietly resolve the ambiguity every time, without anyone noticing that was the job being done.

That's the real shift. Not "add AI to the design system." Prepare the design system for a second reader that reads structure, not intent, and can't ask a colleague what someone meant.

Setup

What Figma needs to earn: being a source, not a guess

The first instinct is to treat Figma as documentation and code as the truth, or the other way round. Neither works if the two drift and nobody notices. What has to happen instead is a decision, made on purpose and kept consistent: for any given layer, either design authors it and code derives it, or code authors it and design mirrors it. Not both, and never silently.

For tokens, that direction runs from Figma into code — a designer sets a value as a variable, and it flows into the codebase from there. That handoff has been manual for most of this project: export, review, paste, rebuild. It's moving to automatic soon, through a plugin our front-end engineer built that lets me release token changes straight from Figma into the design-system repo. The interesting part isn't the automation itself. It's what happens right after: the release triggers an action that reviews the components the change actually touches, using the same information the plugin captured about what changed. Automating the handoff didn't mean removing the check. It moved the check to after the release instead of before it, which is a different trade-off, not a smaller one.

For most component behavior, the direction runs the other way: code is what actually ships, and Figma reflects it. Getting this backwards anywhere is where systems rot, because both sides start editing their own copy of the truth, and neither side is technically wrong. They're just describing two different things under the same name.

The other piece of Figma prep that doesn't get talked about enough: components need to self-report their own maturity, honestly. Which ones are finished and safe to build on, which are still in progress, which were an exploration that never got adopted. A design system without that signal makes an AI, and a new team member, equally likely to build confidently on something that was never meant to ship. And every gap between what Figma defines and what the code actually has a token for needs to be tracked somewhere it can't be ignored — not left as a workaround an engineer quietly invents once and never mentions again.

From description to contract: making the metadata actually count

I wrote good documentation for our components early on: intent, when to use it, when not to, accessibility notes, real examples. It read well. It just turned out nothing in the system actually depended on it. Nothing imported it. The only thing checking it was a script looking for the right words to show up somewhere in the file — which meant it could confirm a phrase existed without ever confirming it was true, that a token it named still existed, that a variant it described was one the component actually had.

That's the difference between a description and a contract. A description is prose that's supposed to be right. A contract is a structure the system can verify, so "wrong" becomes a build failure instead of something a person eventually notices in production.

Getting there meant three real changes. A formal, versioned schema instead of prose spread across two or three docs that could quietly disagree with each other. A real parser that reads structure, not a search for familiar-looking text. And references that actually resolve — if a component's documentation names a variant, that variant has to exist in the code, checked automatically, every time. State the same fact in two places and let them drift, and you've built something worse than no documentation at all, because now it actively lies with confidence.

One more piece worth naming: not every field in that contract has the same owner or changes for the same reason. Some of it is a human decision — what a component is for, what it shouldn't be used for. Some of it is generated straight from the code and should never be hand-edited. Keeping those honest about which is which, including a check that fails the build the moment code and its own documentation disagree, is what stops the two from drifting apart the way the old prose did.

Once that contract actually held everything about a component, I stopped hand-building the thing that documents it for people: the Storybook. AI could generate a full first pass straight from the same structure — every prop, every variant, every state already there, because the contract already had it. I still go through the result by hand afterward, mostly to add the visual polish that makes it something a designer actually wants to open, not just something an engineer tolerates. That's the split worth noticing. The mechanical build stayed mechanical. The part that needed taste stayed mine. AI removed the tedious middle, not the judgment on either end.

Governance: fewer decisions, more structural facts

Governance sounds like a meeting. In practice, the useful version of it is closer to the opposite: deciding, ahead of time, which kinds of issues never need a meeting again because the system can check them itself.

A hardcoded color where a token already exists. A naming convention that got broken. A missing accessibility state. None of those need a fresh human opinion every time they happen — they need a rule, applied consistently, that flags them the same way whether it's a Monday morning or the day before a release. What's left for people is the genuinely ambiguous call: is this the right fix, or does it change what the component actually means. Governance done well doesn't mean checking more. It means being honest about which checks were never really judgment calls to begin with.

The part I'd underline for anyone building this: every issue a system like this surfaces needs an honest bucket, not just a pass or fail. Safe to fix automatically. Needs a human look before fixing. A genuine judgment call. Or deliberately deferred, on purpose, with a reason written down — never just quietly ignored, because an ignored issue and a resolved one look identical a year later unless something records the difference.

And the schema itself needs the same discipline applied to its own decisions. Every non-trivial change to the contract's shape gets written down: what we decided, what we considered instead, and why we didn't do that. Not because anyone reads it on a good day, but because six months later someone always wants to undo a decision for a reason that was already considered and rejected — and a decision log is the only thing that stops that conversation from happening twice.

What I'm learning

The real failure mode is a document that used to be true

The thing I keep coming back to is that none of this fails loudly. It fails as a document quietly describing a state the system left months ago. A "current state" summary someone hand-updates when they remember to. A component labeled stable that hasn't earned that word in a while.

The fix isn't writing better prose. It's refusing to let prose describe a moving target at all. Anything that claims to say "what's true right now" has to be regenerated from what's actually true, on demand, rather than maintained as someone's best memory of it. If a fact can go stale, it shouldn't live as a sentence someone has to remember to update. It should live as something the system recomputes.

This generalizes past one design system

I came across a framework recently, from Grace Han's writing on agentic design systems, that reframes the usual maturity ladder by adding a second axis entirely — not "how adopted is this system" but "how safely can it be understood and operated by a machine." Those turn out to be genuinely different questions. A system can feel completely mature to the humans using it and still be close to unreadable to an AI trying to act on it correctly.

The framing I've found most useful from that same thinking: every artifact in a system like this now has two consumers with different needs. A human needs nuance, examples, the reasoning behind a decision. An AI needs structure, consistent naming, and constraints it can actually check. Neither is optional, and satisfying only one is how you end up with documentation that reads beautifully and still can't be trusted by anything that has to act on it. That test — does this serve both readers — is one I now apply before adding almost anything to the system.

None of this is specific to a component library either. Any shared source of truth a team leans on — a decision log, a research repository, a metrics definition — faces the same question the moment AI starts reading it directly instead of a person summarizing it first.

What's still unbuilt

Some of the harder pieces here are still a roadmap item, not a shipped one. A single map of the whole system that lets an AI navigate it in one read instead of exploring file by file still doesn't exist for us yet. Neither does a fully automated loop that reads its own audit output and proposes the exact fix, waiting only for a person to say yes.

That's fine. A system built to keep changing shape as AI usage evolves is supposed to have an honest, visible list of what it isn't yet. The version of this that would worry me is one that claimed to be finished.