How to stop re-explaining your design system to every AI tool

You ask Claude Code for a settings page. What comes back works, except the spacing is not your spacing, the grey is close to your grey without being it, and the corners are rounder than anything else you ship. So you fix it by hand. Tomorrow you ask for a modal and fix the same three things again.

Nothing there is a bug

The tool had no way to know. It picked something reasonable, because reasonable is all it had.

Your design system lives in a Figma library, a token file, and the heads of two people who have been there longest. None of that is readable at the moment a tool generates a screen. So it guesses, and it will keep guessing every session until something tells it otherwise.

Google shipped a format for this

Google Labs open-sourced DESIGN.md on April 21, 2026, pulling it out of Stitch so it works across tools. Their stated reason is the one above: instead of guessing intent, an agent can know exactly what a colour is for, and check its choices against WCAG rules.

The specification is a single markdown file with YAML front matter for machine-readable tokens and a markdown body for the reasoning behind them. It defines eight sections in a fixed order: Overview, Colors, Typography, Layout, Elevation and Depth, Shapes, Components, and Do's and Don'ts.

The front matter is what a tool reads. The prose is what stops the next designer undoing a decision they did not know was deliberate. Both halves in one file is the actual idea.

Engineers got there first

This pattern is not new, it just arrived in design last.

AGENTS.md does the same job for build steps and conventions, the things a README leaves out because a human contributor would look around and infer them. More than 20 coding tools read it. It is in over 60,000 open-source projects. On December 9, 2025, the Linux Foundation folded it into a new Agentic AI Foundation alongside Anthropic's Model Context Protocol and Block's goose.

That is what a settled format looks like. DESIGN.md is at alpha and has not earned that yet, which is an argument for writing the file, not for waiting.

Write the sections that get guessed wrong

Eight sections is the full spec. You do not need all eight on day one.

Start with Colors, Typography and Layout, because those are what a tool invents first. Write real values. A hex code, not "our brand blue". A spacing scale as numbers, not "keep it consistent". Then add Do's and Don'ts, which is the section that carries the most and takes the least time, because it is where you write down the correction you keep typing.

Components last, once you know which ones a tool keeps reinventing.

What the file will not do

It will not make the output good. Layout, hierarchy and whether the screen should exist at all are still yours, and a tool that knows your spacing scale can still hand you a badly organised page with immaculate spacing.

What it removes is the correction you were making by hand every session that never taught the tool anything.

The design system your tools can actually read

Twenty minutes: three sections, real values, saved next to your work. Point the tool at it before the next prompt instead of correcting it after.