🔥 DESIGN.md와 design-md-chrome: AI에게 디자인 시스템을 먹이는 법
강의 목차
어젯밤에 Claude Code에게 "이 사이트랑 비슷한 톤으로 랜딩페이지 만들어줘" 라고 시켰다가, 같은 프롬프트로 돌릴 때마다 결과물이 완전히 다른 걸 보고 한숨이 나왔다. 색은 비슷한데 여백이 제각각이고, 폰트 스케일은 매번 새로 발명하고, 버튼 라운드 값은 4px·8px·12px을 이리저리 섞어 쓴다. 내가 원하는 건 "일관성"인데, AI가 주는 건 "매번 새로운 디자인"이다.
그러다가 bergside/design-md-chrome 이라는 크롬 확장을 발견했다. 한 줄로 요약하면 웹페이지를 열고 버튼 한 번 누르면, 그 사이트의 디자인 시스템을 마크다운 문서로 추출해서 AI에게 먹일 수 있게 만들어 주는 도구다.
근데 확장 자체보다 더 흥미로운 건 그 뒤에 깔린 DESIGN.md 라는 포맷이었다. "왜 2026년에 굳이 마크다운으로 디자인 시스템을 쓰자는 거지?" 라는 질문에서 시작한 추적이 글 하나 분량으로 쌓여서, 일단 정리해 둔다.
AI가 UI를 매번 다르게 그리는 이유
솔직히 Claude Code나 Cursor, Codex 같은 AI 코딩 도구를 써본 사람이면 다 공감할 거다. 로직은 잘 짠다. 근데 UI를 맡기면 매번 뭔가 어색하다. 브랜드 컬러를 찍어 줘도 다음 컴포넌트에서는 슬쩍 다른 값으로 흐려지고, 간격 변수도 필요할 때마다 새로 만들어 쓴다.
Zoltán Szőgyényi의 Medium 글에서 이 현상을 깔끔하게 정리한 문장이 있다.
AI models are incredible at writing logic, but without strict constraints, they tend to hallucinate design tokens.
번역하면 "AI는 로직은 끝내주게 쓰는데, 엄격한 제약이 없으면 디자인 토큰을 환각한다" 정도. 내가 겪은 증상이 딱 그거였다. "primary-500을 써줘" 라고 말은 알아듣는데, 세 컴포넌트 뒤에서는 #3b7aea 같은 이상한 값이 튀어나와 있다.
해결책으로 제일 먼저 떠오르는 건 디자인 토큰이다. W3C Design Tokens Community Group이 2025년 10월 28일에 첫 안정 버전(2025.10)을 발표했고, Style Dictionary나 Tokens Studio 같은 도구가 Figma → JSON → CSS 변환 파이프라인을 공식적으로 지원한다. Figma, Sketch, Framer, Penpot 등 10개 이상의 도구가 이 스펙을 지원하거나 구현 중이다.
근데 토큰 JSON을 AI에게 그대로 던져도 문제는 별로 안 풀린다. 왜냐면 토큰은 값만 알려주고 언제 쓰는지는 안 알려주기 때문이다.
DESIGN.md 가 뭔가
TypeUI가 제안한 DESIGN.md 는 이 공백을 메우는 마크다운 포맷이다. Bergside LLC가 공개한 포맷이고, TypeUI CLI 자체는 MIT 오픈소스다. 한 줄 정의로는 "AI 코딩 에이전트를 위한 디자인 시스템 블루프린트".
밑에 깔린 철학이 두 가지 있는데, 둘 다 공식 문서에서 가져온 문장이다.
LLM models have gotten so good based on general training data that they only need a little bit of a nudge in the right direction.
The key is to FULLY delegate the creation of design and code to AI, but with the right instructions.
요지는 이거다. LLM은 이미 디자인의 문법을 안다. Figma에서 메가바이트짜리 JSON을 뽑아서 "자, 이제 우리 규칙을 배워" 라고 할 필요가 없다. 잘 압축된 사람 언어로 "이 버튼은 이럴 때 쓴다" 수준의 넛지만 주면, 나머지는 모델이 알아서 한다는 가정.
designproject.io 블로그가 이 차이를 한 문장으로 찔렀다.
Tokens tell an agent what values exist; a design.md tells it when to use them and when not to.
"토큰은 어떤 값이 있는지 를 알려주고, design.md는 언제 그걸 써야 하고 언제 쓰면 안 되는지 를 알려준다."
이게 내가 처음 토큰 파일만 던져서는 해결 안 됐던 이유였다. 값은 있는데 정책이 없으니까, AI가 알아서 정책을 만들어 쓰면서 매번 달라진 거다.
DESIGN.md 가 담는 섹션
TypeUI 공식 문서의 anatomy와 design-md-chrome README에 기술된 생성 구조를 나란히 보면, 실제 파일은 YAML 프론트매터(name, description 같은 메타데이터)에 이어 본문에 11개 섹션이 이어진다.
- Mission — 이 디자인 시스템이 뭘 하려는 건가
- Brand — 제품 정체성, URL, 타깃 오디언스, 서페이스
- Style Foundations — 타이포, 컬러, 간격, 라디우스 같은 시각 토큰
- Accessibility — WCAG 2.2 AA, 키보드/포커스 규칙
- Writing Tone — 문구 톤 가이드
- Rules: Do — "반드시 해라" 수준의 요구사항
- Rules: Don't — "절대 하지 마라" 금지 목록
- Guideline Authoring Workflow — 가이드라인 작성 워크플로
- Required Output Structure — 출력 구조 규격
- Component Rule Expectations — 컴포넌트별 상호작용/상태 규칙
- Quality Gates — 검증 가능한 품질 체크포인트
이 중에서 제일 실용적으로 보이는 건 Rules: Don't 다. designproject.io 팀이 여러 AI 도구로 테스트해 본 결과, don'ts 섹션이 "정확도에 가장 크게 기여하는 단일 요인" 이었다고 한다. 나쁜 생성률이 절반 이하로 떨어졌다는 주장.
예시를 구체적으로 보면 이런 식이다.
## Style Foundations
- primary.900 — 화면당 최고 강조 액션 한 개에만. 한 뷰에 두 개 금지.
- display/xl — 페이지 타이틀 전용
- body/md — 기본 본문
## Rules: Don't
- 카드에 드롭 섀도우 금지
- CTA 버튼 두 개 이상 수직 스택 금지
- body 폰트 크기에 줄간격 1.2 이하 금지## Style Foundations
- primary.900 — 화면당 최고 강조 액션 한 개에만. 한 뷰에 두 개 금지.
- display/xl — 페이지 타이틀 전용
- body/md — 기본 본문
## Rules: Don't
- 카드에 드롭 섀도우 금지
- CTA 버튼 두 개 이상 수직 스택 금지
- body 폰트 크기에 줄간격 1.2 이하 금지이런 식으로 토큰이 아니라 정책을 기술한다. JSON 스키마로는 표현하기 번거로운 "언제 쓰고 언제 안 쓰는가" 의 맥락이, 마크다운에서는 사람이 읽기도 AI가 읽기도 자연스럽다.
Chrome 확장 design-md-chrome 가 하는 일
DESIGN.md가 좋긴 한데, 막상 쓰려면 문제가 하나 있다. 누가 이걸 다 써주느냐. 11개 섹션을 내 제품에 맞춰 처음부터 작성하는 건 짧지 않은 작업이다.
bergside/design-md-chrome 크롬 확장이 해결하려는 게 바로 이 부분이다. 지금 보고 있는 아무 웹페이지에서 DESIGN.md 초안을 자동으로 뽑아 준다.
확장 툴바에서 쓸 수 있는 액션은 여섯 가지다.
| 액션 | 설명 |
|---|---|
| Auto-extract | 현재 페이지의 CSS 스타일을 훑어서 토큰을 추론 |
| Generate DESIGN.md | 추출한 스타일로 11개 섹션을 채운 마크다운 생성 |
| Generate SKILL.md | AI 에이전트가 바로 스킬로 로드할 수 있는 포맷 |
| Refresh | 페이지가 바뀐 뒤 재추출 |
| Download | 로컬로 저장 |
| Explain (?) | 각 필드가 왜 그런지 설명을 덧붙임 |
내 시나리오로 번역하면 이렇다. 레퍼런스로 삼고 싶은 사이트를 크롬에서 연다. 확장을 누른다. DESIGN.md 가 떨어진다. 그걸 내 프로젝트 루트에 넣고 Claude Code에게 "이 가이드 따라서 대시보드 만들어줘" 라고 시키면, 이론적으로는 그 사이트 톤을 유지한 결과물이 나와야 한다.
처음 열었을 때 인상은 "이게 Figma로 가는 수 주짜리 작업을 버튼 한 번으로 우회하려는 거구나" 였다. 결과물이 완벽할 리는 없다. 실제 디자인 시스템은 CSS만 읽어서 복원되는 게 아니라 "왜 그 값인가" 의 의도가 섞여 있으니까. 근데 빈 페이지에서 시작하지 않는다 는 것만으로 체감 속도는 달라진다.
DESIGN.md vs SKILL.md
확장이 두 개의 출력을 만든다는 점이 처음엔 헷갈렸다. 둘 다 같은 추출 과정에서 나오는데, 타깃이 다르다.
- DESIGN.md: 사람과 문서화 시스템용. 포괄적인 디자인 시스템 레퍼런스. 팀 위키에 올리거나 디자이너·개발자가 읽으면서 이해하는 문서.
- SKILL.md: AI 에이전트용. Claude Code 스킬 이나 Cursor 규칙처럼 에이전트가 로드해서 곧바로 실행 기준으로 삼는 포맷.
같은 뿌리에서 갈라진 두 출력이라는 건 중요한 설계 결정이다. 사람이 읽는 문서와 AI가 실행 기준으로 삼는 문서가 분리돼 있어야, 어느 한쪽에만 맞추는 타협을 안 해도 된다. 한 파일에 다 넣으면 결국 사람도 불편하고 AI도 정확도가 떨어지는 함수가 되기 쉽다.
TypeUI가 말하는 "Design Layer for AI agentic tooling" 의 의미가 여기서 드러난다. 레이어라는 단어가 딱이다. 기존 디자인 도구(Figma, Sketch)와 AI 에이전트(Claude Code, Cursor, Codex) 사이에 번역층을 하나 끼워서, 디자이너의 의도를 AI가 읽는 표준으로 통역하겠다는 포지션.
어디서 돌아가나: 생태계
TypeUI CLI 기준으로 지원하는 에이전트는 꽤 넓다. Claude Code, Cursor, Codex, OpenCode, Gemini CLI 등 주요 CLI 계열은 다 커버한다. 레지스트리에는 57개의 무료 디자인 스킬이 미리 올라와 있고, "Paper", "Bento", "Neobrutalism" 같은 스타일을 typeui pull paper 식으로 바로 가져올 수 있다.
라이선스는 커뮤니티 에디션이 MIT 오픈소스로 무료, Single License가 3년 $200, Team License가 3년 $1,500이다. 크롬 확장 쪽도 MIT라서 추출 도구만 쓰고 싶으면 그대로 써도 된다.
참고로 Bergside는 Flowbite 를 만든 팀과 같은 곳이다. Flowbite가 2022년부터 2026년 사이에 3천만 개 이상의 프로젝트에 영향을 줬다고 TypeUI 측은 주장한다(자체 집계 수치라 독립 검증은 안 됐다). 그 팀이 이번엔 "디자인 시스템을 AI가 읽을 수 있게 표준화하자" 는 다음 베팅을 하고 있는 셈이다.
기존 디자인 토큰 표준과 뭐가 다른가
솔직히 처음엔 "이거 W3C 디자인 토큰 스펙과 뭐가 다르지?" 싶었다. 두 접근을 나란히 놓고 보면 이렇다.
- W3C Design Tokens (DTCG): JSON 기반. 값과 타입을 정확히 기술. Figma → Style Dictionary → CSS 변환 파이프라인에 최적. 기계 친화적.
- DESIGN.md: 마크다운 기반. 값도 담지만 정책·의도·제약에 방점. LLM이 읽을 때 맥락 손실이 적음. 사람 친화적이면서도 AI 친화적.
둘이 대립 관계는 아닌 것 같다. 오히려 DTCG 토큰을 소스 오브 트루스로 두고, DESIGN.md 에서 그 토큰을 언제/왜 쓰는지 설명하는 조합이 자연스럽다. 토큰은 라이브러리, DESIGN.md는 코딩 컨벤션 문서 같은 역할.
한 가지 걸리는 건 스펙의 권위다. DTCG는 W3C 커뮤니티 그룹이 수년에 걸쳐 합의한 결과고, 10개 이상의 벤더가 구현 중이다. DESIGN.md는 아직 한 회사(Bergside)의 제안이고, 커뮤니티 채택은 이제 시작이다. 표준이 될지, 먼저 나온 "좋은 관행" 으로 남을지는 더 지켜봐야 한다.
한계와 솔직한 평가
좋은 점
- DESIGN.md 포맷 자체가 깔끔하다. 11개 섹션의 구성이 실제 디자인 시스템을 문서화할 때 놓치기 쉬운 부분(Rules: Don't, Quality Gates)을 강제로 짚게 해 준다.
- 크롬 확장이 MIT라서 진입 장벽이 거의 없다. 설치하고 눌러 보는 데 3분.
- AI 에이전트 생태계와의 궁합이 좋다. 이미 Claude Code·Cursor·Codex에 스킬을 주입하는 표준 방법이 있으니, DESIGN.md를 그 흐름에 태우기가 어렵지 않다.
걸리는 점
- CSS만 읽어서 디자인 의도 를 복원하는 건 본질적으로 한계가 있다. 추출된 초안은 템플릿으로 쓰고, 손으로 다듬는 단계가 반드시 필요해 보인다.
- 스펙이 한 회사 주도라서, 나중에 DTCG처럼 표준화된 대안이 나오면 마이그레이션 부담이 있을 수 있다.
- "랜딩페이지 자동 생성" 같은 데모는 눈에 띄게 잘 돌아가는데, 복잡한 애플리케이션 UI(데이터 테이블, 멀티스텝 폼, 대시보드 편집기)에서도 같은 품질이 나올지는 아직 모르겠다.
내가 다음에 뭘 해 볼 건가
일단 이번 주말에 세 가지를 테스트해 볼 생각이다.
첫째, 내가 운영하는 codingmax.com에 확장을 돌려서, 그동안 암묵적으로 써 온 디자인 규칙이 DESIGN.md 에 얼마나 포착되는지 본다. 이건 역공학 용도.
둘째, 그 DESIGN.md를 Claude Code에 넣고 "같은 톤으로 새 페이지 만들어줘" 시켜 보면서, 일관성이 실제로 유지되는지 확인한다. Rules: Don't 섹션을 얼마나 지키는지가 관전 포인트.
셋째, 내가 만지고 싶은 레퍼런스 사이트 몇 개를 뽑아서 DESIGN.md를 모은다. 라이브러리처럼 쌓아 두고, 사이드 프로젝트마다 어떤 톤으로 갈지 고를 때 카드처럼 뽑아 쓰는 워크플로를 만들어 볼 생각이다.
AI가 UI를 "매번 다르게" 그리는 문제는 당분간 사라지지 않을 것 같다. 그래도 이 문제를 공식 디자인 도구의 책임이 아니라 AI에게 주는 프롬프트 층위로 끌어올린 건 영리한 접근이다. 디자인 토큰이 값의 표준을 해결했다면, DESIGN.md는 정책의 표준을 노리고 있다. 둘 다 자리를 잡으면, 드디어 AI에게 UI를 맡겨도 매번 결과가 요동치지 않는 세상이 오지 않을까 싶다.
솔직히 아직 확신은 없다. 그래도 이번 주말 실험 결과는 다시 글로 남길 예정이다.
참고 자료
- bergside/design-md-chrome (GitHub) — Chrome 확장 리포지토리, MIT 오픈소스
- TypeUI 공식 사이트 — "Design Layer for AI agentic tooling" 포지셔닝과 CLI 다운로드
- The anatomy of DESIGN.md | TypeUI — DESIGN.md 포맷 공식 명세 (anatomy, 철학 인용 출처)
- design.md file: how to write a design system AI agents actually follow | TDP — DTCG 토큰 대비 DESIGN.md의 차이를 정리한 글
- Taming AI-Generated UIs: Meet typeui.sh | Medium — "hallucinate design tokens" 인용 출처
- Design Tokens Community Group | W3C — DTCG 표준 그룹 공식 페이지
- Design Tokens 2025.10 stable 발표 — 2025년 10월 28일 W3C 공식 공지
YouTube 영상
