DESIGN.md: AI 에이전트에게 디자인을 설명하는 파일 하나

📋 요약 한 줄 요약 CLAUDE.md가 에이전트에게 “이 프로젝트에서 일하는 법”을 알려주듯, DESIGN.md는 “이 프로젝트가 어떻게 생겨야 하는지”를 알려주는 파일 포맷이다. 위쪽에는 정확한 값(색상·타이포 토큰), 아래쪽에는 그 값이 왜 존재하고 어떻게 써야 하는지 산문으로 적는다. Google Labs가 스펙과 검증 CLI를 함께 공개했고, 핵심 철학은 의외로 “토큰보다 산문이 중요하다”이다.

1. 어떤 문제를 풀려는 건가

코딩 에이전트에게 UI를 만들어 달라고 해본 사람은 다 겪는 문제가 있다. 오늘 만든 화면과 내일 만든 화면의 디자인이 다르다. 버튼 색이 조금씩 바뀌고, 폰트가 널뛰고, 어제는 각졌던 모서리가 오늘은 둥글다.

이유는 단순하다. 에이전트에게는 디자인 시스템에 대한 기억이 없다. 매번 대화 프롬프트에 “우리 브랜드 색은 이거고, 폰트는 저거고…”를 다시 설명하거나, 아니면 에이전트가 그럴듯한 걸 알아서 지어내게 두는 수밖에 없었다.

DESIGN.md는 이걸 파일 하나로 해결하자는 제안이다. 프로젝트에 CLAUDE.md나 AGENTS.md를 두듯이, 디자인 정체성을 적은 DESIGN.md를 두면 에이전트가 매 세션 그걸 읽고 일관된 UI를 만든다는 것.

2. 파일이 어떻게 생겼나

DESIGN.md 파일 하나는 두 층으로 되어 있다. README의 “Heritage” 예시를 층별로 나눠서 보면:

① 위층 — YAML 프론트매터 (기계가 읽는 디자인 토큰). 파일 맨 위에 ---로 감싸서 두는, 색상·타이포그래피·둥글기 같은 정확한 값들이다:

---
name: Heritage
colors:
  primary: "#1A1C1E"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 3rem
rounded:
  sm: 4px
---

② 아래층 — 마크다운 산문 (그 값들의 이유와 용법). 같은 파일에서 프론트매터 바로 아래에 이어지는 본문이다. 이 색이 왜 존재하고, 어디에 써야 하고, 어디에 쓰면 안 되는지를 적는다:

## Overview

건축적 미니멀리즘과 저널리즘의 무게감. 고급 무광 마감 —
프리미엄 신문이나 현대 갤러리를 연상시키는 UI.

## Colors

- **Primary (#1A1C1E):** 헤드라인과 본문을 위한 깊은 잉크색.
- **Tertiary (#B8422E):** "Boston Clay" — 인터랙션을 이끄는 유일한 색.
- **Neutral (#F7F5F2):** 순백보다 부드러운, 따뜻한 석회암 배경.

토큰(①)은 정확한 값을 주고, 산문(②)은 그 값을 적용하는 감각을 준다. 이 파일을 읽은 에이전트는 어떤 UI를 만들게 될까? 위 스펙을 그대로 따라 렌더링해보면 이런 화면이 나온다:

깊은 잉크색 헤드라인, 슬레이트색 메타데이터, 그리고 화면에서 유일하게 색을 가진 Boston Clay 버튼 — 산문에 적힌 규칙(“인터랙션을 이끄는 유일한 색”)이 그대로 반영된다.

전체 그림에서 DESIGN.md가 어디에 놓이는지 보면:

flowchart LR
    D["DESIGN.md<br/>토큰(YAML) + 산문(Markdown)"]
    D -->|매 세션 읽음| A["코딩 에이전트"]
    A --> U["일관된 UI 코드"]
    D --> L["lint — 11개 규칙 검증"]
    D --> F["diff — 버전 비교·회귀 감지"]
    D --> E["export — Tailwind / W3C DTCG"]
    L -->|JSON findings| A

3. 의외의 핵심 철학: 토큰보다 산문

값을 정확히 주는 게 중요할 것 같지만, 프로젝트의 PHILOSOPHY 문서는 정반대를 말한다:

💬 핵심 문장 생성되는 디자인의 품질은 값의 정밀함보다, 의도가 얼마나 명확하게 서술되었는가에 의해 결정된다.

여기서 나오는 원칙 두 가지가 이 프로젝트에서 가장 곱씹을 만한 부분이다.

첫째, 형용사 목록보다 구체적인 레퍼런스 하나가 낫다.

“모던하고, 깔끔하고, 신뢰감 있고, 프리미엄한” — 이런 형용사는 아무것도 특정하지 못한다. 모델은 그 단어들의 한가운데쯤에 있는, 어디서 본 듯한 평균적인 결과물을 만든다. 반면 “오래된 명문대 전통의 1970년대 대학원 강의 유인물”이라는 한 문장은 완결된 세계를 불러온다: 잉크는 한 색, 여백은 넉넉하고, 세리프체는 읽기 좋은 크기로, 장식은 없음. 형용사는 영역을 묘사하고, 구체적 레퍼런스는 한 점을 찍는다.

둘째, 무엇을 하지 않을지는 레퍼런스가 공짜로 데려온다.

모델은 강의 유인물이 뭔지 알기 때문에, 유인물이 아닌 것도 안다. 유인물은 빛나지 않고, 그라데이션을 쓰지 않는다. 이걸 일일이 나열할 필요가 없다 — “개”라고 말하면 개가 야옹거리지 않는다는 것까지 전달되는 것과 같다. 금지 목록이 길고 장황해진다면, 그건 애초에 설명이 너무 모호했다는 신호다. 구체적 레퍼런스에 의도적인 Do’s and Don’ts 몇 개를 얹는 게 이상적인 조합이다. PHILOSOPHY 문서의 실제 예시(“강의 유인물” 디자인의 Do’s and Don’ts)를 일부 옮기면:

## Do's and Don'ts

- **Don't** 타이틀 페이지에 히어로 연출을 넣지 마라. 진짜 유인물의
  첫 장은 잡지 표지가 아니라 첫 번째 내용 페이지다.
- **Don't** 어디에도 Bold를 쓰지 마라.
- **Don't** 다크 모드, 그라데이션, 글로우, 유리 표면, 그림자,
  둥근 모서리를 도입하지 마라.
- **Do** 유인물을 인쇄물로 취급하라. 화면은 매체일 뿐,
  디자인은 종이 페이지다.
- **Do** vermilion(주홍색)은 다이어그램 안에만 가둬라. 바깥에서
  희소하기 때문에 안에서의 존재가 의미를 갖는다.
- **Do** 소박한 크기 차이를 믿어라. 섹션 제목은 본문의 5배가
  아니라 ~1.9배면 충분하다.

그래서 이 스펙에서 토큰 값은 “렌더링 명령”이 아니라 “산문이 참조하는 맥락”으로 취급된다. 수십 년간 쌓인 CSS와 디자인 툴의 역할을 다시 발명하지 않겠다는 선긋기다.

4. 함께 제공되는 도구: 검증하고, 비교하고, 내보내기

포맷만 던져놓은 게 아니라 CLI가 같이 온다. 출력이 전부 JSON이라서 사람보다는 에이전트가 읽고 행동하도록 설계된 게 특징이다.

npx @google/design.md lint DESIGN.md

{
  "findings": [
    {
      "severity": "warning",
      "path": "components.button-primary",
      "message": "textColor (#ffffff) on backgroundColor (#1A1C1E) has contrast ratio 15.42:1 — passes WCAG AA."
    }
  ],
  "summary": { "errors": 0, "warnings": 1, "infos": 1 }
}

• lint — 파일이 스펙에 맞는지 검사한다. 총 11개 규칙이 있는데 예를 들면: 존재하지 않는 토큰을 참조하면 에러({colors.primary}라고 썼는데 primary가 없음), 버튼의 글자색/배경색 조합이 WCAG 접근성 대비 기준(4.5:1)에 못 미치면 경고, 정의만 하고 아무 데도 안 쓰는 색이 있으면 경고.
• diff — 두 버전의 DESIGN.md를 비교해서 어떤 토큰이 추가·변경·삭제됐는지, 품질이 후퇴(regression)했는지 알려준다. 디자인 시스템 변경을 코드 리뷰하듯 다룰 수 있다.
• export — 토큰을 Tailwind v3 설정, Tailwind v4 @theme CSS, W3C 표준 디자인 토큰 포맷(DTCG)으로 변환한다. 기존 프론트엔드 도구 체인과 연결되는 지점.
• spec — 포맷 명세 자체를 출력한다. 에이전트 프롬프트에 스펙을 주입하는 용도라고 명시되어 있다.

5. 확장은 자유

스펙이 표준화하는 건 최소한(이름 + 색상·타이포·간격·둥글기·컴포넌트)이고, 그 밖은 열려 있다. 예를 들어 모션 섹션은 스펙에 없지만 이렇게 그냥 추가하면 된다:

## Motion

motion:
  feedback: 120ms
  easing: 'cubic-bezier(0.2, 0, 0, 1)'

전환은 빠르고 기계적이다. 아무것도 튀지 않고, 넘치지 않고, 머무르지 않는다.
상태 변화는 문이 닫히는 게 아니라 전등 스위치처럼 느껴져야 한다.

린터는 모르는 섹션을 에러 내지 않고 받아들이고, 에이전트는 산문을 읽는다. 토큰이 명령이 아니라 맥락이기 때문에 스펙을 고칠 필요가 없었다는 게 프로젝트의 설명이다.

6. 현재 상태

• Google Labs 프로젝트, 포맷 버전 alpha — 스펙·스키마·CLI 모두 활발히 바뀌는 중
• npm @google/design.md로 설치, Apache 계열 오픈소스
• 레포에 예제 디자인 시스템 3종(Atmospheric Glass, Paws and Paths, Totality Festival)이 포함되어 있어 실물 감을 잡기 좋다

CLAUDE.md → AGENTS.md로 이어진 “에이전트에게 컨텍스트를 파일로 준다”는 흐름이 디자인 영역으로 넘어온 사례로 볼 수 있다. 포맷 자체가 살아남을지는 지켜봐야 하지만, “형용사가 아니라 레퍼런스로 말하라”는 프롬프팅 원칙은 이 포맷을 안 쓰더라도 바로 가져다 쓸 수 있다.

핵심 요약

• DESIGN.md는 에이전트가 읽는 디자인 시스템 문서다. YAML 토큰(정확한 값) + 마크다운 산문(값의 이유와 용법)의 2층 구조로, 매 세션 흔들리던 에이전트의 UI 결과물에 일관성을 준다.
• 핵심 철학은 산문 > 토큰: “모던하고 깔끔한”(영역) 대신 “1970년대 대학원 강의 유인물”(점) 같은 구체적 레퍼런스가 품질을 결정하고, 충분히 구체적인 레퍼런스는 금지 사항까지 공짜로 데려온다.
• CLI가 lint(11개 규칙 — 깨진 참조, WCAG 대비, 고아 토큰 등) / diff(버전 간 회귀 감지) / export(Tailwind, W3C DTCG) / spec(프롬프트 주입용)을 제공하며, 출력이 JSON이라 에이전트가 직접 소비한다.
• 스펙은 최소만 표준화하고 나머지(모션 등)는 자유 확장 — 토큰이 명령이 아니라 맥락이라 가능한 구조. 현재 alpha 단계.

관련 노트

• AI 시대 코프링은 살아남을 수 있을까 — 에이전트가 개발 주체가 되는 시대의 도구·환경 변화라는 같은 맥락
• KotlinLLM 스마트 매크로 IntelliJ 플러그인 — 에이전트에게 무엇을 어떻게 전달할 것인가에 대한 또 다른 실험