이번 주 개발자 커뮤니티에서 DESIGN.md 포맷이 화제다. Google Labs의 Stitch 프로젝트가 제안한 이 포맷은 디자인 시스템을 마크다운 파일 하나로 표현한다. 색상, 타이포그래피, 간격(spacing), 둥근 모서리(radius), 컴포넌트 토큰 같은 값을 YAML frontmatter에 기계가 읽을 수 있는 형태로 두고, 그 아래 마크다운에는 디자인 판단 기준을 적는다. Claude Code, Cursor, Codex 같은 AI 코딩 에이전트가 매번 참고할 "디자인 시스템의 원본 파일"에 가깝다.

YAML(기계용) + 마크다운(사람·AI용) 이중 구조

DESIGN.md는 두 층으로 구성된다. YAML frontmatter에는 토큰 값이 들어간다. 기계가 파싱해서 색상 코드, 폰트 크기, 간격 값을 바로 읽어낸다. 아래 마크다운 본문에는 "왜 이 색을 쓰는지", "이 버튼 스타일은 어떤 상황에서 쓰는지", "어떤 패턴은 피해야 하는지" 같은 디자인 판단 근거를 적는다. 토큰이 정답, 본문은 이유다. 둘이 어긋났을 때 누구를 믿을지 우선순위를 미리 정해둔 점이 핵심이다.

8개 섹션 순서가 고정되어 있다. colors, typography, spacing, components 등 섹션 자체가 디자인 시스템의 mental model 역할을 한다. CLI 도구가 함께 제공된다. lint, diff, export, spec 명령어로 깨진 참조, 대비비 부족, 고아 토큰, 섹션 순서 위반 같은 항목을 자동 검사한다. DTCG(Design Token Community Group), Tailwind, Figma 변수와의 상호운용 정책도 별도로 명시되어 있다.

예전 질문과 지금 질문이 달라졌다

예전에는 "디자인 시스템을 Figma에 어떻게 잘 정리할까"가 질문이었다. 지금은 "AI 코딩 도구가 우리 디자인 시스템을 어떻게 읽게 할까"로 바뀌었다. 새 페이지를 만들 때 AI가 브랜드의 색, 간격, 컴포넌트 규칙을 따라오게 하려면 무엇이 필요한가가 핵심이다. Claude Design, Claude Code, Figma MCP(Figma Model Context Protocol, AI가 Figma 데이터를 읽게 해주는 연결 규약) 같은 흐름과 맞물려 디자인 시스템이 Figma 안에만 머물지 않고 코드베이스로 들어와 PR에서 리뷰되고 AI 에이전트의 "지속적인 컨텍스트"가 되는 변화가 일어나고 있다.

개발자가 바로 체감하는 변화는 디자인 시스템의 위치다. Notion이나 PDF가 아니라 코드베이스 안에 기준을 두려는 실용적 시도다. 디자이너의 산출물이 PR 단위 리뷰 대상이 된다는 의미이기도 하다. AI가 UI를 더 많이 만들수록 디자인 시스템은 오히려 더 중요해진다. 문제는 "AI가 디자인을 잘하느냐"가 아니라 "AI가 따라야 할 기준을 팀이 얼마나 명확하게 남겨두었느냐"로 이동하고 있다.

28챕터 커리큘럼으로 정리된 스펙

한국어로 풀어낸 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 코딩 도구가 디자인 시스템을 읽는 기준점이 DESIGN.md 하나로 통일된다면, UI 일관성 문제는 기술적 과제가 아니라 문서화 과제로 전환된다.