A free DESIGN.md template for Claude Code, Cursor and Copilot

A DESIGN.md is a plain file that tells a coding agent exactly how your site should look, so it stops falling back on the default purple-gradient, Inter and three-cards look. This page gives an original, fill-in-the-blanks skeleton you can copy, and says where each tool reads it.

Where to put the file and the rule that points at it

Keep DESIGN.md in the project root, next to your CSS. Then add a short rule telling the agent to read it. Each tool looks in a different place:

The rule can be three lines: read DESIGN.md and the stylesheet before writing any page, use only the colours, fonts and components they define, and run a checker when finished.

The skeleton

Replace everything in angle brackets. The more specific the values, the less the agent has to guess. Keep it to one page.

# <Name>: design file

## 1. Atmosphere
<Two sentences: what it feels like, and what it is NOT. Name something from the subject's own world, such as a ledger, a workshop or a harbour.>

## 2. Colour (hex values, each pair checked for 4.5:1 text contrast)
bg <#...> | text <#...> | muted text <#...> | accent <#...> | text on accent <#...>
Use the accent for at most <4> things per screen.

## 3. Type
<One body family and one display family, both from the system font stack unless you self-host.>
h1 <size, weight, line-height>. Body <size/line-height>. <Case rules>.

## 4. Components
<One line each, with what to use it for: row, panel, button, form, table.>

## 5. Layout
<Alignment, column width, spacing scale. Say what the hero is, and that it is not centred if you do not want that.>

## 6. Depth
<Shadows: none, or exactly one.>

## 7. Do / Don't
Do: <three specific habits>.
Don't: card grids of equal boxes, emoji as icons, eyebrow labels, gradients, glow, one big radius on everything, scroll fade-ins.

## 8. Responsive
<What stacks, what scrolls, minimum width 320px, no sideways page scroll.>

## 9. Agent prompt
"Build this page in the <Name> look. Read DESIGN.md and the stylesheet first..."

Check that the agent followed it

A written file is a request, not a guarantee. After the agent builds the page, paste the result into the free AI design tells checker, or run the MIT-licensed slop-lint tool on the folder. It reports the default tells it finds, with the line and the change to make. It is a text heuristic: it can miss a tell written in an unusual way, and it cannot judge taste.

Write your own or start from finished ones

Describe your own brand, not someone else's: files copied from a famous company's site give you that company's look, which is not yours. If you would rather start from something finished, Looksheet has five original looks, each with a DESIGN.md in this shape, working pages and rules files for all four tools above. The live demo shows one. The guide to the tells explains why agents produce the default look in the first place.