DESIGN.md: AI 코딩 에이전트에게 디자인을 영속시키는 구글의 포맷

AI 코딩 에이전트에게 화면(UI)을 만들어 달라고 시켜본 적 있으세요? 분명 같은 프로젝트인데도, 부를 때마다 브랜드 색이 미묘하게 달라지고 간격도 폰트도 제멋대로일 때가 많습니다. 그래서 매번 "우리 브랜드 색은 이거고, 본문은 16px, 버튼은 8px 라운드…"를 다시 설명하게 되죠.

구글이 이 반복을 파일 하나로 끝냈습니다. 이름은 DESIGN.md입니다. AI 코딩 에이전트가 화면을 만들 때마다 가장 먼저 읽는 "디자인 설명서"를 프로젝트에 영구히 박아두는 포맷이에요. 2026-04-21 오픈소스로 공개됐고, 공개 두 달 만에 GitHub 스타 약 2.2만 개, npm 주간 다운로드 약 8만 건을 기록할 만큼 빠르게 관심을 모으고 있습니다.

이 글에서는 DESIGN.md가 정확히 무엇인지, 왜 디자인 일관성 문제를 푸는지, 그리고 어떻게 직접 시작하는지를 "편한 전문가" 눈높이로 정리해 드릴게요.

DESIGN.md란 무엇인가 — 디자인 시스템의 SSOT

DESIGN.md란? 프로젝트 루트에 두는 단일 파일로, AI 코딩 에이전트가 UI를 생성할 때마다 먼저 읽는 "영속 디자인 컨텍스트(persistent context)"입니다. 색·타이포·간격 같은 디자인 시스템 규칙을 한 곳에 못 박아, 에이전트가 매번 다른 결과를 내지 않도록 합니다.

비유하자면 신입 디자이너에게 매번 구두로 브랜드를 설명하는 대신, 한 번 잘 쓴 "브랜드 가이드 한 장"을 책상에 붙여두는 것과 같아요. 누가 와도 그 한 장을 보고 같은 결과를 냅니다.

이미 많은 분이 쓰고 있는 CLAUDE.md나 AGENTS.md를 떠올리면 이해가 빠릅니다. 이 파일들은 "코드를 어떻게 짤지, 어떤 규칙으로 운영할지"를 담는 에이전트용 컨텍스트 파일이죠. DESIGN.md는 그 디자인 버전입니다.

파일	담는 것	역할
`CLAUDE.md` / `AGENTS.md`	코드·운영 규칙	무엇을 어떻게 만들지의 SSOT(Single Source of Truth, 단일 진실 공급원)
`DESIGN.md`	시각·디자인 규칙	어떻게 보일지의 SSOT

즉 코드에 CLAUDE.md가 있다면, 디자인에는 DESIGN.md가 있다는 한 줄로 요약됩니다. README 중심 개발, llms.txt(LLM용 사이트 요약) 같은 "에이전트에게 맥락을 파일로 넘기는" 흐름의 디자인판이라고 볼 수 있어요.

2계층 구조: 토큰(기계용 값) + 산문(사람용 근거)

DESIGN.md의 진짜 핵심은 파일이 2층 구조라는 점입니다. 이 설계가 "AI가 매번 다른 결과를 내는 문제"를 정확히 겨냥하거든요.

위층 — 디자인 토큰 (YAML front matter): 기계, 즉 코딩 에이전트가 그대로 읽어 쓰는 정확한 값입니다. 예를 들어 primary: "#2563EB", 본문 16px, 버튼 8px 라운드처럼요. 여기엔 해석의 여지가 없는 "정답 값"만 들어갑니다.
아래층 — 디자인 근거 (Markdown 산문): 사람이 읽는 맥락입니다. "왜 이 색을 골랐는지, 어떤 상황에 어떻게 적용하는지"를 자연어로 풀어 씁니다.

여기서 디자인 토큰(design token)이란 색·간격·폰트 크기처럼 디자인 시스템을 이루는 "최소 단위 값"에 이름을 붙인 것을 말해요. #2563EB라는 색에 primary라는 이름을 달아두면, 나중에 색을 바꿔도 이름만 참조한 모든 곳이 한 번에 따라옵니다.

작동 방식은 이렇습니다. AI는 정답 값을 토큰에서 읽고, 판단 근거는 산문에서 읽습니다. 토큰이 "무엇을"을 못 박고, 산문이 "왜·언제"를 설명하니, 에이전트가 추측으로 색을 지어낼 여지가 사라지는 거죠. 매번 결과가 흔들리던 문제가 바로 이 지점에서 풀립니다.

토큰 타입 4종과 섹션 순서 8개

DESIGN.md는 토큰을 네 가지 타입으로 정의합니다.

Color — 모든 CSS 색 표기를 지원합니다(hex, rgb(), oklch(), named color).
Dimension — 숫자와 단위(px, em, rem)를 묶은 치수 값입니다.
Token Reference — {colors.primary}처럼 다른 토큰을 참조합니다. 같은 값을 여러 번 적지 않게 해주는 DRY(반복 금지) 장치예요.
Typography — fontFamily·fontSize·fontWeight·lineHeight·letterSpacing 등을 하나로 묶은 객체입니다.

그리고 문서는 8개 섹션을 고정된 순서로 둡니다(섹션 자체는 생략 가능하지만, 쓸 때 순서는 지킵니다).

Overview(브랜드·스타일 개요)
Colors(색)
Typography(타이포그래피)
Layout(레이아웃·간격)
Elevation & Depth(높낮이·그림자)
Shapes(모양)
Components(컴포넌트)
Do's and Don'ts(해도 되는 것·하면 안 되는 것)

컴포넌트(Components) 섹션에서는 버튼 같은 요소마다 backgroundColor·textColor·typography·rounded·padding·size 같은 속성을 묶어 정의합니다. hover(마우스를 올린 상태), active(누른 상태) 같은 상태 변형은 별도 컴포넌트 항목으로 분리해서 적어두면 됩니다. 순서와 구조가 정해져 있으니, 어떤 에이전트가 읽어도 같은 자리에서 같은 정보를 찾는다는 게 장점이에요.

CLI: 디자인에도 린트와 CI가 생겼다

개발자라면 여기서 눈이 번쩍 뜨일 겁니다. DESIGN.md에는 npx @google/design.md라는 **CLI(명령줄 도구)**가 함께 옵니다. 코드에만 있던 린트(lint, 자동 검사)와 CI(지속적 통합) 개념을 디자인에 그대로 들여온 거예요.

서브명령은 네 가지입니다.

명령	역할
`lint`	9개 규칙으로 구조를 검증합니다. 에러가 있으면 종료 코드 1로 끝나서 CI 게이트로 쓸 수 있어요.
`diff`	두 DESIGN.md를 비교해 토큰·산문의 회귀(의도치 않은 변경)를 잡습니다.
`export`	Tailwind v3/v4, W3C 표준 등 다른 포맷으로 변환합니다.
`spec`	포맷 명세를 출력해 에이전트 프롬프트에 주입합니다.

특히 lint의 9개 규칙이 흥미롭습니다. 핵심만 보면 이렇습니다.

broken-ref (error) — 존재하지 않는 토큰을 참조하는 "깨진 참조"를 잡습니다.
contrast-ratio (warning) — WCAG AA 기준 최소 대비비 4.5:1에 못 미치는 색 조합을 감지합니다.
orphaned-tokens (warning) — 정의만 해두고 아무도 안 쓰는 "고아 토큰"을 알려줍니다.
unknown-key (warning) — colours:처럼 영국식 철자 오타를 colors:로 잡아주는 식의 키 검사를 합니다.

WCAG(웹 콘텐츠 접근성 지침)의 대비비 4.5:1은 글자와 배경의 명암 차이 기준이에요. 이 수치가 모자라면 글자가 잘 안 보여서 접근성 문제가 됩니다. 지금까지는 사람이 일일이 눈으로 확인하던 항목인데, DESIGN.md는 이걸 코드의 린트처럼 자동으로 경고해 줍니다. "디자인에도 CI"라는 한 줄 요약이 가능한 이유죠.

참고로 Windows의 PowerShell에서는 .md 접미사가 마크다운 파일 연결과 충돌할 수 있어서, designmd라는 별칭으로 실행하는 걸 권장합니다(npx -p @google/design.md designmd lint).

도구 중립성, Stitch, 그리고 W3C 표준 호환

DESIGN.md가 구글에서 나왔지만 "구글 전용"은 아니라는 점이 중요합니다. 포맷이 **도구 중립적(portable)**이에요.

이 포맷은 원래 구글 Labs의 AI UI 디자인 도구인 Stitch(stitch.withgoogle.com)가 프로젝트 간 디자인 규칙을 주고받으려고 내부적으로 쓰던 형식이었습니다. Stitch는 Gemini 모델 기반으로 텍스트나 이미지에서 UI와 디자인 시스템, 코드를 생성하는 도구죠. 구글은 이 내부 포맷을 도구 중립 표준으로 만들기 위해 2026-04-21 오픈소스로 분리 공개했습니다.

그래서 Stitch가 DESIGN.md를 뽑아내더라도, 그 파일을 읽는 쪽은 Claude Code든 Cursor든 v0든 상관없습니다. 어떤 코딩 에이전트든 같은 파일을 로드해 브랜드 일관 UI를 만든다는 게 핵심이에요. 생태계 신호도 잡힙니다. Anthropic의 공식 skills 저장소에도 "DESIGN.md를 소비·생산하자"는 이슈가 올라와 있거든요.

여기에 W3C Design Tokens(DTCG) 표준과의 호환까지 더해집니다. DTCG(Design Tokens Community Group)의 포맷은 색·간격·타이포그래피 토큰을 도구 간에 교환하기 위한 JSON 표준이에요($value, $type처럼 $를 붙이는 규약이 특징). 첫 안정 버전이 2025-10-28에 발표됐고, Adobe·구글·마이크로소프트·Figma·Meta 등 20곳 넘는 에디터가 참여했습니다. DESIGN.md의 export --format dtcg가 바로 이 표준 tokens.json을 출력하니, Figma·Style Dictionary·Tokens Studio 같은 DTCG 호환 도구와도 자연스럽게 연결됩니다.

어떻게 시작하나 — 한 줄로 린트부터

시작은 생각보다 간단합니다. 이미 DESIGN.md가 있거나 샘플을 만들었다면, 터미널에서 한 줄만 실행해 검증할 수 있어요.

npx @google/design.md lint DESIGN.md

이 명령이 깨진 토큰 참조, 고아 토큰, WCAG 대비비 미달 같은 문제를 자동으로 짚어줍니다. 변환이 필요하면 export로 Tailwind나 W3C DTCG 포맷으로 바꾸고, CI 파이프라인에 lint를 끼워 넣으면 디자인 회귀를 빌드 단계에서 막을 수 있습니다.

실무 관점에서 정리하면 이렇습니다.

토큰으로 값을 못 박고 — 색·간격·폰트의 정답 값을 YAML 토큰에 둡니다.
산문으로 이유를 적고 — 왜 그 값인지, 어떻게 적용하는지를 본문에 자연어로 풉니다.
린트로 점검하고 — lint를 CI에 붙여 접근성과 구조 오류를 자동으로 잡습니다.

신뢰 근거도 충분합니다. Apache-2.0 라이선스의 오픈소스이고, 2026-06-15에 최신 버전 v0.3.0이 나왔으며(이전 v0.2.0은 2026-05-26), npm 주간 다운로드 약 8만 건에 W3C 표준까지 호환하니까요. 다만 포맷 자체는 아직 alpha 단계로 활발히 개발 중이라, 세부 명세가 바뀔 수 있다는 점은 감안하고 시작하시는 게 좋습니다.

마무리

DESIGN.md는 "AI 코딩 에이전트에게 디자인을 시키면 매번 결과가 달라진다"는 오래된 골칫거리를, 프로젝트 루트의 파일 하나로 푸는 포맷입니다. 디자인 토큰으로 정답 값을 못 박고, 산문으로 그 근거를 남기며, 린트로 접근성과 구조를 자동 점검하죠. 무엇보다 도구를 가리지 않고 W3C 표준과도 호환되니, 특정 에이전트에 잠기지 않는다는 점이 매력적입니다.

AI에게 디자인을 맡길 때 일관성으로 고민한 적이 있다면, 파일 하나로 시작해볼 만합니다. 지금 바로 npx @google/design.md lint부터 가볍게 돌려보세요.

자주 묻는 질문 (FAQ)

Q: DESIGN.md는 CLAUDE.md와 무엇이 다른가요?

CLAUDE.md(또는 AGENTS.md)는 코드와 운영 규칙을 담는 에이전트용 컨텍스트 파일이고, DESIGN.md는 색·타이포·간격 같은 시각 규칙을 담는 디자인 SSOT입니다. "코드에 CLAUDE.md가 있다면 디자인에는 DESIGN.md가 있다"고 보시면 됩니다. 둘은 경쟁이 아니라 서로 다른 영역을 맡는 보완 관계예요.

Q: 구글 도구(Stitch)에서만 쓸 수 있나요?

아닙니다. 포맷이 도구 중립적이라 Claude Code, Cursor, v0 등 DESIGN.md를 읽는 어떤 코딩 에이전트든 같은 파일을 로드할 수 있습니다. 구글이 명세를 Apache-2.0 오픈소스로 공개한 이유가 바로 이 이식성입니다.

Q: 디자인 토큰이 뭔가요?

색·간격·폰트 크기처럼 디자인 시스템을 이루는 최소 단위 값에 이름을 붙인 것입니다. 예를 들어 #2563EB라는 색에 primary라는 이름을 달아두면, 나중에 색을 바꿔도 그 이름을 참조한 모든 곳이 한 번에 따라옵니다. DESIGN.md는 이 토큰을 기계가 읽는 정확한 값으로 상단에 둡니다.

Q: 지금 바로 써도 될 만큼 안정적인가요?

핵심 기능(토큰, 린트, export)은 동작하지만, 포맷 버전은 2026-06-28 기준 아직 alpha 단계로 활발히 개발 중입니다. 세부 명세가 바뀔 수 있으니, 프로토타입이나 사내 프로젝트에서 먼저 도입해 보고 변화에 유연하게 대응하는 걸 권합니다.

DESIGN.md: AI 코딩 에이전트에게 디자인을 영속시키는 구글의 포맷