DESIGN.md is a Markdown file in your project that describes your design: colors, fonts, type sizes, spacing, corners and the rules for using them.
Coding agents like Claude Code, Cursor and Codex read it before they write UI, so every screen they build follows the same design.
Why agents need it
Every new chat starts from zero. Without a written design, each page drifts a little: a new shade of blue here, another corner radius there, a third button style. After ten prompts the product looks like ten products.
A DESIGN.md fixes the values once. The agent reads them every time instead of guessing.
What goes in it
- The look in one sentence, so the agent knows the intent behind the numbers.
- Colors with roles: canvas, surface, text, muted text, border, accent, and what the accent is for.
- Type: families, weights and the size scale, with line height.
- Spacing and shape: the grid, section gaps, content width, corner radii, borders and shadows.
- Rules: what to always do and what never to do.
An example
# Design A calm, light interface with one teal accent and tight type. ## Colors - Canvas #FBFBF8, surface #FFFFFF, border #E4E4E0 - Text #18181B, muted text #6B6B70 - Accent #0F766E: primary buttons and links only ## Type - Headings: Instrument Sans 600, 44 / 28 / 20px, tracking -0.02em - Body: Instrument Sans 400, 16px, line height 1.6 ## Spacing and shape - 4px grid, sections 96px apart, content 1120px wide - Corners: 6px on controls, 12px on panels, pill tags - Depth from borders, no shadows ## Rules - One primary button per screen - No gradients, no emoji icons
- Canvas#FBFBF8
- Text#18181B
- Accent#0F766E
- Border#E4E4E0
Make sure the agent reads it
Agents don't open every file on their own. Point to it from the file they always read:
- Claude Code: add
@DESIGN.mdtoCLAUDE.md, which imports it into every session. - Codex and other agents: add "Follow DESIGN.md for all UI" to
AGENTS.md. - Cursor: add a rule in
.cursor/rulesthat points to it.
Make one from a website
The fastest start is a site whose look you already like.
- Paste its address into Siteprint. The colors, fonts, type scale and spacing are free to read.
- Copy the values into the sections above, or let Siteprint Pro write the whole DESIGN.md, measured in a real browser.
- Make it yours. Swap their accent for your brand color, drop what you don't need and add your own rules.
For the steps around it, see how to copy a website's design with AI.
