Design systems need to be everywhere
Figma, code, docs and AI agents all reading from one source.

Zander Whitehurst
9 min read
A design system used to live in two places: a Figma library and a code package. If you were lucky, there was also a documentation site that someone updated now and then. Today that is not enough. Your system now has four audiences, designers in Figma, engineers in code, people reading docs and AI agents building screens, and all of them need to see the same truth.
I learnt this the slightly embarrassing way. I asked an agent to build a settings page and it produced something that looked nothing like our product. I was ready to blame the agent. Then I realised it had read our documentation site, which still described a version of the system we had retired eight months earlier. The agent was right. Our docs were wrong.
One source, many readers
The idea is simple. Every decision in your system should be defined once and then flow outward to every place it is needed. Tokens, component behaviour and usage rules should all have a single home.
When the same information is typed out separately in Figma, code and docs, it will drift. Not because anyone is careless, but because keeping three copies aligned by hand is genuinely hard.
Start with tokens as data
Tokens are the easiest place to begin, because they are already just data. Store them in a plain file that tools can read:
{
"surface": {
"default": { "value": "{grey.0}" },
"raised": { "value": "{grey.50}" }
},
"text": {
"default": { "value": "{grey.900}" },
"muted": { "value": "{grey.600}" }
}
}
From that one file you can generate CSS variables for code, import variables into Figma and render a reference page for your docs. One edit, four places updated.
Figma needs to match code
Designers work in Figma, so Figma needs to reflect what actually exists. That means variables with the same names as your code tokens and components with properties that match the props engineers use.
If a button in code has a variant prop with primary, secondary and ghost, the Figma component should have a property with exactly the same name and options. It sounds fussy. It removes a remarkable amount of confusion.
Code is where it becomes real
Whatever is in Figma, the product people use is built from code. That makes the code package the most important expression of your system. If something exists only in Figma, it does not really exist yet.
Make your components easy to find and easy to use. Typed props, sensible defaults and clear names do a lot of the documentation work for you.
Docs should be generated where possible
Documentation that is written separately from the code goes out of date. Documentation that is generated from the code, or lives right next to it, stays current far more easily.
Some practical ways to do this:
- Pull prop tables directly from component types
- Render live examples using the real components
- Keep usage notes in the same folder as the component
- Generate token reference pages from the token file
Human written guidance still matters, but it should sit alongside generated facts rather than repeating them.
Agents are the newest reader
AI agents read your system through whatever you give them access to. That might be the codebase, Figma through MCP, a rules file or a skill. They do not browse. They read exactly what is in front of them.
Make sure your agents can find:
- The token file and the rule to use semantic tokens
- The component library and what each component is for
- A short rules document covering layout, spacing and common patterns
If any of those only exists in someone's head, the agent will guess.
Watch for the drift points
Drift tends to happen in the same places. Renamed tokens that were only updated on one side. New component variants added in code but not Figma. Docs pages describing old behaviour. Rules that changed in a meeting but never got written down.
I keep a short checklist for every system change: tokens, Figma, code, docs, agent rules. Five boxes. It takes two minutes, and it has caught more problems than any clever tooling I have tried.
Who keeps it all aligned
Keeping everything in sync is a job, and it needs someone to own it. Usually that is the design engineer or a small pairing of one designer and one engineer. Their role is less about building new components and more about making sure every reader sees the same thing. We teach this whole workflow in our AI Design Systems Bootcamp.
This is not glamorous work. I once described it to a friend as "being the librarian for a library that keeps rearranging itself". They did not ask any follow up questions.
Start with one token
Choose one semantic token, say surface-raised, and trace it through every place it appears. Is it named the same in Figma, code and docs? Can your agent find it and understand when to use it? If the answer is no anywhere, fix that one path end to end. Once you have done it for a single token, you will know exactly what it takes to do it for the rest.
Memorisely