skillshop

How to use DESIGN.md: design rules for AI agents

4 min readUpdated Skillshop operator and creator of the Maker Evan YouTube channel

Translated from Korean. View original. Some screenshots are available in Korean only.

DESIGN.md collects a project’s color, typography, spacing and component rules. Ask an AI to read it when working on a screen to apply shared criteria. No special program is required; start by recording the design values your team already uses.

Browse relevant skills and examples on Skillshop.

View original Korean screenshot
스킬샵 디자인 카테고리 화면. 썸네일과 카드뉴스, 브랜드 자산을 다루는 스킬 카드가 놓여 있다.
스킬샵에서 관련 작업의 스킬과 사용 예시를 살펴볼 수 있어요.

What belongs in DESIGN.md?

Record criteria repeatedly checked while building interfaces, such as button colors, heading sizes and card spacing. People and AI can refer to it, but the filename alone is not a standard automatically read by every tool.

README can explain the project, CLAUDE.md or AGENTS.md can hold work rules, and DESIGN.md can hold design criteria. Include the path and an instruction to read it before UI work.

FileContents
README.mdProject purpose and getting started.
CLAUDE.md · AGENTS.mdWork scope, commands and checks.
DESIGN.mdColor, type, spacing and component criteria.
Separate roles and reference required file paths from work instructions.
README.mdWhat it isWhat the project does.
CLAUDE.md · AGENTS.mdHow to workWork sequence and prohibited actions.
DESIGN.mdHow it looksColor, type, spacing and buttons.
Record recurring interface criteria such as colors, type sizes and spacing.
Claude Code project instruction guidance →

Give actual values instead of “clean”

“Make it more modern” has many interpretations. Specific background colors, heading and body sizes, radii and spacing communicate a clearer direction.

First find values already used in the interface. You need not invent every value; collect existing rules and explain exceptions.

Explaining verbally
  • The same request can yield different values
  • Gray and spacing vary across screens
  • Each edit needs another explanation
Providing a file
  • Reference values are documented
  • Screens use the same scale
  • Request that changed rules be read
“More modern” leaves substantial room for interpretation.

Start with color, type and spacing

Give color codes roles so a gray used for text is distinguishable from one used for borders. Record heading and body size, weight and line height.

Record actual spacing units and exceptions. Include default, hover, pressed, disabled and loading button states and keyboard focus. This example illustrates the format; adapt values to your product. # DESIGN.md - Background: #FFFFFF - Body text: #222222 - Body: 16px, line height 1.6 - Heading: 28px, weight 700 - Spacing: 8px unit; explain exceptions - Button: check default, focus, disabled and loading states - Completion: check mobile overflow and contrast

RolesName each value’s use, such as background or warning.
ScaleDocument hierarchy, not one isolated size.
SpacingRecord the base unit and exceptions.
Prohibited stylesDistinguish disallowed values and exceptions.
Assign a role to each color code.
  • Color: codes and usage by role
  • Typography: size, weight and line height
  • Spacing: base unit and exceptions
  • Shape: radius, borders and shadows
  • Components: default, focus, disabled and loading states
  • Restrictions: expressions and styles excluded from the product

Reference the path from work rules

CLAUDE.md or AGENTS.md can hold general development commands, edit scope and validation. Long design criteria can live separately and be referenced for relevant work.

For example, say “Read frontend/DESIGN.md before modifying the UI.” Check that the path is correct and rules are not duplicated or contradictory.

Rules fileGeneral work order in AGENTS.md or CLAUDE.md.
One-line referenceRead DESIGN.md for screen work.
Design fileColor, type and spacing maintained separately.
Keep general commands, scope and checks in the work-rules file.

Keep it where the team can find it

Store it in the repository at a discoverable project or product location. A file only on one person’s computer will not inform teammates’ work.

Separate files if admin and customer interfaces follow different systems. Specify which document applies to which screen; the same approach can convey standards for documents and slides.

Project rootDefaultEasy to reference from instructions.
Shared locationTeamPersonal files are harder for teammates to use.
By productMultipleSeparate admin and customer rules when they differ.
Keep the file in a discoverable shared repository location.
Anthropic's English documentation showing CLAUDE.md locations and scopes
An example from official documentation; check the current linked setup guide.Source: Claude Code documentation
Open full-size image (opens in a new tab)
View original Korean screenshot
CLAUDE.md 배치 위치 표가 범위·위치·목적·사용 사례 열로 나뉘고, 관리 정책·사용자 지침·프로젝트 지침·로컬 지침 네 행이 로드 순서대로 놓여 있다.
공식 문서의 화면 예시예요. 현재 설정은 연결된 공식 안내에서 확인해 주세요.출처: 클로드 코드 공식 문서 · 프로젝트 기억

If rules were not applied, check which file was read

First check whether the AI actually read DESIGN.md. If documentation and code differ, decide which is authoritative and request only the needed changes.

Replace ambiguous phrases such as “appropriate spacing” with values or screen examples. Separate frequently used rules from detailed references. Prohibitions can help but do not guarantee compliance; inspect the resulting screen.

Long fileSeparateSplit core rules from detailed references.
Screen differsCompareCheck differences between code and documentation.
AmbiguousSpecifyUse values or screen examples.
No restrictionsAddSpecify what not to do as well.
First verify that DESIGN.md was actually read.

Transfer an existing design system

Bring color, type and spacing values from Figma or code and explain each role. Match button and card behavior to the actual components.

Have the tool read the document and build one screen. For differences, check whether the document lacked detail or code had exceptions, then add what is needed.

Start with threeTransfer color, type and spacing first.
One screenRequest a screen using that document.
DifferencesAdd missing criteria for mismatches.
Transfer values from Figma or code and explain their roles.

Use someone else’s document as a template

A public DESIGN.md can suggest useful sections. Check its terms and replace values and rules with your product’s own.

A skill may also include a process for completing and checking the document. Inspect its contents and ensure copied example values do not accidentally ship.

A standalone file
  • Use its structure with your values
  • Get ideas for what to document
  • Specify separately when to read it
A packaged skill
  • May include steps to fill in your values
  • May describe when to read the file for UI work
A public document can suggest useful sections.

Browse related skills, creators and examples on Skillshop.

View original Korean screenshot
스킬샵 크리에이터 페이지 화면. 스킬을 만들어 파는 사람들의 프로필 카드가 늘어서 있다.
관련 스킬과 제작자, 사용 예시를 살펴볼 수 있는 스킬샵 화면이에요.
Browse design skills →Browse all skills →How to choose an AI skill →

Frequently asked questions

What should DESIGN.md contain?

Document color roles, heading and body size and weight, line height, spacing and shape. Include component states such as default, focus, disabled and loading, plus the product’s spacing scale and exceptions.

Do I need DESIGN.md if I already have CLAUDE.md or AGENTS.md?

Not necessarily. Separate lengthy design rules when it helps maintenance and specify which path to read for screen work. The filename is not a standard every tool reads automatically.

What if AI ignores DESIGN.md?

Check that it read the file, resolve differences between the document and code, and replace vague wording with values or examples. Consider document length, the actual result and the execution environment.

Sources