Your design system doesn’t live in Figma in Markdown
A structured text version of the portfolio to read, share or use as context in an AI assistant.
_DESIGN SYSTEMS_
# Your design system doesn’t live in Figma
For years we have treated Figma as the source of truth and code as its copy. With AI agents writing interface code, that model stops working. This is the alternative I have implemented and tested: a headless design system.
Javier González · 11 Nov 2026 · 7 min read
## The problem: two systems that look alike
In almost every team I have worked with there are really two design systems. One is in Figma: libraries, variables, components and their variants. The other is in code: tokens, React components, Storybook stories. They look very similar, but nobody can guarantee they are the same.
The gap between them is closed by hand. The designer hands over a screen, the developer interprets it, and in that interpretation everything already decided gets decided again: which variant it is, what spacing, what happens when the text does not fit. Every handover is a translation, and every translation introduces small differences.
While only people did the work, conversation covered the gap. A developer with a doubt asks. An AI agent does not ask: it fills the gap with whatever is most likely. If the rule is not written somewhere it can read, it makes one up.
## The idea: the system is the contract, not the file
A headless design system separates the decisions from the tools that display them. The decisions live in a repository, as text, with change history and review. Figma, React, Storybook, the CMS and the agents are consumers of those decisions. None of them is the original.
“Decentralised from Figma” does not mean “without Figma”. Designers still design there, with real components and variables. What changes is the direction of authority: when Figma and the repository disagree, there is a clear rule about which one wins and a mechanism that flags it.
## The three pieces in the repository
### 1. Tokens
The basic visual decisions: colour, type, spacing, radii, shadows. They are stored in a standard design-token format and transformed into what each consumer needs: Figma variables on one side, CSS properties on the other.
The delicate part is synchronisation. Tokens and Figma variables need to be connected in both directions, but only one direction is in charge. If a designer changes a variable in Figma, that is a proposal to change the repository, not a change to the system.
### 2. Component contracts
This is the piece almost no system has, and the one that changes the outcome most. A contract describes a component so that a person and a machine understand it the same way.
Traditional documentation explains the component. The contract bounds it: it says what is allowed, which makes it possible to check automatically whether a design or a piece of code complies.
### 3. The map between design and code
Every Figma component needs to know its equivalent in code, and the other way round. Without that map, an agent that receives a screen sees rectangles and text. With it, it sees “a primary button inside a product card”, with its properties.
## Connected to Figma: validate and hand over
With those three pieces, work inside Figma changes at two moments.
**Before handover, you validate.**: A plugin compares the design with the contracts: components that do not come from the system, loose values where a token should be, variants that do not exist, missing states. The designer sees this while designing, not three weeks later in a code review.
**At handover, you export structure, not pictures.**: Instead of screenshots with measurements, the handover is a description of the screen: which components it is made of, with which properties and which content. From that description come React packages, Storybook stories or the JSON the CMS needs.
## What “AI-ready” actually means
An agent needs the same things a new developer needs on day one, only written down and unambiguous:
- **Context it can read.**: Tokens and contracts as structured text, not as layers in a design file.
- **Rules it can check.**: If the contract says a primary button appears only once per view, that can be verified.
- **Examples.**: One correct case and one edge case teach more than three paragraphs of description.
With this the agent stops guessing. It builds with the system’s components, not around them, and what it produces can go through the same validation as a person’s work.
You do not need a separate system for AI. Preparing the system for agents and fixing the collaboration between design and front-end turn out to be the same work.
## What changes for the team
- **For design:**: less freedom to improvise values and more certainty that what is designed can be built. Validation arrives while you work.
- **For front-end:**: the handover stops being an interpretation. Structure arrives, and doubts are settled in the contract, not in a message thread.
- **For product:**: decisions are written and versioned. You can see when a rule changed and why.
What does not change is who decides. AI explores, builds and checks; people review and decide.
## What is not solved yet
It would be dishonest to present this as finished.
- **Contracts need maintenance.**: An outdated contract is worse than none, because now a machine obeys it.
- **Governance matters more, not less.**: Someone has to decide who approves a change to a contract and how it is proposed from Figma.
- **A pilot is not production.**: What I describe here is implemented and tested with one design team and one front-end team. Scaling it across an organisation is a different problem.
## Where to start
Do not start with the whole system.
- **Pick one component**: that appears on many screens.
- **Write its contract**: with the template that comes with this article.
- **Connect it:**: link the Figma component to its equivalent in code and its values to tokens.
- **Ask an agent to use it**: in a real flow and watch where it makes a decision the contract leaves open.
- **Fix the contract,**: not the output. Then move to the next component.
If after five components the handover between design and front-end is not shorter, the problem is somewhere else, and finding that out will have cost you little.
Markdown
### Component contract template
A Markdown file for writing your first contract: properties, states, tokens, accessibility, checkable rules, an example and an edge case.
Download the template (https://baguelus.com/recursos/plantilla-contrato-componente-en.md)