AI 코딩 도구를 활용해 UI를 만들고 화면을 빠르게 실험하는 흐름이 보편화되면서, 이제는 단순히 “좋아 보이는 디자인”을 만드는 것보다 “일관된 기준에 맞는 디자인”을 유지하는 일이 더 중요해졌습니다. 문제는 이 기준이 사람끼리만 공유되는 문서에 머물면, AI는 그 의도를 정확히 반영하지 못한다는 점입니다.
이런 배경에서 주목받는 개념이 바로 DESIGN.md입니다. DESIGN.md는 프로젝트의 디자인 원칙과 시각적 규칙을 마크다운 문서로 정리해, 사람이 아니라 AI도 이해할 수 있게 만드는 방식입니다. 쉽게 말해, “우리 서비스는 어떻게 보여야 하는가”를 텍스트로 명확히 선언한 문서라고 볼 수 있습니다.
이 글에서는 DESIGN.md가 무엇인지, 왜 필요한지, 어떤 내용을 담아야 하는지, 그리고 실제 프로젝트에서 어떻게 활용하면 좋은지 자세히 정리해 보겠습니다.
DESIGN.md란 무엇인가
DESIGN.md는 프로젝트의 디자인 시스템을 설명하는 마크다운 문서입니다. 이 문서의 핵심 목적은 AI 코딩 도구나 에이전트가 프로젝트의 시각적 방향을 이해하도록 돕는 데 있습니다.
예를 들어 일반적인 디자인 시스템 문서는 보통 디자이너와 개발자가 참고하기 위한 자료로 존재합니다. 색상 토큰, 타이포그래피 규칙, 버튼 스타일, 카드 구조, 간격 체계 등이 포함되지만, 실제로는 Figma 파일이나 디자인 툴 안에 흩어져 있거나 사람이 해석해야 하는 형태로 정리된 경우가 많습니다.
반면 DESIGN.md는 처음부터 AI가 읽고 반영할 수 있도록 작성된다는 점이 다릅니다. 즉, 단순한 문서가 아니라 AI에게 디자인 방향을 전달하는 인터페이스 역할을 합니다.
한 문장으로 정리하면 이렇습니다.
DESIGN.md는 “이 프로젝트가 어떻게 보여야 하는지”를 AI가 이해할 수 있는 언어로 정리한 디자인 기준서입니다.
왜 DESIGN.md가 필요한가
AI를 활용해 UI를 생성해 본 사람이라면 비슷한 경험을 해봤을 것입니다. 같은 프로젝트 안에서도 어떤 화면은 깔끔하게 나오고, 어떤 화면은 전혀 다른 제품처럼 보입니다. 버튼 모양이 바뀌고, 카드 간격이 흔들리고, 색감이나 분위기가 조금씩 어긋나기 시작합니다.
이 문제가 생기는 이유는 대부분 단순합니다. AI에게 기능 요구사항은 전달했지만, 디자인 의도는 충분히 전달하지 않았기 때문입니다.
예를 들어 아래와 같은 프롬프트는 기능적으로는 충분할 수 있습니다.
- 관리자 대시보드 화면을 만들어 줘
- 결제 내역 테이블과 요약 카드를 추가해 줘
- 모바일에서도 보이게 반응형으로 구성해 줘
하지만 이런 요청만으로는 결과물이 어떤 성격을 가져야 하는지 알기 어렵습니다. 미니멀해야 하는지, 밀도 높은 생산성 툴처럼 보여야 하는지, 프리미엄 SaaS 느낌인지, 개발자 도구처럼 차갑고 정교해야 하는지 기준이 빠져 있기 때문입니다.
DESIGN.md는 바로 이 지점을 해결합니다. 기능 요구사항과 별개로, 화면의 분위기와 구조, 컴포넌트의 성격, 금지해야 할 표현까지 명시함으로써 AI가 엉뚱한 방향으로 생성하지 않도록 잡아주는 역할을 합니다.
DESIGN.md가 기존 디자인 시스템 문서와 다른 점
기존 디자인 시스템과 DESIGN.md는 완전히 같은 것이 아닙니다. 겹치는 부분은 많지만 용도가 다릅니다.
기존 디자인 시스템은 보통 아래와 같은 목적에 강합니다.
- 디자이너와 개발자 간 협업
- 컴포넌트 재사용
- 디자인 토큰 관리
- 브랜드 일관성 유지
- 실제 제품 운영
반면 DESIGN.md는 아래 목적에 특히 강합니다.
- AI가 프로젝트의 디자인 방향을 빠르게 이해하도록 돕기
- UI 생성 결과물의 톤과 구조를 맞추기
- 반복적인 프롬프트 설명을 줄이기
- 화면 생성뿐 아니라 UI 리뷰 기준으로 활용하기
즉, 기존 디자인 시스템이 사람 중심의 운영 문서라면, DESIGN.md는 AI 중심의 해석 문서에 가깝습니다.
이 둘은 서로 대체 관계가 아니라 보완 관계로 보는 편이 더 정확합니다. Figma나 디자인 토큰이 여전히 중요하지만, 그것만으로는 AI가 디자인 의도를 안정적으로 읽지 못할 수 있기 때문에 DESIGN.md 같은 텍스트 기반 문서가 필요해지는 것입니다.
DESIGN.md에는 어떤 내용이 들어가야 하나
좋은 DESIGN.md는 단순히 색상 코드만 적어 놓은 문서가 아닙니다. 시각적 규칙뿐 아니라 제품의 인상, 사용자에게 전달해야 할 분위기, 피해야 할 스타일까지 포함해야 합니다.
보통 다음 항목들이 들어가면 실전에서 활용하기 좋습니다.
1. 브랜드 톤과 전체 분위기
가장 먼저 필요한 것은 제품이 어떤 느낌이어야 하는지 설명하는 문장입니다.
예를 들어 다음과 같은 식입니다.
- 차갑고 정교한 개발자 도구 느낌
- 따뜻하지만 과하지 않은 생산성 앱 느낌
- 프리미엄 금융 서비스처럼 신뢰감 있는 분위기
- 단순하고 절제된 미니멀 인터페이스
이 부분은 추상적으로 보여도 매우 중요합니다. AI는 디자인 요소를 따로따로 조립하는 경향이 있기 때문에, 전체 인상을 먼저 지정해 주어야 결과물이 하나의 성격으로 묶입니다.
2. 색상 체계
브랜드 컬러, 배경색, 본문 텍스트 색, 보조 텍스트 색, 강조 색상, 상태 색상 등을 정의합니다.
여기서 중요한 것은 단순히 헥스 코드만 나열하는 것이 아니라, 어떤 맥락에서 어떤 색을 써야 하는지도 설명하는 것입니다.
예를 들어 아래처럼 적을 수 있습니다.
- 배경은 거의 흰색에 가까운 밝은 중성 톤 사용
- 주요 텍스트는 강한 대비를 가진 짙은 회색 계열
- 강조 색상은 코발트 블루
- 성공 상태는 채도가 과하지 않은 녹색
- 오류 상태는 눈에 띄되 과도하게 공격적이지 않은 레드
이렇게 적으면 AI가 무작정 화려한 색을 쓰는 일을 줄일 수 있습니다.
3. 타이포그래피
타이포그래피는 전체 분위기를 결정하는 핵심입니다. 어떤 폰트를 쓴다는 정보보다도, 제목과 본문이 어떤 성격을 가져야 하는지를 설명하는 것이 더 중요할 때가 많습니다.
예를 들어 다음과 같은 규칙이 유효합니다.
- 제목은 강하고 선명해야 한다
- 본문은 개성보다 가독성을 우선한다
- 과장된 장식형 폰트는 피한다
- UI 텍스트는 안정적이고 중립적인 인상을 유지한다
AI는 종종 헤딩을 지나치게 크고 과장되게 만들거나, 반대로 너무 밋밋하게 만드는 경우가 있는데, 이런 문장이 기준을 잡아 줍니다.
4. 레이아웃과 간격
레이아웃 규칙은 디자인의 밀도와 리듬을 맞추는 데 필요합니다.
예를 들어 다음과 같은 항목을 담을 수 있습니다.
- 데스크톱에서는 12컬럼 그리드를 선호한다
- 섹션 사이 간격은 넉넉하게 유지한다
- 카드 간 여백은 좁지 않게 유지하되 지나치게 띄우지 않는다
- 콘텐츠 최대 폭은 너무 넓지 않게 제한한다
- 모바일에서는 수직 흐름을 우선한다
이런 기준이 없으면 화면마다 여백이 제각각이 되고, 어떤 페이지는 답답하고 어떤 페이지는 지나치게 허전해집니다.
5. 컴포넌트 규칙
버튼, 입력창, 카드, 모달, 테이블, 배지 같은 반복 요소는 꼭 문서에 들어가야 합니다. AI가 가장 많이 흔들리는 영역이기 때문입니다.
예를 들어 다음처럼 쓸 수 있습니다.
- 버튼은 중간 정도의 둥근 모서리를 가진다
- 입력창은 명확한 테두리와 강한 포커스 상태를 가진다
- 카드는 뜬 느낌보다 평평하고 구조적인 느낌을 우선한다
- 테이블은 정보 밀도가 높아도 읽기 쉬워야 한다
- 모달은 그림자를 과하게 사용하지 않는다
이런 규칙이 있으면 신규 화면을 생성할 때 기존 화면과 연결감이 생깁니다.
6. 금지 규칙
실제로는 허용 규칙보다 금지 규칙이 더 중요할 때도 많습니다. AI는 “하지 말아야 할 것”이 명확할수록 품질이 안정되는 경우가 많기 때문입니다.
예를 들면 다음과 같습니다.
- 과한 그라디언트 사용 금지
- 불필요한 3D 장식 금지
- 마케팅 랜딩페이지 같은 과장된 연출 금지
- 과도한 블러와 유리 질감 사용 금지
- 큰 아이콘 남용 금지
- 화려한 애니메이션 남용 금지
이런 항목은 결과물이 프로젝트의 목적에서 벗어나지 않게 해 줍니다.
DESIGN.md는 실제로 어떻게 활용하나
이제 중요한 것은 문서를 만드는 것보다 어떻게 쓰는가입니다. DESIGN.md는 저장해 두기만 하면 의미가 없습니다. 실제 생성 흐름에 계속 연결해야 합니다.
가장 일반적인 활용 방식은 아래와 같습니다.
1. 프로젝트 루트에 추가한다
DESIGN.md는 프로젝트의 루트에 두는 방식이 가장 직관적입니다. AI 에이전트나 코딩 도구가 코드베이스와 함께 이 문서를 읽을 수 있도록 하기 위함입니다.
이렇게 하면 새로운 화면을 생성하거나 기존 UI를 수정할 때, 매번 긴 설명을 프롬프트에 반복하지 않아도 됩니다.
2. 작업 요청과 함께 참조한다
예를 들어 다음과 같이 요청할 수 있습니다.
DESIGN.md를 기준으로 관리자 대시보드의 통계 카드를 구성해 달라- 기존 설정 화면을 모바일 우선 구조로 재작성하되
DESIGN.md의 간격 규칙을 유지해 달라 - 결제 페이지를 다시 설계하되 버튼과 입력창 스타일은
DESIGN.md를 따르게 해 달라
이렇게 하면 기능 지시와 디자인 기준이 분리되어 더 안정적인 결과를 얻을 수 있습니다.
3. UI 리뷰 기준으로 사용한다
DESIGN.md는 생성 단계뿐 아니라 검수 단계에서도 강력합니다.
예를 들어 아래처럼 활용할 수 있습니다.
- 현재 페이지가
DESIGN.md기준에서 어떤 부분이 어긋나는지 점검해 달라 - 버튼 스타일과 카드 간격이 문서와 일치하는지 비교해 달라
- 새로 추가한 컴포넌트가 기존 브랜드 분위기와 맞는지 리뷰해 달라
즉, DESIGN.md는 생성용 프롬프트 보조문서가 아니라 품질 점검 기준서이기도 합니다.
4. 팀의 공통 합의 문서로 활용한다
디자이너, 프런트엔드 개발자, AI 도구가 모두 같은 기준을 보게 만드는 것도 큰 장점입니다.
기존에는 디자이너는 Figma를 보고, 개발자는 구현된 화면을 보고, AI는 짧은 프롬프트만 보고 작업하면서 의도 차이가 생기기 쉬웠습니다. 하지만 DESIGN.md가 있으면 최소한 “이 프로젝트의 시각적 방향은 이것이다”라는 공통 언어를 확보할 수 있습니다.
어떤 팀에게 특히 유용한가
모든 팀이 당장 정교한 디자인 시스템을 구축할 수 있는 것은 아닙니다. 특히 빠르게 제품을 만들어야 하는 환경에서는 더 그렇습니다. 그래서 DESIGN.md는 아래와 같은 경우에 특히 유용합니다.
스타트업과 소규모 팀
리소스가 부족한 팀일수록 디자인 기준을 체계적으로 정리하기 어렵습니다. 이럴 때 DESIGN.md는 무겁지 않게 시작할 수 있는 현실적인 방법입니다.
AI로 빠르게 프로토타입을 만드는 팀
짧은 시간 안에 여러 화면을 만들어야 하면 일관성이 쉽게 무너집니다. DESIGN.md는 그 일관성을 유지하는 최소한의 장치가 됩니다.
프런트엔드 개발자가 디자인까지 함께 잡아야 하는 환경
디자이너가 모든 세부 사항을 직접 관리하기 어려운 상황이라면, 개발자와 AI가 참고할 기준이 꼭 필요합니다. DESIGN.md는 그 역할을 해 줄 수 있습니다.
브랜드 리디자인이나 UI 통합이 필요한 프로젝트
기존 화면들이 제각각이라면, DESIGN.md를 기준으로 점진적으로 통일해 나갈 수 있습니다. 새 기능부터 적용해도 되고, 우선순위가 높은 핵심 화면부터 맞춰도 됩니다.
좋은 DESIGN.md를 작성하는 방법
좋은 DESIGN.md는 무조건 길거나 복잡할 필요가 없습니다. 오히려 너무 많은 내용을 넣으면 AI가 핵심을 흐리게 해석할 수도 있습니다. 중요한 것은 짧더라도 명확하고, 모호하지 않으며, 반복적으로 적용 가능한 규칙을 담는 것입니다.
다음 원칙을 지키면 훨씬 좋아집니다.
1. 추상적인 표현만 쓰지 않는다
“세련되게”, “깔끔하게”, “모던하게” 같은 표현만으로는 부족합니다. 이런 말은 사람끼리는 어느 정도 통하지만 AI에게는 매우 애매합니다.
대신 아래처럼 구체적으로 써야 합니다.
- 배경은 밝은 중성 회색 계열
- 카드 그림자는 약하게
- 버튼은 모서리 반경이 너무 크지 않게
- 제목은 강한 대비와 명확한 위계를 가지도록
- 섹션 간격은 넓고 안정적으로
2. 반복 요소를 먼저 정의한다
프로젝트에서 반복해서 쓰이는 요소부터 정리해야 효과가 큽니다.
예를 들면 아래 순서가 좋습니다.
- 색상
- 타이포그래피
- 버튼
- 입력창
- 카드
- 테이블
- 섹션 간격
- 반응형 동작
이런 항목만 정리해도 AI가 생성하는 화면의 질이 상당히 안정됩니다.
3. 금지 규칙을 반드시 넣는다
대부분의 프로젝트는 “무엇을 할지”보다 “무엇을 하지 말아야 하는지”가 더 중요합니다. 특히 AI는 조금만 자유도가 생겨도 과장된 스타일을 섞는 일이 많기 때문에, 금지 규칙이 필요합니다.
4. 제품 성격을 함께 적는다
생산성 도구, 금융 서비스, 커뮤니티 플랫폼, 개발자 도구는 모두 같은 UI 규칙으로 설명할 수 없습니다. 제품이 전달해야 하는 감정이 다르기 때문입니다.
예를 들어 금융 서비스라면 안정감과 신뢰, 개발자 도구라면 정밀함과 밀도, 커뮤니티 서비스라면 친근함과 접근성이 더 중요할 수 있습니다. 이런 맥락이 문서에 들어가야 AI도 더 적절한 방향으로 생성합니다.
간단한 DESIGN.md 예시
아래는 개념 이해를 위한 아주 단순한 예시입니다.
# DESIGN.md
## Brand Feel
Clean, calm, and precise.
The interface should feel trustworthy and structured, not playful.
## Color
- Background: soft near-white
- Primary text: deep neutral gray
- Accent: cobalt blue
- Success: muted green
- Error: restrained red
## Typography
- Headlines should feel sharp and confident
- Body text should prioritize readability
- Avoid decorative or playful font styles
## Layout
- Use generous spacing between sections
- Prefer clear alignment and consistent rhythm
- Cards should feel structured rather than floating
## Components
- Buttons: medium radius, solid fill
- Inputs: visible borders, strong focus states
- Tables: dense but readable
- Modals: minimal shadow, clear hierarchy
## Avoid
- Heavy gradients
- Flashy animations
- Oversized icons
- Marketing-style visual exaggeration이 정도 문서만 있어도 AI는 단순히 예쁜 UI가 아니라, 어떤 성격의 UI를 만들어야 하는지를 훨씬 더 잘 이해합니다.
실무에 적용할 때의 현실적인 방법
처음부터 완벽한 DESIGN.md를 만들려고 하면 오히려 시작이 늦어집니다. 현실적으로는 아래처럼 접근하는 것이 좋습니다.
먼저 비슷한 스타일의 예시를 참고해 초안을 만듭니다. 그다음 현재 서비스에 맞게 색상, 분위기, 컴포넌트 규칙을 수정합니다. 이후 AI에게 실제 페이지를 몇 개 생성하게 해 보고, 어긋나는 부분을 다시 문서에 반영합니다. 이 과정을 반복하면서 문서를 다듬으면 됩니다.
핵심은 문서를 한 번 작성하고 끝내는 것이 아니라, 결과물을 바꾸는 살아 있는 기준서로 운영하는 것입니다.
DESIGN.md가 중요한 이유를 다시 정리하면
DESIGN.md의 가치는 거창한 새 파일 형식에 있는 것이 아닙니다. 핵심은 디자인 의도를 AI가 읽을 수 있는 방식으로 바꿨다는 점입니다.
예전에는 디자인 시스템을 사람끼리 공유했다면, 이제는 AI도 그 시스템의 독자가 되었습니다. 그렇다면 문서 역시 AI가 이해할 수 있게 바뀌는 것이 자연스럽습니다.
그래서 DESIGN.md는 단순한 유행이 아니라, AI 중심 제작 흐름에서 디자인 기준을 유지하기 위한 현실적인 방법이라고 볼 수 있습니다. 특히 UI를 반복 생성하거나, 여러 명이 협업하거나, 브랜드 일관성이 중요한 프로젝트라면 그 가치가 더 커집니다.
마무리
AI는 점점 더 많은 화면을 빠르게 만들어 줍니다. 하지만 빠르게 만드는 것과 제대로 만드는 것은 다릅니다. 결과물이 서비스의 성격과 맞지 않거나, 페이지마다 분위기가 흔들리고, 컴포넌트의 일관성이 무너지면 오히려 유지보수가 더 어려워집니다.
DESIGN.md는 이런 문제를 줄이기 위한 간단하지만 강력한 장치입니다. 디자인 시스템을 AI가 읽을 수 있는 문서로 정리해 두면, 생성 단계와 리뷰 단계 모두에서 기준이 생깁니다. 결국 중요한 것은 AI를 더 많이 쓰는 것이 아니라, AI가 무엇을 기준으로 판단해야 하는지를 명확히 알려 주는 것입니다.
그 기준을 텍스트로 정리한 문서가 바로 DESIGN.md입니다.
출처
- VoltAgent, awesome-design-md GitHub repository
- DESIGN.md 관련 공개 소개 자료 및 개념 설명 페이지