[심층분석] "이렇게 생긴 페이지 만들어줘"가 진짜 되는 시대 — DESIGN.md라는 새로운 약속

AI한테 UI를 맡겼더니 왜 우리 서비스랑 안 어울릴까

요즘 개발하다 보면 이런 경험 한 번쯤 해보셨을 거예요. AI 코딩 에이전트한테 "로그인 페이지 하나 만들어줘"라고 하면 만들어주긴 해요. 근데 결과물을 보면 뭔가... 우리 서비스랑 안 어울리거든요. 버튼 색깔도 제각각이고, 폰트도 어딘가 낯설고, 여백도 들쭉날쭉하죠. 결국 "아니 이거 말고, 우리 브랜드 톤에 맞게"라고 다시 설명하다가 지쳐버려요.

이 문제가 왜 생기냐면요, AI는 그냥 "평균적으로 예쁜 UI"를 만들 뿐, 여러분의 프로젝트가 어떤 얼굴을 하고 있어야 하는지를 모르기 때문이에요. 사람 디자이너라면 브랜드 가이드를 읽고 "아, 이 서비스는 차분한 톤이구나" 하고 감을 잡는데, AI는 그 가이드를 어디서 읽어야 할지조차 몰랐던 거죠.

오늘 소개할 VoltAgent/awesome-design-md는 바로 이 지점을 파고든 프로젝트예요. 핵심은 DESIGN.md라는 파일 하나인데요. 이게 요즘 개발자·디자이너·이른바 '바이브 코더(vibe coder, 감각적으로 AI와 대화하며 빠르게 만드는 사람들)' 사이에서 조용히 하나의 표준처럼 자리 잡아가고 있어요. 왜 그런지, 그리고 우리가 실무에서 어떻게 써먹을 수 있는지 하나하나 풀어볼게요.

DESIGN.md가 뭐냐면요

DESIGN.md는 원래 구글의 'Stitch(스티치)'라는 UI 생성 도구에서 제안한 개념이에요. 이름 그대로 마크다운(.md) 파일 하나에 우리 프로젝트의 디자인 시스템을 글로 적어둔 것이에요. Figma 내보내기도, 복잡한 JSON 설정도, 특별한 도구도 필요 없어요. 그냥 프로젝트 최상단 폴더에 이 파일 하나 툭 던져두면, AI 코딩 에이전트가 알아서 읽고 "아, 이 프로젝트는 이렇게 생겨야 하는구나" 하고 이해하는 구조예요.

여기서 재밌는 포인트가 있어요. 왜 하필 마크다운일까요? 이유는 단순해요. LLM(거대 언어 모델, ChatGPT나 Claude 같은 AI의 두뇌)이 가장 잘 읽는 형식이 바로 텍스트, 그중에서도 마크다운이거든요. 파싱(parsing, 기계가 데이터를 해석하는 작업)할 필요도 없고 별도 설정도 없어요. 사람이 읽어도 그냥 술술 읽히는 문서를, AI도 똑같이 술술 읽는 거예요. 이 '사람과 AI가 같은 문서를 공유한다'는 발상이 이 개념의 핵심 매력이에요.

이해를 돕기 위해 이미 익숙해진 형제 파일과 비교해볼게요.

| 파일 | 누가 읽나 | 무엇을 정의하나 |
|------|----------|----------------|
| AGENTS.md | 코딩 에이전트 | 프로젝트를 어떻게 만들지 (빌드·규칙) |
| DESIGN.md | 디자인 에이전트 | 프로젝트가 어떻게 보여야 할지 (톤·색·여백) |

쉽게 비유하자면요, AGENTS.md가 "집을 어떤 자재로 어떻게 지어라"는 시공 지침서라면, DESIGN.md는 "거실은 따뜻한 우드톤에 조명은 은은하게" 같은 인테리어 콘셉트 문서예요. 둘 다 있어야 집이 제대로 완성되겠죠.

그냥 '색깔 목록'이 아니라 '디자인의 이유'까지 담는다

여기서 오해하기 쉬운 부분을 짚고 갈게요. "그거 그냥 색상 코드랑 폰트 적어둔 거 아냐?"라고 생각할 수 있는데, 이 프로젝트가 강조하는 건 표면적인 값이 아니라 깊이(depth)예요.

좋은 DESIGN.md는 세 가지를 담아요.

• 토큰(tokens): 색상, 간격, 폰트 크기 같은 재사용 가능한 최소 단위 값이에요. "주 색상은 #E07A5F" 같은 것들이죠.
• 패턴(patterns): 버튼은 이렇게, 카드는 저렇게 같은 반복되는 UI 구성 방식이에요.
• 규칙(rules): "강조는 색이 아니라 여백으로 준다", "그림자는 최소한만 쓴다" 같은 디자인 철학과 판단 기준이에요.

이 세 번째, '규칙'이 진짜 중요해요. 단순히 "파란색 써"라고만 하면 AI는 아무 데나 파란색을 칠하지만, "파란색은 클릭 가능한 요소에만 쓴다"는 규칙을 주면 AI가 훨씬 사람 디자이너처럼 판단하거든요. 그래서 결과물이 '어디서 본 듯 어색한 UI'가 아니라 '진짜 그 브랜드가 만든 것 같은 UI'로 나오는 거예요.

실제로 이 저장소에는 유명 브랜드들의 디자인 언어를 분석해 만든 DESIGN.md들이 들어 있어요. 예를 들면 이런 식이에요.

• Claude (Anthropic): 따뜻한 테라코타 색 강조, 깔끔한 편집자스러운 레이아웃
• ElevenLabs: 어두운 시네마틱 UI, 오디오 파형 느낌의 감성
• Mistral AI: 프랑스식 미니멀리즘, 보라 톤
• Ollama: 터미널 우선, 흑백의 단순함

기존 방식과 뭐가 다른 걸까 — Figma, 디자인 토큰, Storybook과 비교

디자인 시스템을 관리하는 방법은 원래도 많았어요. 그럼 이게 왜 새삼 주목받을까요? 기존 방식들과 비교하면 차이가 확 보여요.

Figma 내보내기 방식은요, 디자인 도구에서 만든 화면을 개발자가 보고 그대로 옮기는 방식이에요. 예쁘고 정확하지만, AI 입장에선 이미지라서 '왜 이렇게 디자인했는지'를 못 읽어요. 비유하자면 완성된 요리 사진만 주고 "똑같이 만들어"라는 거예요. AI는 재료도 레시피도 모른 채 눈대중으로 따라 할 수밖에 없죠.

디자인 토큰 JSON 방식은 색·폰트 값을 기계가 읽기 좋은 형식으로 정리한 거예요. 정확하긴 한데 값의 나열일 뿐, "이 색을 언제 왜 쓰는지"라는 맥락이 빠져요. 재료 목록은 있는데 레시피 설명이 없는 거죠.

Storybook은 컴포넌트를 실제로 눈으로 보고 관리하는 도구인데, 훌륭하지만 세팅이 무겁고 사람이 보는 용도에 가까워요.

반면 DESIGN.md는 재료(토큰) + 조리법(패턴) + 요리사의 철학(규칙)을 사람도 AI도 읽는 한 장의 글로 묶은 접근이에요. 정밀함에서는 Figma나 토큰 JSON에 밀릴 수 있지만, 'AI가 맥락째 이해하고 스스로 판단하게 만든다'는 점에서 완전히 다른 결이에요. 요즘처럼 코드의 상당 부분을 AI가 생성하는 흐름에서는, 이 '맥락 전달력'이 엄청난 무기가 되는 거예요.

다만 냉정하게 짚을 점도 있어요. 글로 적힌 규칙은 해석의 여지가 있어서, 픽셀 단위의 정확성이 필요한 프로덕션 디자인에는 부족할 수 있어요. 또 'AI가 알아서 잘 이해하겠지'라는 기대가 항상 맞는 것도 아니고요. 그래서 현실적으로는 Figma나 토큰 시스템을 대체한다기보다, 그 위에 얹는 AI용 안내문 정도로 보는 게 맞아요.

한국 개발자에게 주는 시사점 — 지금 당장 5분이면 시작해요

그럼 실무에서 어떻게 써먹을까요? 구체적인 시나리오로 볼게요.

시나리오 1 — 사내 툴/관리자 페이지 만들 때. 디자이너 없이 개발자가 급하게 어드민 페이지를 찍어내야 할 때 많잖아요. 이때 DESIGN.md에 우리 회사 색상·버튼 스타일·여백 규칙을 30줄 정도 적어두면, 이후 AI가 만드는 모든 화면이 일관된 톤을 유지해요. 페이지마다 색이 미묘하게 달라지는 그 고질병이 사라지는 거죠.

시나리오 2 — 사이드 프로젝트/MVP를 빠르게 만들 때. 디자인 감각이 부담스러운 백엔드 개발자라면, 이 저장소에서 마음에 드는 브랜드의 DESIGN.md를 가져다 쓰세요. 프론트엔드 초안 퀄리티가 확 올라가거든요.

시나리오 3 — 팀의 디자인 지식을 문서로 남길 때. 그동안 디자이너 머릿속에만 있던 "우린 이런 톤이야"를 글로 적어두면, 사람 신입에게도 좋은 온보딩 문서가 되고 AI에게도 지침이 돼요. 사람과 AI가 같은 문서를 보는, 앞서 말한 그 장점이 그대로 실현되는 거죠.

도입할 때 고려할 점도 있어요. 첫째, 처음부터 완벽하게 쓰려 하지 마세요. 색 몇 개, 규칙 몇 줄로 시작해서 결과물을 보며 다듬는 게 훨씬 현실적이에요. 둘째, 규칙은 '값'이 아니라 '판단 기준'으로 적으세요. "#333 써"보다 "본문 텍스트는 순검정 대신 짙은 회색으로 부드럽게"가 AI에게 훨씬 잘 먹혀요. 셋째, AGENTS.md와 함께 쓰면 시너지가 커요. 하나는 '어떻게 만들지', 하나는 '어떻게 보일지'를 나눠 맡으니까요.

학습 로드맵을 짧게 제안하자면요 — (1) 이 저장소에서 브랜드 하나 골라 DESIGN.md를 열어보고 어떻게 썼는지 구조를 눈에 익히세요. (2) 내 프로젝트에 복사해 AI로 페이지를 하나 뽑아보세요. (3) 마음에 안 드는 부분을 규칙으로 추가하며 나만의 버전으로 발전시키세요. 이 세 단계면 개념이 몸에 붙어요.

마무리 — '문서가 곧 디자인'이 되는 흐름

DESIGN.md가 흥미로운 건, 단순한 유행 파일이 아니라 AI 시대에 협업의 기본 단위가 바뀌고 있다는 신호이기 때문이에요. 예전엔 사람끼리 회의하고 Figma로 소통했다면, 이제는 사람도 AI도 함께 읽는 마크다운 문서 한 장이 그 자리를 채워가고 있어요. README.md가 프로젝트 소개의 표준이 되고, AGENTS.md가 에이전트 지침의 표준이 되어가듯, DESIGN.md도 그 계보에 합류하려는 셈이죠.

물론 이게 모든 디자인 문제를 풀어주진 않아요. 정밀함이 필요한 곳엔 여전히 사람의 손과 전용 도구가 필요하고요. 하지만 "우리 서비스 톤에 맞는 화면을 빠르게, 일관되게"라는 아주 현실적인 갈증을, 놀랄 만큼 가벼운 방식으로 긁어준다는 점만큼은 분명해요.

여러분은 어떠세요? AI한테 UI를 맡겼다가 어색한 결과에 한숨 쉰 적, 다들 있으시죠. 만약 여러분의 서비스를 위한 DESIGN.md를 딱 다섯 줄로 요약한다면, 어떤 규칙을 가장 먼저 적으시겠어요? 댓글로 각자의 '디자인 한 줄 철학'을 나눠보면 재밌을 것 같아요.