design/design-md
에반9년차 개발자
DESIGN.md — AI 디자인 에이전트가 읽는 디자인 시스템 한 장
Figma·노션·PDF에 흩어진 색·폰트·간격을 YAML+마크다운 한 장에. Stitch·Cursor·Claude Code가 매 화면 같은 룰로 만들어요.
에반9년차 개발자무료
DESIGN.md · GOOGLE STITCH · TOKEN SPEC
AI 디자인 에이전트가
매번 다른 화면을 뱉어내요?
DESIGN.md 한 장이면 톤이 잠겨요.
Stitch, Cursor, Claude Code, v0.
AI 도구로 화면을 뽑을 때마다 색도 다르고, 폰트 크기도 다르고,
모서리 둥근 정도도 다 다르게 나와요.
이 스킬은 Google Stitch 팀이 만든 DESIGN.md 규격을 한국어로 풀어 주고,
바로 복붙해서 쓸 수 있는 템플릿과 @google/design.md CLI 사용법까지 정리해 둔 한 묶음이에요.
받아서 프로젝트 루트에 두면, 그때부터 AI가 같은 룰로 그려요.
SITUATION
이런 적, 한 번쯤은 있죠.
"버튼 다섯 개만 다시 만들어 줘."
Stitch에 시켰는데, 첫 화면은 민트, 두 번째 화면은 짙은 초록, 세 번째 화면은 갑자기 파랑이 나와요.
똑같은 프롬프트인데 결과가 매번 달라요.
Figma에는 컬러 토큰, 노션에는 가이드, 메일에는 로고 png. 거기에 디자이너 머릿속의 "이건 좀 부드러운 느낌으로요"까지.
그걸 AI 에이전트에 매번 다시 통역해 줘야 해요.
AI가 매번 다른 화면을 뽑는 게 아니라, 내가 매번 다른 룰을 주고 있던 거예요.
WHY IT BREAKS
왜 매번 톤이 달라져요?
AI 디자인 에이전트는 "이 프로젝트가 어떤 톤이다"를
코드 어딘가에서 찾아 읽으려 해요. 그런데 그 한 장이 없어요.
결국 매 화면마다 프롬프트 안에 색 hex, 폰트 크기, 둥근 정도를 다시 풀어 적어야 해요.
한두 번이면 참는데, 매 화면이 그러니까 본 작업보다 통역이 길어져요.
DESIGN.md SPEC
"DESIGN.md는 AI 디자인 에이전트가 읽는
디자인 시스템 한 장이다."
디자인 시스템 한 장이다."
Google Stitch · Design Agent Spec
SOLUTION
그래서 DESIGN.md가 나왔어요.
Google Stitch 팀이 정의한 평문 형식이에요.
README.md가 사람을 위한 거라면, AGENTS.md는 코딩 에이전트용,
DESIGN.md는 디자인 에이전트가 읽는 한 장이에요.
두 층 구조예요. 위쪽 YAML 머리말에는 hex 색, 폰트 속성, 간격 스케일이 토큰으로 들어가고,
아래 마크다운 본문에는 "왜 이 색을 골랐는지" 같은 설명이 들어가요.
AI는 위쪽을 보고 그리고, 사람은 아래쪽을 읽고 합의해요. 디자인이 진화하면 같이 자라는 살아있는 문서예요.
WHAT YOU GET
들이면 뭐가 좋은데요?
막연한 약속 말고, 다섯 가지만 콕 짚어 볼게요.
-
AI가 매번 같은 톤으로 그려요.
Stitch, Cursor, Claude Code, v0 같은 도구가 프로젝트 루트의 DESIGN.md를 읽어요. "이 색 써 줘"를 매 프롬프트마다 다시 적지 않아도 같은 결과가 나와요.
-
디자이너와 개발자가 같은 단어를 써요.
토큰 이름이 한 장에 박혀 있어요.
colors.primary-60이 곧 hex이고, 곧 Tailwind 클래스예요. "그 민트 말고 좀 더 어두운 민트요"가 사라져요. -
새 화면 시작이 빨라져요.
"이 프로젝트 분위기로 새 결제 화면 그려 줘"라고만 던지면 AI가 본문을 읽고, 토큰을 들고, 일관된 화면을 한 번에 뱉어요.
-
Tailwind, DTCG로 한 번에 내보내요.
@google/design.md export명령으로 Tailwind config과 DTCG JSON을 뽑아요. 디자인 시스템 한 장을 코드 여러 형식으로 옮길 때 손이 안 묶여요. -
화면 톤 사고가 사전에 잡혀요.
CLI 린터가 깨진 토큰 참조, WCAG 명도비 미달, 외톨이 토큰을 미리 잡아요. 배포 전에 "그 버튼 글씨 안 보이는데요"가 줄어요.
WHO IT'S FOR
누가 쓰면 좋아요?
WHAT'S INSIDE
안에 뭐가 들어 있어요?
DESIGN.md 한 장은 정해진 8개 섹션으로 채워요.
이 스킬은 그 8개를 한국어로 풀고, 각 섹션을 바로 복붙할 수 있는 템플릿으로 만들어 뒀어요.
01 · OVERVIEW
브랜드와 분위기 한 단락.
타깃과 감정, 톤을 짧게 적어요. "따뜻한 갈색의 동네 카페 앱, 친근하고 둥근 느낌" 한 줄이면 충분해요. 이 단락이 아래 모든 토큰의 근거가 돼요.
02 · COLORS
최소 primary 한 개부터.
관례는 primary · secondary · tertiary · neutral 4계열. 각 계열은 0부터 100까지 톤 스케일을 가질 수 있어요. 전부 sRGB hex로 적어요. 예: "#1A1C1E".
03 · TYPOGRAPHY
보통 9~15단계 의미 토큰.
역할 + 크기 변형으로 이름을 정해요. headline-large, body-medium, label-small 같은 식. 각 토큰은 fontFamily, fontSize, fontWeight, lineHeight, letterSpacing을 묶은 객체예요.
04 · LAYOUT
그리드와 간격 스케일.
몇 칼럼, 어떤 거터, 어떤 간격 단위를 쓰는지 적어요. spacing은 보통 4px, 8px, 12px 같은 단계로 토큰화해서 AI가 여백을 즉흥적으로 정하지 않게 막아요.
05 · ELEVATION
그림자로 위계 정리.
버튼·카드·모달의 상하 위계를 그림자 단계로 표현해요. elevation-1, elevation-2 같은 토큰으로 묶고, 본문에는 "왜 얇게 유지하는지"를 한 줄 적으면 좋아요.
06 · SHAPES
모서리 둥근 정도.
rounded.sm, rounded.md, rounded.full 같은 단계로 적어요. 버튼·카드·아바타가 어느 단계를 쓰는지 컴포넌트 섹션에서 다시 가리켜요.
07 · COMPONENTS
button-primary, input, card.
위에서 정의한 토큰을 참조해서 컴포넌트를 정의해요. 참조는 {colors.primary-60}처럼 중괄호 경로로 적어요. AI가 같은 컴포넌트를 매번 같은 모양으로 그려요.
08 · DO & DON'T
짧은 가드레일 목록.
"primary 위에 secondary 텍스트를 쓰지 마세요" 같은 한 줄짜리 규칙. 본문 마지막에 짧게 묶어 두면, AI의 자유 분방한 시도를 막아 줘요.
HOW TO USE
이렇게 쓰면 돼요.
DESIGN.md를 만드는 길은 세 갈래예요.
셋 중 하나로 시작하고, 나머지 단계는 같아요.
-
한 줄 설명으로 AI에게 맡기기.
Stitch 같은 도구에 "따뜻한 동네 카페 앱, 부드럽고 둥근 느낌" 한 줄을 던져요.
AI가 8개 섹션을 알아서 채워 줘요. 이 스킬에 든 한국어 프롬프트 예시를 그대로 복붙해도 돼요. -
브랜드 자산에서 뽑기.
기존 사이트 URL이나 로고 이미지가 있으면 그걸 입력으로 줘요.
AI가 거기서 팔레트와 폰트, 분위기를 추출해 초안을 만들어요.
이 스킬 안에는 추출 결과를 다듬는 체크리스트가 들어 있어요. -
손으로 직접 적기.
위 YAML 머리말 + 아래 마크다운 본문 구조만 지키면 돼요.
별도 문법은 없어요. 동봉된 빈 템플릿 한 장을 그대로 채워 가면 30분 안에 첫 버전이 나와요. -
CLI로 검증하고 내보내기.
터미널에서
npx @google/design.md lint로 깨진 토큰 참조와 명도비를 잡아요.
npx @google/design.md export --format tailwind로 Tailwind config을,--format dtcg로 DTCG JSON을 뽑을 수 있어요.
Node.js 18 이상이면 별도 설치 없이 실행돼요.
파일만 두고 CLI 없이 쓰는 것도 가능해요. AI 도구는 마크다운만 있어도 읽어요.
LINTER · WCAG · 8 RULES
린터가 잡아 주는 8가지.
npx @google/design.md lint 한 줄이면 결과가 JSON으로 나와요.
배포 전에 토큰이 깨졌는지, 글씨가 안 보이는지 미리 잡아 줘요.
-
broken-ref · error
토큰 참조가 실제로 정의돼 있지 않을 때 잡아요. 유일한 error 등급이라 빌드 전에 무조건 고쳐야 해요.
-
missing-primary · warning
colors 섹션에 primary 이름이 없으면 경고해요. AI가 보통 primary부터 찾기 때문에 이 이름이 비면 톤이 흔들려요.
-
contrast-ratio · warning
컴포넌트의 배경과 글씨 명도비가 WCAG AA 4.5:1 미만이면 경고해요. 배포 전에 글씨 안 보이는 사고가 미리 잡혀요.
-
orphaned-tokens · warning
정의는 했지만 어떤 컴포넌트도 참조하지 않는 토큰을 짚어 줘요. 쓰지 않는 토큰이 쌓이면 시스템이 점점 흐려져요.
-
missing-typography · warning
colors는 있는데 typography 토큰이 비어 있을 때 알려 줘요. 글씨 룰이 없으면 AI가 폰트 크기를 즉흥적으로 정해요.
-
section-order · warning
8개 섹션 순서가 정규(overview → colors → typography → layout → elevation → shapes → components → do/don't)에서 벗어나면 경고해요.
-
missing-sections · info
spacing이나 rounded 같은 선택 섹션이 비어 있을 때 정보 등급으로 알려 줘요. 큰 프로젝트에선 채우면 일관성이 올라가요.
-
token-summary · info
섹션별 토큰 개수를 요약해 줘요. "color 토큰만 38개 쌓였네"처럼 시스템이 비대해지는 징후를 감지할 수 있어요.
FAQ
자주 묻는 질문.
정말 매 화면이 같은 톤으로 나와요?
DESIGN.md 한 장을 프로젝트 루트에 두고 AI 에이전트에게 "이 파일 참고해서 그려 줘"라고만 시키면 같은 토큰을 들고 그려요. 색 hex, 폰트 크기, 모서리 단계가 토큰으로 박혀 있어서 즉흥성이 줄어요.
설치는 어떻게 해요? 또 지우려면요?
CLI를 쓰려면
npm install @google/design.md 또는 npx @google/design.md ...로 실행해요. 파일만 두고 쓰는 거라면 설치 자체가 필요 없어요. 지울 땐 DESIGN.md 파일만 삭제하면 끝이에요.어떤 AI 도구가 이걸 읽어요?
Google Stitch는 공식적으로 DESIGN.md를 읽어요. Cursor, Claude Code, v0 같은 일반 코딩 에이전트도 마크다운 파일을 그대로 읽기 때문에 프롬프트에 "이 파일 참고"만 붙이면 동작해요.
환경 요건이 어떻게 돼요?
CLI를 쓰려면 Node.js 18 이상이 필요해요. 파일만 두고 AI에게 읽히는 방식이면 런타임 요건이 따로 없어요. 메모장에서도 편집할 수 있어요.
이미 Figma에 디자인 시스템이 있어요. 옮기는 게 가능해요?
가능해요. 이 스킬 안에 "Figma 변수 → DESIGN.md 토큰" 매핑 체크리스트가 들어 있어요. 색·간격·둥근 정도부터 옮기고, 마지막에 컴포넌트 섹션을 채우는 순서를 권장해요.
Tailwind와 같이 쓰려면요?
npx @google/design.md export --format tailwind로 Tailwind config을, --format dtcg로 DTCG JSON을 뽑아요. 어느 쪽이든 DESIGN.md 한 장이 진실의 근원이 돼요.디자이너와 협업할 때는 어떻게 써요?
본문(마크다운)은 디자이너 언어로 적어요. "이 색을 쓰는 이유", "어느 화면에서 어떻게 보이길 원하는지". 토큰(YAML)에는 hex와 단위만 정확히 적어요. 한 파일 안에서 두 언어가 같이 살아요.
한계는 어디까지예요?
모션 속도·이징, 다국어 폰트, 다크 모드 자동 전환은 아직 표준 안에 들어 있지 않아요. 본문에 자유 형식으로 적어 두면 AI가 참고는 해 주지만, 토큰처럼 보장되진 않아요.
이런 분께는 안 맞을 수 있어요.
- 완전히 자유로운 일러스트 위주 화면을 만드는 분. 토큰화가 큰 도움이 안 돼요.
- 한 화면짜리 정적 홍보 페이지만 필요한 분. 8섹션 작성이 좀 과해요.
- 이미 사내 토큰 시스템이 단단하게 박혀 있는 큰 팀. 마이그레이션 비용이 더 클 수 있어요.
DESIGN.md · GOOGLE STITCH SPEC · 한국어 가이드 + 템플릿 + CLI
