DESIGN.md - Google Labs Code의 토큰과 마크다운으로 디자인 시스템을 문서화하는 포맷
목차
개요
DESIGN.md는 Google Labs Code에서 발표한 디자인 시스템 문서화 포맷이다. YAML 토큰과 Markdown 문서를 결합한 이중 구조(dual structure)로 디자인 시스템을 표현한다. Rubric의 커리큘럼은 28개 챕터로 이 포맷을 다루며, 단순 따라하기가 아니라 “왜 이렇게 설계되었는가”를 추적하도록 유도한다.
핵심 메시지는 짧다. “토큰이 답이고, 본문 텍스트는 그 추론(reasoning)이다.”
배경
디자인 시스템은 보통 Figma 같은 디자인 도구나 별도 문서 사이트에 분산되어 있다. 색상, 타이포그래피, 컴포넌트 변형 같은 의사결정의 사유는 본문 글에 흩어지고, 실제 토큰 값은 별도 데이터로 관리된다. 이 구조에서는 토큰과 그 토큰을 채택한 이유가 분리되어 시간이 지나면 사유는 사라지고 값만 남는다.
DESIGN.md는 두 레이어를 한 파일 안에서 구조화한다. YAML로 정형화된 토큰 데이터를 표현하고, Markdown으로 그 토큰을 채택한 사유와 사용 가이드를 함께 적는다. 사람과 도구 모두가 같은 파일을 출처(source of truth)로 삼는 것이 목표다.
핵심 내용
핵심 철학: 토큰 우선
DESIGN.md의 첫 모듈인 M1은 포맷의 의도를 정리한다. 토큰은 디자인 결정의 답(answer)이고, 본문 텍스트는 그 답에 도달한 추론을 기록한다. 디자인이 왜 그 선택을 했는지를 추적할 수 있도록 의도된 구조다.
YAML과 Markdown의 분리는 단순 미적 결정이 아니다. 구조화된 데이터(YAML)는 도구가 파싱해 lint, diff, export에 사용하고, 사람이 읽기 위한 설명(Markdown)은 디자이너와 엔지니어 사이의 의사소통 매체가 된다. 같은 파일이 두 가지 역할을 동시에 수행한다.
8개 섹션 구조
DESIGN.md는 정해진 순서로 8개 섹션을 강제한다. 순서를 강제하는 이유는 디자인 시스템 내에서 의존성이 한 방향으로 흐르도록 하기 위함이다. 색상 토큰이 정의되어야 컴포넌트 토큰이 색상을 참조할 수 있는 식이다.
| 순서 | 섹션 | 설명 |
|---|---|---|
| 1 | Overview | 디자인 시스템 개관 |
| 2 | Colors | 색상 토큰 |
| 3 | Typography | 타이포그래피 토큰 |
| 4 | Layout | 레이아웃 규칙 |
| 5 | Elevation | 그림자와 깊이 |
| 6 | Shapes | 모서리, 형태 |
| 7 | Components | 컴포넌트와 변형 상태 |
| 8 | Do’s and Don’ts | 가드레일 |
마지막 Do’s and Don’ts 섹션은 가드레일 역할이다. 컴포넌트의 잘못된 사용 사례를 명시적으로 기록해 디자인 시스템 사용자가 같은 실수를 반복하지 않게 한다.
토큰 스키마
M2 모듈은 토큰의 표준 타입을 정의한다. 색상은 정해진 값 형식으로, 치수(dimensions)는 단위와 함께 길이 값으로, 타이포그래피는 폰트 구조로 표현된다. 중요한 것은 토큰 참조(token reference) 문법이다.
토큰끼리 서로를 참조할 때는 중괄호 문법을 사용한다. 예를 들어 컴포넌트 토큰이 색상 토큰을 가리킬 때 {colors.primary} 같은 형태로 적는다. 이 참조 메커니즘이 색상 팔레트 변경 시 모든 의존 컴포넌트가 자동으로 업데이트되는 기반이다.
CLI 도구
M5 모듈은 네 개의 CLI 명령을 다룬다. 각 명령은 DESIGN.md 파일을 입력으로 받아 다른 결과를 만들어낸다.
| 명령 | 역할 |
|---|---|
| lint | 파일 검증과 규칙 위반 탐지 |
| diff | 버전 간 변경 비교 |
| export | 다른 포맷으로 변환 |
| spec | 스키마 출력 |
lint는 8개의 규칙을 검사한다고 커리큘럼이 명시한다. diff는 단순 텍스트 diff가 아니라 토큰 단위 변경을 추적해 디자인 변경 PR 리뷰를 가능하게 한다. export는 DESIGN.md를 CSS 변수, JSON, 플랫폼별 토큰 포맷으로 변환한다.
의미와 시사점
DESIGN.md의 흥미로운 지점은 디자인 문서가 lintable하고 diffable해진다는 것이다. 지금까지 디자인 시스템 변경은 Figma 라이브러리 업데이트나 Storybook 스크린샷 비교에 의존했다. DESIGN.md를 사용하면 디자인 변경이 코드 PR과 동일한 워크플로 - lint, diff, review - 위에 올라온다.
두 번째로 주목할 부분은 커리큘럼이 강조하는 전이 가능성이다. “이 접근을 왜 선택했는지를 추적하라”는 원칙은 API 스펙, 프롬프트, 팀 문서에도 그대로 적용된다. 구조화된 토큰과 사유를 함께 적는 패턴은 디자인 시스템에 한정된 발명이 아니라 문서 형식 일반에 적용 가능한 패턴이다.
마지막으로 토큰 참조 문법은 LLM 친화적이다. {colors.primary} 같은 명시적 참조는 LLM이 디자인 시스템 변경을 제안할 때 어떤 토큰이 어떤 토큰을 참조하는지를 정확히 추적할 수 있는 단서가 된다. 디자인 도구와 코드 생성 에이전트 사이의 공유 언어 후보로 자리 잡을 가능성이 있다.
결론
DESIGN.md는 디자인 시스템의 토큰과 그 사유를 하나의 파일에서 함께 다루는 포맷이다. 8개 섹션 구조와 토큰 참조 문법, lint/diff/export/spec CLI는 디자인 문서를 코드처럼 다루기 위한 인프라다. 디자인 시스템을 구축 중이거나 LLM 친화적 문서 포맷을 찾는 팀이라면 검토할 가치가 있다.