Google Labs가 Stitch 프로젝트에서 제안한 DESIGN.md 포맷이 흥미로워서 며칠 동안 스펙을 뜯어보다가, 혼자 보고 끝내기 아까워서 한국어로 풀어 28챕터짜리 커리큘럼 형태로 정리해 두었습니다. 같은 주제를 공부하시는 분들이 처음부터 영문 스펙을 뒤지지 않아도 되게, 그리고 저처럼 "AI한테 디자인 시스템을 어떻게 읽힐까"라는 질문을 갖고 계신 분들이 한 번에 훑어볼 수 있게 만든다는 느낌으로 작업했습니다.
DESIGN.md는 디자인 시스템을 마크다운 파일 하나로 표현하려는 포맷입니다. 색상·타이포그래피·spacing·radius·component token 같은 값을 YAML frontmatter에 기계가 읽을 수 있는 형태로 두고, 그 아래 마크다운에는 "왜 이 색을 쓰는지", "이 버튼 스타일은 어떤 상황에서 쓰는지", "어떤 패턴은 피해야 하는지" 같은 디자인 판단 기준을 적습니다. 즉, 단순 스타일 가이드가 아니라 Claude Code, Cursor, Codex 같은 AI 코딩 에이전트가 매번 참고할 "디자인 시스템의 원본 파일"에 가깝습니다.
배경 — 정리하면서 다시 짚어본 변화
• 예전 질문: "디자인 시스템을 Figma에 어떻게 잘 정리할까"
• 지금 질문: "AI 코딩 도구가 우리 디자인 시스템을 어떻게 읽게 할까", "새 페이지를 만들 때 AI가 우리 브랜드의 색·간격·컴포넌트 규칙을 따라오게 하려면 무엇이 필요한가"
• Claude Design, Claude Code, Figma MCP 같은 흐름과 맞물려 디자인 시스템이 Figma 안에만 머물지 않고 코드베이스로 들어와 PR에서 리뷰되고 AI 에이전트의 "지속적인 컨텍스트"가 되는 변화
DESIGN.md 포맷의 핵심 (스펙을 읽으면서 인상 깊었던 부분)
• YAML(기계용) + 마크다운(사람·AI용) 이중 구조 — 토큰은 기계가 파싱하고, 본문은 사람이 판단 근거를 남기는 층
• 토큰이 정답, 본문은 이유 — 둘이 어긋났을 때 누구를 믿을지 우선순위를 미리 정해둔 점이 깔끔함
• 8개 섹션 순서가 고정 — colors, typography, spacing, components 등 섹션 자체가 디자인 시스템의 mental model 역할
• lint / diff / export / spec CLI — 깨진 참조, 대비비 부족, 고아 토큰, 섹션 순서 위반 같은 항목을 자동 검사
• DTCG, Tailwind, Figma 변수와의 상호운용 정책을 별도로 명시
커리큘럼 구성 (28챕터, 7개 모듈)
• M1 포맷 철학 · 3챕터 — 이 포맷이 풀려는 문제, 이중 구조, 토큰·본문 우선순위
• M2 토큰 스키마 · 5챕터 — 스키마 전체 / 색 / 길이·단위 / 폰트 / 토큰 참조
• M3 섹션 구조 · 6챕터 — 8개 섹션 순서와 각 섹션의 설계 원칙
• M4 실제 예시 읽기 · 3챕터 — Atmospheric Glass, Paws & Paths, Totality Festival 케이스
• M5 CLI · 4챕터 — lint, diff, export, spec
• M6 린트 규칙 · 4챕터 — broken-ref, contrast, orphaned, section-order 등 8개
• M7 확장성 · 2챕터 — 모르는 내용 처리 정책, DTCG·Tailwind와의 관계
• 최종 정리 · 1챕터 — 27챕터 요약 + 실무에 가져갈 원리 10개
정리하면서 들었던 생각
• AI가 UI를 더 많이 만들수록 디자인 시스템은 오히려 더 중요해질 것 같다는 느낌. 문제는 "AI가 디자인을 잘하느냐"가 아니라 "AI가 따라야 할 기준을 팀이 얼마나 명확하게 남겨두었느냐"로 이동하고 있는 듯
• DESIGN.md는 그 기준을 Notion·PDF가 아닌 코드베이스 안에 두려는 실용적 시도. 디자이너의 산출물이 PR 단위 리뷰 대상이 된다는 의미이기도 함
• 디자인 시스템을 만들고 있거나, AI 코딩 도구로 UI를 만들면서 "왜 결과물이 매번 제각각이지"를 느껴본 분들이 같이 보면 좋을 것 같아서 공유합니다. 잘못 이해하고 정리한 부분이 있으면 댓글로 알려주시면 반영하겠습니다.
궁금한게 있는데 DESIGN.md는 디자인을 뽑아내기 위한 지시사항이라고 보면. 결국 처음 몇페이지.. 또는 한 페이지, 무드 보드를 생성하기 위해 사용되고. 그 이후에는 코드 - 지시.md 간의 불일치가 발생해서 계속 양방향 동기화를 해야 하지 않나요?
결국 이후의 디자인은 코드를 source of truth로 보고 일관성있게 변수나 이름 같은 것들을 재사용해야 하는데. DESIGN.md를 지속적으로 업데이트하며 SSoT로 관리하지 않으면 계속 토큰을 하드코딩하는 게 아닌가 싶은데. 실제 사용에 있어 이런 문제가 없는지 궁금합니다.