Use with AI / DESIGN.md

DESIGN.md

DESIGN.md is the design file AI coding agents read before they build UI: exact tokens at the top, the reasoning below. Here is what goes in one, how each tool reads it, and 16 ready-made files.

5 min readformat: alphaexample: Lagoonupdated Oct 17, 2026

What a DESIGN.md file is

DESIGN.md is a plain-text file that describes a visual identity to coding agents. It has two layers: design tokens in YAML front matter at the top, and the reasoning behind them in Markdown below. The tokens give an agent exact values, and the prose tells it when and why to use them.

The format is an open specification from Google Labs, published as google-labs-code/design.md on GitHub together with a linter, a diff tool and an exporter. It is still marked alpha, so expect small changes as it matures.

Because it is just Markdown, every AI coding tool can read it: Claude Code, Claude Design, Cursor, Lovable and v0 all take it as context, and you can read and edit it yourself in any editor.

What goes in it

The front matter holds the tokens: colors, typography, rounded corners, spacing and components, where each component points at the tokens it uses. Below it come up to eight sections, always in this order:

  • Overview · the character of the style in a few sentences
  • Colors · what each color role is for
  • Typography · which font and weight carry which role
  • Layout · the grid, spacing and density
  • Elevation & Depth · how surfaces separate
  • Shapes · the corner radius and its pairings
  • Components · buttons, fields, cards and their states
  • Do's and Don'ts · rules an agent can check its work against

Here is the top of a real one, the DESIGN.md of Lagoon, our free style:

vibecoded-lagoon/DESIGN.md
1version: alpha
2name: "Lagoon"
3description: "Clear, roomy, dependable. A deep teal and mist system ..."
4colors:
5 primary: "#144948"
6 primary-foreground: "#ffffff"
7 background: "#eef1f1"
8 card: "#ffffff"
9 muted-foreground: "#5e5658"
10 border: "#e3e8e8"
11 ring: "#3c8a7f"
12 # ... 60 more color roles
13typography:
14 heading-lg:
15 fontFamily: "Inter"
16 fontSize: 24px
17 fontWeight: 700
18 lineHeight: 1.25
19 # ... display, body, label and code roles
20rounded:
21 "none": 0px
22 "sm": 8px
23 "md": 11px
24 "lg": 14px
25components:
26 button-primary: # one per view; padding is horizontal
27 backgroundColor: "{colors.primary}"
28 textColor: "{colors.primary-foreground}"
29 typography: "{typography.label-md}"
30 rounded: "{rounded.button}"
31 height: "{spacing.control-md}"
32 padding: "{spacing.4}"
33---
34
35## Overview
36
37Lagoon is the dependable workhorse of the family: misty
38blue-gray surfaces, a deep teal accent that turns into bright
39aqua in dark mode, and Inter throughout. Controls are roomy at
4044 px, buttons and badges are full pills and cards use 20 px
41...
noteSections an agent does not know are kept, so a file can add its own, such as Responsive Behavior or an Agent Prompt Guide. Ours add both.

How AI tools read it

Each tool has its own place for project context. The file stays the same; only where you put it changes.

Claude CodeOne line in CLAUDE.md points every session at the file; the design skill loads it when you ask for UI. Read the guide
Claude DesignUpload it with the theme and a few screens, and Claude Design builds your design system from them. Read the guide
CursorAdd it as a project rule, so every chat and edit follows it. Read the guide
LovablePut it in the project knowledge and paste the theme once. Read the guide
v0Attach it with the theme, or import the pack once as a design system. Read the guide

Writing a good DESIGN.md

  • Name colors by role, such as primary, muted-foreground or border, so the agent picks by meaning and never by shade.
  • Give every role a value in light and dark mode, and keep text at 4.5:1 contrast against its background.
  • Add a component entry for each state that looks different: button-primary, button-primary-hover, button-primary-disabled.
  • Write the Do's and Don'ts as rules a reviewer could tick off: one primary button per view, labels above fields, an empty state with a next step.
  • Keep the prose short and concrete. Say what a value is for, and leave out what any designer would assume.

Then lint it. The official CLI checks the structure, broken token references and WCAG contrast, and reports in JSON an agent can act on:

terminal
1npx @google/design.md lint DESIGN.md

The same CLI exports the tokens to a Tailwind v4 theme or to DTCG tokens, which helps when you start from DESIGN.md and need the code side too:

terminal
1npx @google/design.md export --format css-tailwind DESIGN.md > theme.css

DESIGN.md, the theme and the skill

DESIGN.md sets the rules, but an agent still needs the values in code and a nudge to use them. That is why every Vibecoded style ships three files that work together:

DESIGN.mdThe rules: roles, states, layout and the do's and don'ts. Read by every agent.
theme.cssThe values as shadcn/ui and Tailwind v4 variables, so components read the right color with no raw hex. See the 16 themes
skill/An agent skill that tells Claude Code which component to reach for and when to read DESIGN.md. About design skills
tipIf a screen drifts, ask the agent to compare it with DESIGN.md and list what differs. Fixing from that list is faster than a new prompt.

16 ready DESIGN.md files

Every style below comes with a complete DESIGN.md of about 650 lines, linted and contrast-checked in light and dark, next to the theme, the tokens, the agent skill and a Claude Design kit. Each one is original, drawn by our studio in Budapest. The Lagoon Style Pack is free.

Questions

What is DESIGN.md?

A Markdown file that describes a design system to AI coding agents: tokens in YAML front matter, and the reasons behind them in prose. It comes from an open Google Labs specification.

Where do I put DESIGN.md in my project?

Anywhere the agent can read it, usually the project root or the folder of your design pack. Then point your tool at it: a line in CLAUDE.md for Claude Code, a project rule in Cursor, the project knowledge in Lovable.

Is DESIGN.md the same as a style guide?

It is a style guide written for an agent. The tokens are exact and machine-readable, and the prose is short enough to fit in the context of every request.

Can I turn DESIGN.md into Tailwind or design tokens?

Yes. The official CLI exports a Tailwind v4 theme, a Tailwind v3 config or DTCG tokens. Our packs already include theme.css and DTCG tokens generated from the same Figma library.

Does DESIGN.md work with Cursor, Lovable and v0?

Yes. Any tool that reads project files or context can use it. Our setup guides show the exact place for each tool.

Are the Vibecoded styles copies of real brands?

No. Every style is an original design system drawn by our studio, with its own colors, type, motifs and illustrations.

Try a complete DESIGN.md for free

Lagoon comes with its DESIGN.md, theme, tokens and agent skill, for an email address.

Was this page helpful?