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.
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:
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.
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:
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:
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:
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?