.md – a new standard for design systems?

What the format actually is

A design.md is essentially two layers in the same file. A YAML block at the top with tokens – colors, typography, radius, spacing – and a list of components expressed as combinations of those tokens. Below that, prose explaining the design thinking.

Read against a classic design system model, this is less new than it first appears. The foundation is still there – colors, tokens, typography, radius, spacing. The difference is that it's machine-readable rather than embedded in Figma variables or a Supernova export. And the prose underneath is what would previously have been called rationale or brand guidelines.

What's genuinely different is how components are handled.

Where did the components go?

In a classic system, components are something concrete. A dropdown exists as a Figma component and as a corresponding Vue or React component in the code library. In the .md format, components are specifications instead – "a primary button has this background color, this radius, this padding". There is no actual implementation in the file.

That doesn't mean components disappear. It means the implementation comes from three other places. The agent's own knowledge of how to build an accessible dropdown, trained on millions of examples. Open source libraries like shadcn/ui that work as copyable templates rather than installed packages. And – most importantly – the project's own committed components once they've been generated the first time. The first time an agent needs a dropdown, it creates one, and it gets committed to the repo. The next time, it should import that one instead of creating a new one.

This is a different way of thinking about component libraries. Instead of a central library each product pulls in as a dependency, it becomes a set of source code each project owns and lives with. The format says how something should look, but the implementation grows inside the project.

The consistency question – the easy thing to miss

This is where it gets interesting, and where classical design system thinking comes back stronger than one might first expect. A .md file alone isn't enough to keep a system consistent. It gives you color consistency and token consistency, but not implementation consistency. Without the right structure around it, you risk ending up with the same tertiary color on buttons throughout the product, but ten different dropdown implementations with different HTML, different ARIA attributes, and different animations.

Three things are required for it to hold together over time.

Tokens as the source of truth. Change a color in the .md file and everything that references it updates. It's the same principle as Figma variables or CSS custom properties, but the format is directly readable by the agent without a plugin or export step.

The file in the repo, not in the agent's memory. AI agents have short memory between sessions. That's the whole point of keeping the spec as a file in the project – each session starts by reading it. Nothing important is stored in the agent.

Committed components and an instruction file that says "import, don't create new ones". This is the layer that makes dropdown number two actually become dropdown number one. A design.md says how a button should look. An AGENTS.md or CLAUDE.md tells the agent where to look for existing components before writing new ones. Without that second layer, the design system drifts, even if the colors stay correct.

The parallel to classical design systems is actually quite clear once you think about it. Foundation becomes YAML tokens. Component specifications become YAML components. The component library becomes committed code in the project. Documentation becomes prose in the same file. Nothing disappears – it's packaged together in a format an agent can act on.

How we think about it at Intunio

We follow the development closely and see it as a natural extension of our token work rather than a break from how we've worked. Token-based design systems have been at the core of modern deliveries for several years. Moving from Figma variables and Style Dictionary to a machine-readable file an agent can consume directly is a step in the same direction – not a new direction.

What changes is what the delivery looks like at the other end. When code is no longer necessarily written by a human but by an agent reading the spec, the clarity of the spec itself becomes even more important. There's less room for implicit knowledge, for "whoever builds this will understand how we usually do things". Every design decision has to be written down, because that's what the agent will read.

At the same time, it's worth saying outright that the format isn't finished. Google's design.md is early, competing formats will emerge, and it's still unclear which will win in the long run. The principle – a machine-readable spec, committed code, and an instruction file for the agent – holds regardless of which format becomes the standard.

What to take away

A design system has never been about the files it's stored in. It has been about ensuring that a product looks and behaves consistently no matter who builds the next part. When "whoever builds the next part" becomes an AI agent, the goal doesn't change – but the tools and formats do.

The .md format is an early attempt to meet that. It isn't a wholly new way of thinking about design systems, it's a new way of packaging them so they're readable by something that isn't human. Foundation is still there, components are still there, documentation is still there. What's new is that all of it becomes text an agent can act on directly, without plugin, export, or handoff.