피그마는 사람용, 디자인 시스템에 AI를 위한 문서가 하나 더 필요해졌어요

디자인 MD 파일

"선생님, AI 진도가 너무 빨라요." 요즘 디자이너들끼리 하는 말이에요. 며칠만 지나도 새 AI 툴이 나오고, 디자인을 코드로 바꿔주는 툴도 계속 늘어요. 그런데 이 빠른 진도를 따라가려고 보니 한 가지가 걸립니다. AI가 우리 팀 디자인 시스템을 제대로 못 읽어요.

피그마는 사람이 보기에 좋아요. 근데 AI가 읽기엔 어려워요. 그래서 생긴 게 DESIGN.md 파일이라는 흐름이에요. 구글 스티치도 쓰고, 개발자들이 CLAUDE.md나 AGENTS.md 쓰듯 디자인 쪽에도 팀 규칙을 Markdown으로 적어두는 거예요.

피그마만으로는 AI한테 설명이 안 돼요

예전에 디자인 시스템이라고 하면 보통 Figma 안에 컴포넌트를 정리하는 것을 떠올렸어요. 버튼, 컬러, 타이포그래피, 간격 규칙. 디자이너와 개발자가 참고하는 방식. 거기서 한 걸음 더 간 게 디자인 토큰이에요. color.primary = #3366FF, spacing.md = 16px, radius.button = 8px. Figma와 코드에서 같은 이름으로 쓰는 체계. 요즘 많이들 이렇게 해요.

문제는 AI가 들어오면서예요.

사람은 화면만 봐도 "이 버튼은 Primary 버튼", "이 간격은 16px 규칙" 금방 이해해요. AI는 달라요. 피그마 파일 전체를 읽고 구조를 이해하는 것부터 쉽지 않아요. Figma MCP 같은 방식으로 연결하더라도 컴포넌트 관계나 디자인 의도를 완벽히 파악하지 못하는 경우가 많대요. AI한테 "해줘"라고 했을 때 비슷하게 그리는 척은 해요. 근데 우리 팀 디자인 시스템에 정확히 맞춰주지는 못해요.

반대로 코드만 있으면 디자이너가 이해하기 어려워요. 코드 안에는 값은 있지만 왜 그렇게 만들었는지, 어떤 상황에서 써야 하는지 같은 맥락이 잘 드러나지 않거든요. 그래서 최근엔 Figma와 별도로 "AI가 읽을 수 있는 디자인 문서"를 같이 만드는 흐름이 생겨요. 버튼 규칙, 컬러 사용 기준, 간격 체계, 모달 동작 방식을 텍스트로 정리한 문서. 그게 디자인 MD 파일이에요.

MD 파일 개념

한 페이지짜리 팀 약속 문서

디자인 MD 파일은 쉽게 말하면 "우리 팀이 디자인할 때 지켜야 할 약속을 텍스트로 정리한 문서"예요. 보통 Markdown 형식(.md)으로 작성해요. 들어가는 내용은 이런 것들.

디자인 원칙과 UI 규칙을 텍스트로 설명하는 문서. 예전에는 이런 내용을 Figma 안에 적어두거나 Slack으로 공유했어요. 근데 AI는 Slack 대화를 읽지 못하고, Figma의 구조도 완벽히 이해하지 못해요. "우리 팀 디자인은 이렇게 해"라고 AI한테 알려주려니 MD 파일이 필요해진 거예요.

AI 시대엔 공통 언어가 셋으로 늘어나요

예전엔 디자인 시스템이 디자이너와 개발자 사이의 공통 언어였어요. 이제는 AI까지 포함한 공통 언어가 돼야 해요.

Claude나 Cursor 같은 툴로 코드를 만들 때 "우리 팀 버튼 규칙에 맞춰서 결제 완료 화면 만들어줘"라고 할 수 있어요. 근데 AI는 우리 팀의 디자인 규칙을 모르잖아요. 버튼 Radius가 4px인지 12px인지, Primary Color가 뭔지, 카드 간격이 몇 px인지 판단할 수 없어요. 피그마나 스토리북이 있더라도 대부분 컴포넌트 단위 정보만 담겨 있어서 실제 화면을 팀 스타일에 맞게 설계하기는 어려워요.

이때 디자인 MD 파일을 같이 제공하면 AI가 문서를 읽고 우리 팀의 원칙과 규칙을 이해한 뒤 일관된 결과를 만들어내요. MD 파일은 AI한테 디자인 시스템을 설명해주는 안내서인 셈이에요.

MD 파일이 있으면 뭐가 좋아지느냐

새로 온 디자이너의 첫 주가 달라져요

새 디자이너가 입사하면 항상 비슷한 질문을 해요. "버튼 Radius 몇 px였죠?", "모달은 Bottom Sheet로 가나요?", "Primary Color 뭐 쓰나요?", "에러 메시지는 어떤 컬러 써야 해요?" 예전엔 Slack으로 물어보고, 예전 파일 찾아보고, 누군가 답해주기를 기다리고. MD 파일이 있으면 한 문서만 보면 돼요.

"우리 팀 버튼 Radius 몇 px야?"라고 AI한테 물으면 MD 파일을 읽고 바로 답해줘요. 새로 온 디자이너는 사람한테 계속 물어보지 않아도 되고, 팀도 반복 설명을 줄일 수 있어요.

AI가 팀 스타일을 이해해요

AI한테 "로그인 화면 만들어줘" 하면 보통은 입력창 2개, 버튼 1개짜리 일반적인 화면이 나와요. MD 파일과 함께 요청하면 결과가 달라져요. 다만 중요한 건 규칙을 무조건 많이 적는다고 좋은 결과가 나오는 게 아니라는 점. AI가 이해하기 쉬운 문서는 "중요한 기준이 무엇인지"가 명확해야 해요.

너무 세세한 규칙을 끝없이 나열하면 오히려 우선순위를 판단하지 못하고, 서로 충돌하는 기준 때문에 결과가 흔들려요. 로그인 화면이라면 색상이나 간격만 정하는 게 아니라 화면이 어떤 원칙으로 동작해야 하는지를 정의하는 게 중요해요.

[UX 목적] 사용자가 핵심 행동까지 빠르게 도달할 수 있어야 합니다. 입력, 확인, 오류 처리, 보조 행동이 한 흐름 안에서 자연스럽게 이어져야 합니다. 화면 안에서 가장 중요한 행동이 명확하게 드러나야 합니다.
[레이아웃 원칙] 화면 좌우 여백은 모바일 기준 24px을 사용합니다. 주요 콘텐츠 영역은 화면 중앙에 배치하고, 핵심 CTA는 첫 화면 안에서 확인 가능해야 합니다. 보조 행동 요소는 주요 CTA 아래에 배치하고, 버튼과의 간격은 16px을 유지합니다.
[입력 필드 원칙] 입력창 높이는 48px로 통일합니다. 입력창 간 간격은 12~16px. 입력창과 CTA 버튼 사이는 16px. 에러 메시지는 입력창 바로 아래 8px 간격으로 노출합니다.
[CTA 원칙] CTA 버튼은 Primary Button 컴포넌트를 사용. 브랜드 메인 컬러와 반전 텍스트 컬러. 높이·좌우 패딩은 Large 사이즈 기준. 모바일에서는 키보드가 올라와도 CTA 영역이 가려지지 않도록 안전 영역을 포함. CTA 버튼은 화면 하단 고정 레이아웃, 첫 화면 기준 1 스크롤 안에 노출되도록 설계.

결국 디자인 MD 파일은 단순한 스타일 가이드가 아니에요. AI를 우리 팀의 새로운 디자이너처럼 활용하기 위한 지식 문서에 가까워요. 모든 걸 다 적기보다 "우리 팀이 중요하게 생각하는 핵심 규칙"을 우선순위 있게 정리하는 게 더 중요한 거죠.

같은 질문이 반복되지 않아요

MD 파일 없이 AI로 수천 번의 딸깍으로 서비스를 제작하면 팀마다 버튼 모양, 컬러, 간격이 다 달라져요. 서비스가 뒤죽박죽 되는 거예요. MD 파일은 "우리 팀은 이렇게 만든다"는 기준점 역할을 해요.

실무에서 반복되는 질문들이 있잖아요.

이런 질문은 팀 시간을 계속 잡아먹어요. MD 파일이 있으면 모두가 같은 문서를 참고하니까 자연스럽게 줄어요. 그 결과 서비스 전반에 통일된 디자인 원칙이 적용되고, 제품 일관성도 높아지고요.

MD 파일 하나로는 디자인 시스템이 완성 안 돼요

"MD 파일만 잘 만들어두면 디자인 시스템 끝난 거 아닌가요?" 많은 팀이 묻는대요. 근데 실제로는 부족해요. 디자인 시스템은 보통 세 가지가 함께 있어야 제대로 작동해요.

즉 Figma, MD 파일, Storybook이 각각 다른 역할을 맡아야 한다는 거예요.

[Figma] 장점: 시각적으로 디자인하고 화면 구조를 빠르게 확인. 단점: 왜 이런 규칙을 쓰는지, 어떤 상황에서 써야 하는지 설명하기 어렵고 AI가 읽기 어려움.
[MD 파일] 장점: 디자인 원칙, 사용 기준, 예외 상황을 텍스트로 정리. 단점: 실제 화면이 어떻게 생겼는지 직관적으로 보여주기 어려움.
[Storybook] 장점: 구현된 컴포넌트와 인터랙션을 실제 코드 기준으로 검증. 단점: 디자인 의도나 운영 원칙까지 설명하기엔 한계.

버튼 하나를 예로 들어볼게요.

같은 버튼이라도 세 도구가 보는 관점이 달라요. Figma는 "어떻게 보여야 하는가", MD 파일은 "왜 이렇게 만들었는가 + 언제 써야 하는가", Storybook은 "실제로 제대로 구현되었는가".

디자인 시스템은 "컴포넌트 파일 하나"로 끝나는 게 아니에요. 아래처럼 구성되는 게 가장 현실적.

Figma - 시각적 원본 / MD 파일 - 규칙 문서 / Storybook - 실제 구현 검증

여기에 여유가 있는 팀이라면 토큰 관리 도구, 코드 컴포넌트 라이브러리, 운영 가이드까지 추가할 수 있어요.

Design Token - 컬러, 간격, Radius, 타이포그래피 값을 코드와 연결 / Component Library - 실제 서비스에서 재사용하는 UI 컴포넌트 모음 / 운영 가이드 - 누가 수정할 수 있는지, 변경 시 어떤 절차를 거치는지 정리

MD 파일은 디자인 시스템의 중요한 축이지만 혼자서 모든 역할을 하지는 못해요. "보여주는 도구", "설명하는 문서", "검증하는 환경"이 함께 있어야 제대로 굴러가요.

MD 파일은 어떻게 생겼을까

생각보다 단순해요. 코드처럼 보이지만 사실은 디자인 설명서에 가까워요.

# Button
## Primary Button
- Background: #3366FF
- Text Color: White
- Radius: 8px
- Padding: 12px 16px
- Use Case: 주요 CTA
## Secondary Button
- Border: 1px solid #DADADA
- Text Color: #111111
- Background: White
- Radius: 8px
# Spacing
- 4px: 아이콘과 텍스트
- 8px: 작은 컴포넌트 간격
- 16px: 카드 내부 간격
- 24px: 섹션 간격
# Modal
- Desktop: Center Modal
- Mobile: Bottom Sheet

디자이너의 새 역할은 '규칙을 쓰는 일'이에요

지금까지 나온 흐름을 보면, 앞으로의 디자인 시스템은 단순히 컴포넌트를 모아두는 라이브러리에서 끝나지 않을 가능성이 높아요. 예전에는 Figma 안에 버튼, 컬러, 타이포그래피를 정리해두면 20명 내외 디자인 팀이 쓰기에 충분했거든요.

지금은 디자이너뿐 아니라 개발자, PO까지 AI로 화면을 그려요. AI가 화면을 만들고, 코드를 생성하고, 문서를 읽고, 팀의 스타일을 학습하는 시대가 됐어요. 이 과정에서 디자인팀의 새 역할은 "우리 팀은 어떤 기준으로 디자인하는가"라는 원칙을 세우고, 사람뿐 아니라 AI도 이해할 수 있게 설명하는 일.

디자인 시스템은 더 이상 하나의 툴 안에서 끝나는 개념이 아니에요. 여러 도구와 문서가 연결된 구조로 발전하는 중이고요. 특히 AI를 활용하는 팀일수록 문서화된 규칙의 중요성은 더욱 커져요. AI는 새로운 스타일을 만드는 것보다, 정해진 기준을 반복 적용하는 데 강하거든요. 반대로 기준이 모호하면 팀 스타일과 맞지 않는 결과가 계속 나와요.

그래서 앞으로 디자이너는 컴포넌트를 만드는 능력뿐 아니라, 규칙을 텍스트로 정리하고 지속적으로 관리하는 제품 운영 역량도 중요해질 거예요. 디자인 시스템은 점점 UI 라이브러리를 넘어, 사람과 AI가 함께 참고하는 제품 운영 문서에 가까워지는 중이에요.