AI 에이전트에게 설정 화면, 온보딩 모달, 대시보드, 가격 페이지를 따로 요청하면 각각은 “괜찮아” 보이지만 하나로 모아 놓으면 로고만 같은 서로 다른 제품처럼 느껴진다. design-md는 이 문제를 저장소 안의 텍스트 파일 하나로 해결한다.

왜 DESIGN.md가 필요한가

에이전트는 Figma를 거의 읽지 못하고, 브랜드 PDF는 더 무용하다. DESIGN.md는 디자인 규칙을 에이전트가 실제로 참조하는 곳, 즉 저장소 텍스트 파일에 넣는 방식이다.

• README.md → 사람에게 프로젝트 설명
• AGENTS.md → 코딩 에이전트에게 저장소 운영 방식 설명
• DESIGN.md → 디자인·코딩 에이전트에게 제품이 어떻게 보여야 하는지 설명

에이전트가 UI를 생성할 때 흔히 발생하는 실수 목록이다:

• 잘못된 radius / font weight
• CTA 위계 혼란
• 강조색 남용
• 아무 이유 없이 새 카드 스타일 발명
• 제품과 맞지 않는 폼 필드
• 모바일에서 스프레드시트처럼 깨지는 레이아웃

에이전트가 불완전한 맥락으로 요청을 처리했기 때문이다. DESIGN.md는 그 맥락을 미리 제공한다.

DESIGN.md 작성 5단계

1. 실제 소스에서 시작하기

“아름답게 만들어 줘”보다 구체적인 출발점이 필요하다.

• 기존 앱 UI
• 공개 마케팅 사이트
• Figma 파일
• 맘에 드는 화면 스크린샷
• getdesign.md 또는 awesome-design-md 같은 레퍼런스 모음

제품이 이미 있다면 에이전트에게 현재 UI에서 초안을 추론하게 한다. 신제품이라면 레퍼런스 방향을 먼저 정한다.

2. 분위기가 아닌 결정을 기록하기

약한 DESIGN.md가 쓰는 표현:

Minimal, Premium, Clean, Friendly

강한 DESIGN.md가 쓰는 표현:

– 화면당 강조색은 하나, 주요 액션에만 사용한다. – 본문은 15–16px, line-height 1.4 이상. – 카드는 무거운 그림자 대신 border와 surface 대비로 구분. – Primary 버튼은 filled, 보조 액션은 text 또는 outline. – 비어 있는 상태(empty state)는 직접적이고 기능적으로, 장난스러운 표현은 자제.

PM은 최종 그림자 토큰 없이도 제품 판단을 이름 붙일 수 있다: 촘촘한지 여유 있는지, 장난스러운지 진지한지, 액션 위주인지 검토 위주인지.

3. 에이전트가 참조하는 섹션 채우기

Google이 제안하는 기본 구조:

• Overview, Colors, Typography, Layout
• Elevation, Shapes, Components
• Do’s and Don’ts

제품에 따라 특화 섹션을 추가할 수 있다.

규칙이 적혀 있으면 잘못된 출력물을 훨씬 쉽게 지적할 수 있다.

4. 에이전트가 파일을 인용하게 만들기

파일을 첨부하고 기대하는 것은 너무 소극적이다. 에이전트에게 자기 출력물을 파일 기준으로 검토하게 요청한다.

- DESIGN.md에서 이 화면이 따른 규칙을 나열해 줘.
- DESIGN.md에 없는 새 패턴을 발명한 곳을 알려 줘.
- 버튼, 카드, 입력창, 타이포그래피, 간격, 모바일 동작을 DESIGN.md와 비교해 줘.
- UI를 변경하기 전에 어느 DESIGN.md 섹션이 그 변경을 정당화하는지 말해 줘.
- DESIGN.md가 침묵하면 그렇다고 말하고, 파일을 확장할지 물어봐 줘.

마지막 프롬프트가 핵심이다. 새로운 제품 결정이 생길 때마다 일회성으로 처리할지 시스템에 추가할지 선택하게 된다.

5. 인간 검토와 함께 사용하기

DESIGN.md는 에이전트가 반복해서 재결정하지 않도록 결정을 적어두는 곳이다. 이 파일이 할 수 없는 것도 있다:

• 제품이 Linear, Notion, Ramp, Workday 중 어느 느낌이어야 하는지 결정
• 화면이 사용자에게 어떤 감정을 줘야 하는지 결정

파일이 디자이너를 대체한다는 기대는 잘못됐다. 디자이너와 PM이 결정을 한 번 인코딩해서 에이전트가 화면마다 재협상하지 않게 하는 것이 올바른 용법이다.

PM 체크리스트

파일 작성 전 확인 사항

• 이 파일이 적용될 제품 영역은 어디인가?
• 가장 좋은 맛의 기준이 되는 화면은 어느 것인가?
• 경고 예시가 될 화면은 어느 것인가?
• 탐색용인가, 프로덕션 코드용인가, 검토 전용인가?
• 팀에 Figma 토큰, Tailwind 설정, 브랜드 규칙, 컴포넌트 문서가 있는가?

파일에 반드시 포함해야 할 항목

• Overview: 제품이 어떤 느낌이어야 하는지 평문으로
• Color roles: hex 값 + 각 색상의 역할
• Typography & Spacing: 크기, 굵기, line-height, 밀도, 리듬
• Components & States: 버튼, 입력창, 카드, 내비게이션, 테이블, empty, loading, error, disabled
• Layout & Responsive: 그리드, 최대 너비, gutter, 축소되는 요소, 유지되는 요소
• Accessibility: 대비율, 키보드 내비게이션, focus 스타일, 모션 제한
• Do’s and Don’ts: 생성된 화면마다 새 느낌을 막는 가장 빠른 방법

Do’s and Don’ts 예시:

✅ 화면당 명확한 주요 액션 하나만 유지.
✅ 운영 페이지에서 스캔 속도 우선.
✅ 비어 있는 상태는 다음 액션을 안내하는 데 집중.

❌ 이 파일을 업데이트하지 않고 새 버튼 스타일 생성 금지.
❌ 강조색을 장식 목적으로 사용 금지.
❌ 승인·검토·파괴적 액션을 저대비 메뉴 안에 숨기기 금지.
❌ 밀도 높은 B2B 워크플로를 소비자 랜딩 페이지처럼 만들기 금지.

프롬프트 사용법

# 생성 시
DESIGN.md를 먼저 읽어. 요청이 파일과 충돌하면, 생성 전에 충돌 내용을 설명해.

# 구현 시
가능한 경우 기존 컴포넌트를 사용해. 새 패턴이 필요하면 DESIGN.md가 왜 커버하지 않는지 설명해.

# 검토 시
불일치, 누락된 상태, 접근성 위험, 반응형 문제, 새 패턴을 발명한 곳만 반환해.

파일 업데이트 시점

업데이트해야 할 때:

• 새 컴포넌트 패턴이 두 번 이상 등장할 때
• 디자이너가 시각적 방향을 바꿀 때
• 에이전트의 반복 실수가 감지될 때
• 같은 리뷰 코멘트가 계속 돌아올 때
• 특정 기능 영역에 다른 밀도 규칙이 필요할 때

업데이트하지 말아야 할 때: 한 명이 카드 radius를 싫어한다고 해서. 세 화면이 세 가지 다른 카드 radius를 발명했다면 시스템 문제다.

흔한 실패 유형

지루함은 장점이다. 흔한 디자인 결정은 반복되어야 하고, 진짜 어려운 제품 결정은 여전히 사람 몫이다.

관련 문서

• design-md — DESIGN.md 기술 스펙 (YAML 토큰 스키마, CLI 도구, 섹션 순서)
• awesome-design-md — 69개 브랜드의 DESIGN.md 레퍼런스 모음
• impeccable — DESIGN.md 기반 AI 프론트엔드 디자인 스킬 시스템

참고 자료

• DESIGN.md | The One File AI Needs to Match Your UI — X (George from prodmgmt.world) (2026-04-28)
• getdesign.md — DESIGN.md 예시 파일 모음