design.md: AI가 생성한 UI가 계속 어긋난다면, Google의 design.md를 놓치고 있는 것입니다

Vibe Coding (바이브 코딩)을 하면서 AI의 레이아웃이 항상 조금씩 어긋난다는 것을 느낀 적이 있나요? "여기 간격이 틀렸어", "저기 색상이 일관되지 않아"라고 계속 말해도, AI는 여전히 약간 깨진 화면을 만들어내나요? 만약 그렇다면, 진짜 이유는 당신이 AI에게 디자인 시스템 (design system)의 규칙을 제대로 전달하지 않았기 때문입니다.

정확히 이 문제를 해결하기 위해, 이 포스트에서는 Google Labs에서 출시한 AI 디자인 시스템 사양(spec)인 design.md를 살펴봅니다. 목표는 Claude Code, Cursor, GitHub Copilot과 같은 AI 코딩 (AI Coding) 도구들이 실제로 당신의 디자인 시스템을 읽고 일관된 UI를 생성하게 만드는 것입니다. 그래야 당신이 영원히 "색상이 틀렸어", "폰트 크기가 틀렸어"라고 반복하지 않아도 됩니다.

만약 CLAUDE.md / AGENTS.md와 같은 AI용 규칙 파일에 아직 익숙하지 않다면, 먼저 CLAUDE.md and Rules for AI: Writing Tips That Make AI Understand Your Project와 Agent Skills: More Token-Efficient Than MCP를 살펴보세요. 그러면 design.md가 왜 존재하는지 훨씬 더 잘 이해될 것입니다.

design.md의 기원

design.md는 사실 Google의 AI 디자인 도구인 Stitch(Google I/O 2025에서 처음 공개됨)에서 나왔습니다. Stitch는 Gemini 기반의 UI 디자인 도구로, 프롬프트 (Prompt)를 입력하거나 스케치를 업로드하면 프론트엔드 (frontend) 코드를 포함한 UI 화면을 생성합니다.

2026년경, Google은 GitHub에 Apache 2.0 라이선스로 design.md 형식을 직접 공개했습니다 (google-labs-code/design.md). 이것이 실무적으로 무엇을 의미할까요? 그들은 Stitch의 디자인 시스템 규칙을 "표준화 (standardise)"하려고 시도하고 있는 것입니다.

Vibe Coding 개발자들이 겪는 가장 흔한 고충은 일관되지 않은 UI와 일관되지 않은 스타일입니다. 하지만 이 디자인 사양을 오픈 소스로 공개함으로써 얻는 비즈니스 가치는 매우 큽니다. Claude Code, Cursor, GitHub Copilot 또는 다른 어떤 AI 코딩 도구를 사용하더라도, 이 사양을 사용하여 일관된 UI를 생성할 수 있기 때문입니다.

이것이 Google에 가져다주는 몇 가지 예시는 다음과 같습니다:

표준이 되면서 정의를 소유하게 된다는 것. OpenAPI나 Kubernetes를 생각해 보세요. 출시 때는 무해해 보였지만, 모두가 채택하면서 누가 스펙의 방향에 대해 가장 큰 목소리를 내느냐에 따라 그것이 결정되었습니다.
다른 AI 도구들이 자발적으로 동맹군이 됩니다. Claude Code, Cursor, Copilot 등이

"그냥 CLAUDE.md에 넣으면 안 되나요?" — 가능합니다. 하지만 CLAUDE.md(및 AGENTS.md)는 AI를 위한 "자연어 규칙 (natural-language rules)"입니다. 여기에는 구조화된 팔레트(palette)나 토큰 시스템(token system)이 없습니다. 이를 읽은 후에도 AI는 여전히 "어떤 헥스(hex) 코드가 Primary인가" 또는 "이 버튼에는 어떤 코너 반경(corner radius)을 사용해야 하는가"를 추측해야 하며, 결국에는 추측에 의존하게 됩니다.

따라서 design.md는 기본적으로 해당 "디자인 시스템 규칙 (design system rules)" 문서를 기계가 정밀하게 파싱(parse)할 수 있으면서도 + 인간이 그 이면의 논리를 이해할 수 있는 파일로 변환하는 것입니다.

design.md는 실제로 어떤 모습인가요?

매우 간단합니다. design.md는 단순한 마크다운 (Markdown) 파일입니다. 구조는 두 부분으로 나뉩니다:

YAML 프론트매터 (YAML Front Matter): 정밀한 디자인 토큰 (색상, 타이포그래피, 간격, 코너 반경, 컴포넌트).
마크다운 본문 (Markdown body): 디자인 근거 (rationale) — 왜 이 색상을 사용하는지, 언제 사용해야 하는지, 언제 사용하지 말아야 하는지.

파일을 이런 방식으로 분리함으로써, AI는 단순히 "Primary는 #1A1C1E이다"라는 것만 아는 것이 아니라, "Primary는 헤드라인과 핵심 텍스트에 사용되는 짙은 잉크 색상이다"라는 것도 알게 됩니다. 따라서 UI를 생성할 때 버튼에 잘못된 색상을 사용하거나 텍스트에 잘못된 크기를 사용할 가능성이 훨씬 낮아집니다.

YAML 토큰 블록 (YAML token block)

YAML 블록은 대략 다음과 같은 형태를 띱니다:

---
name: Heritage
colors:
...

몇 가지 주요 포인트:

colors, typography, rounded, spacing, components가 5가지 주요 토큰 카테고리입니다.
토큰은 서로를 참조할 수 있습니다 — button-primary의 backgroundColor가 "{colors.tertiary}"라면, 나중에 tertiary를 변경했을 때 이를 사용하는 모든 요소가 자동으로 업데이트됩니다.
색상은 hex, rgb, hsl, oklch 등 모든 유효한 CSS 색상 문자열을 지원합니다.

Tailwind의 tailwind.config.js나 W3C 디자인 토큰 형식 모듈 (Design Tokens Format Module, DTCG)을 사용해 보셨다면 익숙하게 느껴질 것입니다.

마크다운 본문 블록 (Markdown body block)

YAML의 닫는 --- 이후에는 인간(및 AI)이 읽을 수 있도록 작성된 디자인 근거가 나옵니다.

공식적으로 권장되는 섹션 순서:

개요 (Overview)
색상 (Colors)
타이포그래피 (Typography)
레이아웃 (Layout)
고도 및 깊이 (Elevation & Depth)
도형 (Shapes)
컴포넌트 (Components)
권장 사항 및 금지 사항 (Do's and Don'ts)

오직 Colors (및 그 내부의 기본 색상)만 필수 (required) 사항입니다. 나머지는 선택 사항입니다. 여러분의 디자인 시스템 (design system)에 해당 요소가 있는 경우에만 작성하세요.

구체적인 예시 — Colors 블록은 다음과 같이 보일 수 있습니다:

## Colors

Primary (#1A1C1E): 헤드라인 및 핵심 텍스트를 위한 딥 잉크 (Deep ink).
...

이는 기본적으로 AI에게 "이 색상은 Tertiary라고 불리며, 기본 액션 버튼 (primary action buttons)에 사용하고, 본문 텍스트 (body text)에는 사용하지 마세요"라고 말하는 것과 같습니다.

잠깐 — CLI가 있다고?

네, 맞습니다. design.md는 lint, diff, export, spec이라는 네 가지 기능을 수행하는 CLI (Command Line Interface)를 함께 제공합니다.

설치 및 사용:

npm install @google/design.md
npx @google/design.md lint DESIGN.md

Windows에서는 .md 확장자가 파일 연결 프로그램에 의해 처리될 수 있으므로, designmd 별칭 (alias)을 사용하세요:

npx -p @google/design.md designmd lint DESIGN.md

lint: DESIGN.md 구조 검증

ESLint, Stylelint, Prettier와 유사한 느낌입니다. lint는 다음 사항을 확인합니다:

YAML 스키마 (schema)가 올바른지
토큰 참조 (token references)가 깨졌는지 (예: {colors.tertiery}, 'a'가 빠졌나요?!)
기본 색상 (primary colour)이 있는지
WCAG AA 대비 (contrast)를 통과하는지 (이것이 핵심 기능입니다)
정의되었지만 한 번도 사용되지 않은 고립된 토큰 (orphan tokens)이 있는지
섹션 순서가 권장 사항과 일치하는지

WCAG AA 규칙의 경우, "secondary에 대한 on-secondary의 대비가 X.X:1에 불과하여 AA를 통과하지 못합니다"라고 즉시 알려줍니다. 디자인 시스템 파일에 접근성 (Accessibility) 체크 기능이 내장되어 있는 것입니다.

diff: 두 버전 비교

디자인 시스템을 위한 git diff와 같습니다:

npx @google/design.md diff old/DESIGN.md new/DESIGN.md

어떤 토큰이 변경되었는지, 어떤 토큰이 삭제되었는지, 어떤 토큰이 추가되었는지 알려줍니다. 활용 사례: primary를 #1A1C1E에서 #0A0A0A로 변경했을 때, "이로 인해 얼마나 많은 컴포넌트 (components)의 색상이 바뀌게 될지" 알고 싶을 때 사용합니다.

export: 다른 형식으로 변환

이 기능은 특히 design.md를 "업스트림 (upstream)" 소스로 사용하고자 할 때 진정으로 인상적입니다.

형식	설명
`json-tailwind`	Tailwind v3 설정 객체로 변환
...

사용법:

npx @google/design.md export DESIGN.md --format json-tailwind > tailwind.config.js
npx @google/design.md export DESIGN.md --format css-tailwind > tailwind.css
npx @google/design.md export DESIGN.md --format dtcg > design-tokens.json

당신은 design.md에만 집중하면 됩니다. 그다음 Tailwind / CSS / DTCG로 내보내기만 하세요. 프론트엔드 개발자, 디자이너, 그리고 AI 코딩 도구(AI Coding tools)가 모두 동일한 단일 진실 공급원 (source of truth)을 사용하게 됩니다.

spec: AI에게 명세(spec)를 전달하기

npx @google/design.md spec

design.md 자체의 형식 명세 (format spec)를 출력합니다. 이를 Claude Code / Cursor / Copilot에게 전달하며 "내 DESIGN.md를 읽을 때 이 명세를 따라주세요"라고 말하세요. 그러면 AI는 YAML 스키마 (YAML schema)를 파싱하는 방법, 토큰 참조 (token references)가 {path.to.token} 구문을 사용한다는 점, 무엇이 필수이고 무엇이 선택 사항인지를 알게 됩니다. --rules를 추가하면 린팅 규칙 (linting rules)도 함께 출력됩니다.

AI 코딩 도구와 함께 사용하기

전체적인 설계 목표는 "UI 디자인 시스템을 AI가 지속적으로 이해할 수 있는 무언가로 바꾸는 것"입니다. 따라서 사용법은 간단합니다:

프로젝트 루트에 DESIGN.md를 둡니다.
CLAUDE.md / AGENTS.md / .cursor/rules/*.mdc 파일에 다음 한 줄을 추가합니다: "UI 관련 작업 시, 먼저 DESIGN.md를 읽고 그 안에 있는 토큰 (tokens)과 디자인 근거 (design rationale)를 엄격히 준수하세요."

이것으로 끝입니다.

마지막으로, 다소 진부할 수 있지만 한 가지 주의사항을 말씀드리자면:

design.md를 무관한 쓰레기 정보로 채우지 마세요.

전체적인 설계 철학은 AI에게 당신의 디자인 지식을 정제된 (distilled) 버전으로 제공하는 것입니다. 이는 Agent Skills와 같은 방향성을 가집니다. AI에게 모든 것을 주지 말고 핵심 포인트만 전달하세요.

현재 design.md는 Claude Code / Cursor / Copilot을 위한 공식 통합 예제를 제공하지 않으며, CLI와 TypeScript API만 제공합니다. 따라서 CLAUDE.md / AGENTS.md / rules 파일을 통해 AI가 design.md를 읽도록 가이드해야 합니다.

마무리

그렇다면 design.md란 진정으로 무엇일까요?

"YAML 토큰 + Markdown 디자인 근거 (design rationale)" 형식으로 작성된 AI 코딩 도구용 디자인 시스템 문서입니다.
이 문서가 해결하는 페인 포인트 (pain point)는 AI가 생성한 UI의 색상, 글꼴 크기, 간격이 일관되지 않다는 점입니다.
내장된 CLI를 통해 린트 (lint, WCAG 대비 체크 포함), 디프 (diff), Tailwind / DTCG로의 내보내기 (export)가 가능하며, AI를 위한 스펙 (spec)을 출력할 수 있습니다.

이 정보가 "AI가 일관되지 않은 색상, 글꼴 크기, 간격을 가진 UI를 생성하는" 문제를 해결하여, 여러분의 AI 코딩 워크플로우 (workflow)가 훨씬 더 원활하게 진행되는 데 도움이 되기를 바랍니다.

Insights