문제: AI는 디자인을 기억하지 못합니다
Figma 디자인 시스템이 아무리 정교해도 AI 에이전트는 그것을 모릅니다. 매 대화마다 색상 코드를 복붙하거나, 에이전트가 임의로 선택한 컬러가 브랜드와 전혀 다른 상황이 반복됩니다.
디자인 토큰에 값만 있고 이유가 없으면, 에이전트는 "왜 이 색인지" 모른 채 비슷해 보이는 다른 값을 쓸 수 있습니다.
design.md는 이 문제를 YAML 토큰 + 마크다운 설명의 조합으로 해결합니다. 토큰에는 정확한 값이, 산문에는 그 결정의 배경이 함께 담깁니다.
기존 방식과 비교
DESIGN.md 파일 구조
파일은 YAML 프론트매터(토큰 값)와 마크다운 본문(설계 이유)으로 구성됩니다.
---
name: Heritage
colors:
primary: "#1A1C1E"
tertiary: "#B8422E"
typography:
h1:
fontFamily: Public Sans
fontSize: 3rem
spacing:
sm: 8px
md: 16px
lg: 32px
rounded:
default: 4px
---
## 컬러 팔레트
Primary는 깊은 중립 톤으로 콘텐츠의 무게감을 표현합니다.
Tertiary의 테라코타 레드는 CTA에서만 제한적으로 사용해
브랜드의 절제된 에너지를 강조합니다.
## 타이포그래피
Public Sans는 모더니즘과 가독성의 균형을 잡습니다.
h1은 3rem으로 섹션 계층을 명확히 구분합니다.에이전트는 이 파일을 읽으면 토큰 값과 그 이유를 함께 이해합니다. 단순히 "#B8422E를 써라"가 아니라 "CTA에서만 제한적으로 쓰는 색"임을 알게 됩니다.
4가지 CLI 도구
토큰 유형
DESIGN.md가 정의할 수 있는 4가지 핵심 토큰 카테고리입니다.
에이전트에게 디자인 시스템 주입하기
DESIGN.md를 Claude Code나 Cursor에 연결하면 에이전트가 매 컴포넌트 생성 시 토큰을 자동 참조합니다. spec 명령어로 출력한 명세를 시스템 프롬프트에 추가하는 방법이 가장 간단합니다.
이후 "헤더 컴포넌트 만들어줘"라고 하면 에이전트가 primary 컬러, h1 타이포그래피, md 간격을 자동으로 적용합니다.
설치 및 시작 방법
CLI 설치
npm으로 전역 설치합니다. Windows에서는 파일 확장자 충돌을 피해 designmd 별칭을 사용합니다.
npm install -g @google/design.md
DESIGN.md 파일 생성
프로젝트 루트에 DESIGN.md 파일을 만듭니다. YAML 프론트매터에 색상·폰트·간격 토큰을 정의하고, 마크다운 본문에 각 결정의 이유를 적습니다.
린터로 검증
구조가 올바른지, 색상 대비비가 WCAG를 통과하는지 확인합니다. JSON 출력이므로 CI/CD 파이프라인에 바로 통합 가능합니다.
npx @google/design.md lint DESIGN.md
Tailwind로 익스포트
정의한 토큰을 Tailwind 설정 파일로 변환합니다. 기존 프로젝트에 바로 통합할 수 있습니다.
npx @google/design.md export --format tailwind DESIGN.md
에이전트에 연결
spec 명령어로 에이전트 프롬프트용 명세를 출력하고 CLAUDE.md 또는 .cursorrules에 추가합니다. 이후 모든 AI 생성 코드에 디자인 시스템이 자동 반영됩니다.
npx @google/design.md spec DESIGN.md >> CLAUDE.md
솔직한 한계
아직 알파 버전입니다. 스펙이 활발하게 변경 중이며 프로덕션 사용 전 변경 로그를 반드시 확인하세요.
에이전트가 반드시 따르진 않습니다. DESIGN.md를 시스템 프롬프트에 주입해도 에이전트가 항상 토큰을 참조한다는 보장은 없습니다. 린터를 CI에 연결해 생성된 코드를 검증하는 단계가 필요합니다.
Figma 직접 연동은 없습니다. Figma Variables에서 DESIGN.md로 자동 변환하는 공식 플러그인은 아직 없습니다. 수동으로 토큰을 옮겨야 합니다.