Google DESIGN.md: AI 코딩 에이전트에게 디자인 시스템을 읽히는 가장 현실적인 방법

Google Labs · DESIGN.md · AI Agent Design Contract

AI 코딩 에이전트가 프론트엔드를 잘 만드는 것처럼 보이는 순간은 많다. 하지만 실제 제품팀이 부딪히는 문제는 다르다. 한 번은 꽤 괜찮은 화면을 만들지만, 다음 작업에서는 색·타이포그래피·간격·컴포넌트 성격이 조금씩 흔들린다. 에이전트는 코드를 잘 고쳐도, 팀의 시각 언어를 지속적으로 기억하지 못한다.

Google Labs의 google-labs-code/design.md가 흥미로운 이유는 여기 있다. 이 프로젝트는 “AI가 더 예쁜 UI를 만들게 하자”가 아니라, 에이전트가 디자인 시스템을 읽고 따를 수 있는 휴대 가능한 문서 계약을 만들자는 쪽에 가깝다.

DESIGN.md cover

2026년 6월 25일 기준 GitHub Trending에서도 이 저장소가 다시 강하게 노출됐다. 위키의 당일 스냅샷에는 TypeScript 기반, Apache-2.0 라이선스, 1.6만 개 이상의 스타, 그리고 “visual identity를 coding agents에게 설명하는 포맷”이라는 설명이 함께 기록돼 있다. 단순한 디자인 토큰 유틸리티라기보다, 에이전트 시대의 프론트엔드 운영 방식이 어떻게 바뀌는지 보여주는 신호로 읽는 편이 맞다.

핵심 논지: 에이전트에게 필요한 건 “스타일 프롬프트”가 아니라 “디자인 계약”이다

DESIGN.md의 README는 이 포맷을 “visual identity를 coding agents에게 설명하는 format specification”이라고 정의한다. 파일은 두 층으로 구성된다.

YAML front matter — 색상, 타이포그래피, 간격, 라운딩, 컴포넌트 토큰처럼 기계가 읽기 쉬운 값
Markdown body — 왜 그런 디자인인지, 어떤 감각을 지켜야 하는지, 어디서 과하면 안 되는지를 설명하는 사람용 문장

이 조합이 중요하다. 색상값만 주면 에이전트는 #1A1C1E를 쓸 수는 있다. 하지만 그 색이 “deep ink for headlines”인지, “버튼 배경에 써야 하는 primary”인지, “모든 텍스트에 남발하면 안 되는 무드의 중심축”인지는 알기 어렵다. 반대로 “고급스럽고 미니멀하게”라고만 말하면 결과는 매번 평균적인 SaaS 랜딩 페이지로 수렴한다.

DESIGN.md는 이 둘을 붙인다. 토큰은 정확한 값을 주고, 산문은 그 값이 어떤 세계관 안에서 쓰여야 하는지 설명한다.

토큰과 산문이 합쳐지는 디자인 계약

Google의 철학 문서가 특히 강하게 말하는 부분도 이 지점이다. “생성된 디자인의 품질은 값의 정밀도보다 의도가 얼마나 명확하게 설명됐는지에 더 크게 좌우된다”는 주장이다. 즉 DESIGN.md의 중심은 토큰 테이블이 아니라 디자인 의도를 전달하는 산문이다.

이건 꽤 실무적인 통찰이다. 많은 팀이 디자인 시스템을 토큰 저장소나 컴포넌트 라이브러리로만 이해한다. 하지만 AI 에이전트에게 일을 맡기면, 토큰보다 먼저 필요한 것은 “이 브랜드는 무엇을 하지 않는가”, “이 화면은 어떤 정서를 가져야 하는가”, “이 컴포넌트는 왜 이런 제약을 갖는가” 같은 문맥이다.

왜 지금 중요한가: 에이전트는 코드를 고치지만, 브랜드 일관성은 자동으로 생기지 않는다

AI 코딩 도구가 빠르게 확산되면서 프론트엔드 작업의 병목은 조금씩 달라지고 있다. 예전에는 “이 UI를 구현할 사람이 있는가”가 문제였다면, 이제는 “여러 에이전트와 여러 세션이 만든 화면이 같은 제품처럼 보이는가”가 더 큰 문제가 된다.

실무에서 흔히 생기는 실패는 이런 식이다.

Claude Code가 만든 설정 화면과 Codex가 만든 온보딩 화면의 버튼 밀도가 다르다.
Cursor 세션에서 만든 카드 컴포넌트가 기존 디자인 시스템의 여백 규칙을 미묘하게 벗어난다.
프롬프트에는 “우리 브랜드답게”라고 썼지만, 에이전트는 그 브랜드를 본 적이 없다.
Figma에는 정답이 있지만, 에이전트가 읽는 작업 컨텍스트에는 정답이 없다.

DESIGN.md는 이 간극을 줄이는 형식이다. 저장소의 스펙 문서는 DESIGN.md를 “self-contained, plain-text representation of a design system”이라고 설명한다. 이 말이 핵심이다. Figma 파일이나 내부 위키가 아니라, 코드 저장소 안에 들어갈 수 있는 평문 문서라는 점이 중요하다.

평문이면 Git으로 리뷰할 수 있고, PR에서 diff를 볼 수 있고, 에이전트가 매 작업마다 읽을 수 있다. 에이전트가 기억을 못 한다면, 기억을 기대하지 말고 매번 읽을 수 있는 계약 파일을 제공하는 편이 더 안정적이다.

스펙의 설계가 좋은 이유: tokens.json을 대체하려는 게 아니다

DESIGN.md의 스펙은 디자인 토큰 JSON 커뮤니티 그룹의 2025.10 포맷에서 아이디어를 가져왔다고 밝힌다. 색상, 타이포그래피, spacing 같은 typed token group과 {path.to.token} 참조 문법을 채택한다. 동시에 README는 이 토큰들이 tokens.json, Figma variables, Tailwind theme config와 쉽게 변환될 수 있다고 설명한다.

여기서 중요한 건 DESIGN.md가 기존 디자인 시스템 도구를 없애려 하지 않는다는 점이다. 오히려 중간 계층에 가깝다.

계층	기존 역할	DESIGN.md가 더하는 것
Figma variables	디자이너의 시각 토큰 원천	에이전트가 읽을 수 있는 평문 변환 대상
tokens.json	빌드/테마 파이프라인의 구조화 데이터	토큰의 의도와 사용 맥락
Tailwind config	구현 레벨의 클래스/테마 설정	왜 이 값이 선택됐는지에 대한 설명
README/브랜드 가이드	사람용 설명	코드 작업 세션에 직접 들어가는 운영 문서

즉 실무적인 사용법은 “우리의 디자인 시스템을 모두 DESIGN.md로 갈아엎자”가 아니다. 더 현실적인 접근은 이렇다.

기존 Figma variables나 theme config에서 핵심 토큰을 뽑는다.
제품의 시각 정체성을 설명하는 산문을 붙인다.
컴포넌트별 사용 의도와 금지 패턴을 적는다.
에이전트 작업 지시에서 DESIGN.md를 먼저 읽고 구현하라고 고정한다.
변경은 PR에서 diff로 리뷰한다.

이렇게 보면 DESIGN.md는 디자인 시스템의 “소스 오브 트루스”라기보다, AI 작업자가 읽을 수 있는 디자인 시스템 운영 인터페이스에 가깝다.

lint와 diff가 중요하다: 디자인 문서를 CI 대상으로 만든다

README에서 눈에 띄는 기능은 npx @google/design.md lint DESIGN.md와 npx @google/design.md diff DESIGN.md DESIGN-v2.md다. lint는 broken token reference, WCAG contrast ratio, 구조적 문제를 JSON으로 알려주고, diff는 토큰 변경과 산문 회귀 가능성을 비교한다.

DESIGN.md lint와 diff

이 부분은 “문서 포맷” 이상의 의미가 있다. 디자인 지침이 CI 대상이 된다는 뜻이기 때문이다.

에이전트에게 디자인 문서를 읽히는 것만으로는 부족하다. 에이전트가 문서를 고치거나, 토큰을 추가하거나, 컴포넌트 지침을 바꿀 때 그 변경이 안전한지도 봐야 한다. lint와 diff는 그 최소한의 안전장치다.

특히 한국의 작은 제품팀이나 스타트업 환경에서는 디자이너가 모든 에이전트 생성 UI를 실시간으로 감수하기 어렵다. 이때 DESIGN.md 같은 문서가 있으면, 최소한 다음 질문에 자동으로 답할 수 있다.

새 토큰이 기존 참조를 깨뜨렸는가?
주요 색 조합의 대비가 접근성 기준을 통과하는가?
컴포넌트 토큰 참조가 유효한가?
디자인 방향이 “어느 정도” 바뀌었는가?

완전한 디자인 리뷰를 대체하지는 못한다. 하지만 에이전트가 대량으로 UI를 생성하는 환경에서 가장 기본적인 품질 게이트로는 충분히 의미가 있다.

가장 흥미로운 철학: “구체적 참조”가 형용사보다 강하다

DESIGN.md의 철학 문서는 꽤 좋은 프롬프트 설계 교훈도 준다. “modern, clean, trustworthy, premium” 같은 형용사는 넓은 영역을 가리키지만, “오래된 명문 대학의 대학원 세미나 핸드아웃” 같은 구체적 참조는 하나의 세계를 가리킨다는 주장이다.

이건 에이전트 UI 작업에서 정말 자주 보이는 차이다. “깔끔하게”라고 쓰면 모델은 평균적인 드리블 UI를 만든다. 반면 “인쇄된 기술 핸드아웃처럼, 장식보다 정보 밀도를 우선하고, CTA를 과하게 띄우지 말라”고 쓰면 훨씬 일관된 제약이 생긴다.

중요한 건 구체적 참조가 자동으로 negative constraint를 만든다는 점이다. “세미나 핸드아웃”이라고 하면 그 안에는 이미 “글로시한 히어로 이미지가 아니다”, “그라디언트 배경이 아니다”, “과한 마케팅 카피가 아니다”라는 배제가 들어 있다.

DESIGN.md가 산문을 중시하는 이유도 여기 있다. 에이전트에게 디자인을 맡길 때 좋은 문장은 장식이 아니라 제약이다. 좋은 산문은 에이전트가 해도 되는 것과 하면 안 되는 것을 동시에 좁힌다.

한국 개발팀이 바로 적용한다면: 작은 DESIGN.md부터 시작하면 된다

처음부터 완전한 스펙 문서를 만들 필요는 없다. 오히려 첫 버전은 짧아야 한다. 한국의 개발팀이나 1인 제품 빌더라면 다음 정도로 시작해도 충분하다.

---
version: alpha
name: Product UI
colors:
  ink: '#111827'
  surface: '#F9FAFB'
  accent: '#2563EB'
typography:
  heading:
    fontFamily: Pretendard
    fontSize: 32px
    fontWeight: 700
  body:
    fontFamily: Pretendard
    fontSize: 16px
    lineHeight: 1.6
spacing:
  card: 24px
  section: 64px
---

## Overview

이 제품은 개발자용 운영 도구다. 화면은 마케팅 랜딩보다 콘솔에 가깝고,
정보 밀도와 신뢰감을 우선한다. 장식적 그라디언트보다 명확한 상태 표시와
읽기 쉬운 표를 우선한다.

## Do's and Don'ts

- Do: 상태, 비용, 실패 원인을 명확히 보여준다.
- Do: 표와 로그 영역은 좁은 행간보다 가독성을 우선한다.
- Don't: 버튼을 과하게 크게 만들거나 SaaS 랜딩 페이지처럼 꾸미지 않는다.
- Don't: 핵심 운영 화면에 장식용 일러스트를 넣지 않는다.

이 정도만 있어도 에이전트의 출력은 달라진다. 특히 반복 작업에서 차이가 난다. 첫 세션에서 만든 화면만 괜찮은 것이 아니라, 다음 주에 다른 에이전트가 고친 화면도 같은 규칙 안에 들어올 가능성이 커진다.

에이전트가 공유하는 디자인 계약

실무 해석: 에이전트 시대의 디자인 시스템은 “컴포넌트 라이브러리 + 운영 문서”가 된다

DESIGN.md를 단순한 새 파일 포맷으로 보면 과소평가하기 쉽다. 더 큰 흐름은 이렇다.

AI 에이전트가 제품 코드를 직접 수정하는 환경에서는 디자인 시스템도 사람이 보는 문서에서 끝나면 안 된다. 에이전트가 읽고, 검증하고, 변경 이력을 남기고, PR에서 리뷰받을 수 있어야 한다. 즉 디자인 시스템은 점점 컴포넌트 라이브러리 + 토큰 + 산문형 운영 문서 + CI 게이트의 조합으로 바뀐다.

이 변화는 프론트엔드 팀의 역할도 바꾼다.

디자이너는 “예쁜 화면”보다 “에이전트가 오해하지 않는 설명”을 더 자주 써야 한다.
프론트엔드 리드는 디자인 토큰뿐 아니라 에이전트 작업 규칙을 코드 저장소에 넣어야 한다.
제품팀은 Figma와 코드 사이에 평문 계약 레이어를 둘 필요가 있다.
CI는 타입 체크와 테스트뿐 아니라 디자인 규칙의 최소 위반도 잡아야 한다.

물론 DESIGN.md 하나로 디자인 품질 문제가 사라지지는 않는다. 에이전트는 여전히 맥락을 놓치고, 시각적 판단은 여전히 사람의 감수가 필요하다. 하지만 적어도 “매번 프롬프트에 브랜드 설명을 다시 쓰는 방식”보다는 훨씬 낫다.

주의할 점: DESIGN.md는 프롬프트 만능주의가 아니다

이 포맷을 도입할 때 가장 조심해야 할 오해는 두 가지다.

첫째, DESIGN.md는 디자인 시스템을 자동으로 만들어주지 않는다. 나쁜 디자인 원칙을 잘 적으면, 에이전트는 그 나쁜 원칙을 더 일관되게 따른다. 결국 좋은 문서는 좋은 판단에서 나온다.

둘째, 토큰만 채우면 된다고 생각하면 실패한다. 프로젝트의 철학 문서가 말하듯 DESIGN.md의 핵심은 산문이다. 색상표와 spacing scale만 있으면 기존 tokens.json과 크게 다르지 않다. 실제 차이는 “왜”와 “언제 쓰지 말아야 하는가”를 적는 데서 나온다.

그래서 첫 도입 기준은 이렇게 잡는 편이 좋다.

브랜드 형용사보다 구체적 참조를 쓴다.
컴포넌트마다 사용 의도와 금지 상황을 적는다.
에이전트가 실수한 UI를 보고 DESIGN.md에 제약을 추가한다.
DESIGN.md 변경은 코드 변경처럼 리뷰한다.
lint/diff를 CI에 붙여 최소한의 구조적 안전장치를 만든다.

결론: AI 프론트엔드의 병목은 생성 능력이 아니라 일관성이다

Google Labs의 DESIGN.md가 보여주는 방향은 분명하다. AI 에이전트가 UI를 더 많이 만들수록, 팀은 더 많은 “생성”이 아니라 더 강한 “일관성 장치”가 필요해진다.

이 프로젝트의 실용적 메시지는 단순하다.

에이전트에게 디자인 감각을 기대하지 말고, 에이전트가 반복해서 읽을 수 있는 디자인 계약을 만들어라.

한국 개발자와 빌더에게도 이건 꽤 즉시 적용 가능한 교훈이다. Figma를 완벽히 자동화하지 않아도 된다. 거대한 디자인 시스템을 새로 만들 필요도 없다. 먼저 저장소 루트에 작은 DESIGN.md를 두고, 에이전트 작업 지시에 “이 파일을 먼저 읽어라”를 붙이는 것부터 시작하면 된다.

AI 코딩 에이전트 시대의 프론트엔드 품질은 누가 더 멋진 프롬프트를 쓰느냐가 아니라, 누가 더 잘 유지되는 계약을 갖고 있느냐에서 갈릴 가능성이 크다.