How to Give Claude a Design System to Work From

Why the prompt is the wrong place for design

Style words in a prompt are adjectives, and a model resolves an adjective by averaging. Ask for modern and you get whatever modern meant across millions of pages of training data, which is roughly the landing page you have already seen forty times this year. Ask for a background of #0B0D10 and you get #0B0D10. The difference is not that one prompt is longer. It is that one of them contains a decision and the other contains a mood.

There is a second problem, and it is worse on multi page builds. A prompt applies to one message. By the time you are asking for the fourth page, the values from the first page are buried under several thousand tokens of code, and the model reconstructs them from memory of the conversation rather than reading them. So the homepage nav is 72px tall and the about page nav is 64px. Body text is #5A6270 in one place and #6B7280 in another. Nobody can name what is wrong, they just feel that the site is slightly loose, which is most of why AI built sites read as AI built.

A file fixes both. It is a single source of truth that does not degrade over a long session, and it turns vague taste into values you can check mechanically. You can diff it. You can ask the model to audit a page against it. You cannot do either with the word sleek.

The six things the file has to pin down

Short beats complete. A one page spec that you actually attach beats a twenty page brand book that sits in a folder, because everything in the file competes for the model attention and long files get skimmed. Six categories cover almost every decision a small site needs.

1. Color, with a job per color

Four to six values, each with a written purpose. Not a palette, an assignment. Page background, surface or card background, border, body text, heading text, and one accent. The job matters more than the hex, because the failure you are preventing is the model using your accent for six different things until the page has no hierarchy left.

2. A type scale with a cap

Name the font stack, then list the only sizes allowed, and say which element uses which. Three or four sizes is enough for a marketing site. The cap is the useful part. Without it you end up with 15px, 16px and 17px text on the same page, which reads as sloppiness rather than variety.

3. A spacing scale, and the rule that nothing off scale ships

Pick a small set of numbers, say 8, 16, 24, 40 and 72, and state that every margin and padding value has to be one of them. This one line does more for how finished a page looks than any color choice. Uneven gaps are the thing people notice first and can never articulate.

4. Shape rules

Corner radius, border width and color, and your position on shadows. Pick one radius for cards and one for buttons and inputs, then say so. Mixed radii on the same screen is a common generated-output tell, and it happens because nothing in the prompt ever told the model to be consistent about it.

5. Two or three component recipes

Write out the primary button, the card, and whatever your most repeated block is, as a list of the values they use. The point is that page five gets the same button as page one without you pasting page one into the chat again.

6. The do-not list

Covered on its own below, because it is the section that earns the most and the one most people skip.

A worked example, short enough to actually use

Here is the shape of a real spec. Swap the values for yours and keep the structure. Written out as plain text in a file, this takes ten minutes and gets reused for the life of the site.

Project: one line on what the site is and who it is for. The model uses this for the hundred small judgments the spec does not cover.

Colors.

• Page background #0B0D10. Nothing else is a page background.
• Surface #14171C, used for cards and the nav bar only.
• Border #262B33, one pixel, used on every card and input.
• Body text #9AA3B0. Heading text #F2F4F7.
• Accent #E2552B. Buttons, links and one hairline per card. Never a background fill wider than a button, never a gradient.

Type. Headings in the display family at 40px desktop and 30px mobile, weight 700. Section headings 24px, weight 600. Body 17px, line height 1.7. Small print 14px. No other sizes.

Spacing. Allowed values 8, 16, 24, 40, 72. Section vertical padding 72 desktop, 40 mobile. Gap inside a card 16. Nothing off this list.

Shape. Cards 12px radius. Buttons and inputs 8px. No shadows anywhere, depth comes from the border and the surface color.

Primary button. Accent background, #0B0D10 text, 8px radius, padding 12 by 22, weight 600, no uppercase, no icon. Hover darkens the background by about ten percent and changes nothing else.

Card. Surface background, one pixel border, 12px radius, 24px padding, a 20px heading, body text, no icon, no image.

Layout. Content max width 1120px, single column on mobile, two columns above 900px. Left aligned text everywhere except the hero headline.

That is the whole thing. Notice how much of it is a restriction rather than an instruction. The sentences doing the real work are the ones that say never, only and no other.

Where the file lives so the model reads it every time

Writing the spec is the easy half. Getting it in front of the model on every request is what decides whether it matters. Three places work, and they are not equivalent.

Project knowledge is the best option if you are working in a Claude project. The file is attached to every conversation in that project, so a chat you open three weeks later starts with the same spec as the one you opened today. This is also where the model picks it up without you remembering to.

A file in the repo is the right answer if you are using a coding agent that reads your directory. Put it at the root with a name the agent will treat as instructions. The advantage over project knowledge is that the spec travels with the code, so the version that built the site is the version sitting next to it.

Pasting it above the request works and costs nothing to set up. The downside is that you will forget, usually around the fifth page, which is exactly when drift starts. If this is your method, keep the spec in a note you can paste in two keystrokes and treat it as part of the prompt rather than a reference.

One rule regardless of where it lives: the file is the only copy. When you change a value, you change it in the file and then ask the model to apply the file, rather than telling the chat to use a slightly darker border and leaving the spec stale. A spec that disagrees with the site is worse than no spec, because now you cannot tell which one is wrong.

The do-not list carries more weight than the palette

Values tell the model what to use. They do not stop it reaching for the composition it has seen ten thousand times, which is where the generic look actually comes from. The do-not list is the part of the file that addresses composition, and it should be specific enough to be checkable. Mine, roughly:

• No gradient anywhere, especially violet to blue, and especially behind a hero.
• No row of three equal cards with an icon above a heading above two lines of text.
• No emoji used as an interface icon.
• No centered column of short centered paragraphs.
• No glassmorphism, no blurred translucent panels, no floating dashboard mockup at an angle.
• No stock photography of people in an office.
• No feature list that happens to contain exactly three items unless there are exactly three things.
• No testimonial block until there are real testimonials to put in it.

That last one is a content rule rather than a design rule, and it belongs in the file anyway. A model asked to build a landing page will produce a testimonial section with invented quotes because the pattern expects one, and a page with fake social proof on it does more damage than a page with none. The spec is a good place to make that decision once.

Add to the list every time you catch something. The list is a record of the defaults you have already had to argue with, which makes it the most personal part of the file and the part that gets better with use. For the longer catalogue of what to watch for, there is a full post on the tells and the fix for each.

Making the model grade its own output against the file

A spec you never enforce decays quietly. The cheap enforcement move is to ask for an audit instead of eyeballing the result. After the model builds a page, in the same conversation:

List every color value, font size, spacing value and border radius used in the page you just wrote. Put each one next to the spec entry it matches. Flag anything that is not in the spec. Do not fix it yet, just report.

This works because it turns a judgment into a lookup, and models are considerably better at lookups. You will usually get a short list of three or four strays, often a border color that drifted or a 20px gap that should have been 16 or 24. Fix those, then ask the same question again. Two rounds is normally enough.

Run the same audit against the do-not list separately, because composition violations do not show up in a table of values. Ask directly whether the page contains anything on the do-not list, and the model will often admit to the gradient it just added. For checking a site you already have rather than one you are building, the scored audit post covers the mechanical checks, and the general habit of making the model verify its own work is worth building early if you are new to writing code this way.

The format other people are converging on

If you would rather not invent the file structure, there is now a published format for exactly this. Google Labs released design.md, described in the repository as a format specification for describing a visual identity to coding agents. It is a plain text file with two layers: YAML front matter holding the machine readable tokens, then markdown sections with the reasoning behind them. The canonical section order runs overview, colors, typography, layout, elevation and depth, shapes, components, and dos and donts. There is a command line tool that lints a file, diffs two versions to catch regressions, and exports the tokens to other formats.

Worth knowing about, and the section list is a good checklist even if you never adopt the format. Whether you need the formal version depends on scale. For a six page site built by one person, the plain text spec above is faster to write, easier to edit, and the model reads it just as well. For a team where several people and several agents touch the same product, a linted file with versioned tokens starts earning its keep, because now the question of who changed the border color has an answer.

The project is marked alpha, so the format may move. The underlying idea is the stable part: the spec is an artifact, not a sentence in a prompt, and it belongs in version control next to the thing it describes.

What a spec file will not fix

It will not give you taste. A spec built from values you picked badly produces a consistent site that looks consistently wrong, and consistency makes bad choices more visible rather than less. If you are unsure about the palette, take it from something you already admire and would be happy to be compared to, then write those values down. Borrowed values beat invented ones at the start.

It will not write your copy. The file governs the shell, and the generic feeling of a page comes from the words at least as much as the layout. Specific claims, real numbers, actual names.

It will not survive being ignored. The common failure is not a bad spec, it is a good spec that stopped being attached after week one, usually because the person got comfortable and started prompting from memory. The file costs nothing to attach and everything to forget.

And it will not replace looking at the page. Load it on a phone, then at 1440px, then with the text zoomed. A spec catches value drift, not the heading that wraps badly at 390px wide. Those two kinds of checking are complements, not substitutes.

Open a text file right now and write the five colors with their jobs, the four font sizes, the five spacing values, your radius rule and three things you never want to see. That is a usable spec and it takes about ten minutes. Attach it to the project, build the next page from it, then ask the model to list every value it used and flag the strays.

The whole trick is moving design out of the conversation and into an artifact. A conversation forgets. A file does not, and neither does anyone who opens it six months from now wondering which orange was the real one.

Related: How to Prompt Claude for a Website That Ships First Try

Common questions

What should a Claude design system prompt actually contain?

Exact values rather than adjectives: four to six colors each with a stated job, a capped type scale naming which element uses which size, an allowed spacing scale, corner and border rules, two or three component recipes written as value lists, and a do-not list of compositions you never want. Keep it to one page so it gets read rather than skimmed.

Should the design spec go in project knowledge or in the prompt?

Project knowledge if you are working in a Claude project, because it attaches to every conversation automatically and you cannot forget it. A file in the repo root if your agent reads the directory, since the spec then travels with the code. Pasting it above each request works too, but drift starts the first time you forget, which is usually around the fifth page.

How do I stop Claude using different colors and spacing on each page?

Give it a fixed list of allowed values and state that nothing off the list ships, then enforce it. After each page, ask the model to list every color, font size, spacing value and radius it used, match each against the spec, and flag anything unmatched. Fix the strays and ask again. Two rounds usually clears a page.

Do I need a formal format like design.md or is a plain text file enough?

A plain text file is enough for a small site built by one person, and it is faster to write and edit. The formal format is worth it once several people or several agents touch the same product and you need linting, versioned tokens and a diff that catches regressions. The section list in the published spec makes a decent checklist either way.

Will a design system stop my site looking AI generated?

It fixes the mechanical half: inconsistent spacing, drifting colors, mixed corner radii, mismatched buttons. It does not fix generic composition or generic copy, which is why the do-not list and the writing matter just as much. A consistent site built from weak values looks consistently weak, so pick the values with care.