DESIGN.md Explained - The Format Reshaping How AI Builds UI

🧠 Google has open-sourced the spec. What is DESIGN.md and why should product teams care?

🔒 The Knowledge Series breaks down emerging AI technologies with practical playbooks designed specifically for product teams. Get 100+ guides and practical tutorials covering everything from Claude Code and MCP to agentic workflows, vibe coding, and more.

---

Google has announced that it is officially open-sourcing its DESIGN.md format - a standardized specification originally developed for its own design tool, Stitch.

The spec turns design systems into something “agent-native” and interoperable, with some arguing that it will form the basis of the future of design.

And following the announcement, some have even predicted that it is inevitable that the design role will change fundamentally. One prominent Silicon Valley venture capitalist and former product leader at Google and Meta made a particularly controversial prediction and argued that design is “the first AI casualty”:

In Gokul’s view, larger companies will likely not backfill design roles as product teams use centralized design systems that feed into AI tools to generate UI and prototypes on demand.

As you might imagine, there has been plenty of pushback against this from several folks in the tech community who argue that this is a poor take on how the role of design might evolve. But whether he’s ultimately proven right or not, it’s now clear that design systems and markdown files are rapidly reshaping some of the traditional tools processes that product teams took for granted. And companies like Google and Anthropic are increasingly pushing the format as the de facto way to get the most of out design systems in their own tools.

In this Knowledge Series, we’ll unpack the DESIGN.md format in more detail to bring you up to speed with what it is, how it works and how you can develop your own DESIGN.md system. We’ll also get hands-on with how to use DESIGN.md files in tools like Claude Design and explore some prompts you can use to build your own migration tools and systems from scratch.

Coming up:

• What is DESIGN.md? The potential impact of DESIGN.md on product teams and the software development process

• Hands-on examples of DESIGN.md in action: how you can use it with tools like Claude Design, Cursor and Google Stitch

• Prompts you can use to build your own interactive tools including a DESIGN.md side interactive editor to see the spec come to life in real time

---

The Knowledge Series

What is DESIGN.md and how does it work?

Here’s a snapshot of what the DESIGN.md is and how it fits into the wider design process:

Put simply, DESIGN.md is a plain-text file that gives your AI agents a structured, persistent understanding of an entire design system. In many ways, it’s almost like a design counterpart to other well established files that are routinely used in software development like README.md files.

And they’re not entirely new. After they were initially released as part of Stitch almost a year ago, the format started to pop-up outside of Google’s own tools. Developers began to write their own versions of DESIGN.md and companies even started to share their own markdown files that designers could use if they wanted to adopt similar design language.

But, Google’s new open-source specification standardizes the format for the first time, outlining a structured approach that product teams can use in their own development process.

We’ll get some hands on experience with a real world DESIGN.md file later but for now, let’s focus on some of the structural decisions the format introduces.

The two layer structure

Every DESIGN.md has two parts living in the same file:

1. A section at the top containing machine-readable design tokens - exact hex codes, font sizes, spacing values, corner radii, and component styles. Written in YAML (a data format that’s similar to JSON).

2. A markdown body below that, containing human-readable rationale explaining why those values exist and how to apply them.

In other words, the file format is designed to allow product teams separate out the “what” from the “why”.

Here’s an example of the top half of the spec which includes values for things like colors and typography:

And here’s an example of the markdown beneath that to provide extra context and detail about how the system is designed:

Why this is a powerful, pragmatic approach to building agentic design systems

The “what” (tokens) is for machines. A coding agent doesn’t need to know that primary is “Golden Retriever orange” evoking joyful energy. It needs a hex code like #855300. A hex code is precise, unambiguous, executable so when an agent generates a button, it pulls the hex, applies it and moves on.

The “why” (prose) is for judgment calls. When a situation arises that the tokens don’t cover which might include things like an edge case, a new component type, an unexpected layout constraint, an agent (or a human) needs context to make a decision that stays on-brand:

“The brand personality is optimistic, trustworthy, and active”

or

“never crowd elements”

are instructions that can’t be tokenised but can guide a decision. So in these cases, they fill the gaps and help guide the agent to make design decisions that fit with the wider system.

The potential impact of this on product teams

For product teams, the adoption of DESIGN.md has some potentially significant, practical implications.

Before we look at some hands on examples together, let’s first consider what the potential impact of widespread adoption of AI design systems like this might be.