Design rules in CLAUDE.md

Why the rules belong in a file

A prompt lasts one conversation. A fresh session starts without your earlier one, so the careful brief that set the type and spacing on Monday is not there on Thursday when you ask for a new page. The page gets built from whatever Claude can infer from the code, and small differences creep in: a new grey, a 14px label where the rest are 13px.

A rules file fixes that at the source. It is also a better record for people. A new teammate can read one page and know how the interface is meant to be built.

What to put in it

• Where values live. The path of the tokens file, and the rule that components use tokens and never raw values.
• The values themselves. Colours in hex, the type sizes, the spacing scale, radii, durations. Short lists, not prose.
• Component rules. Reuse before writing new; which states every control must have; no new dependencies without asking.
• Motion limits. Which properties may animate, how long, and what happens under reduced motion.
• A never list. The specific habits you don't want: gradient text, emoji in the interface, placeholder copy.
• The definition of done. The commands to run and the widths to check before saying a task is finished.

Keep it short and current

The file is read alongside everything else in a session, so every line should be a rule someone would otherwise break. Leave out what Claude can see from the code and anything that reads like a mission statement. One screen of text is a good size for the design section.

Update it when a decision changes, in the same change as the code. A rules file that disagrees with the project is worse than none, because Claude Code will try to follow both.

Let Claude help write it

On an existing project, ask Claude Code to read the styles and draft the design section from what is there: the colours in use, the sizes, the spacing. Then edit the draft down to what you want to be true. On a new project, make "write CLAUDE.md with the tokens and rules from this brief" the first step of the build, as in the Claude Code website prompt.

Test that it holds

Open a new session and give a small task with no design detail at all: "add an empty state to the projects list". If the result uses your tokens, your type sizes and your states, the file is doing its job. If it doesn't, the missing rule is the one to add.

An example design section for CLAUDE.md

# Design rules

Read this before any change to the interface. If a request conflicts with a rule here, stop and ask.

## Tokens
- All colours, sizes, spacing, radii and durations live in src/styles/tokens.css as CSS custom properties. Components use the properties, never raw values.
- Colours: ground #f6f4ef, surface #ffffff, ink #171613, muted #6f6c63, accent #2447d6. No other colours without asking.
- Type: [typeface] only. Sizes 13, 15, 18, 24, 40, 72px. Weights 400 and 600.
- Spacing scale: 4, 8, 12, 16, 24, 40, 64, 96px. Radius: 8px on controls, 16px on cards.

## Components
- Stack: Vite + React + TypeScript, plain CSS. No UI library, no icon pack, no new dependency without asking.
- Reuse what is in src/components before writing anything new. A new component needs my OK.
- Every interactive element has hover, focus-visible, active and disabled states.

## Motion
- Durations: 0.15s for colour, 0.3s for position, ease-out. Animate transform and opacity only.
- Under prefers-reduced-motion, remove movement and keep state changes.

## Layout
- Desktop design width 1440px, 12 columns, 24px gutters. One column below 720px with 16px margins.
- Nothing scrolls sideways at 390px.

## Never
- Gradient text, emoji in the interface, placeholder copy, shadows on text.

## Before you say you are done
- Run npm run build and npm run lint, and fix what they report.
- Open the changed screen at 390px and 1440px.
- Tell me what you checked and what you could not.

Written for this page as a starting point; swap the parts in [brackets] for your own. The full prompt of each uberdesigner template is longer and specific to one finished design, and it is tested by rebuilding the template from the prompt alone.

Keep reading

• How to prompt Claude for designThe working method for design work with Claude and Claude Code: brief, plan first, build, run and look, then correct with specifics.
• Connecting uberdesigner to Claude Code over MCPHow to add the uberdesigner MCP server to Claude Code, sign in, and what to ask once the template library is connected.
• Claude chat or Claude Code for design workWhich to use for what: the Claude chat app for one HTML file to look at, Claude Code for a real project. How to move a draft from one to the other.

• Whole sites
• Components
• Redesigns