DESIGN.md 완벽 정리 — 코딩 에이전트에게 디자인을 알려주는 포맷

AI 코딩 도구로 화면을 만들어 보신 적 있으신가요? 그러면 한 번쯤 이런 경험을 하셨을 거예요. "버튼 만들어줘"라고 하면 그라디언트 버튼, 전부 대문자로 된 헤딩, 아무도 요청하지 않은 호버 애니메이션이 달린 generic한 카드가 나옵니다. 어떤 프로젝트든 결과물이 다 비슷비슷하죠. 이걸 요즘 AI slop(AI가 뱉어내는 영혼 없는 generic 결과물)이라고 부릅니다.

Google이 이 문제를 정면으로 겨냥한 포맷을 내놨습니다. 바로 DESIGN.md예요. 코딩 에이전트(Claude Code·Cursor 같은 AI 개발 도구)에게 "우리 제품은 이런 디자인 정체성을 가진다"고 한 파일로 알려주는 명세입니다. 이 글에서는 DESIGN.md가 무엇인지, 왜 만들어졌는지, 실제로 어떻게 쓰는지, 그리고 지금 도입해도 되는지까지 차근차근 풀어드릴게요.

DESIGN.md란 무엇인가요?

DESIGN.md의 공식 한 줄 정의는 **"코딩 에이전트에게 시각적 정체성을 설명하기 위한 포맷 명세"**입니다. 쉽게 말하면, AI 코딩 도구가 매 작업마다 영구적으로 참조하는 "우리 제품 디자인 설명서"예요.

이 파일의 가장 큰 특징은 **두 층(layer)**으로 되어 있다는 점입니다.

층	내용	역할
YAML front matter	머신이 읽는 디자인 토큰 (`---` 안에 작성)	정확한 값 (정규 토큰)
마크다운 본문	사람이 읽는 디자인 근거 (`##` 섹션)	"왜 그 값인지·어떻게 쓰는지" 맥락

여기서 디자인 토큰(design token)이란 색·간격·글꼴 크기 같은 디자인 값을 변수처럼 정해둔 것을 말해요. 예를 들어 "주요 색은 #1A1C1E"처럼요. DESIGN.md는 이 정확한 값(토큰)과, 그 값을 어떻게 써야 하는지에 대한 설명(prose)을 한 파일에 묶습니다.

토큰 타입은 4종류를 지원합니다.

타입	형식	예시
Color	모든 CSS 색상 (hex, `rgb()`, `oklch()` 등)	`"#1A1C1E"`, `"oklch(62% 0.18 250)"`
Dimension	숫자 + 단위 (`px`, `em`, `rem`)	`48px`, `-0.02em`
Token Reference	`{경로.토큰}`	`{colors.primary}`
Typography	글꼴 관련 속성 객체	`fontFamily`, `fontSize`, `lineHeight` 등

섹션은 ## 헤딩으로 작성하고, 생략은 할 수 있지만 있는 섹션은 반드시 정해진 순서를 지켜야 합니다. 순서는 다음 8개예요.

Overview (Brand & Style)
Colors
Typography
Layout (Layout & Spacing)
Elevation & Depth (Elevation)
Shapes
Components
Do's and Don'ts

왜 만들어졌나요? — Google Stitch에서 태어난 다리

DESIGN.md의 뿌리는 Google Stitch입니다. Stitch는 Google Labs의 AI 디자인 도구로, 프롬프트나 이미지를 고해상도 UI 화면으로 만들고 실제 코드로 내보낼 수 있어요. 2026년 3월 18일 업데이트로 단발성 작업에서 "AI 네이티브 무한 캔버스"로 진화했습니다.

DESIGN.md는 원래 이 Stitch 내부에서 디자인 규칙(타이포그래피·색상 토큰·컴포넌트 규칙·간격)을 담던 포맷이었어요. Stitch 안에서는 프로젝트끼리 디자인 규칙을 가져오고 내보내는 데 썼습니다. 새 디자인을 시작할 때마다 처음부터 다시 만들지 않아도 되게요.

그러다 2026년 4월 21일, Google이 이 초안 명세를 오픈소스(Apache-2.0 라이선스)로 공개했습니다. Stitch 밖의 어떤 도구에서도 쓸 수 있게 된 거죠. 오늘(2026-06-25) 기준으로 공개된 지 약 두 달 남짓 됐습니다(GitHub 저장소 자체는 4월 10일 생성).

이게 왜 중요할까요? "바이브 디자인 ↔ 바이브 코딩"의 고리가 닫혔기 때문입니다. 디자이너가 Stitch에서 UI를 만들어 DESIGN.md로 내보내면, 개발자의 AI 코딩 도구가 그 파일을 읽어서 디자인과 일치하는 프론트엔드 코드를 만들어 줍니다. 디자인과 코드 사이를 잇는 다리 역할을 하는 거예요.

핵심 철학 — "값보다 의도가 결과를 좌우한다"

DESIGN.md를 이해하는 가장 중요한 열쇠는 설계 철학입니다. 공식 PHILOSOPHY.md 문서는 단호하게 말합니다.

"생성되는 디자인의 품질은 값의 정밀함보다 의도가 얼마나 명확히 서술됐느냐로 결정된다."

토큰 값(#1A1C1E 같은 것)이 렌더링 지시가 아니라, prose(서술 문장)가 참조하는 맥락일 뿐이라는 거예요. 즉 색 코드를 아무리 정확히 박아둬도, "왜 그 색인지·어떻게 써야 하는지"를 글로 설명하지 않으면 AI는 generic한 결과를 냅니다.

형용사 대신 구체적 레퍼런스

AI slop을 푸는 핵심 통찰이 여기 있어요. "Modern, clean, trustworthy, premium"(모던하고, 깔끔하고, 신뢰감 있고, 고급스러운) 같은 형용사를 늘어놓으면, AI 모델은 그 단어들의 평균을 만듭니다. 그래서 어디서 본 듯한 generic한 결과가 나오는 거죠.

반면 "1970년대 명문대 대학원 강의 핸드아웃"이라는 구체적 레퍼런스 한 문장은 완전히 다릅니다. 이 한 문장이 잉크 한 색, 넓은 여백, 읽기 좋은 세리프 글꼴, 장식 없음까지 한 세계를 통째로 전달해요. PHILOSOPHY.md의 표현을 빌리면 이렇습니다.

"형용사는 영역을 묘사하고, 구체적 레퍼런스는 한 점을 묘사한다."

형용사는 넓은 영역을 가리키니 AI가 그 안에서 헤매고, 구체적 레퍼런스는 정확히 한 점을 찍어주니 AI가 거기로 갑니다.

빼놓은 것이 성격을 정의한다

또 하나 흥미로운 논지는 "negative constraints(빼놓은 것)"입니다. 구체적 레퍼런스를 주면 "하지 말 것"이 자동으로 따라와요. "강의 핸드아웃"이라고 하면 모델은 그것이 빛나지 않고 그라디언트를 쓰지 않는다는 걸 압니다. 일일이 "그라디언트 쓰지 마"라고 적을 필요가 없어요. 그래서 길고 장황한 "하지 말 것" 리스트가 필요하다는 건, 오히려 설명이 너무 모호했다는 신호라고 봅니다.

마지막으로 DESIGN.md는 명세가 아니라 사용자를 통해 자라는 포맷을 지향합니다. 명세는 최소 구조만 표준화하고(이름 + 색·타이포·간격·둥글기·컴포넌트), motion이나 아이콘 같은 영역은 자유롭게 열어둡니다. linter는 값을 받고 에이전트는 prose를 읽으니, 명세를 바꾸지 않아도 확장되는 구조예요.

어떻게 쓰나요? — 파일 구조와 CLI 3종

실제로 어떻게 쓰는지 봅시다. DESIGN.md 파일 자체는 위에서 본 것처럼 YAML 토큰 + 마크다운 prose 구조입니다. 대략 이런 모양이에요.

---
colors:
  primary: "#1A1C1E"
typography:
  heading:
    fontFamily: "..."
    fontSize: 48px
---

## Overview

이 제품의 시각 정체성은 ...

## Colors

Primary는 아껴 씁니다 — 화면당 한 번, 가장 중요한 액션에만.

그리고 npm 패키지 @google/design.md(현재 v0.3.0, 첫 배포 2026-04-21)가 명령줄 도구(CLI)를 제공합니다. "DESIGN.md 포맷을 위한 linter이자 exporter"로, 크게 3가지 기능이 있어요.

# 1. lint — 구조 검증 + 접근성 + 깨진 토큰 참조 잡기
npx @google/design.md lint DESIGN.md

# 2. diff — 두 버전 간 토큰 회귀(regression) 감지
npx @google/design.md diff before.md after.md

# 3. export — 다른 포맷으로 변환 (Tailwind, DTCG)
npx @google/design.md export DESIGN.md --format dtcg

각각 무슨 일을 하는지 정리하면 이렇습니다.

명령	하는 일
`lint`	구조 정확성 + WCAG 명도대비(글자 가독성 기준) + 깨진 토큰 참조 검증. `{colors.primary}`가 정의 안 됐으면 에러로 종료
`diff`	두 DESIGN.md 버전을 비교해 토큰 단위 변경을 보고. "이후" 파일에 문제가 더 많으면 회귀로 판정
`export`	토큰을 Tailwind 설정(v3/v4) 또는 DTCG(W3C 표준)로 변환

여기에 spec 명령도 있어서 명세 자체를 출력할 수 있는데, 에이전트 프롬프트에 명세 맥락을 주입할 때 유용합니다. 모든 명령은 파일 경로나 표준 입력(-)을 받고, 결과는 에이전트가 바로 쓸 수 있는 JSON으로 나옵니다. 프로그래밍 API(import { lint } from '@google/design.md/linter')도 제공돼요.

DTCG(W3C 디자인 토큰 표준)와는 어떻게 다른가요?

DESIGN.md를 얘기하면 꼭 나오는 질문이 "DTCG랑 뭐가 다르냐"입니다. DTCG(Design Tokens Community Group)는 W3C 커뮤니티 그룹으로, 디자인 토큰을 도구끼리 주고받는 표준 파일 포맷을 정의해요. JSON 기반이고, 2025년 10월 28일에 첫 안정판(first stable version)에 도달했습니다. Adobe·Amazon·Google·Microsoft·Figma·Meta 등 20명 넘는 에디터가 참여했죠.

결론부터 말하면 둘은 경쟁이 아니라 레이어가 다릅니다.

	DTCG	DESIGN.md
목적	도구 간 토큰 교환 표준	코딩 에이전트에게 의도를 서술
형식	JSON (`.tokens.json`)	마크다운 (YAML 토큰 + prose)
핵심 가치	토큰 값의 정확성·이식성	"왜 그 값인지"의 맥락

DTCG가 토큰을 깔끔하게 주고받는 "운반 표준"이라면, DESIGN.md는 그 위에 "AI 에이전트가 이해할 의도 서술 레이어"를 한 겹 더 얹은 거예요. 실제로 DESIGN.md의 토큰은 W3C Design Token Format에서 영감을 받았다고 공식 문서에 명시돼 있고, 앞서 본 export --format dtcg로 표준 토큰을 그대로 뽑아낼 수 있습니다. 그래서 둘은 서로 보완하는 관계입니다. DESIGN.md로 의도를 담고, 필요하면 표준 DTCG로 내보내면 되니까요.

한계와 채택 현황 — 17.7K stars, 그리고 신중론

빠르게 퍼지고 있는 건 분명합니다. 4월 10일 저장소 생성 이후 오늘(2026-06-25) 기준 GitHub stars 17,704개를 기록했어요. 공개 초기인 5월 초에 이미 11,000개를 넘었으니, alpha(초기 시험판) 라벨에 비하면 채택 곡선이 꽤 가파릅니다.

하지만 정직하게 한계도 봐야 합니다. 가장 권위 있는 검증 사례는 Atlassian(Jira·Confluence 만드는 회사)입니다. Atlassian은 자사 콘텐츠 파이프라인으로 DESIGN.md를 만들어 바이브 코딩 도구에서 테스트했어요. 결과는 양면적이었습니다.

효과: 같은 프롬프트를 파일 유무로 비교하니, 생성 UI가 "generic slop → 알아볼 수 있는 Atlassian 스타일"로 확실히 개선됐습니다.
한계: DESIGN.md는 기존 컴포넌트를 재사용하기보다 다시 만드는 경향이 있었습니다. 그리고 프로덕션에서는 자사 MCP 서버 + 스킬이 더 나은 추상화였다고 평가했어요. DESIGN.md는 "기존 디자인 시스템을 어떻게 다시 구현할지"가 아니라 "어떻게 사용할지"를 설명하는 데 한계가 있다는 거죠.

또 공식 status가 **alpha**라는 점을 잊으면 안 됩니다. 공식 입장 자체가 "명세·토큰 스키마·CLI 모두 활발히 개발 중이니 포맷 변경을 예상하라"입니다. 그래서 "AI 우선 단일 제품 팀이라면 지금 도입, 이미 Tokens Studio나 Figma 변수로 사는 멀티브랜드 조직이라면 한 분기 더 지켜보라"는 신중론이 나옵니다.

생태계 신호도 있어요. Anthropic의 skills 저장소에는 "frontend-design 스킬이 Google Labs의 open spec에 따라 DESIGN.md를 소비·생산하도록 고려하자"는 이슈(#1008)가 열렸습니다.

1인·소규모 팀에게 주는 의미

그래서 코딩 에이전트로 직접 제품을 만드는 1인·소규모 팀에게 DESIGN.md는 어떤 의미일까요?

핵심은 **"디자인 의도를 한 파일에 못 박아 두면, AI가 매번 처음부터 헤매지 않는다"**는 점입니다. 1인 팀은 디자이너와 개발자가 같은 사람일 때가 많죠. 머릿속에만 있던 "우리 제품은 이런 느낌이어야 한다"를 글로 적어두면, AI 코딩 도구가 작업할 때마다 그 기준을 참조합니다. 그라디언트 버튼과 대문자 헤딩의 무한 반복에서 벗어날 수 있어요.

특히 Atlassian 같은 큰 조직이 "기존 시스템 재사용은 약하다"고 지적한 한계가, 1인·소규모 팀에게는 오히려 덜 치명적입니다. 재사용할 거대한 컴포넌트 라이브러리가 없는 경우가 많고, "generic → 우리만의 스타일"로 바꿔주는 것만으로도 충분히 가치가 있으니까요.

다만 alpha 단계라는 점은 기억하세요. 포맷이 바뀔 수 있으니, 핵심 디자인 결정을 DESIGN.md에만 의존하기보다 "AI에게 의도를 전달하는 한 가지 좋은 방법"으로 활용하는 게 현실적입니다. 형용사를 늘어놓는 대신 구체적 레퍼런스 한 문장을 적는다는 철학 자체는, DESIGN.md를 쓰지 않더라도 모든 AI 코딩에 바로 적용할 수 있는 교훈이고요.

자주 묻는 질문 (FAQ)

Q. DESIGN.md와 CLAUDE.md는 뭐가 다른가요?

CLAUDE.md는 AI 코딩 도구가 매 세션 자동으로 읽는 "프로젝트 전체 컨텍스트"입니다. 코드 규칙, 작업 방식, 프로젝트 구조 등 광범위한 내용을 담아요. DESIGN.md는 그중에서도 시각 디자인 시스템 레이어만 따로 떼어낸 전용 파일입니다. 색·타이포·컴포넌트·간격 같은 디자인 정체성에 집중하죠. 둘은 경쟁이 아니라, 역할이 나뉜 별개 파일로 함께 쓸 수 있습니다.

Q. DTCG와 DESIGN.md, 둘 다 써야 하나요?

레이어가 달라서 함께 쓰는 게 자연스럽습니다. DTCG는 도구끼리 토큰을 주고받는 표준(JSON)이고, DESIGN.md는 그 토큰에 "왜 그렇게 쓰는지" 의도를 더한 마크다운입니다. DESIGN.md로 의도까지 담은 뒤, 다른 도구로 넘겨야 할 때 export --format dtcg로 표준 토큰을 뽑아내면 됩니다. 표준 이식성과 AI 친화적 맥락을 둘 다 챙기는 방식이에요.

Q. 지금 도입해도 되나요?

상황에 따라 다릅니다. AI 코딩 도구로 빠르게 빌드하는 단일 제품 팀이라면 지금 시도해볼 가치가 충분합니다(공개 두 달 만에 stars 17,704개로 확산 중). 다만 공식 status가 alpha라 포맷이 바뀔 수 있고, 이미 Tokens Studio나 Figma 변수 같은 성숙한 시스템으로 운영하는 멀티브랜드 조직이라면 한 분기 정도 더 지켜보는 게 안전합니다.

Q. 형용사 대신 구체적 레퍼런스를 쓰라는 게 무슨 뜻인가요?

"모던하고 깔끔하게" 같은 형용사는 AI가 그 단어들의 평균을 만들어 generic한 결과를 냅니다. 대신 "1970년대 명문대 강의 핸드아웃" 같은 구체적 레퍼런스 한 문장을 주면, 색·여백·글꼴·장식 없음까지 한 번에 전달돼 AI가 정확한 방향을 잡아요. "형용사는 영역을, 구체적 레퍼런스는 한 점을 묘사한다"는 게 DESIGN.md 철학의 핵심입니다.

Q. DESIGN.md를 쓰면 AI slop이 완전히 사라지나요?

완전히는 아닙니다. Atlassian 테스트에서 DESIGN.md는 generic한 결과를 "알아볼 수 있는 브랜드 스타일"로 바꿔주는 효과가 분명했지만, 기존 컴포넌트를 재사용하기보다 다시 만드는 경향이나 프로덕션에서의 추상화 한계도 함께 드러났습니다. AI slop을 줄이는 강력한 도구이되, 만능은 아니라고 보는 게 정확합니다.

DESIGN.md 완벽 정리 — 코딩 에이전트에게 디자인을 알려주는 포맷