# DESIGN.md — AI 코딩 도구를 위한 디자인 시스템 단일 파일 포맷 (한국어 정리)

> Clean Markdown view of GeekNews topic #28861. Use the original source for factual precision when an external source URL is present.

## Metadata

- GeekNews HTML: [https://news.hada.io/topic?id=28861](https://news.hada.io/topic?id=28861)
- GeekNews Markdown: [https://news.hada.io/topic/28861.md](https://news.hada.io/topic/28861.md)
- Type: news
- Author: [neostom432](https://news.hada.io/@neostom432)
- Published: 2026-04-25T09:22:09+09:00
- Updated: 2026-04-25T09:22:09+09:00
- Original source: [rubric.im](https://rubric.im/curriculum/design-md)
- Points: 8
- Comments: 2

## Topic Body

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를 만들면서 "왜 결과물이 매번 제각각이지"를 느껴본 분들이 같이 보면 좋을 것 같아서 공유합니다. 잘못 이해하고 정리한 부분이 있으면 댓글로 알려주시면 반영하겠습니다.

## Comments



### Comment 56270

- Author: m00nlygreat
- Created: 2026-04-25T10:40:57+09:00
- Points: 1

궁금한게 있는데 DESIGN.md는 디자인을 뽑아내기 위한 지시사항이라고 보면. 결국 처음 몇페이지.. 또는 한 페이지, 무드 보드를 생성하기 위해 사용되고. 그 이후에는 코드 - 지시.md 간의 불일치가 발생해서 계속 양방향 동기화를 해야 하지 않나요?  
  
결국 이후의 디자인은 코드를 source of truth로 보고 일관성있게 변수나 이름 같은 것들을 재사용해야 하는데. DESIGN.md를 지속적으로 업데이트하며 SSoT로 관리하지 않으면 계속 토큰을 하드코딩하는 게 아닌가 싶은데. 실제 사용에 있어 이런 문제가 없는지 궁금합니다.

### Comment 56276

- Author: neostom432
- Created: 2026-04-25T11:52:12+09:00
- Points: 1
- Parent comment: 56270
- Depth: 1

DESIGN.md => 코드 방향은 자동화하기 쉬운데, 반대로 코드에 새로 생긴 패턴이 DESIGN.md로 올라오는 건 자동이 안 돼서 사람이 직접 챙겨야 하더라구요. 시간이 지나면 코드엔 자잘한 하드코딩이 쌓이는데 문서엔 안 올라가는 일이 누적되구요.  
  
다만 이 포맷의 철학 자체가 "디자인 시스템을 코드베이스 안에서 계속 가꾸어 나간다"는 쪽이라, 이게 단점이라기보다는 의도된 운영 방식에 가깝다고 봅니다. Notion이나 PDF에 박제해두던 가이드를 PR 단위 리뷰 대상으로 끌어내린 만큼, 사람이 주기적으로 손보는 책임도 같이 따라오는 구조인 것 같아요. 저희 프로젝트에 도입해 봤는데 도입 전보다 화면 일관성이 확실히 올라갔고, 그 효용이 체감되니 수동 리뷰가 부담으로 느껴지지 않더라구요. 결국 AI가 따라야 할 기준을 팀이 얼마나 명확하게 남겨두는가의 문제이고, 그 기준을 살아있게 유지하는 손길까지는 사람이 가져가는 구조라고 정리하게 됐습니다.