DESIGN.md가 오픈소스가 됐다 — 구글이 AI 코딩 에이전트의 디자인 표준을 풀었다

AI 코딩 에이전트에게 "대시보드 만들어줘"라고 요청하면 매번 기본 Tailwind 블루가 돌아온다. 매번 브랜드 가이드를 프롬프트로 다시 설명해야 했고, 그래도 다음 컴포넌트는 또 다른 비주얼 언어로 나왔다.

2026년 4월 21일 구글 Labs는 그 매번 0에서 시작하는 문제를 단일 파일 컨트랙트로 해결할 사양을 공개했다. 디자인 도구 Stitch의 핵심 기능인 DESIGN.md 포맷이 Apache 2.0 라이선스로 오픈소스화된 것이다. 한 마디로 "디자인 시스템의 README.md"다.

무엇이 발표되었나

발표는 Google Blog의 Cassia Xu(Google Labs Software Engineer)가 작성한 포스트로 시작됐다. 핵심 사실 정리는 다음과 같다.

함께 풀린 것은 사양 문서뿐이 아니다. 실제로 쓸 수 있는 도구 세트가 동시에 공개됐다.

1. CLI 툴: npx @google/design.md (lint, diff, export, spec 4종 명령)
2. Stitch MCP 서버 + Agent Skills: Claude Code, Cursor, Gemini CLI, Antigravity 호환
3. 공식 문서: stitch.withgoogle.com/docs/design-md/overview
4. GitHub 저장소: 사양 + 컨트리뷰션 가이드

이번 공개는 Stitch 2.0 출시(2026-03-19)에 이은 두 번째 메이저 업데이트다. 형식이 Google 울타리를 벗어나 업계 공통 인프라로 자리잡으려는 첫걸음이다.

DESIGN.md 9개 섹션 구조 — 두 층의 컨트랙트

DESIGN.md는 두 층으로 구성된다. 위쪽은 YAML 프론트매터로 머신이 판독할 수 있는 토큰을 담고, 아래쪽은 마크다운 본문으로 사람이 판독할 수 있는 근거를 담는다. 토큰만 있으면 AI가 값을 알지만 의도를 모르고, 근거만 있으면 의도는 알지만 정확한 값을 모른다. 두 층이 모두 있어야 완전하다.

YAML 프론트매터 예시

---
name: Heritage
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 3rem
  body-md:
    fontFamily: Public Sans
    fontSize: 1rem
rounded:
  sm: 4px
  md: 8px
spacing:
  sm: 8px
  md: 16px
---

9개 표준 섹션

9번 "Agent Prompt Guide"가 가장 신선하다. 전통 디자인 시스템은 인간만 위해 만들어졌기에 이런 섹션을 가질 이유가 없었다. DESIGN.md는 처음부터 AI 에이전트를 청자로 가정한다.

토큰의 시맨틱 역할 — 핵심 통찰

색상 #B8422E는 그 자체로 아무 의미가 없다. 하지만 "Boston Clay — the sole interaction driver"라는 한 줄이 붙으면 AI 에이전트는 "이 색은 인터랙션 가능한 요소에만 써야 한다"는 것을 알게 된다. DESIGN.md는 디자인 토큰을 단순 변수가 아닌 시맨틱 역할로 가르친다.

CLI 4종 — 실제로 쓰이는 명령어

# 1. LINT — 검증
npx @google/design.md lint DESIGN.md
npx @google/design.md lint --format json DESIGN.md

# 2. DIFF — 버전 비교 (CI에서 회귀 감지)
npx @google/design.md diff DESIGN.md DESIGN.next.md

# 3. EXPORT — 다른 포맷으로 변환
npx @google/design.md export --format tailwind DESIGN.md > tailwind.theme.json
npx @google/design.md export --format dtcg DESIGN.md > tokens.json

# 4. SPEC — 사양 자체를 프롬프트에 주입
npx @google/design.md spec
npx @google/design.md spec --rules-only --format json

lint의 자동 WCAG 검증은 "textColor (#ffffff) on backgroundColor (#1A1C1E) has contrast ratio 15.42:1 — passes WCAG AA." 같은 결과를 매 검증마다 반환한다. 무료 접근성 감사가 빌트인이다.

diff의 회귀 감지는 "after" 파일이 "before"보다 에러나 경고가 많으면 종료 코드 1을 반환한다. CI에서 의도치 않은 디자인 시스템 드리프트를 잡아낸다.

Claude Code, Cursor, Copilot 통합 방법

Claude Code

CLAUDE.md에 한 단락만 추가하면 된다.

# CLAUDE.md에 추가

Always read DESIGN.md at project root before generating any UI.
Use the design tokens and rationale to make all styling decisions.
Run `npx @google/design.md lint DESIGN.md` and fix errors before shipping.

Cursor

.cursorrules에 동일한 패턴을 적용한다.

Before writing UI code, read @DESIGN.md.
Use the token values and semantic descriptions for all design decisions.
Do not use arbitrary color values — reference design tokens only.

GitHub Copilot 등 일반 에이전트

# 사양을 프롬프트에 주입
npx @google/design.md spec > design-spec-context.txt

# 그 다음 프롬프트에서 참조:
"Use the attached DESIGN.md to style all components."

같은 파일, 다른 도구, 동일한 결과. 이것이 표준 포맷의 힘이다.

awesome-design-md 커뮤니티 — 69+ 템플릿

VoltAgent/awesome-design-md 저장소는 발표 직후 빠르게 성장해 69개 이상의 실제 브랜드 DESIGN.md 템플릿을 모았다. (QJC의 awesome-design-md 스킬은 58개로 시작했으나 커뮤니티가 11개를 더 추가했다.)

각 폴더는 DESIGN.md + preview.html + preview-dark.html을 함께 제공해 통합 전 시각 확인이 가능하다.

DESIGN.md vs Figma — 어디서 이기고 어디서 지나

현실적 결론: 둘 다 산다. Stitch + DESIGN.md는 아이디에이션, 빠른 프로토타이핑, 디자인-투-코드 단계에서 강력하다. Figma는 다듬기, 딥 협업, 최종 폴리시 단계에서 여전히 우월하다. 하이브리드 워크플로우가 자연스러운 정착지다.

한계와 비판

거버넌스

Apache 2.0이긴 하지만 메인 메인테이너는 여전히 Google Labs 단독이다. W3C나 OpenAPI Initiative 같은 독립 위원회가 아직 없다. 진짜 표준이 되려면 Google 울타리 밖 다중 거버넌스가 필요하다.

팀 기능

Figma의 세분화된 권한, 컨텍스트 코멘트, 브랜칭, 공유 리소스 관리가 모두 Git에 위임된다. Git은 강력하지만 디자이너 워크플로우용으로 만들어지지 않았다. 20명 UX 디자이너 팀이 Figma 대체로 보긴 어렵다.

Gemini와의 결합도

Gemini는 DESIGN.md를 자연어 컨텍스트로 읽고 확률적 판단으로 적용한다. 컴파일된 CSS처럼 정확한 컴플라이언스를 보장하지 않는다. 픽셀 퍼펙트 출력이 필요하다면 DESIGN.md는 가이던스 레이어이지 강제 레이어가 아니다.

채택 초기

Stitch에서는 네이티브로 동작한다. 다른 도구에서는 수동 프롬프트 참조 방식이다. Figma, v0, Cursor가 본격 통합해야 사실상 표준이 된다.

QJC 관점 — 이게 왜 우리에게 중요한가

QJC는 이미 awesome-design-md 스킬(58개 브랜드 카탈로그)과 design-creator 에이전트가 DESIGN.md를 자동 참조하도록 구축되어 있었다. 이번 공식 오픈소스화는 우리가 한 발 앞서 베팅했던 형식이 업계 표준 후보로 격상되었다는 신호다. 다음 액션이 가능해진다.

1. CLI 통합: npx @google/design.md lint를 design-creator 에이전트의 검증 단계에 추가하면 WCAG 자동 감사가 무료다.
2. Stitch MCP 연동: design-md 스킬을 Claude Code에 설치하면 Stitch 프로젝트에서 자동 생성이 가능하다.
3. Tailwind 변환 파이프라인: export --format tailwind로 우리 웹앱 themes에 직접 적용한다.
4. awesome-design-md 카탈로그 11개 추가 동기화: 커뮤니티가 추가한 11개 브랜드를 신규 수집한다.

오늘부터 시작하는 4단계

당장 오늘 자기 프로젝트에 DESIGN.md를 도입하는 가장 빠른 경로다.

1. 자기 프로젝트 루트에 DESIGN.md 한 장 만들기 — VoltAgent/awesome-design-md 카탈로그에서 가까운 브랜드를 골라 복사하면 5분이면 끝난다.
2. CLAUDE.md에 참조 규칙 한 줄 추가 — "Always read DESIGN.md at project root before generating any UI."
3. npx @google/design.md lint 한 번 실행 — WCAG 위반과 토큰 참조 오류를 한 번에 잡아낸다.
4. AI한테 "대시보드 만들어줘" 다시 요청 — 같은 프롬프트, 다른 결과를 보게 된다.

매번 0에서 시작하던 시대가 끝난다. 한 파일이 컨트랙트가 되는 시대가 시작됐다.

참고 자료

• Google Blog: Stitch + design.md
• Stitch DESIGN.md 공식 문서
• VoltAgent/awesome-design-md (GitHub)