design.md
A design.md is a short markdown document where a designer writes down how they actually design. Not an "about me". A contract that AI agents, collaborators and tools can read so the output reflects you.
Tools like Claude, Cursor, Codex and Lovable can ship working interfaces in minutes. The bottleneck is not generation. It is taste. Without a logical brief, agents fall back to generic UI: generic spacing, generic copy, generic decisions. With a design.md, the AI inherits your taste before it writes a line of code.
A design.md is not a portfolio bio. It is the same kind of input you would hand a senior collaborator on day one: how you reach for layout, what you avoid, what you measure success against, what voice you write in.
Yelmo recommends five sections to start. Adapt freely.
How I work
Your default move. What you reach for first when starting a layout, a flow, a system.
What I look for
Your evaluation criteria. The rules an AI can use to self-audit its output before showing it to you.
Tools
The stack. Concrete: Figma, Linear, Granola, Claude Code, Cursor, Lovable. Specific is better than abstract.
Influences
The work that shapes yours. Specific people, products, books.
Recent thinking
What you are chewing on right now. This dates the doc and tells the agent what is fresh in your head.
A strong design.md is short (400 to 700 words), opinionated about voice, specific about constraints, and honest about what you avoid.
## What I look for
- Sentence case in every label, button, heading. Never title case.
- Spacing scale of 4px. Components align to the grid.
- Body copy contrast ratio of 4.5:1 minimum. Captions never dip below 3:1.
- One primary action per surface. If a screen has two, the screen is wrong.
- No em-dash. Use comma, colon, parens, or "and".
Notice these are testable. An AI can run them as a checklist against its own output. That is what makes a design.md a contract, not a vibe.
A design.md on Yelmo is not just a page to read. Every Yelmo profile is also an MCP server. When you connect a designer's Yelmo to Claude Code, Cursor, or Claude Desktop, the agent loads their design.md (and their published skills) as session context before answering.
For Claude Code, one line in your terminal:
claude mcp add --transport http yelmo-<handle> https://yelmo.ai/api/mcp/<handle>Cursor uses a one-click deep link from any profile’s install modal. Claude Desktop adds the server through claude_desktop_config.json. Yelmo gives you the exact JSON snippet to paste.
Then ask anything: “design an onboarding screen the way @handle would”. The output respects their voice, their spacing rules, the modals they avoid, the tokens they use. That's the contract becoming code without you copying or pasting.
Free. Sign in with Google. The coach asks one question at a time and helps you turn your taste into a contract your AI can actually follow.
design.md
A design.md is a short markdown document where a designer writes down how they actually design. Not an "about me". A contract that AI agents, collaborators and tools can read so the output reflects you.
Tools like Claude, Cursor, Codex and Lovable can ship working interfaces in minutes. The bottleneck is not generation. It is taste. Without a logical brief, agents fall back to generic UI: generic spacing, generic copy, generic decisions. With a design.md, the AI inherits your taste before it writes a line of code.
A design.md is not a portfolio bio. It is the same kind of input you would hand a senior collaborator on day one: how you reach for layout, what you avoid, what you measure success against, what voice you write in.
Yelmo recommends five sections to start. Adapt freely.
How I work
Your default move. What you reach for first when starting a layout, a flow, a system.
What I look for
Your evaluation criteria. The rules an AI can use to self-audit its output before showing it to you.
Tools
The stack. Concrete: Figma, Linear, Granola, Claude Code, Cursor, Lovable. Specific is better than abstract.
Influences
The work that shapes yours. Specific people, products, books.
Recent thinking
What you are chewing on right now. This dates the doc and tells the agent what is fresh in your head.
A strong design.md is short (400 to 700 words), opinionated about voice, specific about constraints, and honest about what you avoid.
## What I look for
- Sentence case in every label, button, heading. Never title case.
- Spacing scale of 4px. Components align to the grid.
- Body copy contrast ratio of 4.5:1 minimum. Captions never dip below 3:1.
- One primary action per surface. If a screen has two, the screen is wrong.
- No em-dash. Use comma, colon, parens, or "and".
Notice these are testable. An AI can run them as a checklist against its own output. That is what makes a design.md a contract, not a vibe.
A design.md on Yelmo is not just a page to read. Every Yelmo profile is also an MCP server. When you connect a designer's Yelmo to Claude Code, Cursor, or Claude Desktop, the agent loads their design.md (and their published skills) as session context before answering.
For Claude Code, one line in your terminal:
claude mcp add --transport http yelmo-<handle> https://yelmo.ai/api/mcp/<handle>Cursor uses a one-click deep link from any profile’s install modal. Claude Desktop adds the server through claude_desktop_config.json. Yelmo gives you the exact JSON snippet to paste.
Then ask anything: “design an onboarding screen the way @handle would”. The output respects their voice, their spacing rules, the modals they avoid, the tokens they use. That's the contract becoming code without you copying or pasting.
Free. Sign in with Google. The coach asks one question at a time and helps you turn your taste into a contract your AI can actually follow.