Google Opens Up DESIGN.md, a Format for Sharing Design Systems with AI Agents
Google has introduced DESIGN.md, an open alpha specification for sharing visual rules with AI agents. The file describes a design system and helps keep interfaces consistent.
Google has published an open specification for DESIGN.md, a file format for describing visual rules that AI agents can read when creating interfaces. According to a DEV.to article published on October 4, 2026, the specification was introduced by the Stitch team. The idea is for an agent to work from defined colors, typography, and components instead of trying to guess what someone means by “make it modern.” The format is still in alpha.
What Goes into DESIGN.md
The file has two layers. It starts with a YAML block containing machine-readable tokens for colors, typography, spacing, and border radii. That is followed by Markdown text explaining the design intent and rules for applying it. This gives the agent not just a color value, but also an explanation of the role that color plays in the design.
The format can also describe components. For a primary button, for example, you can specify its background, text color, padding, and corner shape, with the hover state defined separately. That is more precise than asking for “a prominent button.” After one redesign, I would only hand out requests like that with a definition of “prominent” attached.
The specification provides sections for overall design direction, palette, typography, grid and spacing, shadows, shapes, components, and usage rules. You do not have to fill in every section, but the ones you include must follow the prescribed order. The file describes not one successful screen, but a set of shared decisions for future screens and changes to them.
The repository includes an example called Heritage: dark headings, a warm, light background, and a separate color for interactive elements. It shows how to describe an interface’s character before writing code, not a palette everyone should use.
A command-line utility is available alongside the format. The command npx @google/design.md lint DESIGN.md checks, among other things, for invalid references between tokens and WCAG contrast compliance. It returns structured JSON that an agent can work with. There is also a command for comparing two versions of a design system, making it easier to spot differences in tokens and written rules.
What This Changes When Building a Website
The proposed workflow is to put DESIGN.md in the project root and have the agent read it before creating an interface. If a team uses several tools to work on a site, a shared file could eliminate the need to restate the visual requirements for each one. The article’s author sees interoperability as an argument for the specification: you can write similar instructions in notes alongside your CSS, but those notes have no common format.
For a website owner, this is not a way to get a design at the press of a button. Someone still has to choose the colors, fonts, and appearance of components. But once those decisions are made, they can be documented so a new screen does not look out of place on a familiar site. A marketer can discuss a specific design rule, while a developer can compare versions of it instead of interpreting yet another vague request.
There are limitations, too. The specification is still in alpha, and a file will not create a design system where decisions have yet to be made. The article mentions complaints about timeouts when connecting to Stitch via MCP and about Stitch feeling unintuitive. Those comments concern the experience of using the tool; it would be premature to treat them as a final verdict on the format.
Third-party projects have already sprung up around DESIGN.md: a directory of files collected from real websites and a tool for generating one from a page URL. But I would not accept a file generated from a website’s appearance without checking it. It might describe what is visible rather than what the people making the design decisions intended.
My Take: The Rules Matter More Than the File
I like the idea of documenting visual decisions in a way both people and tools can read. Especially when a site gets updated between other tasks: today someone edits a room description, tomorrow they add a page, and the day after that they discover the booking button is once again elegantly masquerading as decoration. A rule for what an action looks like on the site is more useful here than another request to “make it look nice.”
But I would not confuse a completed DESIGN.md with a successful interface. You can give an agent precise instructions on the palette and border radii, then hide the price so well that a guest changes their mind before booking. My test is simpler: can visitors see the full amount, understand what it includes, and move easily to booking? If the file helps preserve those decisions through updates, great. If it just adds to the project’s document collection, a nice name will not save it.
Sources
Where the news comes from. The text is a retelling in the author’s own words; the facts come from the source, the opinion is the author’s.
Client commissioning a website for a family guesthouse
I help my relatives rent out their guesthouse in Cyprus and update its website between bookings. I’ve already been through one redesign after which the booking button looked more like a decorative element.
All posts by the authorRelated articles
$mol Adds Node.js Storage Support and New UI Tools
August and September updates to $mol and Giper Dev include Node.js support in $mol_storage, new editor features, and UI tools. Here’s what developers should check.
Chrome to Add JPEG XL Support Starting with Version 155
Starting with Chrome 155, the browser will be able to open JPEG XL images. Site owners should compare the format with AVIF and check browser support before changing file formats.
Google Updates Its AI Content Guidelines: What to Check Before Publishing
Google has updated its AI content guidelines: texts need fact-checking and editing before publication. What does this mean for editorial teams and website owners?
Discussion 4
Kanat Esenov
In our training business, we’ve had the best results when the team documents a few practical rules—button states, heading styles, and which colors mean “primary”—before asking an agent to build a page. A DESIGN.md file could make that handoff repeatable, but I’d keep it simple enough that the next editor can update it without a developer.
Clara Ursu
On a recent project, documenting primary and secondary button states plus heading hierarchy stopped the agent from inventing inconsistent variants; the Markdown guidance mattered as much as the tokens, and the file stayed useful because the team could edit it directly.
Ulyana Babayan
@kiara_urso The agent can now stop inventing button variants and focus on inventing new ways to interpret “make it modern” 😄 Nice reminder that editable Markdown may be the most human-friendly part of the whole system.
Jānis Bērziņš
For our ceramics catalog, I’d start with a short rule for product cards—keep the piece’s proportions clear, use a consistent heading hierarchy, and don’t let decorative motion delay the photos. That’s easy for my team to edit and gives an agent less room to “modernize” away the details shoppers need.