Coding agents are good at layout and bad at taste: left alone, they reach for
blue-500, a 6px radius and whatever font the framework ships with. A
DESIGN.md fixes that by giving the agent your real tokens and a few rules
before it writes any UI.
This guide covers what to put in one, where to put it, and how to stop it going stale.
What a DESIGN.md contains
A good one is short and literal. Agents follow exact values far better than adjectives like "clean" or "modern".
- Rules
- Two or three lines the agent must obey — "use these tokens for every colour, font size and radius; don't invent new hex values".
- Colour
- Each token with its value and its role: primary action, page background, body text, surface.
- Typography
- The font family and the size scale.
- Radius and spacing
- The steps the agent should pick from instead of making new ones.
- CSS
- The same tokens as a
:rootblock, so the agent can paste them into the project.
Write one in a minute
Open the free DESIGN.md generator and paste your
tokens — a :root block, your globals.css, a Tailwind config, token JSON, or
just hex codes.
Check the roles. Variables named --brand / --primary, --background,
--foreground and --surface become the rules for actions, page and text.
Rename a variable in the box to steer it.
Copy the result into DESIGN.md in your repository root.
Make your agent read it
Agents load a project instructions file on every session. Add one line to it:
| Agent | File | Line to add |
|---|---|---|
| Claude Code | CLAUDE.md | Follow DESIGN.md for every colour, font size and radius. |
| Codex, and agents that read AGENTS.md | AGENTS.md | Same line. |
| Cursor | .cursor/rules/design.mdc | Same line. |
| GitHub Copilot | .github/copilot-instructions.md | Same line. |
Then ask for UI the way you normally would. When the agent picks a colour, it now picks yours.
Keep it current
A DESIGN.md is a snapshot, so it drifts when your tokens change. Two ways to avoid that:
- Regenerate it whenever the tokens change — paste the new
:rootinto the generator and replace the file. - Let the agent fetch it. Connect your agent to Xtractly's
Agent Bridge and ask it to call
get_themewithformat: "design-md". It gets the current version of a saved theme every time, and can write the file itself.
Starting from a site you admire
If you don't have tokens yet, take them from a live site. Open the page, open
the Xtractly extension's Design System panel (Alt + F) and save the palette
and type scale as a theme. The theme exports as DESIGN.md, CSS, Tailwind,
shadcn/ui, design tokens or Figma variables — and your agent can read it over
the Agent Bridge. The brand pages show what that looks like for
well-known sites.