That is where DESIGN.md comes in: an open standard, still in alpha, that brings the decisions behind a design system — colour, typography, iconography, spacing, components and usage rules — into a text file that both people and agents can read. At Workoholics, as an agency specialising in the design and development of digital experiences, we are testing the workflow between Figma and Dev to see whether AI can not only execute faster, but also better understand the thinking and principles behind our designs. Creativity and technology, this time, speaking (quite literally) the same language.
17 September, 8:30 in the morning, Workoholics HQ, Done Bikendi Plaza 2, Bilbao. We were working with Claude Code to take an interface already designed in Figma into development. The design system was well defined, with colour tokens with names and purposes, a defined type scale, spacing, components and all their variants… Everything was in place.
We gave the agent the context and asked it to implement the design. The result worked, but visually it was quite far from what we had defined. Colours that did not exist in our palette appeared, spacing was invented, a random typeface was used… there was no sign of the system. Ene bada!
It wasn’t an AI failure; it was a lack of context. Without knowing the rules it needed to work with, it had filled in the gaps itself. Poor thing.
A new interlocutor in design and development
At WKHS, our design and development teams work closely and in coordination across all kinds of projects. Constant communication between both teams allows us to understand each other’s needs, resolve questions as we go and ensure that the final result is developed consistently with what has been designed. Since a large part of the agency team started using Claude Code for programming, agents have become a new interlocutor in that process. And a very welcome one, too.
Today, we can connect them to Figma and give them access to components, variables and information from the design itself. But having access to the system does not necessarily mean understanding all the decisions and rules behind it. If we do not provide that context clearly, they fill in the gaps themselves. With good intentions, yes, but by improvising. This is where DESIGN.md comes in.
DESIGN.md: what is it and what isn’t it?
It is worth pausing here and clearing up this question, because we asked ourselves exactly the same thing at Workoholics: is a DESIGN.md a Design System? Not quite.
A DESIGN.md is not the design system itself; it is a representation of that system in a format that both people and AI agents can read. The system still lives where it needs to live: in Figma, with its components, variants, documentation and all the decisions we make around it.
DESIGN.md is a plain-text file that captures part of that system — colour tokens, type scales, spacing, radii, shadows, component behaviour rules, etc. — while also allowing us to explain how and why they should be used. In other words, it does not replace the design system; it complements it.
And if we incorporate it into our methodology and processes, it can save us quite a bit of time. Essentially, many of the rules that we would otherwise have to explain again in a prompt become part of the project’s own context. And that makes a real difference.
There is, however, one important thing to bear in mind. DESIGN.md does not update automatically when the design system changes in Figma. If we modify a token, a component or any other rule, we also need to reflect that change in the file. That is why it is worth treating it as a living part of the design system and thinking from the outset about the processes or automations needed to prevent it from eventually saying one thing while Figma says another.
Reducing friction between design and development
DESIGN.md helps turn some of that scattered knowledge — which often lives in the heads of the people who have worked on the system — into a single, version-controlled and accessible document.
Its value becomes particularly clear when someone joins a project or when it changes hands. Instead of reconstructing the context through questions, memory or several variations of “hang on, I’ll show you where it is”, we can find many of the rules we need to keep working in an organised way, without losing time or consistency.
Of course, DESIGN.md does not replace collaboration between design and development. At Workoholics, that remains — and will continue to remain — the foundation.
What it can do is reduce friction. Or, in other words, fewer back-and-forth conversations to confirm a detail, fewer different interpretations of the same component and less time spent explaining decisions that have already been made.
And here we have found something we particularly like. Having to explain a design system clearly to an AI also forces us to explain it better to each other: what each token means, why each rule exists, what genuinely forms part of the system and where the exceptions begin.
Ultimately, it forces us to organise that conversation between design and development more effectively. And that is where creativity and technology meet again in a fairly natural way. Technology helps us execute and accelerate processes, but it still needs decisions, intention and judgement behind it. That remains our job.
Is DESIGN.md a client deliverable?
This is one of the questions we are asking ourselves most internally, and the honest answer is: it depends.
DESIGN.md falls short if we think of it as documentation for presenting a design system. It does not replace a Figma library, a visual guide or an explanation of the decisions we have made. Its value lies elsewhere.
As a technical complement to the design system, particularly for clients whose product and development teams already work with AI agents, it can be a very useful addition. It allows some of the system’s rules to travel with the project and be available from day one to the tools that team will be working with.
We can think of it as a pocket-sized version of the design system. In other words, it does not contain everything behind it, nor does it aim to. But it does capture a particularly useful part of the system when that design needs to move from Figma into code and start being interpreted by agents too.
And that opens up an interesting possibility for us as an agency: delivering design systems that are prepared not only for people, but also for the tools those people work with.
What’s next
We are still learning how to keep all of this alive without simply turning it into another maintenance task. Clearly, that is one of the real challenges. But if there is one thing we are certain of, it is that design never ended in Figma.
There are now new ways of making sure the decisions we make there travel with the project and continue to make sense when they reach development, other teams or an AI agent. But there is one non-negotiable condition: none of this replaces the conversation between the person designing and the person developing.
Tools such as DESIGN.md can remove friction along the way. The judgement, the questions and the decisions we make together are still ours. And we hope they remain that way.
If you are thinking about the same things, or have found a better way of solving them, get in touch. We are sure we will keep learning together.