Google DESIGN.md : the open-source standard that gives code agents a visual memory

Google DESIGN.md : the open-source standard that gives code agents visual memory

🔎 Code agents know how to code, but they are blind to design

Since late 2024, code agents have exploded. Claude Code, Cursor, Copilot — all generate functional interfaces in a matter of seconds. Except that a recurring issue ruins the experience: the visual result is almost always disappointing.

Colors drift from one component to another. Spacing is inconsistent. Typographies do not respect any hierarchy. Even worse, if you ask the agent to fix a button, it can break the harmony of the entire page.

On April 21, 2026, Google Labs released a structural answer to this problem: the DESIGN.md spec, under the Apache 2.0 license. In a few weeks, the official repo and the community collection awesome-design-md surpassed 22,000 combined GitHub stars. A strong signal: the dev community had been waiting for this format for a long time.

DESIGN.md is to design what AGENTS.md is to code conventions. A single file, readable by a human and interpretable by an agent, that encodes the entire visual identity of a project. No more hex code hallucinations. Agents finally know why a color exists and what it is used for.

The essentials

• DESIGN.md is an open format created by Google Labs to describe a visual identity in a structured way that is interpretable by code agents.
• The official repo surpassed 10,000 stars in 8 days, and the community collection awesome-design-md reaches 68,000+ stars (April-May 2026 data, Kristopher Dunham/Medium).
• It integrates design tokens, components, typography, spacing, animations, and WCAG validation.
• The format is already integrated into Stitch, Google Labs' design tool, with export/import between projects.
• It is a bridge between the designer's intent and execution by the agent — not a design tool, a communication protocol.

Recommended tools

Why code agents are catastrophic at design

The fundamental problem: the lack of visual memory

A code agent like Claude Opus 4.7 or GPT-5.5 does not "see" your design system. It reads your files, it interprets your system prompt, but it has no structured representation of your visual identity.

In practice, here is what happens: you give it a Figma site or text instructions like "use dark blue and rounded corners". The agent generates a first component — correct. Then you ask it for a second component in another file. There, it reguesses the colors, the spacing, the font sizes. With each generation, there is a drift.

According to the analysis by Kristopher Dunham, code agents "hallucinate hex codes and drift visually from one generation to the next". This is not a model bug. It is a format problem: there was no standard for transmitting a design system to an agent in a persistent and unambiguous way.

The system prompt is not enough

Many devs try to mitigate this problem by stuffing their system prompt with visual rules: "primary color: #1a56db, border-radius: 8px, font-size: 14px...". This works roughly for a single component. But as soon as the project grows, the prompt becomes unmanageable.

A real design system contains dozens of tokens, interaction rules, component states (hover, focus, disabled), accessibility constraints. All of this does not fit in a prompt. And above all, a prompt is linear — a DESIGN.md is structured into sections that the agent can query selectively.

It is not a model problem

Claude Opus 4.7 (94.3 on the agentic benchmark) or GPT-5.5 (98.2) are not "bad at design". They are poorly informed. Give them a well-written DESIGN.md, and the same models produce consistent interfaces. The problem lies in the transmission channel, not in the receiver.

What DESIGN.md exactly is — and what it is not

A spec, not a tool

DESIGN.md is not a software. It's a file format — a specification that describes how to organize a project's visual information so that a code agent can understand it. The file sits at the root of your project, at the same level as your AGENTS.md or your README.

The most accurate comparison comes from the designmd.app site: "DESIGN.md is to design what AGENTS.md is to code conventions". It is not a visual design system (like Figma). It's the textual representation of that design system, in a format that agents can parse.

The structure of the spec

The format, as defined in the GitHub repo, is organized around several sections:

• Design tokens: colors, spacing, shadows, border radii — the atoms of the system.
• Typography: families, sizes, weights, line heights, modular scale.
• Components: buttons, inputs, cards, modals — with their states (default, hover, focus, disabled, error).
• Layout and grid: breakpoints, templates, max-widths, gutters.
• Animations and transitions: durations, easing, allowed movements.
• Accessibility (WCAG): minimum contrast ratios, touch target sizes, tab order.
• Visual patterns: composition, alignment, and hierarchy rules.

Each section is structured to be unambiguous. No "use a nice shade of blue". But rather: primary: #1E40AF, on-primary: #FFFFFF, contrast-ratio: 7.1:1 (WCAG AAA).

What DESIGN.md is NOT

It is not a replacement for Figma. It is not a design tool. It is not a CSS framework. It is not a prompt template. It is a communication protocol between a designer (or a dev doing design) and a code agent. The designer writes the file. The agent reads it and complies with it.

How DESIGN.md solves the consistency problem

From intent to code, without information loss

The conceptual breakthrough of DESIGN.md is that the agent no longer receives just values — it receives reasoning. The spec explicitly includes why a color exists, in what context it is used, and what its constraints are.

When the agent reads that surface-elevated: #FFFFFF is used "for cards and modals that float above content, with a level 2 shadow", it won't apply it to a page background. The intent is encoded in the token.

Built-in WCAG validation

This is a detail that matters: the spec includes accessibility requirements directly in the tokens. When you declare a text/background color pair, you include the contrast ratio and the target WCAG level.

The agent can no longer generate light gray text on a white background "because it looks clean". The DESIGN.md tells it that the minimum ratio is 4.5:1 (AA), period. It's a safety net that didn't exist before.

Persistence between sessions

The DESIGN.md file lives in the repo. It doesn't change between two coding sessions. The agent rereads it with every new task. Result: a component generated on Monday is visually consistent with the one generated on Thursday. This is the "visual memory" promised in the title — not a memory in the model, but a memory in the project.

The ecosystem building around the format

Stitch: the reference integration

Google Labs didn't just publish the spec. They integrated it into Stitch, their experimental design tool. In Stitch, you can export your project's rules to DESIGN.md, and import them into another project.

David East, from Google Labs, presented this feature in an explainer video on April 21, 2026. The idea: a designer configures their design system in Stitch, exports the DESIGN.md, and drops it into the dev's repo. The code agent reads the file and generates UIs that match the brand — not an approximation, but a faithful translation.

awesome-design-md: the community collection

The community immediately created awesome-design-md, a collection of DESIGN.md files for well-known design systems (Material Design, Tailwind, custom systems). In just a few weeks, this repo alone reached 68,000+ stars (according to the account by Kristopher Dunham). A signal that devs want ready-to-use templates, not just an abstract format.

Templates and practical guides

Resources sprang up almost immediately. BuildMVPFast offers a template + guide for creating a functional DESIGN.md with Cursor, Claude Code and Copilot. designmd.app serves as an explanatory hub. The ecosystem resembles what happened around AGENTS.md: a simple standard, quickly adopted, with an explosion of community resources.

What this changes for designers

The designer becomes an author of specs, not pixels

This is perhaps the most profound change. Today, a designer spends hours on Figma pixel-perfecting interfaces. Then a dev (or an agent) approximately transcribes them into code. The final result never exactly matches the mockup.

With DESIGN.md, the designer's role evolves: they no longer produce static mockups, they produce an executable spec. DESIGN.md becomes the main deliverable. The code agent becomes the faithful executor.

A possible new workflow

The ideal workflow looks like this: the designer defines their design system in Stitch (or directly in DESIGN.md), exports the file, commits it in the repo. The dev or code agent reads the spec and generates the components. The designer reviews the result in production — not in Figma.

This workflow already partially exists in teams that use design tokens in JSON. But DESIGN.md goes further: the format is readable in natural language, not just by machines. A human can read it and understand the design system. An agent can too.

The (real) threat to component design

Let's be direct: if your work as a designer essentially consists of drawing buttons and cards in Figma, DESIGN.md + code agents makes this task obsolete. The agent can generate dozens of component variants in a few seconds, all consistent with the spec.

What remains irreplaceable: brand strategy, visual hierarchy decisions, the overall user experience, aesthetic judgment. DESIGN.md automates the execution, not the thinking.

Initial community feedback

Immediate enthusiasm on Reddit

On the subreddit r/WebAfterAI, the discussion quickly turned to enthusiasm. Early user feedback confirms the problem: "I spent half my time fixing the colors and spacing the agent made up." With DESIGN.md, the same users report immediate visual consistency.

Comparisons with other approaches are revealing. Some had tried putting their design system into CSS variables and asking the agent to use them. It worked partially — but the agent didn't understand the semantics of the tokens. DESIGN.md adds the missing semantic layer.

The trajectory toward an industry standard

The article from Design Bootcamp asks the question bluntly: will DESIGN.md become an industry standard? The signals are positive. The format is open, simple, solves a real problem, and initial adoption is massive.

The parallel with AGENTS.md is illuminating. The latter started as an informal convention and is now natively supported by most agents. DESIGN.md is following the same trajectory: a Google repo, an active community, integrations popping up.

Limitations raised

A few nuanced voices are worth mentioning. First, the quality of the DESIGN.md depends entirely on the person writing it. A poorly written spec produces mediocre results — the classic garbage in, garbage out. Second, the format is young. Not all agents natively support it yet. Finally, translating a complex design system (with sophisticated interactive states) into structured text remains a difficult exercise.

How to use DESIGN.md with current agents

With Claude Code and Claude Opus 4.7

Claude Opus 4.7 excels at interpreting structured specs. Place your DESIGN.md at the root of your project and reference it in your initial instruction: "Strictly follow the DESIGN.md file for all visual decisions". The agent will read the file and comply with it component by component.

The advantage of Claude Opus 4.7: its ability to understand the reasoning behind the tokens, not just the values. If your spec says a color is reserved for destructive actions, it won't use it for a "Save" button.

With Cursor and GPT-5.5

GPT-5.5 (agentic score 98.2) is the most powerful model for this type of task. In Cursor, add a rule to your .cursorrules: "Always read DESIGN.md before generating or modifying a UI component". The model will apply the tokens with remarkable fidelity.

Autonomous code agents like those found in the best autonomous AI agents can also benefit from the format. An agent like DeerFlow de ByteDance, which works over the long term, has an even greater need for stable visual anchoring. Without DESIGN.md, an agent coding over several days will visually drift. With it, it stays aligned.

With open-source and local models

Since the format is in plain text, it works with any model capable of reading files — including models hosted locally via Ollama. Kimi K2.6 Moonshot AI (88.1 on the benchmark) or GLM-5 from Z.AI (82) can correctly interpret a well-structured DESIGN.md. The quality of the interpretation will be lower than GPT-5.5, but the format remains readable.

For sensitive projects that require local hosting, DESIGN.md is a major asset: no need to send your Figma mockups to a third-party cloud. The spec lives in your repo, your agents read it locally.

DESIGN.md in the broader context of search agents and autonomous agents

A challenge for agents that create interfaces

The problem that DESIGN.md solves goes beyond the solo dev use case. Industrial search agents like OpenSeeker-v2, which search for and synthesize information, are increasingly generating interfaces. Without a visual spec, each generated page has its own look.

Autonomous agents that code over the long term — like ByteDance's DeerFlow — have a critical need for DESIGN.md. When an agent works on a project for days, visual drift is inevitable without an anchor point. DESIGN.md becomes its compass.

The intersection with AI tools for marketing and SEO

For marketing teams using AI tools for marketing or AI tools for SEO, visual consistency is a business issue. A landing page generated by an agent that doesn't follow the brand guidelines means a collapsing conversion rate.

DESIGN.md allows marketing teams to define a visual spec once, and distribute it to all agents generating front-end content. The designer no longer becomes a bottleneck — they become an architect.

❌ Common mistakes

Mistake 1: Copy-pasting a DESIGN.md found online without adapting it

A DESIGN.md for Material Design won't work for your SaaS startup. The tokens, components, constraints — everything must match your product. Use community templates as a starting point, not as a finished product.

Mistake 2: Including too much or too little detail

A 3-line spec ("dark blue, rounded corners, sans-serif font") is useless — the agent will guess everything else. A 2,000-line spec with every micro-state of every component is counterproductive — the agent will lose the thread. Aim for 200-500 lines for a standard project. Cover the tokens, the 5-10 key components, and accessibility rules.

Mistake 3: Not including interactive states

This is the most common mistake. You define a primary blue button, but you forget the hover, focus, disabled, and loading states. The agent will invent these states — probably poorly. Every interactive component must list all its states with their associated tokens.

Mistake 4: Ignoring the accessibility section

Many devs treat the DESIGN.md as a file of colors and spacing, and skip the WCAG section. This is a mistake. Accessibility validation is one of the key advantages of the format. Without it, your agent will generate inaccessible interfaces — and you will inherit the debt.

Mistake 5: Placing the file in the wrong location

The DESIGN.md must be at the root of your project, where the agent naturally finds it. If you bury it in a /docs/design/ folder, some agents won't discover it. The convention is clear: repo root, exact name DESIGN.md.

❓ Frequently Asked Questions

Does DESIGN.md replace Figma?

No. DESIGN.md is a textual format that describes a design system. Figma is a visual design tool. The two are complementary: you can design in Figma, then translate your decisions into DESIGN.md. Google Labs' Stitch does precisely this bridging.

Which code agent supports DESIGN.md natively?

No agent "supports it natively" in the sense of a hardcoded integration (June 2026). But all agents capable of reading project files — Claude Code, Cursor, Copilot — will correctly interpret a well-formatted DESIGN.md if it is referenced in the instructions.

Does it work with free models?

Yes, the format is text. Models accessible via APIs IA gratuites like Groq or OpenRouter can read and interpret a DESIGN.md. The execution quality will be lower than GPT-5.5, but the format remains functional. For tight budgets, this is an excellent use case for meilleurs outils IA gratuits.

Can a non-technical designer write a DESIGN.md?

Yes. The format is in structured natural language, not code. A designer can write it without knowing CSS. The tokens section uses simple key-value pairs. The components sections describe states in French or English. The guide de designmd.app is a good starting point.

How long does it take to create a DESIGN.md?

For an existing project with a mature design system: 2 to 4 hours to translate your rules into the DESIGN.md format. For a new project: allow 1 to 2 hours to define the base tokens and components. It is an investment that pays off as soon as the first components are generated by the agent.

Is DESIGN.md compatible with Tailwind CSS?

Yes, and it is even an ideal use case. You can express your tokens in Tailwind values (blue-600, rounded-lg, text-sm). The agent will translate them directly into Tailwind classes. The spec does not dictate the technical implementation — it dictates the values and semantics.

✅ Conclusion

DESIGN.md does not solve an AI model problem — it solves a communication problem between human and machine. By giving code agents a structured, persistent, and semantic representation of a design system, Google Labs has bridged the last major gap between design and generative code.

The format is young, the ecosystem is exploding, and the initial adoption leaves little doubt about its trajectory. If you use a code agent on a daily basis, add a DESIGN.md to your next project. The time invested in the spec will be recovered a hundredfold on component iterations.

To go further into the tools that integrate this type of spec, check out our selection of the meilleurs outils IA pour le code — and for the agents that need it the most, our comparison of the meilleurs agents IA autonomes.