Agent-Ready Design Systems: What I Learned Writing 15 Articles About It

I have spent the last year writing about one problem from 15 different angles. I did not plan it that way. Each article felt like its own thing at the time. Looking back, they are all the same argument, and I only understood the shape of it somewhere around the tenth piece.

The argument is this. Your design system has two users now. One of them cannot guess.

Every design system I have built in 19 years, at Dow Jones, at DHL, at Rolls-Royce, was built for people. People are extraordinary at filling gaps. A designer joins the team, reads half the documentation, watches what everyone else does, and infers the rest. The system works because humans quietly patch it in their heads.

Agents do not patch anything. They build what the documentation says, and nothing else.

The agent did not break our design system. It just stopped pretending it was complete.

That sentence took me a year to earn. This page is the short version of how I got there, with links to the long versions.

It Starts With a Button You Did Not Build

The first crack showed up as a button. I had a CLAUDE.md telling the agent how to behave. I had a DESIGN.md with every token, every color, every spacing value. The agent generated a screen, and somewhere in that screen was a button it built from scratch. My colors. My border radius. Not my component. Never my component. I wrote about that in I Gave My Agent CLAUDE.md and DESIGN.md, which is still the most read thing I have published.

The diagnosis was uncomfortable. Our Figma library had 60+ components. The agent knew none of them existed. Not because it was careless, but because nothing in the repo told it they were there. It did what any reasonable system does when given tokens and no constraints. It built what it needed from available materials.

Every wrong component was a missing sentence in our documentation. That realisation turned into Your Design System Has Two Users Now, and into a file I now put in every repo: system.md. Three questions per component. What is this. When do you use it. When do you not.

Then the Tokens Stop Being Yours

I assumed tokens were the solved part. They are not. Apple shipped Liquid Glass controls and Google shipped Material 3 Expressive, and both quietly moved the rendering context out of the system author's hands. Your token says one thing. The user's transparency slider says another. I wrote that up in Apple and Google Just Turned Your Design Tokens Into Suggestions.

The structural answer is a three-tier token system, the same one Google runs across Android in Material 3. I explained why it survives five products in The Token Structure That Survives Five Products. The auditing answer is token-resilience, a framework for checking whether your tokens hold up when the user controls the render.

Components Need Structure, Not Just Names

Figma shipping native Slots was the missing primitive. It let me stop describing component structure in prose and start encoding it. I built an intelligence layer on top of it and wrote about it in Figma Finally Has Native Slots.

Around the same time I stopped believing in handoff as a concept. The problem was never the handoff. It was Experience Drift, the slow divergence between what was designed and what shipped. That is The End of Static Mockups. Config 2026 pushed it further, into what I think is the right mental model: Living Product Systems, where design, code, and agents are one system rather than three artifacts passed down a line.

Motion is the part almost nobody has touched. Keyframes record how pixels move and nothing else. Thirty years after Flash, our tools still cannot say why anything moves. I proposed the Motion Envelope in that piece: every animation declares its purpose, and a verifier proves the compiled output matches the intent.

Governance Is the Real Product

The through-line, the thing I did not see until I had written most of these, is that design systems were never really about components. They are about judgment. Systems helped teams scale creation. What we need now is a way to scale judgment. That is the argument in From Design Systems to Design System Agents, and it is why I built DSI.

Governance does not scale by writing more documentation nobody reads. It scales by making the rules machine-readable and then checking them automatically, every time, without a human having to care.

The Tools

DSI: Design System Intelligence audits a system for token compliance, hardcoded styles, contrast risk, naming quality, and structural consistency, then returns a health score with Fix First prioritization and root-cause signals. DSI: Slot builds, converts, and audits slot-ready components using Figma's native Slot feature. Both are free.

system.md is the annotation template: every variable carries a description, every component carries a Development note answering the three questions. ds-manifest is the repo template behind it. Token Resilience Audit Board is the Figma board for auditing token resilience directly on canvas.

What I Would Tell You to Do Monday

Do not try to document everything at once. Pick one surface. One set of components. One page type.

Fill in the Figma variable descriptions for every token on that surface. Add Dev Mode notes to every component it uses. Write the system.md entries for those components only. Run the agent. See what breaks.

Then fix the file, not the prompt. This is the part people get wrong. A prompt fix feels faster and disappears the moment the session ends. A file fix compounds. Every rule you write down is a rule you never explain again, to an agent or to the designer who joins next quarter.

And be honest about which problems this actually solves. Agents are very good at generating the flow. They cannot question the experience, which is a different job and still yours. I wrote about that in AI Can Generate the Flow, and about the broader version of the mistake in Everyone Is Learning to Prompt. Nobody Is Learning to Think.

The Uncomfortable Part

For every component we documented, there was a rule we had been applying unconsciously for years. Nobody had written it down. We never needed to, because everyone on the team already knew.

Filling in those files surfaced three years of institutional memory that had been living in Slack threads, onboarding calls, and the heads of the two designers who had been there from the start. Not one line of it was in the design system.

We spent three years building a system for designers. It took an agent that cannot guess to finally make us build one for real.