AI UI 워크플로우를 위한 design.md vs 디자인 토큰 비교

저는 Dora입니다. 일주일의 대부분을 코딩 에이전트와 AI UI 툴 안에서 보냅니다 — Cursor, Claude Code, Stitch, 흔히 쓰는 도구들 — 문서화할 시간도 없을 만큼 빠르게 인터페이스를 만들고 또 만들면서요. 한 달쯤 전부터 제가 건드리는 거의 모든 레포에서 같은 파일이 보이기 시작했습니다: DESIGN.md. 같은 이름, 같은 YAML-위에-산문-아래 형태. 세 번째 프로젝트에서 이게 우연이 아니라는 걸 깨달았습니다. 대부분의 팀이 tokens.json으로 배포하던 것을 대체하는 파일이었습니다.

그래서 제 컴포넌트 라이브러리 하나를 두 번 재구성했습니다 — 한 번은 클래식한 DTCG 스타일 토큰 파일로, 한 번은 DESIGN.md로 — 그리고 같은 코딩 에이전트를 둘 다에 적용했습니다. 이 비교에서 제가 어디에서도 정리된 글을 찾을 수 없었던 부분이 바로 이겁니다: 각 형식이 무엇인지가 아니라, 각각이 실제로 무엇을 최적화하고 있는지, 그리고 지금 당장 여러분의 스택에 어느 것이 맞는지입니다.

design.md vs 전통적인 디자인 토큰

각 형식이 최적화하는 것

디자인 토큰은, 고전적인 의미에서, 하나의 방법론입니다. 이 용어는 2014년경 Salesforce에서 매우 구체적인 확장 문제를 해결하기 위해 만들어졌습니다: 네 장의 티켓을 제출하지 않고도 웹, iOS, Android, 네 개의 코드베이스 전반에 걸쳐 색상 결정을 동기화하려면 어떻게 해야 할까요? 답은 플랫폼에 구애받지 않는 이름-값 쌍으로, JSON이나 YAML에 저장되어 빌드 시점에 각 플랫폼에 필요한 형식으로 변환됩니다. 그 방법론은 이제 W3C의 Design Tokens Community Group에 의해 성문화되었고, 2025년 말 기준으로 DTCG 형식은 안정적인 v1 스펙을 갖추고 있습니다.

토큰은 결정론적 배포를 위해 최적화되어 있습니다. 16진수 코드가 들어가면, 모든 플랫폼, 모든 빌드에서 영원히 동일한 16진수 코드가 나옵니다. 모호함이 없습니다. 서사도 없습니다 — 토큰 파일은 primary: #1A1C1E라고 알려주지만, 그 색상이 왜 존재하는지, 언제 사용하지 말아야 하는지는 알려주지 않습니다.

DESIGN.md는 2026년 4월 Google Labs가 오픈소스로 공개했으며, 다른 것을 최적화합니다: 코딩 에이전트에게 토큰 파일이 다루지 않는 결정을 내릴 수 있는 충분한 맥락을 제공하는 것입니다. 토큰을 위한 YAML 전문(front matter)과 그 아래 근거를 위한 산문으로 구성된 단일 마크다운 파일입니다. 같은 파일, 두 개의 독자 — 파서를 위한 결정론적 부분과, 레포를 읽는 LLM을 위한 서사 부분.

이것이 실제 구분입니다. “구식 vs 신식”이 아닙니다. “JSON vs Markdown”도 아닙니다. 값 vs 같은 파일 안의 값 더하기 근거입니다.

AI 에이전트가 새로운 요구사항 집합을 만드는 이유

인간이 디자인을 구현할 때, “토큰이 #1A1C1E라고 한다”와 “이 빈 상태에는 특정한 어조가 필요하다” 사이의 간극은 인간이 채웁니다. 그들은 Figma 파일을 봤습니다. 브랜드 워크숍에 참석했습니다. 보조 버튼이 주장적이 아니라 조용하게 느껴져야 한다는 걸 압니다.

코딩 에이전트는 그런 것이 없습니다. 레포에 넣은 것과 파일명에서 추론할 수 있는 것만 있습니다. 그래서 토큰 파일이 완전히 명세하지 않는 화면을 생성하도록 요청할 때 — 엣지 케이스, 새 컴포넌트, 레이아웃 결정 — 에이전트는 추측하거나 훈련 데이터에서 가장 많이 본 것으로 기본값을 설정합니다. 모두가 불평하는 “AI 베이지” 미학의 출처가 바로 이것입니다: 나쁜 모델이 아니라, 그저 부족한 맥락.

DESIGN.md가 해결하는 것이 바로 이것입니다. GitHub의 공식 스펙은 이에 대해 명확합니다 — 토큰은 에이전트에게 정확한 값을 제공하고, 산문은 왜 그 값이 존재하고 어떻게 적용해야 하는지 알려줍니다. 형식은 두 가지 모두를 기대합니다.

design.md가 가치를 더하는 곳

지속적인 서사 맥락

테스트 첫 48시간 안에 알아챈 것: 같은 에이전트에게 같은 작업 지시를 줬을 때, 산문 맥락이 있으면 눈에 띄게 다른 결과물이 나옵니다. “약간 더 나은 색상”이 아닙니다. 다른 레이아웃 선택, 다른 카피 레지스터, 다른 컴포넌트 밀도. 두 번의 실행에서 토큰 값은 동일했습니다 — 변한 것은 에이전트가 “브랜드 보이스는 절제되고 편집적이며; 장식보다 여백을 선호한다”는 문단을 가졌는지 여부였습니다.

이것이 전통적인 토큰 파이프라인이 전달하지 못하는 부분입니다. DTCG JSON 파일은 --color-primary를 정확하게 설명할 수 있지만, 에이전트에게 기본 색상이 드물게 사용되어야 한다는 것은 말할 수 없습니다. DESIGN.md는 그 판단을 누군가 다시 프롬프트에 입력하지 않아도 모든 생성 과정에 지속적으로 전달합니다.

효과가 있습니다.

생성 워크플로우에서 더 나은 멀티스크린 일관성

두 번째 테스트에서 같은 앱의 화면 여덟 개를 이틀에 걸쳐 생성했습니다. 토큰만 있는 맥락으로는 5~8번 화면부터 표류하기 시작했습니다 — 같은 팔레트지만 레이아웃 언어가 느슨해졌습니다. DESIGN.md가 있을 때는 표류가 훨씬 작았습니다. 제로가 아닙니다. 더 작았습니다.

왜 그런지에 대한 제 해석: 산문 섹션이 에이전트가 파일을 읽을 때마다 재앵커 역할을 합니다. 토큰만으로는 에이전트에게 개별 값에서 올바를 충분한 정보를 줍니다. 서사는 토큰이 예상하지 못한 결정들 전반에 걸쳐 일관성을 유지하기에 충분한 정보를 줍니다. 일회성 생성에서는 그 간극이 중요하지 않습니다. 멀티스크린 출력과 지속적인 반복에서는 복리로 쌓입니다.

이것이 또한 DESIGN.md가 더 넓은 에이전트 지시 스택과 잘 어울리는 부분입니다 — 대부분의 설정은 이제 SKILL.md 파일과 함께 AGENTS.md에서 참조하므로, 디자인 시스템이 에이전트의 지속적인 지시의 나머지 부분과 같은 컨텍스트 레이어에 위치합니다.

전통적인 토큰이 여전히 이기는 곳

두 가지 시나리오, 둘 다 실제입니다.

웹을 넘어선 크로스플랫폼 배포. iOS, Android, React Native 앱, 마케팅 사이트에 동일한 디자인 시스템을 배포하고 있다면, Style Dictionary나 Terrazzo를 통한 DTCG 파이프라인이 여전히 최소 저항 경로입니다. DESIGN.md의 YAML은 공식 @google/design.md CLI를 통해 DTCG JSON으로 내보낼 수 있지만, 진실의 원천 문제는 여전히 중요합니다 — 토큰 그래프가 크고, 다중 테마이며, 비AI 툴링이 소비한다면, DTCG를 정규 형식으로 유지하는 것이 더 깔끔한 설정입니다.

확립된 거버넌스를 가진 성숙한 디자인 시스템. 토큰은 단순한 파일 형식이 아닙니다. 약 10년의 축적된 실천을 가진 방법론입니다 — 프리미티브 레이어, 시맨틱 레이어, 앨리어싱, 테마, Nathan Curtis가 Tokens in Design Systems에서 제시한 전체 분류 체계. 팀이 이미 그렇게 운영하고 있다면, DESIGN.md가 그것을 대체하지 않습니다. 에이전트를 위한 컨텍스트 레이어로서 그 위에 또는 옆에 위치합니다. 토큰은 정규 소스로 유지되고, 마크다운은 AI 직면 번역본이 됩니다.

실수는 DESIGN.md를 토큰 파이프라인의 대체제로 읽는 것입니다. 그렇지 않습니다. 다른 소비자를 가진 다른 레이어입니다.

AI UI 파이프라인을 구축하는 팀을 위한 의사결정 프레임워크

레포에 무엇을 넣을지 결정할 때 저는 네 가지 질문으로 계속 돌아옵니다:

1. 이 파일을 누가 읽습니까? 주요 소비자가 CSS, Swift, Kotlin을 출력하는 빌드 파이프라인이라면, 정규 형식의 토큰이 필요합니다. 주요 소비자가 수요에 따라 UI를 생성하는 코딩 에이전트라면, DESIGN.md가 필요합니다. 둘 다라면, 둘 다 유지합니다 — 마크다운 파일의 YAML이 토큰의 하위 집합을 미러링하도록 합니다.
2. UI 서피스가 얼마나 자주 재생성됩니까? 저빈도 팀(안정적인 제품, 가끔 새 화면)은 대부분의 가치를 토큰에서 얻습니다. 고빈도 팀(빠른 프로토타이핑, 에이전트 기반 반복, 매주 새 화면)은 맥락 누락 간극을 예리하게 느낍니다. 재생성 빈도가 높을수록, 산문 레이어가 그 가치를 더 잘 발휘합니다.
3. 플랫폼이 몇 개입니까? 에이전트 기반 생성으로 웹 전용 또는 웹 중심이라면 — DESIGN.md가 더 단순한 스택입니다. 심각한 네이티브 존재감을 가진 세 개 이상의 플랫폼이라면 — 토큰 우선으로, DESIGN.md는 다운스트림 아티팩트로.
4. 근거가 이미 어딘가에 문서화되어 있습니까? 브랜드 가이드라인, 보이스 문서, 컴포넌트 철학이 에이전트가 절대 읽지 않을 Notion 페이지에 있다면, DESIGN.md가 이번 분기에 할 수 있는 단일 최고 레버리지 이동입니다. 새 문서를 만드는 것이 아닙니다 — 기존 문서를 에이전트가 실제로 여는 파일로 옮기는 것입니다.

이것이 제 프레임워크입니다. 여러분의 것은 다를 수 있습니다. 제가 강조하고 싶은 것: 새롭다는 이유로 형식을 선택하지 마세요. 파일을 읽는 사람이 누구인지를 기준으로 선택하세요.

FAQ

design.md는 디자인 토큰의 대체제입니까?

아닙니다. DESIGN.md는 디자인 토큰(YAML 전문 안에)과 그 주변의 근거(마크다운 산문 안에)를 담은 래퍼입니다. 그 안의 토큰은 여전히 관습적인 의미의 디자인 토큰입니다. 이미 DTCG 형식 토큰 파일이 있다면, DESIGN.md가 그것을 대체하지 않습니다 — AI 에이전트를 위한 병렬 아티팩트로 위치하거나, 필요할 때 마크다운이 DTCG JSON을 내보낼 수 있습니다.

AI 에이전트는 왜 숫자 토큰 이상이 필요합니까?

대부분의 UI 생성 요청이 토큰 그래프로 완전히 명세되지 않기 때문입니다. “가격 페이지 생성”은 어떤 토큰 파일도 다루지 않는 수백 개의 마이크로 결정을 요구합니다 — 위계, 밀도, 어조, 무엇을 강조할지. 서사 맥락 없이는 에이전트가 훈련 데이터에서 본 것으로 그 간극을 채우고, 그 결과 대부분의 AI 생성 UI가 공유하는 일반적인 외형이 나옵니다. DESIGN.md의 산문이 그 간극을 닫는 것입니다.

어떤 워크플로우가 design.md에서 가장 많은 혜택을 받습니까?

제가 가장 효과를 본 세 가지 패턴:

• Cursor, Claude Code, 또는 Stitch를 사용해 직접 손으로 작성하는 것보다 빠르게 UI를 배포하는 솔로 빌더와 소규모 팀.
• AI 생성 화면 간의 일관성이 실제 문제가 되고 있는 여러 내부 제품을 유지 관리하는 디자인 시스템 팀.
• 모든 코딩 에이전트를 위해 클라이언트의 디자인 언어를 인코딩하는 단일 드롭인 파일을 원하는 에이전시와 계약 팀.

워크플로우가 주로 가끔 AI 지원을 받는 수동 코딩이라면, 한계 가치가 떨어집니다.

언제 클래식 디자인 토큰 인프라로 충분합니까?

에이전트로 UI를 생성하지 않거나, 플랫폼 범위가 웹을 훨씬 넘어설 때입니다. 네이티브 모바일 중심, 다중 테마 화이트 라벨 제품, 성숙한 디자인 옵스 실천 — 이것들은 여전히 마크다운 파일보다 DTCG 생태계에서 더 많은 것을 얻습니다. 둘은 상호 배타적이지 않지만, 하나에만 투자해야 한다면, 답은 실제 생성 마찰이 어디에 있는지에 달려 있습니다.

결론

솔직한 버전: DESIGN.md는 패러다임 전환이 아닙니다. 특정 간극에 대한 집중적인 해결책입니다 — 토큰 파일이 전달하지 않는 근거가 부족한 코딩 에이전트. 그 간극이 실재하는 워크플로우에서는 이득이 즉각적이고 명확합니다. 그렇지 않은 워크플로우에서는 전통적인 토큰이 여전히 역할을 합니다.

저는 운영하는 모든 AI 생성 프로젝트에 DESIGN.md를 사용한 지 두 달이 됐습니다. 워크플로우에 남아 있는데, 그것이 제가 신뢰하는 유일한 테스트입니다. 토큰 파일도 어디 가지 않았습니다 — 항상 해오던 일을 여전히 하고 있고, 이제 더 많은 것이 필요한 독자를 위한 형제 파일이 생겼을 뿐입니다.

직접 프로젝트에서 실행해 보세요. 이틀이면 이 글보다 더 많은 것을 알려줄 것입니다.

이전 게시물:

• GitHub Copilot vs 프라이빗 코딩 어시스턴트
• Claude Code vs Cursor 2026
• 프로덕션에서의 MCP: Model Context Protocol 워크플로우
• 에이전트 워크플로우 도구 연결 패턴 및 함정
• Claude Code 에이전트 하네스 아키텍처