05 · Best practice
Ship a DESIGN.md with brand tokens
Tokens at the source level so contributors can't reach default indigo by accident.
Without a brand spec in the repo, every artifact Claude generates will look like ChatGPT made it. Mesh gradients, default Tailwind blues, soft shadows where you wanted hard ones. With a brand spec in the repo — encoded as a skill — every artifact comes out looking like the same studio shipped it.
Owen Williams (Design Manager at Stripe, on Claire Vo's How I AI) calls the alternative "the Tailwind Indigo blur slop." Designers and PMs at Stripe were generating prototypes that looked nothing like the actual product, until they wired the company's design system into Claude as an MCP + a bundle of rules.
The lesson generalizes: give the agent your design system, or accept that everything will look like the agent's default.
How to do it
Start with the Notion Brand Design Template — fill in your colors, fonts, voice rules.
Convert it to a SKILL.md in <repo>/skills/<your-brand>/SKILL.md. The skill format is the same as any other skill — name, description with trigger terms, body.
Reference your DESIGN.md (or the brand skill) from CLAUDE.md so every session loads it automatically.
Add a "what not to do" section. This is where the brand spec earns its keep.
What goes in it
- Color tokens — hex values, not "purple."
- Type scale — sizes, weights, line-heights. Specific.
- Logo rules — when to use which variant, clear space, what not to do.
- Voice — sentence patterns, banned words.
- Cards / surfaces — shadow signatures, border radii.
- Iconography — priority order of icon sources.
- What not to do — the most important section.
Why both a DESIGN.md and a skill
The skill is what auto-loads when Claude is generating a UI component or a release note. The DESIGN.md is what a human contributor reads first when they open the repo. Same content, different consumption pattern.
Anti-patterns
- A DESIGN.md that's just a Figma link. Claude can't open Figma. Put the rules in markdown.
- One color in the file when you actually use four.
- No "what not to do" section.
- A brand spec without trigger phrases in the description — it won't auto-load.