DESIGN.md is a single file that solves the main problem of vibcoding: “AI beige”

If you’ve ever generated an interface through Cursor, Claude Code, or Lovable, you’ll know the result. It's working. It looks like... nothing concrete. Greyish-white background, blue default button, Inter font, 16px indentations. Technically correct, visually – nothing.

This phenomenon is called “AI beige” – a visual “hospital average” result that gives a model when she has no idea about your brand. The Dashboard prompt, without additional context, almost always returns the same set of patterns because the model relies on the statistically most frequent decisions from the training data.

In March 2026, Google introduced a format that solves this problem systemically – DESIGN.md.

## What's DESIGN? md

DESIGN.md is an ordinary Markdown file that is placed at the root of the project. Inside is a description of the visual system of the product: color tokens, typography, indentations, the shape of the components, and the brand philosophy in free form.

The format first appeared in March 2026 as part of a major update to Google Stitch, an AI interface design tool that also included infinite canvas, a design agent with project memory and instant prototyping. In April 2026, Google opened the specification as a separate project under the Apache 2.0 license.

The idea itself is not new – DESIGN.md conceptually continues the line of files like README.md and AGENTS.md: put next to the code a file that is read not only by people, but also by agents, and fix the context in it once, rather than repeating in each prompt.

Today, the format is understood by the main AI development environments: Cursor, Claude Code, v0, Bolt, Codex, Aider and Stitch itself. If the root of the repository is DESIGN.md, the agent uses it as a source of truth in generating any UI code.

## What a file consists of: two layers in one document

The official specification describes DESIGN.md as a two-part file: YAML front matter with design tokens and a body in Markdown with the rationale for these decisions.

-
name: Heritage
colors:
primary: "#1A1C1E"
secondary: "#6C7278"
tertiary: "#B8422E"
neutral: "#F7F5F2"
typography:
h1:
fontFamily: Public Sans
fontSize: 3rem
body-md:
fontFamily: Public Sans
fontSize: 1rem
rounded:
sm: 4px
md: 8px
spacing:
sm: 8px
md: 16px
-

#Overview

Architectural minimalism meets with journalistic weight.
The interface should look like a premium matte surface.
An expensive newspaper or a modern gallery.

#Colors

**Primary (#1A1C1E):** Deep ink for titles and main text
**Tertiary (#B8422E):** "Boston Clay" is the only color for interactive elements

The logic is simple: tokens are specific values (#1A1C1E, 16px, Public Sans). Without them, the agent guesses colors. The prose part** is qualitative descriptions and justifications (“minimalistic like Linear”, “warm like Airbnb”). Without it, the agent knows the colors, but doesn’t understand the character – and can place them incorrectly.

The token system relies on the W3C Design Tokens specification, including the syntax of links between tokens of the type {colors.primary} – that is, one token can refer to another, and when the base value is changed, all associated ones will be updated automatically.

## File structure: 8 sections by specification

The official format describes eight sections. They may be omitted if they are not relevant to the project, but if they are present, they should go in that order. The model reads the file from top to bottom, so order prioritizes the context.

1. Overview (aka Brand & Style). A holistic description of the nature of the product: the identity of the brand, the target audience, the emotion that the interface should evoke. This is the basic context for any decisions not covered by the specific rules below - a kind of fallback for the agent.

**2. Palette with semantic roles: primary, secondary, tertiary, neutral. For each color - hex-value, descriptive name and rule of use. Without a semantic name, a model may, for example, mistakenly use the error color as an accent.

3. Typography. Levels of typography (usually 9-15: headers of different levels, body of text, signatures, labels). Tokens include fontFamily, fontSize, fontWeight, lineHeight, letterSpacing. Models need specific numbers - the wording "large font" is useless as an instruction.

4. Layout (aka Layout & Spacing). Grid and indentation strategy: grid-based, field-based, safe zones. Indentation tokens set the scale (sm, md, lg, xl).

5. Elevation & Depth. How visual hierarchy is communicated If shadows are used, their parameters (spread, blur, color) are set. For flat design, alternative techniques are described: boundaries, color contrast.

6. Shapes. Form language: curvature radii for buttons, cards and other rectangular elements through rounded tokens (sm, md, lg, full).

7. Components. Component-level tokens – each component is mapped to a group of properties: backgroundColor, textColor, typography, rounded, padding, size. The states (hover, active, pressed) are described by separate records with the associated name:

components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "{colors.on-tertiary}"
    rounded: "{rounded.sm}"
    padding: 12px
  button-primary-hover:
    backgroundColor: "{colors.tertiary-container}"

**8. Do's and Don'ts. * Explicit restrictions and prohibitions. Models respond well to negative instructions – what you can’t do is just as important as what you should do

##Do's and Don'ts
Use primary only for the most important action on the screen.
Do not mix rounded and sharp corners in one view
Observe the contrast WCAG AA (minimum 4.5:1 for plain text)
Do not use more than two fonts on the same screen

## How it works in practice

Standard project structure:

your-project
ы ─ DESIGN.md ← description of the design system
─ AGENTS.md ← Link to DESIGN.md for Agents
─ package.json
─ src/

In AGENTS.md, one line in the section about UI is enough:

## UI & Design System
Follow ./DESIGN.md for all visual decisions.

After that, any prop to the agent automatically takes into account the design system of the project. Instead of “make a button”, the agent makes a button in a given style – with the desired tokens, radius and hover state described in the file.

The difference between “before” and “after” is well documented: the same prompt “Build a modern dashboard” without DESIGN.md gives an average interface – the same AI beige. With a file - an interface with a specific character corresponding to the described system.

## Official CLI: lint, diff, export, spec

The format has an official @google/design.md package with four commands.

lint – checks the file for errors: broken links between tokens, contrast by WCAG AA, orphan tokens, section order, missing typography.

npx @google/design.md lint DESIGN.md

diff - compares two versions of the file at the token level, shows changes. Returns the output code 1 if regression is detected – convenient for CI.

npx @google/design.md diff DESIGN.md DESIGN-v2.md

export – converts tokens to Tailwind theme config or to tokens.json DTCG format (W3C Design Tokens Format).

npx @google/design.md export --format tailwind DESIGN.md
npx @google/design.md export --format dtcg DESIGN.md

spec - displays the full format specification. It is useful when you need to insert the context of the specification directly into the prompt agent.

npx @google/design.md spec
npx @google/design.md spec --rules --format json

## Where to get the finished file

Writing DESIGN.md from scratch for each project is a long time, especially if you need to pick up tokens, check the contrast and think through the wording for each section. Therefore, a small ecosystem of ready-made solutions has developed around the format.

Stitch (stitch.withgoogle.com) - you can generate DESIGN.md for free directly in the official Google tool: set brand colors and fonts, get a file on the output.

getdesign.md is a library of ready-made files for real brands: Stripe, Linear, Vercel, Notion, Airbnb and others. You download the right kind of file, put it in a repository, and the agent starts building a Linear-style interface without further explanation.

designmd.app is a larger library of templates with different aesthetic trends, from Y2K and brutalism to enterprise systems like IBM Carbon. It also contains detailed documentation on specifications and guides.

When choosing a finished file, it is worth remembering that the specification is officially in alpha status. The format evolves, and future versions may change the structure - it is worth periodically checking files through lint after updating dependencies or CLI.

## Connecting with AGENTS.md and why it is especially important for teams

If you are already using AGENTS.md to control the behavior of agents in a project, DESIGN.md is embedded in one line and starts working immediately. The logic is the same: do not explain the rules in each prompt, but fix them once in a file next to the code.

For teams, the effect is particularly noticeable. In the past, two developers working in parallel at Cursor and Claude Code on the same project inevitably created a visual drift - each agent interpreted "modern minimalist design" in its own way in the absence of specifics. DESIGN.md at the root of the repository acts as a single source of truth for all agents at the same time, regardless of who generates the code and in what tool.

## Format limitations

DESIGN.md is not a replacement for a complete design system. It does not manage application states, does not check animations, does not validate availability at the component level (although the linter checks for color contrast at the token level). This is the context for an agent, not a production-ready pipeline design token.

For a serious product, DESIGN.md is more logical to consider as a starting point or as a layer between Figma and code, but not as a replacement for both.

The quality of the result depends on the quality of the file. Superficial DESIGN.md with three colors and one font will give a minimal effect compared to default. A well-designed file – with all eight sections, meaningful semantic token names, and a clear philosophy in Overview – yields a fundamentally different result.

And then there's the alpha format. This means that the specification may change, and the syntax in older ready-made files from libraries may over time diverge from the current version of the CLI. Running lint after updates is no extra precaution.

## Outcome

DESIGN.md is AGENTS.md for the visual part of the project: a single file at the root of the repository that tells agents once “this is what it should look like and why” – instead of repeating it in each prompt.

The format combines exact tokens in YAML (for specific values) and textual explanations in Markdown (for intent and context), a combination that distinguishes it from conventional token files like tokens.json, which the model can read but cannot interpret.

For a single Vibcoder, this means the end of AI beige effortlessly. For the team, there is visual coherence between parallel agents. The easiest way to try it is through a ready-made library: take a file under a similar brand from getdesign.md or designmd.app, put it in the project and compare the result of generating UI before and after.