Google's DESIGN.md: What the Design System Spec Means for Your Website

Web Design · October 6th, 2026 · 10 min read · By the Havenoro team

A markdown file on GitHub now has 26,300 stars, and the reason it exists is one of the least discussed shifts in web design this year. Google released a draft specification called DESIGN.md: a plain text file whose only job is to tell an AI coding agent what your brand looks like and, more importantly, why. It has 2,104 forks and 38 open issues. It is licensed under Apache 2.0 and it is, by Google's own labelling, at version alpha.

We think this is the most interesting thing to happen in web design in 2026, and not for the reason most people are excited about it. Nobody needs a new file format. What this actually tells you is that the layer of the job worth paying for has moved.

Here is what the spec does, how it compares to what you already use, and the question that appeared in the replies that we think matters more than the spec itself.

What is DESIGN.md and why did it take off?

DESIGN.md is a text file that describes your visual identity to AI coding agents. It pairs machine-readable design tokens with plain-language rationale, so an agent can make a correct decision about a colour or spacing value it has never seen before. It is an alpha-stage open-source spec from Google, not a web standard, and nothing on the public web requires you to have one.

26,300 GitHub stars for a specification file

2,104 Forks, meaning people shipped something

alpha The format version Google publishes it under

The mechanism is straightforward. You write a markdown file, and it does two jobs that a stylesheet cannot do at the same time. The first job is storage: exact colour values, type scales, spacing steps, border radii. The second job is judgement: the reasoning that tells an agent what to do when it hits a situation your file never anticipated.

That second job is the interesting one. A traditional stylesheet can say --color-red: #e63946. It cannot say "this red is reserved for one thing, and here is what that thing is, so do not use it for a button." Without the reasoning, a machine has to guess, and machines guessing at brand decisions is how you end up with a website that technically follows your stylesheet and looks like nobody made it.

What is actually inside a DESIGN.md file?

Two layers, and the split between them is the whole idea.

The first layer is YAML front matter, fenced at the top of the file. It holds the design tokens in a structured, machine-readable form. Colour tokens accept any CSS colour notation, including hex, rgb(), and lch(). Spacing tokens take a number plus a unit. There are also component tokens that map a component name to a group of properties, such as backgroundColor, textColor, typography, rounded, and padding. These tokens are normative. They are the values, and they are the part an agent obeys.

The second layer is the markdown body, organised into sections. This is the human-readable rationale: what the design is trying to feel like, which colour carries which meaning, when a heading should be large and when it should be small, what the spacing rhythm is meant to accomplish. This layer does not override the tokens. It gives them meaning.

Google also ships a CLI with an export command that converts tokens to other formats, and a linter that runs nine rules against a parsed file and returns findings as structured JSON, including WCAG contrast ratio checks. So the practical loop is: describe your design once, validate it, then export it wherever it needs to go.

The token structure is explicitly inspired by the W3C Design Token Format, which is the closest thing here to an actual standard. That lineage matters, because it means the values are not Google's private format. They are portable by design.

Here is the part that made people grumble, and it is worth taking seriously. A recurring question in the discussions was why this is not simply a globals.css file with a .md extension. Depending on your mood, that is either a fair criticism of the format or an accurate summary of the last forty years of software engineering. Both readings were present. Nobody settled it, which is a very efficient way to summarise every file format argument ever had.

How does DESIGN.md compare to what you already use?

This is the practical question for anyone running a business, and the honest answer is that DESIGN.md occupies a space the other options do not cover well. Your current setup almost certainly already handles values. Very few setups handle reasoning.

Four ways to record design decisions, and what each one can actually do
Approach	Stores values	Stores reasoning	Machine-readable	Portable across tools
CSS custom properties	Yes	No	Yes, for browsers only	Poor
Design tool tokens	Yes	Partially, as naming convention	Yes, inside one platform	Poor
Static brand guideline PDF	No	Yes	No	Fails at exactly the moment it is needed
DESIGN.md	Yes	Yes	Yes, for agents	Intended, at alpha

Capability comparison only. Nothing in this table is a requirement for a functioning website.

The brand guideline PDF row is not a strawman. It is what most small businesses actually have, and the failure mode is familiar. A studio signs off a 40-page PDF, hands it to a development team, and three months later the team discovers the guidelines never explained how the brand should behave on a slow connection, what an error message should sound like, or how much space belongs between two sections. Those are all design decisions. None of them were in the document.

The question in the replies that actually matters

Most of the reaction to the announcement was about the format. There was a directory of scraped DESIGN.md files within a day, a tool that generates them from any URL, and at least one person who genuinely believed Google had begun executing markdown files as a matter of policy.

The comment worth your attention was much quieter than that. Somebody asked: "I have no design rules. So how can I export them?"

That question is the whole thing. It is not a complaint about the spec. It is an accurate description of the state of the average business, and it is why this file format is going to keep spreading whether or not alpha survives. Most companies cannot fill in a DESIGN.md because they have never written down their design rules in the first place.

Every business already has a design system. It is called whatever Dave did in 2019, and it has never once been written down in a file that anybody could read.

That is the actual blocker, and it is not a technical one. Producing a usable design system means making and recording a set of decisions, and those decisions include:

Which colours mean what, and which one is reserved for a single purpose
How many type sizes exist, and which one wins in a given space
What the spacing scale is, and how it creates rhythm
How buttons, cards, and form fields behave, including hover and error states
What the brand feels like, in words a designer and a machine can both act on
Which combinations are forbidden, not merely discouraged

You can have every one of those answers already and still fail, if they live in four different people. This is the part we get asked about constantly, and the honest framing is that documenting a design system is not a file-writing exercise. It is a decision-making exercise. The markdown comes last.

Why this matters for how your site gets found in 2026

There is a second reason to care, and it is less discussed than the first.

Search is no longer the only thing reading your website. Answer engines and AI assistants read it too, and they are increasingly deciding what to say about your business before a human ever arrives. That is the situation our answer engine optimisation work exists to address.

The relevant shift is that these systems want structured information, not vibes. They want to know what your colours mean, what your products do, and how your claims are supported. A site with documented design intent is easier for a system to summarise accurately, and a site where the design decisions are implicit and inconsistent is a site that gets summarised confidently and wrong.

The pattern is worth stating plainly, because it is the same pattern underneath the whole file format story. Readmes first, then CLAUDE.md for agent behaviour, now DESIGN.md for visual identity. The format that wins will be the plainest one every tool can read. Every business that wants to be understood correctly by both people and machines is heading toward writing things down.

What we still do not know

Three things, stated plainly rather than glossed over.

The format will change. It is alpha, with 38 open issues. Expect the token schema, the section structure, and probably the CLI to move before anyone calls it stable. If you build tooling against it, build it loosely.

It competes. Other platforms have their own conventions for expressing design intent to agents. The argument that a text file wins because every agent can read a text file is strong, but it is not the same argument as one implementation winning.

Having one will not make your site look good. This is the part most commentary skips. A DESIGN.md faithfully describing a mediocre design system produces a mediocre website, faster. The format raises the floor for consistency and does nothing whatsoever for taste.

If you want the practical version, our custom website design process is where the design system gets built, and the cost estimator will price a scope before you talk to anybody.

Frequently asked questions

What is a DESIGN.md file?

A DESIGN.md file is a plain text file that describes a brand's visual identity so that AI coding agents can use it. It has two layers: machine-readable design tokens in YAML front matter, and human-readable design rationale in the markdown body. The tokens are the authoritative values, and the prose explains why each value exists and when it should be applied.

Do I need a DESIGN.md file for my website?

Almost certainly not yet. DESIGN.md is still an alpha-stage specification, and no browser renders it and no search engine reads it. What a business actually needs is the underlying asset: a documented design system covering colour, typography, spacing, components, and motion. A DESIGN.md file is only a portable, machine-readable way of recording that system.

What is the difference between DESIGN.md and CSS variables?

CSS variables store values that a running site consumes. DESIGN.md stores values plus the reasoning behind them, so an agent can make a decision about a colour or spacing value it has never encountered before rather than guessing. CSS custom properties answer what the value is. DESIGN.md also answers why it is that value and when it applies.

Is DESIGN.md an official web standard?

No. It is an open-source specification published by Google, licensed under Apache 2.0 and currently marked at version alpha. Its token structure is inspired by the W3C Design Token Format, which is the closest thing to an emerging standard, but DESIGN.md itself has no standards body behind it and the format is expected to change.

What are design tokens and why do they matter?

Design tokens are named values for things like colour, typography, spacing, and border radius, stored once and reused everywhere. Naming matters more than the storage mechanism: a token called surface-raised means something specific to everyone who touches the project, while a hex code means nothing about intent. Tokens are what let a design system be changed in one place instead of hunted down across dozens of files.

How much does it cost to create a design system for a small business?

A documented design system for a small business website is usually part of a full custom design engagement rather than a standalone purchase, and it adds roughly 15 to 20 percent to a custom web design project. A brand-only token library for a business that already has a working site can be produced in one to two weeks. The cost is driven by the decisions required, not by writing the file.

Should I document my design system before hiring a web design agency?

No. That work is usually the most valuable part of a design engagement, and arriving with a partial or incorrect system tends to anchor the project to decisions made without full context. What helps is having examples of what you like and dislike, a clear sense of who the site is for, and any existing brand assets such as a logo, colour list, or font licence.

Will AI replace web designers?

The execution layer is already largely automated, and that is precisely why the decision layer is becoming the paid work. Specs like DESIGN.md exist to give agents your decisions so a machine can produce competent output. Someone still has to decide what the decisions are. The scarce skill in 2026 is judgement about what to specify, not the ability to produce the artefact.