I used to think design was about what you could see. The color of a button. The curve of a corner. The weight of a font. I thought design was the paint on the wall, the leather on the saddle, the shine on the bit. But after years of building, breaking, and rebuilding, both in code and in life, I’ve learned that design isn’t about the surface. It’s about the promise.
Then I found it. Not in a stable, but in code. A new way of speaking to the machines we build. A new way of encoding the soul of our creations.
It’s called DESIGN.md.
And if you are a builder, a creator, or anyone who cares about the integrity of what they make, this changes everything.
The Problem with Chaos
Think about the last time you tried to explain a vision to a developer, a designer, or even a friend. You describe a feeling. “Make it feel warm,” you say. “Make it feel urgent.” “Make it feel trustworthy.”
What do they hear?
“Warm” means orange to one person. It means soft rounded corners to another. To a third, it means a specific serif font. “Urgent” means red to one. It means bold typography to another.
We speak in abstractions. But machines—and often, the humans working with them—need precision. When we rely on vague instructions, we get chaos. We get inconsistency. We get a product that feels disjointed, like a horse that is fighting the bit because the rider’s hands are inconsistent.
I’ve seen projects die because of this. I’ve seen brands fracture because one team interpreted “primary blue” as #0056D2 and another interpreted it as #007BFF. Small differences. Massive consequences. The brand loses its voice. The user loses their trust.
We were speaking different languages. And in that silence, the connection broke.
Enter DESIGN.md
DESIGN.md is not just a file format. It is a bridge. It is a Rosetta Stone for the modern builder.
Created by Google, this specification combines two things that have always been separate: the machine-readable precision of code, and the human-readable nuance of prose. It uses YAML front matter for tokens—exact hex codes, exact pixel values, exact font weights. This gives agents, compilers, and developers the exact values they need. No ambiguity. No guesswork.
But then, it adds Markdown prose. It tells you why those values exist. It tells you the story behind the color. It tells you the intent behind the spacing.
It looks like this:
---
name: Heritage
colors:
primary: "#1A1C1E"
secondary: "#6C7278"
tertiary: "#B8422E"
neutral: "#F7F5F2"
typography:
h1:
fontFamily: Public Sans
fontSize: 3rem
---
## Overview
Architectural Minimalism meets Journalistic Gravitas. The UI evokes a
premium matte finish — a high-end broadsheet or contemporary gallery.
## Colors
The palette is rooted in high-contrast neutrals and a single accent color.
- **Primary (#1A1C1E):** Deep ink for headlines and core text.
- **Secondary (#6C7278):** Sophisticated slate for borders, captions, metadata.
- **Tertiary (#B8422E):** "Boston Clay" — the sole driver for interaction.
See the difference?
The YAML gives the machine the exact hex code: #1A1C1E. There is no debate. There is no interpretation. It is deep ink. It is precise.
But the prose tells you why. It tells you this is “Architectural Minimalism.” It tells you this color is “Deep ink.” It gives the color a name: “Boston Clay.” It gives the design a soul.
This is the bridge. This is the connection.
Why It Changes Everything
For years, we have treated design and code as separate entities. Designers create mockups. Developers write code. Handoffs are messy. Context is lost. The soul of the design is lost in translation.
DESIGN.md changes this because it makes the design system persistent. It makes it structured. It makes it understandable to both humans and AI agents.
Think about what this means for the future of building.
We are entering an era where AI agents will write much of our code. They will generate our components. They will style our interfaces. But AI cannot understand “vibe.” AI cannot understand “feel.” AI needs context. AI needs rules.
DESIGN.md provides that context. It provides the rules. It tells the agent not just what color to use, but why it matters. It tells the agent that this is “Journalistic Gravitas.” It tells the agent that this is “Premium Matte.”
This allows AI to build with intention. It allows AI to build with soul.
But it’s not just about AI. It’s about us.
As humans, we struggle with consistency. We forget. We drift. We change our minds. A DESIGN.md file is a source of truth. It is a contract. It is a promise to ourselves and to our teams that we will remain consistent. That we will remain clear. That we will remain trustworthy.
The Horse and The Rider
I often think about my horse, Dakota.
Dakota taught me that trust is not given. It is earned. It is earned through consistency. Through clarity. Through repetition.
If I pull on the reins one day and loosen them the next, Dakota becomes confused. He becomes anxious. He stops trusting me.
In software, we do the same thing. We change a hex code here. We change a font size there. We change a padding value there. We create chaos. We create anxiety for our users. They don’t know what to expect. They don’t trust the interface.
DESIGN.md is the reins. It is the consistent signal. It tells the developer, the designer, and the AI agent exactly what to expect. It creates a rhythm. A rhythm of trust.
When I started applying these principles to my work, everything changed. My designs became more consistent. My code became cleaner. My team stopped arguing about hex codes and started talking about intent. We stopped talking about what to build and started talking about why we were building it.
We found our rhythm. We found our trust.
How to Use It
Using DESIGN.md is simple. It is designed to be lightweight. It is designed to be integrated into your existing workflow.
1. Create the File
Create a file named DESIGN.md in the root of your project.
2. Define Your Tokens
Use YAML front matter to define your design tokens. Colors. Typography. Spacing. Shapes. Be precise. Use hex codes. Use pixel values. Be exact.
3. Write the Prose
Use Markdown to explain your decisions. Why did you choose this color? What is the intent behind this typography? What is the vibe of your brand? Tell the story.
4. Lint and Validate
Use the CLI tool to validate your file.
npx @google/design.md lint DESIGN.md
This will check for broken references. It will check for contrast ratios. It will ensure your design system is structurally sound.
5. Export and Use
Export your tokens to Tailwind, CSS, or JSON.
npx @google/design.md export --format tailwind DESIGN.md > tailwind.config.js
Now, your designers, developers, and AI agents all have the same source of truth. They all speak the same language. They all understand the intent.
The Promise
This is not just about code. It is not just about design. It is about the promise we make to our users.
When we are consistent, we are trustworthy. When we are clear, we are respectful. When we are intentional, we are humane.
DESIGN.md helps us keep that promise. It helps us build with integrity. It helps us build with soul.
I learned this from a horse. I learned that trust is earned through consistency. Through clarity. Through repetition.
DESIGN.md is the tool that allows us to keep that promise. It is the bridge between the human and the machine. Between the artist and the engineer. Between the rider and the horse.
It is the silent language of trust.
And it changes everything.
Getting Started
You don’t need to overhaul your entire workflow. You don’t need to rewrite your entire codebase. You just need to start.
Create a DESIGN.md file. Define your primary color. Write a sentence about why it matters. Lint it. Export it. Share it.
Start small. Be consistent. Be clear. Be intentional.
