r/DesignSystems • u/No_Draw4901 • 4h ago
We rebuilt our design system so our team and AI agents follow the same rules and get the same UI
Our team (one designer, one engineer) spent 3 weeks rebuilding our design system, MBSW, around one question: can a human and an AI agent start from the same source and end up with the same UI?
When we asked AI to follow our old system, it kept rebuilding components we already had and picking colors that were only close. The rules it needed lived only in someone's head, not anywhere it could read.
What we changed:
- Two layers per component. An intent doc (MD) written by the team explains when and why to use it. The values (JSON) are generated by a script from a Figma version the design team has approved.
- No AI summarizing Figma. We first had AI read Figma through MCP and turn it into JSON, but the same component came out slightly different every run. Pinning the Figma version and using the REST API made the output identical, whoever runs it.
- Tokens mapped by intent, not by value. Different tokens can share the same color, so the value alone can't tell you which token it is. We map values through Figma variables and keep each confirmed mapping.
- No filling gaps by guessing. If we've agreed on a behavior that isn't drawn in Figma, it goes in the intent doc. If a token mapping is missing or ambiguous, the AI doesn't pick one just because the name or color looks close; it waits until we confirm.
It's public (React 19, MIT) if you want to see how the docs and tokens are structured: https://rdo.sh/G1SCiIV
Curious how other teams approach this. Do you write documentation with AI as a reader in mind, and what has worked or not?


