코딩 에이전트를 위한 design.md란 무엇인가?

저는 Dora입니다. 지난주에 Claude Code에게 사이드 프로젝트에 새 화면 세 개를 추가해 달라고 요청했습니다. 두 번째 화면쯤 되자 버튼 둥글기가 달라져 있었고, 헤드라인 폰트가 슬그머니 바뀌어 있었으며, “secondary” 회색이 다른 회색이 되어 있었습니다. 프롬프트 구조는 같았습니다. 모델도 같았고. 세션도 같았습니다. 결과물이 그냥 이전에 결정한 것들을 신경 쓰지 않게 된 것입니다.

이 마찰이 바로 코딩 에이전트를 위한 design.md가 제거하려는 것입니다. AI 에이전트가 UI를 생성할 때마다 읽을 수 있는 형태로 디자인 시스템을 담아두는 평범한 마크다운 파일입니다 — 일회성 프롬프트가 아니라 지속적인 컨텍스트로요. Stitch가 읽습니다. Claude Code가 읽습니다. Cursor가 읽습니다. 저장소 루트의 컨텍스트 파일을 읽는 다른 모든 것도 마찬가지입니다.

design.md란 무엇이며 Google Labs가 왜 공개했는가

파일 형식과 디자인 시스템 역할

DESIGN.md 파일은 두 개의 레이어가 하나의 문서에 쌓인 구조입니다. 상단은 YAML 전문(front matter)으로 — 색상, 타이포그래피, 간격, 둥근 모서리, 컴포넌트 — 구조화된 토큰으로 작성됩니다. 그 아래에는 토큰이 무엇을 위한 것이며 어떻게 사용하는지 설명하는 마크다운 산문이 이어집니다. 토큰은 에이전트에게 정확한 값을 제공합니다. 산문은 그 값이 왜 존재하는지를 알려줍니다.

GitHub의 공식 DESIGN.md 사양에서 가져온 전문의 대략적인 모습은 다음과 같습니다:

yaml

---
version: alpha
name: Heritage
colors:
  primary: "#1A1C1E"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 48px
    fontWeight: 600
    lineHeight: 1.1
rounded:
  sm: 4px
spacing:
  sm: 8px
  md: 16px
---

그 아래에는 ## Overview, ## Colors, ## Typography가 일반 마크다운으로 이어집니다. 섹션 순서는 고정되어 있습니다 — Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do’s and Don’ts. 섹션은 건너뛸 수 있지만, 포함된 섹션은 해당 순서대로 나타나야 합니다. 섹션 제목 중복은 오류로 파일을 거부합니다.

토큰 참조 구문은 W3C Design Tokens Format Module에서 가져온 것으로 — {colors.primary}와 같이 중괄호 경로를 사용합니다. 참조는 프리미티브 값(그룹 아님)을 가리켜야 하며, 타이포그래피 토큰에 대한 복합 참조가 허용되는 components 섹션 내부는 예외입니다. 현재 사양에서 색상 값은 SRGB 헥스만 가능합니다. W3C DTCG 2025.10 안정 사양이 지원하는 Display P3와 Oklch는 DESIGN.md에서 아직 지원되지 않으며, 저장소는 이를 version: alpha 마커로 공개적으로 표시합니다. 와이드 게이먿 토큰을 관리하는 분이라면 알아두면 좋습니다.

이 형식은 CLI와 함께 제공됩니다 — npm의 @google/design.md입니다. npx @google/design.md lint는 파싱된 파일에 대해 일곱 가지 규칙을 실행합니다. 제가 가장 자주 접하는 두 가지: broken-ref(오류 심각도)는 해석되지 않는 토큰 참조를 잡아내고, contrast-ratio(경고)는 컴포넌트의 backgroundColor/textColor 쌍을 WCAG AA의 4.5:1 최소값과 대조합니다. 나머지 세 가지 — missing-primary, orphaned-tokens, 그리고 구조적 규칙들 — 은 대부분의 팀이 파일 편집 후 일주일 안에 도입하는 문제들을 드러냅니다. CLI에는 diff(버전 간 토큰 수준 회귀 탐지)와 export(Tailwind v3 config, Tailwind v4 @theme CSS, 또는 W3C DTCG JSON)도 있습니다.

코딩 에이전트에게 지속적인 시각적 컨텍스트가 중요한 이유

문제는 단순합니다. UI를 생성하는 에이전트는 읽을 수 있는 구조화된 것을 제공하지 않으면 디자인 시스템에 대한 기억이 없습니다. 팔레트를 프롬프트에 설명하고, 버튼을 받고, 카드를 요청하면 간격 논리가 초기화되는 것을 볼 수 있습니다. 모델이 코드 작성을 못하는 게 아닙니다. 닻이 없는 것입니다.

design.md가 그 닻입니다. Stitch는 모든 생성 요청에서 이것을 컨텍스트로 전달합니다. Claude Code와 Cursor는 에이전트가 답하기 전에 읽는 저장소 루트의 파일인 CLAUDE.md나 AGENTS.md와 같은 방식으로 이것을 읽습니다. 오픈소스 발표에서 Google의 표현은 이것이 에이전트로 하여금 프롬프트에서 의도를 추측하는 것이 아니라 “색상이 정확히 무엇을 위한 것인지 알 수 있게” 해준다는 것입니다.

저는 두 프로젝트 모두에서 이것을 테스트했습니다. 절차: 루트에 DESIGN.md를 놓고, 이전에 드리프트가 발생했던 동일한 다섯 화면(랜딩, 가격, 회원가입, 대시보드, 설정)을 재생성한 다음, 전문에 대한 토큰 위반을 세었습니다. 파일이 있을 때 Claude Code는 정확한 primary 및 tertiary 헥스 값과 선언된 rounded.sm을 사용하여 5/5 화면을 생성했습니다. Cursor는 4/5를 생성했습니다 — 대시보드가 카드에서 rounded.sm(4px)을 rounded.md(8px)로 계속 재정의했는데, DESIGN.md 산문이 이를 명시적으로 금지하지 않았기 때문입니다. “Do’s and Don’ts” 줄 — “카드 모서리는 rounded.sm을 사용하고, 절대 rounded.md를 사용하지 않음” — 을 추가하자 다음 재생성에서 수정되었습니다.

AI UI 생성에서 실제로 해결하는 문제

화면과 반복 간 일관성

이전 세션에서 깨진 것은 한 화면의 품질이 아니었습니다. 각각의 개별 화면은 괜찮아 보였습니다. 두 번째 화면은 첫 번째 화면이 결정한 것을 알지 못했습니다. 모든 생성은 “당신의 브랜드”에 대한 약간씩 다른 해석에서 시작되었습니다.

이것이 design.md가 타겟으로 하는 실패 모드입니다. “UI를 더 예쁘게 만들기”가 아니라 — 생성 전반에 걸쳐 동일한 UI로 만들기입니다. 토큰은 규범적입니다. 전문이 tertiary: "#B8422E"라고 말하면, 에이전트는 이것을 “따뜻한 오렌지색”으로 해석할 여지가 없습니다. 그 헥스 값이거나 틀린 것이고, lint가 그렇게 말할 것입니다.

주 1회 5개, 10개, 20개의 화면을 생성하는 고빈도 워크플로우에서 — 이것은 첫 번째 출력 품질보다 더 중요합니다. 규모에서 화면당 하나의 불일치는 정리 작업이 됩니다. 파일에 한 번 정의된 코딩 에이전트 디자인 토큰은 시작되기 전에 그 정리 작업을 없애버립니다.

산문과 토큰의 조합이 토큰만보다 강한 이유

저는 이 부분을 거의 무시할 뻔했습니다. 헥스 값이 이미 YAML에 있는데 “Boston Clay는 상호작용의 유일한 동인”이라는 단락을 왜 쓰나요?

에이전트가 토큰이 다루지 않는 판단을 내리는 데 산문을 사용하기 때문입니다. 토큰은 tertiary가 #B8422E라고 말합니다. 산문은 그 색상이 상호작용에만 사용된다고 말합니다 — 장식적인 악센트나 헤드라인에는 아닙니다. 프롬프트가 모호할 때(“알림 배지 추가”), 산문이 배지가 상호작용 색상을 받을지 중립색을 받을지 결정합니다. 위의 Cursor 실행에서 누락된 산문 제약이 대시보드가 드리프트한 정확한 이유였습니다.

같은 논리가 Do’s and Don’ts에도 적용됩니다 — “카드에 드롭 섀도우를 사용하지 말 것” 또는 “버튼 레이블에는 항상 문장 대소문자를 사용할 것”과 같은 명시적 가드레일. 부정적 제약은 순수한 토큰이 표현할 수 없는 무게를 갖습니다. 이것은 CSS 파일이 아니라 에이전트를 위한 디자인 사양입니다.

이 형식은 Stitch에 국한되지 않습니다. 사양은 Apache 2.0이고, CLI는 npm에 있으며, DTCG 내보내기는 W3C 표준을 읽는 모든 도구로 토큰이 흐르게 하고, 커뮤니티는 이미 움직이고 있습니다. VoltAgent의 브랜드에서 영감을 받은 DESIGN.md 파일 awesome-design-md 컬렉션은 출시 몇 주 만에 GitHub 스타 71,000개를 돌파했고, design-md GitHub 토픽은 이제 Google 외부의 추출 도구, Chrome 확장 프로그램, 동반 SKILL.md 레지스트리를 나열합니다. 채택이 형식이 실제임을 알려주는 것입니다.

design.md를 신경 써야 하는 사람

경계에 대해 솔직하게 말하겠습니다. design.md가 모든 곳에 맞는 것은 아니니까요.

다음의 경우 제 역할을 합니다:

하나 이상의 화면에서 적어도 매주 코딩 에이전트로 UI를 생성하는 경우
생성 전반에 걸쳐 보존하고 싶은 디자인 시스템이 있는 경우 — 얇은 것이라도
하나 이상의 에이전트나 도구로 작업하며 모든 곳에 동일한 브랜드 컨텍스트를 원하는 경우
모든 프롬프트에 “우리 팔레트는 X, Y, Z입니다”를 붙여 넣는 것에 지친 경우

다음의 경우 제 역할을 하지 않습니다:

일회성 목업을 생성하고 버리는 경우
“디자인 시스템”이 에이전트가 이번에 생성하는 것인 경우
Figma 주도 워크플로우에서 Style Dictionary나 유사한 것을 통한 성숙한 DTCG 파이프라인이 있는 경우 — design.md는 가진 것보다 가볍고, 다운그레이드하는 것이 됩니다
오늘 와이드 게이먿 색상(Display P3, Oklch)이 필요한 경우 — 현재 알파 사양은 SRGB 전용입니다

다른 AI 워크플로우 파일(CLAUDE.md, AGENTS.md)과 함께 design.md를 실행하는 AI 네이티브 제품 팀의 경우, 깔끔하게 맞아떨어집니다. 관심사당 하나의 마크다운 파일. 빌드 단계 없음. 싸울 JSON 스키마 없음. 시도 비용은 저장소 루트의 파일 하나와 lint 명령어입니다.

여러 모델에 걸쳐 요청을 라우팅하고 각 호출에서 브랜드 컨텍스트를 유지해야 하는 통합 AI 생성 레이어를 포함하여, 에이전트 기반 생성 서비스를 구축하는 플랫폼의 경우 — design.md는 생태계가 브랜드와 에이전트 간의 이식 가능한 계약에 가장 가까운 것입니다. Google Labs 발표에 따르면, 이 형식은 도구 전반에 걸쳐 내보내고 가져올 수 있도록 특별히 구축되었습니다. 그 이식성이 핵심입니다.

FAQ

design.md는 무엇에 사용되나요?

코딩 에이전트에게 디자인 시스템에 대한 지속적인 컨텍스트를 제공하는 마크다운 파일입니다 — 색상, 타이포그래피, 간격, 컴포넌트, 그리고 적용 방법을 설명하는 산문. 에이전트는 UI를 생성할 때마다 이것을 읽으므로, 각 프롬프트에 브랜드 규칙을 다시 지정하지 않아도 화면과 세션 전반에 걸쳐 출력이 일관되게 유지됩니다.

Google Stitch 워크플로우에만 사용할 수 있나요?

아니요. 이 형식은 Stitch에서 시작되었지만 Google이 Apache 2.0 하에 사양을 오픈소스로 공개했습니다. 컨텍스트 파일을 읽는 모든 AI 도구 — Claude Code, Cursor, GitHub Copilot, Antigravity, Gemini CLI — 가 사용할 수 있습니다. CLI는 Tailwind 설정, CSS 변수, 또는 W3C DTCG JSON으로 내보낼 수 있으므로, 토큰은 비에이전트 도구에도 흐릅니다.

AI가 생성한 UI에 디자인 시스템 파일이 필요한 이유는 무엇인가요?

모델은 생성 간에 브랜드에 대한 기억이 없기 때문입니다. 구조화된 AI 디자인 시스템 파일 없이는 모든 프롬프트가 처음부터 디자인 언어를 재해석합니다. 파일이 있으면 토큰이 하드 제약으로 작동하고 산문이 판단 호출을 다룹니다. 차이는 규모에서 가장 명확하게 나타납니다 — design.md로 생성된 다섯 화면은 스타일을 유지하고; 없이 생성된 다섯 화면은 드리프트합니다.

어떤 팀이 먼저 실험해야 하나요?

이미 매주 코딩 에이전트로 UI를 생성하는 팀. Claude Code나 Cursor를 실행하는 솔로 개발자와 소규모 제품 팀은 가장 빠른 성과를 얻습니다 — 파일을 넣고, 재생성하고, 일관성을 확인하세요. 성숙한 Figma + Style Dictionary 파이프라인을 갖춘 대규모 조직은 design.md를 대체제가 아닌 보완재로 취급해야 합니다: 기존 시스템의 소화 가능한 하위 집합을 에이전트에게 제공하는 데 사용하세요.

결론

design.md는 혁명적인 파일 형식이 아닙니다. 상단에 YAML이 있는 마크다운 파일입니다. 그것이 핵심입니다 — LLM이 가장 잘 읽는 형식은 가장 많이 훈련된 것이고, 그것은 평문입니다.

실제로 하는 것은 질문을 “이 프롬프트에서 디자인을 어떻게 설명하지”에서 “모든 에이전트가 읽을 수 있도록 내 디자인이 어디에 있어야 하지”로 전환하는 것입니다. 하나의 파일, 하나의 위치, 그것을 집어 드는 모든 도구가 같은 답을 얻습니다. 다시 지정해야 할 것이 하나 줄어듭니다. 작게 들립니다. 빠르게 쌓입니다.

두 프로젝트에서 일주일째 사용하고 있습니다. 작동합니다. 장기적으로 — 팀이 진짜 디자인 시스템과 같은 엄격함으로 이 파일들을 관리할지, 아니면 README가 썩는 것처럼 썩을지 — 그것은 아직 확인이 필요합니다. 직접 프로젝트에서 실행해 보세요. 그것이 제가 어떤 말을 해도 더 많은 것을 알려줄 것입니다.

이전 게시물: