구글이 공개한 DESIGN.md, 이것이 무엇이기에 이토록 주목받는가

2026년 4월 21일, 구글 랩스(Google Labs Code)가 DESIGN.md라는 독특한 포맷을 오픈소스로 공개했다. 저장소는 github.com/google-labs-code/design.md이고, 버전은 v0.1.0, 아직 alpha 단계이다. 쉽게 말하면 AI 코딩 에이전트에 전달하는 디자인 시스템 명세서이다. 마크다운 파일 하나에 컬러, 타이포, 스페이싱, 컴포넌트 규칙을 모두 적어두고, 클로드 코드(Claude Code)나 커서(Cursor) 같은 도구가 이를 읽어 UI를 일관되게 생성하도록 만드는 것이다.
 
공개 직후 해커뉴스 프론트페이지에 올라가면서 화제가 되었다(4월 21일자 "Show HN: DESIGN.md" 스레드, 댓글 300개 이상 달렸다). 최근 AI 코딩 에이전트를 쓰면서 "화면 만들 때마다 디자인 톤이 제각각 나온다"는 불만이 쌓여 있었는데, 구글이 이를 한 파일 표준으로 밀어붙였다. 심지어 이 흐름을 "바이브 디자인(vibe design)"이라고 브랜딩하고 있다. 바이브 코딩에 이어 바이브 디자인이다. 용어를 정말 잘 만들어낸다.
 
이 글에서는 DESIGN.md가 정확히 무엇이고, 어떤 구조로 되어 있으며, 클로드 코드 같은 AI 에이전트에 어떻게 적용하는지, 그리고 기존 JSON 디자인 토큰(DTCG)과는 무엇이 다른지 솔직하게 살펴본다. 2026년 4월 기준으로 한국어 매체에서 포맷 자체를 깊이 다룬 글이 거의 없기에, 실전 팁까지 함께 정리했다.
 
https://github.com/google-labs-code/design.md

GitHub - google-labs-code/design.md: A format specification for describing a visual identity to coding agents. DESIGN.md gives a

 
 
 

DESIGN.md는 도대체 무엇인가

 
한 줄로 요약하면 마크다운으로 쓴 디자인 시스템 명세서이다. YAML 프론트매터에 토큰값(머신이 읽는 부분)이 들어가고, 그 아래 마크다운 본문에 설계 근거와 사용 규칙(사람이 읽는 부분)이 붙는 2-레이어 구조이다. 왜 하필 마크다운인가? AI 에이전트의 컨텍스트 윈도우에 그대로 주입하기 좋고, 사람도 그냥 눈으로 읽을 수 있기 때문이다.
 

누가 만들었고 언제 공개되었는가

 
제작 주체는 구글 랩스(Google Labs) 내 코드 팀이다. 원래는 2026년 3월에 공개된 구글 스티치(Stitch) 업데이트의 부속 기능으로 처음 등장했다. 스티치는 구글이 밀고 있는 AI 디자인 캔버스 도구로, 그 안에서 "디자인 시스템을 어떻게 AI에 전달할 것인가"를 고민한 끝에 나온 포맷이다. 그러다 4월 21일, 포맷 자체만 별도 오픈소스 저장소로 분리해 공개했다. 스티치를 쓰지 않는 사람도 이 표준만 가져다 쓸 수 있도록 개방한 것이다.
 

어디서 받을 수 있는가

 
저장소는 github.com/google-labs-code/design.md이고, 라이선스는 오픈소스이며 alpha 단계이다. 공식 발표는 blog.google의 구글 랩스 카테고리에 올라와 있다. 별도 문서 사이트는 아직 없고, README와 저장소 내 examples/ 디렉토리가 전부이다.
 

왜 화제가 되었는가

 
개발자 입장에서 정말 불편했던 지점이 있었다. 클로드 코드에 "대시보드 화면을 만들어달라"고 요청하면, 첫 번째 화면과 두 번째 화면의 색상이 다르게 나온다. 폰트 크기도 제각각이고 여백도 일관성이 없다. 매번 프롬프트에 "컬러는 #3B82F6, 본문은 16px..." 같은 내용을 일일이 붙이는 것은 지나치게 비효율적이었다. DESIGN.md는 이를 한 파일로 해결하겠다는 시도이다. 프로젝트 루트에 두면 AI 에이전트가 알아서 읽어 일관된 UI를 생성한다.
 

바이브 디자인이 왜 지금 터졌는가

 
2024~2025년에는 "바이브 코딩(vibe coding)"이라는 말이 유행했다. 개발자가 타이핑 대신 AI에 "이런 기능을 만들어달라"고 말로 지시하는 흐름이다. 2026년에 구글이 들고 나온 것이 그 디자인 버전인 바이브 디자인이다.
 

AI 코딩 에이전트의 고질적 약점

 
최근 클로드 코드, 커서, 윈드서프(Windsurf), 키로(Kiro) 같은 AI 코딩 에이전트가 코드는 잘 생성하지만 UI 일관성은 형편없다. 우선 에이전트가 디자인 컨텍스트를 매 세션 기억하지 못하는 것이 가장 크다. 그렇다고 프롬프트마다 풀 스펙을 다시 붙이면 토큰이 대량으로 소모된다. 게다가 컴포넌트 간 관계(예: 이 버튼은 저 카드 안에서만 쓰인다)를 에이전트가 알지 못하니 제멋대로 섞어 쓴다.
 
결과적으로 "AI가 만든 UI 10개 중 7개는 결국 사람이 손봐야 한다"는 후기가 흔했다. 4월 초 해커뉴스에 올라온 "Why AI-generated UIs still need a human" 글(ID 39812xx)이 400표 이상을 얻으며 개발자 커뮤니티에서 상당히 회자되었는데, 댓글 톤은 대체로 이 문제에 동의하는 분위기였다.
 

바이브 디자인 컨셉

 
구글이 블로그에서 밀고 있는 바이브 디자인의 골자는 단순하다. "말로 만들고 AI가 그린다". 다만 AI가 제멋대로 그리지 않도록 가드레일 역할을 하는 파일이 필요한데, 그것이 DESIGN.md이다. 사람은 "이런 느낌의 랜딩 페이지를 만들어달라" 수준으로만 얘기하고, 나머지는 DESIGN.md에 적힌 토큰과 규칙 안에서 AI가 알아서 처리한다.
 

CLAUDE.md, AGENTS.md 패밀리에 합류

 
이 포맷이 튀어나온 맥락을 보면 금세 이해된다. 이미 AI 에이전트 생태계에는 컨텍스트 파일 패밀리가 쌓여 있었다. 클로드 코드가 프로젝트 루트에서 자동으로 읽는 CLAUDE.md가 있고, OpenAI 쪽에서 밀고 있는 범용 포맷 AGENTS.md가 있다. 구글 제미나이 CLI용 GEMINI.md, 커서용 .cursorrules까지 합치면 이미 네다섯 개 포맷이 공존하는 상태였다.
 
이 패밀리에 "디자인 전용 컨텍스트" 자리가 비어 있었고, 거기에 DESIGN.md가 꽂힌 것이다. 다른 벤더들이 굳이 다른 표준을 만들 이유가 약해 자연스럽게 참조 대상이 될 가능성은 커 보이나, 아직 alpha이고 v0.1.0이라 "표준 확정"이라고 말하기에는 이르다.
 

DESIGN.md 구조 뜯어보기

 
이제 파일 내부가 어떻게 생겼는지 살펴본다. 매우 단순하다. YAML 프론트매터 + 마크다운 본문, 이 조합이다.
 

2-레이어 구조의 의미

 
레이어 1(YAML 프론트매터)은 머신이 파싱하는 영역이다. 여기에 색상, 폰트, 간격 같은 토큰값이 구조화되어 들어간다. CLI 도구나 익스포트 파이프라인이 이 값만 추출해 간다.
 
레이어 2(마크다운 본문)는 사람과 AI가 함께 읽는 영역이다. "이 컬러는 CTA 버튼에만 쓸 것", "Primary는 경고 상황에서는 쓰지 말 것" 같은 설계 의도와 사용 규칙을 자연어로 적는다. AI 에이전트는 토큰값만 보는 것이 아니라 이 맥락도 함께 읽어 판단한다. JSON에 주석조차 달 수 없는 기존 포맷과 가장 크게 달라지는 지점이 여기이다.
 

지원 토큰 종류

 
공식 저장소 기준 v0.1.0에서는 컬러(배경, 전경, 브랜드, 상태), 타이포그래피(폰트 패밀리, 사이즈 스케일, 라인 높이, 굵기), 스페이싱(4/8 그리드 기반 스케일), 라운디드 코너(보더 라디우스 스케일), 그리고 컴포넌트 단위 규칙(버튼, 카드, 폼 필드 등)까지 다룰 수 있다. 컴포넌트 레벨은 아직 예시가 얕아, 실전에서는 자기 프로젝트 상황에 맞춰 직접 채워 넣어야 한다.
 

실제 코드 블록 예시

 

---
name: "샘플 디자인 시스템"
version: "0.1.0"
colors:
  brand:
    primary: "#5B5BF5"
    secondary: "#14B8A6"
  surface:
    background: "#0F0F1A"
    card: "#1A1A2E"
  text:
    primary: "#F1F5F9"
    muted: "#94A3B8"
typography:
  font_family:
    sans: "Pretendard, Inter, sans-serif"
    mono: "JetBrains Mono, monospace"
  scale:
    body: "16px"
    h1: "32px"
    h2: "24px"
    h3: "18px"
  line_height:
    body: 1.7
spacing:
  scale: [4, 8, 12, 16, 24, 32, 48, 64]
rounded_corners:
  sm: "4px"
  md: "8px"
  lg: "12px"
---

# 샘플 디자인 시스템

## 사용 규칙

### Primary 컬러
`#5B5BF5`는 주요 액션 버튼과 링크에만 씀. 경고/위험 상황에는
절대 쓰지 않음. 한국어 본문에서 링크로 쓸 때는 밑줄 추가함.

### 한국어 타이포 예외
본문 폰트는 Pretendard 우선, 행간은 1.7 유지. 한국어는 영문보다
행간을 넓혀야 가독성이 좋음.

 
이런 식이다. 한국어 타이포 주석까지 자연어로 남길 수 있는 것이 포인트이다. JSON 토큰만으로는 이런 설계 의도를 담을 수 없다.
 

왜 JSON이 아니라 마크다운인가

 
이것이 가장 중요한 지점이다. 기존에는 W3C Design Token Community Group(DTCG)의 JSON 포맷이 업계 표준이었다. 다만 구글이 굳이 마크다운을 택한 이유가 몇 가지 있다.
 
첫째, AI 컨텍스트에 훨씬 잘 맞는다. LLM에 JSON을 1000줄 주입하는 것보다 마크다운 500줄을 주입하는 편이 토큰 효율이 낫다. 자연어 설명이 그대로 들어가기에 "왜 이렇게 정했는지"를 AI가 이해한다. 둘째, 사람이 리뷰하기 쉽다. PR에서 디자이너도 읽을 수 있고, 깃허브에서 그대로 렌더링된다. JSON은 들여쓰기를 세면서 봐야 한다. 셋째, CLAUDE.md, AGENTS.md와 같은 컨벤션이라 러닝커브가 거의 없다. 이미 프로젝트 루트에 있는 다른 컨텍스트 파일 옆에 하나 더 두는 느낌으로 도입된다.
 
물론 단점도 있다. 머신 파싱을 엄격하게 강제하려면 JSON이 낫다. 그래서 DESIGN.md는 프론트매터에 YAML을 쓰는 하이브리드 구조를 택한 것이다. 앞쪽 YAML은 파싱용, 뒤쪽 마크다운은 설명용으로 역할을 분리했다. JSON 디자인 토큰이 빌드 시스템을 위한 포맷이라면, DESIGN.md는 AI 에이전트를 위한 포맷으로 자리 잡는 셈이다.
 

CLI 도구로 무엇을 할 수 있는가

 
저장소에 CLI가 함께 포함되어 있다. 아직 alpha라 기능이 많지는 않으나, 실전에서 쓸 만한 것은 린트, diff, 그리고 익스포트(Tailwind / DTCG) 이렇게 네 가지이다.
 

린트(lint): 깨진 참조 + WCAG 검증

 

npx design lint ./DESIGN.md

 
이 명령어가 꽤 유용하다. 토큰 간 순환 참조, 선언되지 않은 토큰 사용, 중복 정의를 잡아주고, WCAG 명도 대비까지 검증한다. 배경 + 전경 색 조합이 AA(4.5:1) 기준 미달이면 경고를 출력한다. 디자인 시스템을 만들다가 "이 글자색이 이 배경에서 거의 보이지 않는다"는 버그를 출시 전에 잡을 수 있다.
 

diff: 버전 비교

 

npx design diff v0.1.0 v0.2.0

 
두 버전 간 토큰 차이를 사람이 읽을 수 있게 출력해준다. "Primary 컬러가 #3B82F6에서 #5B5BF5로 변경되었다" 같은 변경 리포트가 깔끔하게 나온다. 디자인 시스템 릴리즈 노트 자동 생성에 바로 활용할 수 있다.
 

Tailwind config 익스포트

 

npx design export tailwind ./DESIGN.md > tailwind.config.js

 
DESIGN.md에서 바로 Tailwind CSS config로 내보낸다. 프론트 프로젝트에서 바로 쓸 수 있다. Tailwind가 프론트엔드 AI 자동화 파이프라인의 사실상 기본값이라, 구글도 여기부터 지원해준 모양새이다.
 

DTCG 익스포트

 

npx design export dtcg ./DESIGN.md > tokens.json

 
W3C DTCG 포맷(JSON)으로도 출력해준다. 기존 Style Dictionary 파이프라인이나 Figma Tokens 플러그인과 호환되도록 설계한 것이다. 즉, DESIGN.md를 소스오브트루스로 두고, 빌드 시점에 JSON이든 CSS Variables든 Tailwind든 추출해 쓰는 구조가 가능하다.
 

클로드 코드와 커서에 실제로 적용해보기

 
아마 가장 관심 있는 부분일 것이다. 저장소의 공식 셋업 가이드는 짧게만 제공되고 있어, 실전에서 어떻게 써야 잘 작동하는지 정리한다.
 

프로젝트 루트에 DESIGN.md 두기

 
가장 기본이다. 프로젝트 최상위에 DESIGN.md 파일을 만들고 위 예시처럼 YAML + 마크다운을 채우면 된다. 이름은 대문자 DESIGN.md를 권장한다. CLAUDE.md, AGENTS.md가 모두 대문자라 생태계 컨벤션을 맞추는 것이다.
 

클로드 코드에서 인식시키기

 
클로드 코드는 프로젝트 루트의 CLAUDE.md를 자동으로 읽으나, DESIGN.md는 아직 자동 로드되지 않는다(2026년 4월 기준). 두 가지 우회 방법이 있다. 하나는 CLAUDE.md 안에 "UI 작업 시 DESIGN.md를 먼저 읽고 토큰 내에서만 작업할 것"이라고 명시적으로 적어두는 것이다. 이 방법이 가장 확실하다. 다른 하나는 세션 시작 시 "DESIGN.md를 읽고 로그인 화면을 만들어달라"와 같이 프롬프트에 직접 포함시키는 것이다. 개인적으로는 전자, 즉 CLAUDE.md에 한 줄 박아두는 방식이 훨씬 편하다고 본다. 매번 프롬프트에 적는 것은 몇 번만 해도 번거로워진다.
 

커서, 윈드서프, 키로에서의 차이

 
커서는 .cursorrules에 DESIGN.md를 참조하라고 적어두면 된다. 윈드서프는 .windsurfrules 파일이 같은 역할을 한다. 키로는 자체 컨텍스트 시스템이 있는데 DESIGN.md를 인덱싱 대상에 추가하면 된다. 결국 모든 에이전트에서 공통으로 통용되는 파일 하나로 관리된다는 점이 DESIGN.md의 장점이다. 에이전트를 갈아타도 재작성할 필요가 없다.
 

한국어 디자인 시스템에 적용할 때 팁

 
한국어 프로젝트에 DESIGN.md를 쓸 때 주의할 점이 있다. 우선 폰트 패밀리에 Pretendard나 Noto Sans KR을 명시해야 한다. 기본값이 Inter라 한국어 가독성이 많이 떨어진다. 행간은 1.6~1.8로 넉넉하게 잡는 편이 좋다. 영문 기준 1.4~1.5로 잡으면 한글이 답답해 보인다. 자간은 -0.02em 정도로 살짝 조여주면 한글 본문이 훨씬 깔끔해진다. 그리고 마크다운 본문에 "이 스케일은 한국어 기준"이라고 적어두는 것이 의외로 중요하다. 그래야 AI 에이전트가 나중에 영문 카피를 붙일 때도 같은 스케일을 유지하라는 맥락을 이해한다.
 
현재 공식 샘플은 전부 영문 기준이라 한글 특화 토큰 작성 예시가 없다. 직접 만들어 블로그에 공유하면 한국어 SEO 관점에서도 차별화 포인트가 된다.
 

JSON 디자인 토큰과 무엇이 다른가

 
기존에 디자인 토큰을 다뤄본 사람이라면 여기가 가장 궁금할 것이다. 솔직하게 비교해봤다.
 

DTCG / Style Dictionary와의 포지션

 
W3C DTCG는 엄격한 JSON 스키마 기반 표준이다. Style Dictionary는 이를 빌드 도구로 묶은 OSS이다. 이 둘은 빌드 파이프라인 친화적이고, Figma Tokens Studio 같은 디자인 툴과 양방향 동기화가 된다는 점이 최대 장점이다. 반면 DESIGN.md는 AI 에이전트 친화적이다. 사람과 AI가 함께 읽을 수 있고, 자연어 맥락을 담을 수 있다. 대신 스키마 강제력이 약하고, 도구 생태계가 아직 빈약하다.
 
둘은 경쟁하기보다 공존할 가능성이 크다. 실제로 DESIGN.md의 CLI가 DTCG 익스포트를 지원한다는 점이 이를 보여준다. DESIGN.md를 소스오브트루스로 두고, 빌드 시점에 DTCG JSON을 추출해 Style Dictionary에 넘기는 워크플로우가 가장 현실적인 접근으로 보인다.
 

Figma Tokens / Tokens Studio와 호환되는지

 
직접 호환은 아직 지원되지 않는다. DTCG 익스포트를 거쳐야 Tokens Studio에 임포트할 수 있다. 커뮤니티에서 플러그인 작업이 이미 진행 중인데, 가장 눈에 띄는 것은 저장소 이슈 #18에서 제안된 figma-design-md-sync 프로토타입이다(작성자 @kyletaylored, 4월 22일 기준 코멘트 40개). 2026년 하반기쯤에는 네이티브 지원도 나올 것으로 보이나, 아직 로드맵 공식 문서는 없다.
 

단점은 없는가

 
있다. 솔직하게 적는다.
 
첫째, alpha 단계라 스펙이 깨질 수 있다. v0.1.0이라 v0.2.0에서 브레이킹 체인지가 나올 가능성이 있고, 프로덕션 도입은 다소 이르다. 둘째, 빌드 파이프라인 통합이 빈약하다. DTCG는 성숙한 Style Dictionary 생태계가 있지만, DESIGN.md는 이제 막 시작이라 자체 빌드 자동화를 구성해야 한다. 셋째, 대형 디자인 시스템에는 아직 부족하다. 수백 개 컴포넌트, 멀티 브랜드, 다크/라이트 모드 분기까지 쓰는 팀에 v0.1.0은 분명 부족하고, 스타트업 프로토타입이나 중소 프로젝트에 더 잘 맞는다. 넷째, AI 에이전트 자동 로드 표준이 잡혀 있지 않다. 클로드 코드는 CLAUDE.md를 자동 로드하지만, DESIGN.md 자동 로드 표준은 아직 없어 각 에이전트별로 연결 설정을 해줘야 한다.
 

도입할 가치가 있는가

 
결론부터 말하자면, 지금 따라가 두면 나중에 편할 확률이 높다. "이것이 무조건 표준으로 굳는다"라고 단정할 근거는 아직 없지만, 컨텍스트 파일 패밀리 안에 디자인 자리 하나가 비어 있었고 구글이 거기에 가장 먼저 깃발을 꽂은 것은 사실이다. CLAUDE.md가 코드 맥락을 담당했다면, DESIGN.md는 UI 맥락을 담당하는 포지션이다. AI 에이전트 중심 워크플로우로 가고 있다면 지금 미리 DESIGN.md 하나 만들어두는 정도는 품이 크지 않고, 실제로 써본 체감으로도 화면 3~4개 만들다 보면 톤이 틀어지는 횟수가 확 줄어든다.
 
지금 바로 도입해도 되는 팀은 AI 에이전트(클로드 코드, 커서)로 프론트 작업이 많은 개인 개발자, 디자인 시스템이 아직 크지 않은 초기 스타트업, 프로토타입을 빠르게 뽑는 에이전시나 사이드 프로젝트, 그리고 한국어 디자인 시스템을 AI에 표준화해 넘기고 싶은 팀이다. 반대로 아직 기다려도 되는 쪽도 있다. 이미 Style Dictionary + Figma Tokens로 빌드 파이프라인이 잘 돌아가는 대형 팀, 디자인 시스템에 수백 개 컴포넌트가 있고 QA 프로세스가 엄격한 엔터프라이즈, alpha 단계 리스크를 감당할 수 없는 프로덕션 환경이 그런 경우이다. 이런 팀은 v0.3 정도가 나오고 생태계가 안정화되는 것을 보고 진입해도 늦지 않다.
 
마지막으로, 저장소 URL을 한 번 더 밝힌다: github.com/google-labs-code/design.md. 본인 프로젝트에 한번 적용해보고, 클로드 코드와 커서에서 DESIGN.md 적용 전후로 무엇이 달라졌는지 써보면 감이 온다. 한글 폰트 토큰을 세팅한 사례는 한국어 커뮤니티에 아직 거의 없기에, 블로그에 정리해두면 누군가는 정말 고마워할 것이다.