디자인 시스템을 AI에게 '기억'시키는 파일 하나: DESIGN.md

하루 만에 별 1,407개. google-labs-code/design.md가 GitHub 트렌딩 1위에 올랐다. 총 누적 별은 19,000개를 넘겼다. 단순한 유행이 아니다. AI 코딩 에이전트 시대에 디자인 시스템을 어떻게 다룰 것인가라는 오래된 고통에 Google Labs가 정면으로 답을 내놨다.

이게 뭔가

DESIGN.md는 코딩 에이전트(Cursor, Claude Code, Copilot 등)에게 디자인 시스템을 전달하기 위한 파일 포맷 명세다.

비개발자에게 쉽게 설명하자면 이렇다. AI에게 "버튼을 파란색으로 만들어"라고 매번 말하는 대신, 프로젝트 루트에 DESIGN.md 파일 하나를 두면 에이전트가 그것을 읽고 우리 브랜드 색상, 폰트, 간격 규칙을 스스로 기억한 채 코드를 짠다. 마치 신입 개발자에게 디자인 가이드라인 문서를 넘겨주는 것과 같다.

파일 구조는 두 층으로 이루어진다. YAML 프론트매터에는 색상값, 폰트 크기, 간격, 모서리 반경 같은 토큰을 기계가 읽기 좋게 정의하고, 마크다운 본문에는 "왜 이 색인가", "언제 쓰는가"를 사람이 읽기 좋게 서술한다.

토큰은 에이전트에게 정확한 값을 주고, 산문은 맥락과 의도를 준다. 둘 다 있어야 에이전트가 일관된 UI를 만든다.

왜 지금 뜨는가

AI 코딩 도구 사용이 급격히 늘면서 "에이전트가 매번 다른 UI를 뱉는다"는 불만이 팀 단위로 터져 나오고 있다. 오늘은 버튼이 #3B82F6, 내일은 #2563EB. 폰트는 Inter였다가 Roboto가 된다. 디자인 시스템이 있어도 에이전트는 모른다.

기존 해결책들은 부분적이었다. .cursorrules나 CLAUDE.md는 코드 스타일 규칙엔 강하지만 디자인 토큰을 구조적으로 담기엔 부적합했다. Figma 플러그인이나 Storybook은 에이전트가 직접 소비하기 어렵다.

DESIGN.md는 이 틈을 노린다. Google Stitch라는 자체 AI 디자인 도구와 함께 공개되면서 실제 프로덕션 적용 경로까지 제시한 점도 신뢰를 높였다. Apache-2.0 라이선스라 상업적 사용도 자유롭다.

핵심 기능

공식 CLI(@google/design.md)는 두 가지 핵심 커맨드를 제공한다.

lint — 명세 유효성 검사, 토큰 참조 오류 탐지, WCAG 명암비 자동 계산까지 수행하고 결과를 구조화된 JSON으로 반환한다. 에이전트가 바로 읽는 형태다.

diff — 두 버전의 DESIGN.md를 비교해 어떤 토큰이 추가·삭제·변경됐는지, 그리고 디자인 회귀(regression)가 발생했는지 감지한다. 버전 관리와 코드 리뷰에 바로 붙인다.

누구에게 쓸모 있나

AI 도구를 쓰는 프론트엔드 개발자는 에이전트가 디자인 규칙을 무시하는 현상을 줄인다. 디자인 시스템 오너는 Figma 변수를 DESIGN.md 토큰으로 내보내 코드베이스와 단일 진실 공급원을 맞춘다. 풀스택 솔로 개발자는 디자인 감각 없이도 에이전트가 일관된 UI를 유지하도록 가이드를 위임한다. 디자이너-개발자 협업 팀이라면 디자이너가 DESIGN.md를 관리하고 개발자는 에이전트에게 맡기는 분업 구조가 된다.

시작하기

별도 설치 없이 npx로 바로 실행된다. Node.js 환경이면 충분하다.

프로젝트 루트에 DESIGN.md 파일을 만들고 아래 CLI로 검증하면 된다.

# DESIGN.md 파일 문법 검사 + WCAG 명암비 확인
npx @google/design.md lint DESIGN.md

# 두 버전 비교 — 디자인 토큰 변경사항 추적
npx @google/design.md diff DESIGN.md DESIGN-v2.md

공식 명세 문서에 전체 스키마가 정리되어 있다.

사용 예시

① 기본 DESIGN.md 파일 작성 — YAML 프론트매터에 토큰, 마크다운에 설계 의도를 기술한다.

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

## Colors

고대비 뉴트럴 팔레트에 단일 액센트(Boston Clay)를 사용한다.
액센트는 CTA 버튼과 링크에만 쓴다. 남용하지 않는다.

② lint로 유효성 검사 — 에러 0, 명암비 통과 여부를 JSON으로 확인한다.

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

③ diff로 버전 간 토큰 회귀 감지 — PR 리뷰 시 어떤 값이 바뀌었는지 즉시 파악한다.

{
  "tokens": {
    "colors": { "added": ["accent"], "removed": [], "modified": ["tertiary"] },
    "typography": { "added": [], "removed": [], "modified": [] }
  },
  "regression": false
}

한계·주의

몇 가지 냉정한 시각이 필요하다.

에이전트가 자동으로 읽지는 않는다. DESIGN.md는 포맷 명세일 뿐이다. Cursor나 Claude Code가 이 파일을 컨텍스트로 집어넣으려면 .cursorrules나 CLAUDE.md에서 명시적으로 참조하거나, 에이전트 설정에 포함시켜야 한다. 파일을 만든다고 마법처럼 작동하지 않는다.

완성도는 아직 진행 중이다. Google Labs 레포지토리 특성상 프로덕션 안정성보다 실험적 성격이 강하다. 명세가 변경될 수 있으므로 핵심 프로젝트에 도입할 때는 버전을 고정해 두는 것이 안전하다.

토큰 설계는 여전히 사람의 몫이다. 파일 포맷이 아무리 좋아도 잘못된 색상값과 모호한 산문을 에이전트가 교정해주지는 않는다. "쓰레기를 넣으면 쓰레기가 나온다"는 원칙은 그대로 적용된다.

AI가 디자인을 대체하는 것이 아니라, 디자인 의도를 AI에게 정확히 전달하는 새로운 인터페이스가 필요해졌다. DESIGN.md는 그 인터페이스의 초기 답안이다. 완성형은 아니지만, 방향은 옳다.