Guide

What is design.md?

design.md is a plain text file that describes your design system: your colors, fonts, spacing, components and the rules for using them. You put it in a project and tell your AI coding tool to follow it, so the screens it builds match your design instead of its guesses.

Why AI tools need one

Ask an AI tool to build a settings page and it will. But it has never seen your brand, so it picks a blue it likes, spacing that looks about right, and a button style from somewhere on the internet. Ask for a second page and it picks slightly different ones. After a week, no two screens quite match.

A design.md gives it the answers before it starts: which blue, which spacing steps, what a button looks like in every state, and rules like “one main button per screen”. It works the way a style guide works for a new designer on your team, except the reader is an AI and the guide is written so it can follow it to the letter.

What goes in a good design.md

The excerpts below come from Harbor, an example system made with the builder for a finance product. Every design.md the builder makes has the same parts.

A short header

A few lines at the top that say what the system is called, which themes it has and which icons it uses. Tools can read them at a glance.

---
name: Harbor
version: 1.0.0
generator: Design System Builder
tokens: harbor.tokens.json
modes: [light, dark]
default-theme: light
component-shape: rounded
icons: lucide (outline, stroke 1.75)
---

Rules, first

Numbered do's and don'ts that the AI reads before anything else. They catch the most common mistakes, like typing in a color by hand instead of using the system's.

## Rules (read first)

1. **Use semantic tokens only.** Use `color.*`, `space.*`, `radius.*`, `shape.*`, `typography.*`. Never hard-code hex values, px values or font sizes, and never use `palette.*` directly in UI.
2. **Only use the color pairings listed here.** Text on `accent` uses `on-accent`, text on `positive-subtle` uses `positive-text`, and so on. Every listed pair is contrast-checked. An unlisted pair is not.
3. **Design for light and dark.** Never assume a white background. Use `bg` / `surface`, not white.
4. **Spacing comes from the scale.** If a value isn't on the scale, use the nearest step.
5. **Controls use `shape.control`, containers use `shape.container`.** Don't mix radii by hand.
6. **One primary button per view or section.** Other actions use secondary, outline or ghost buttons.

Token names

Tokens are your design decisions saved as named values. Instead of #4f46e5, the AI writes color.accent. Change the color once and everything that uses the name follows. design.md lists every name and how it appears in code.

Color, with approved pairings

Besides the colors themselves, a good design.md lists which text and background colors may go together. Each pair has been checked for contrast in light and dark mode, so text stays readable for everyone.

### Approved pairings (contrast-checked)

| Foreground | Background | Light | Dark | Requirement |
| --- | --- | --- | --- | --- |
| `text` | `bg` | 17.83 | 19.24 | 4.5 text |
| `text` | `surface` | 17.83 | 17.07 | 4.5 text |
| `text-muted` | `bg` | 7.55 | 7.62 | 4.5 text |
| `text-muted` | `bg-subtle` | 7.23 | 6.76 | 4.5 text |
| `text-muted` | `surface-raised` | 7.55 | 5.56 | 4.5 text |
| `text-inverse` | `surface-inverse` | 17.83 | 16.25 | 4.5 text |

Typography, spacing, shape and more

Your text styles, the spacing scale, corner radius, borders, layout grid and breakpoints (the screen widths where a layout changes), icons, shadows and motion. Each comes with the rule for using it, not only the values.

Components and their states

Buttons, text fields, tabs and the rest: their sizes and variants, which tokens they use, and how they look when hovered, pressed, focused or disabled. This is where AI tools most often go wrong without a guide.

### Button

Use buttons for actions. Use a link for navigation.

| Size | Height | Padding x | Text | Icon | Icon gap |
| --- | --- | --- | --- | --- | --- |
| `sm` | 32 | `sm` 12 | `label-md` | 16 | `xs` 8 |
| `md` | 40 | `md` 16 | `label-md` | 16 | `xs` 8 |
| `lg` | 48 | `lg` 24 | `label-lg` | 20 | `xs` 8 |

An accessibility checklist

A last list for the AI to check its work against: readable contrast, visible focus, labels for icon buttons, and respect for people who turn off animation.

Open Harbor's full design.md to see all of it. It opens as plain text, the way an AI tool reads it.

design.md, tokens, CSS and Tailwind: what's the difference?

The builder exports the same system in several formats, for different readers. They all come from the same choices, so they always match.

The other files hold values. design.md also holds the reasons and rules, which is what an AI needs to make good choices on its own.

How to use it with your AI tool

In AI coding tools

Save design.md in the main folder of your project. Then point your tool to it from its instructions file: a file the tool reads at the start of every task.

• Codex, Cursor, GitHub Copilot and many others read AGENTS.md. Add a line like the one below.
• Claude Code reads CLAUDE.md. A line with @design.md pulls the whole file in.

## Design
Before building or changing any screen, read design.md and follow its rules.
Use only the tokens it lists. Never type in colors, sizes or fonts by hand.

@design.md

If your tool uses a different file, its documentation will say which. The line to add is the same.

In chat assistants

For ChatGPT, Claude and other assistants that can open web pages, you don't need the file at all. In the builder's Export step, copy the link for AI tools and paste it into the chat. The link opens as your design.md.

A first prompt to try

Build a settings page with a profile form and a save button.
Follow design.md: use its tokens, its Button and Text field specs, and check
the result against its accessibility checklist.

Make yours in a few minutes

1. Go through the builder's steps, from Brand to Components. Each one starts with good defaults, so skip any you're happy with.
2. Watch the live preview change as you go, in light and dark, on phone and desktop sizes.
3. Download design.md from the Export step, along with tokens, CSS or Tailwind if you need them.

Common questions

Is design.md an official standard?

Not quite. It's a convention: a Markdown file with a predictable name that AI tools are told to read. In 2026 Google Labs published an open DESIGN.md format, still in alpha, with tokens in the header and a set order of sections. The builder's design.md covers the same ground in its own layout, and works with any tool that reads Markdown.

Do I need to know how to code?

No. You make your choices visually in the builder, and it writes the file. Whoever builds the product, a developer or an AI tool, uses it from there.

Which AI tools does it work with?

Any tool that can read a file in your project, such as Claude Code, Cursor, Codex, GitHub Copilot and Windsurf, and any chat assistant that can open a web page, using the link for AI tools.

What happens when I change my design?

Change it in the builder and export again, then replace the old file. Every export comes from the same choices, so design.md, tokens, CSS and Tailwind stay in step.

Is it free?

Yes. There's no account, and your systems save in your browser, so nothing is uploaded. Use Share to send a system to someone else.