DESIGN.md 입문: AI의 UI를 '그럴싸한 수준'에서 벗어나게 하는 설계 파일

AI에게 UI를 만들게 하면, 화면은 정돈되어 있지만 어디선가 본 듯한 서비스처럼 되기 쉽습니다. 둥근 카드, 청보라색 그라데이션, 중앙 정렬된 hero, 무난한 CTA. 나쁘지는 않습니다. 하지만 그 제품만의 개성은 남지 않습니다.

DESIGN.md는 이 문제에 상당히 직접적으로 대응하는 파일입니다. 색상, 글꼴, 여백, 모서리 곡률(corner radius), 컴포넌트의 외형뿐만 아니라 "왜 그렇게 보여야 하는가"까지 Markdown에 작성하여 AI 코딩 에이전트(AI coding agent)에게 읽힙니다. Google의 사양 문서에서는 YAML front matter에 두는 토큰이 정규 값이며, Markdown 본문이 그 적용 문맥(context)을 제공한다고 설명합니다.

getdesign.md는 이 DESIGN.md를 즉시 시도해 볼 수 있도록 만든 카탈로그 겸 CLI입니다. Stripe 스타일, Linear 스타일, Vercel 스타일과 같이 공개된 외형을 바탕으로 한 DESIGN.md를 찾아, getdesign

npm 패키지의 npx getdesign add {slug}

로 프로젝트에 배치할 수 있습니다.

이 기사에서는 DESIGN.md를 두는 이유, 사용법, 주변 도구를 구분하는 방법을 차례대로 정리합니다.

우선 결론

DESIGN.md는 AI에게 전달하는 "시각 설계의 전제 파일"입니다.

README.md가 인간을 위한 입구이고, AGENTS.md가 에이전트를 위한 작업 절차라면, DESIGN.md는 에이전트를 위한 디자인 시스템(design system)입니다. 프로젝트 루트(root)에 두고, AI에게 "UI를 작성하기 전에 DESIGN.md를 읽으라"고 지시합니다. 그러면 색상, 모서리 곡률, 그림자, 여백, 피해야 할 표현을 매번 프롬프트(prompt)로 설명해야 하는 부담을 줄일 수 있습니다.

DESIGN.md는 README나 AGENTS.md를 대신하는 것이 아닙니다. 역할을 나눈다면 다음과 같습니다.

README.md: 인간을 위한 개요, 도입, 사용법
AGENTS.md: 에이전트를 위한 작업 절차, 테스트, 규약
DESIGN.md: 에이전트를 위한 시각 설계, 토큰(token), UI 판단
ADR/PRD: 설계 판단이나 제품 요구사항(product requirement)의 이력

그림: DESIGN.md는 UI 그 자체가 아니라, AI가 UI를 작성하기 전에 참조하는 시각적 판단의 근거입니다. README.md나 AGENTS.md와 나란히 프로젝트 문맥(context)으로 배치하여 구현, 검증, 리뷰로 연결합니다.

역사적 경위: Stitch의 UI 생성에서 도구 간을 넘나드는 설계 파일로

DESIGN.md는 Google Labs의 AI UI 디자인 도구인 Stitch의 흐름을 보면 이해하기 쉽습니다. 처음부터 독립된 문서 표준으로 퍼진 것이 아니라, UI 생성과 디자인 시스템의 전달 과정을 단축하려는 문맥에서 등장했습니다.

Google Developers Blog는 2025년 5월 20일에 Stitch를 발표했습니다. 당시 Stitch는 자연어(natural language)나 이미지로부터 UI 디자인과 프론트엔드 코드를 만드는 Google Labs의 실험으로 소개되었습니다. 주안점은 UI를 생성하고, Figma로 붙여넣거나 코드를 export 하여 디자인과 개발 사이의 왕복을 줄이는 것이었습니다.

그 후, Stitch는 단발성 UI 생성 도구에서 더 넓은 "AI-native software design canvas"로 나아갑니다. Google Blog의 Stitch 관련 기사에서는 새로운 캔버스, 디자인 에이전트, MCP server, SDK, skills, developer tools로의 export가 설명되어 있습니다. 이 문맥에서 DESIGN.md는 디자인 시스템을 다루는 새로운 도구로 등장했습니다. 기사에서는 URL로부터 디자인 시스템을 추출하는 것, 또는 DESIGN.md를 사용하여 디자인 규칙을 다른 디자인·코딩 도구로 import/export 하는 것이 설명되어 있습니다.

Google의 design.md 리포지토리는 GitHub API상에서 2026년 4월 10일에 생성되었습니다. 그리고 Google Blog는 2026년 4월 21일에 Stitch의 DESIGN.md 형식을 open-source화했다고 발표했습니다. 이 기사는 DESIGN.md를 Stitch 내에서 프로젝트 간의 디자인 규칙을 export/import 하기 위한 형식으로 설명하며, draft specification을 공개함으로써 특정 도구나 플랫폼에 종속되지 않고 사용할 수 있게 한다고 밝히고 있습니다.

시계열은 다음과 같습니다.

2025년 5월: Stitch가 자연어와 이미지로부터 UI와 코드를 생성하는 Google Labs의 실험적 프로젝트로 등장한다.
2026년 3월: Stitch가 AI-native design canvas로 확장되며, 디자인 에이전트(Design Agent), MCP, SDK, skills, export 기능이 전면에 나선다.
2026년 4월: DESIGN.md의 draft specification(초안 명세)이 공개되며, Stitch 내부의 설계 규칙 교환 형식에서 도구를 넘나드는 agent-friendly(에이전트 친화적)한 설계 시스템 형식으로 확장된다.
같은 시기 전후로: getdesign.md와 같은 카탈로그, getdesign CLI, DesignMD Directory, Claude Code Skill wrapper 등이 등장하며, DESIGN.md를 '명세'에서 '배포·취득·에이전트 연동'의 에코시스템(Ecosystem)으로 밀어 올린다.

이 경과를 보면, DESIGN.md는 'Figma의 대체 파일'이 아닙니다. Stitch에서 탄생한 AI UI 생성의 맥락을 Cursor, Claude Code, Windsurf, v0, Lovable 등의 에이전트 환경에서도 읽을 수 있는 형태로 만드는 것입니다. 인간만이 읽는 디자인 가이드라인을, AI도 매번 참조할 수 있는 프로젝트 자산으로 바꾼다. 그렇게 이해하는 것이 실체에 더 가깝습니다.

그림: Stitch의 UI 생성부터 DESIGN.md 명세 공개, 주변 에코시스템으로의 전개. Apple 스타일의 DESIGN.md 지정에 맞춰 저밀도·흑백 타일·단일 블루 액센트로 구성.

DESIGN.md의 내용: YAML로 값을 결정하고, Markdown으로 이유를 작성한다

Google의 명세에 따르면, DESIGN.md는 Markdown 본문만으로도 성립할 수 있습니다. 다만 색상이나 여백 등의 토큰(Token)을 기계적으로 다루려면, ---로 둘러싸인 YAML front matter에 값을 두고, 그 뒤에 Markdown 본문으로 사용법을 설명하는 구성이 다루기 쉽습니다.

YAML에는 주로 다음 키(Key)를 작성합니다. 자세한 schema(스키마)는 Google의 docs/spec.md에서 확인할 수 있습니다.

version: 현재는 alpha가 사용됨
name: 디자인 시스템 이름
description: 외관에 대한 짧은 설명
colors: 색상 토큰
typography: 타이포그래피(Typography) 스타일
rounded: 모서리 곡률(Rounded) 스케일
spacing: 여백(Spacing) 스케일
components: 버튼이나 카드 등의 컴포넌트(Component) 정의

토큰 참조에는 {colors.primary}와 같은 방식을 사용합니다. 예를 들어, 버튼의 배경색에 {colors.primary}, 글자색에 {colors.on-primary}를 지정하면 색상 값을 한 곳에서 관리할 수 있습니다.

Markdown 본문에는 Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do's and Don'ts 등을 작성합니다. 모든 항목을 다 적을 필요는 없습니다. 다만, 존재하는 섹션은 명세에서 제시된 순서에 맞추는 것이 권장됩니다.

값만 적어두는 것은 별로 도움이 되지 않습니다. #0066cc라는 값만으로는 AI가 이를 링크에 사용해야 할지, CTA(Call to Action)에 사용해야 할지, 혹은 포커스 링(Focus Ring)에 사용해야 할지 판단하기 어렵습니다. DESIGN.md에서는 값에 역할과 설명을 덧붙입니다. 이는 정의되지 않은 화면을 만들 때도 AI가 디자인 시스템의 사고방식을 참조할 수 있도록 하기 위함입니다.

Google CLI로 할 수 있는 것

Google은 @google/design.md라는 CLI를 공개하고 있습니다. 역할은 DESIGN.md를 찾아 배치하는 것이 아닙니다. 이미 존재하는 DESIGN.md를 검증하고, 차이점(Diff)을 확인하며, 다른 형식으로 변환하는 것입니다. CLI의 개요는 Google README에도 나와 있습니다.

자주 사용하는 명령어는 다음과 같습니다.

npx @google/design.md lint DESIGN.md
npx @google/design.md diff DESIGN.md DESIGN-v2.md
npx @google/design.md export --format css-tailwind DESIGN.md > theme.css
...

lint

lint는 깨진 토큰 참조, 대비비 (contrast ratio), 섹션 순서 등을 확인합니다. diff는 두 DESIGN.md 간의 토큰 변경 사항이나 회귀 (regression)를 감지합니다. export는 Tailwind v3 JSON, Tailwind v4 CSS, DTCG tokens JSON 등으로 변환합니다.

getdesign.md 사용법

getdesign.md는 DESIGN.md 파일을 찾아 도입하기 위한 카탈로그입니다. 조사 시점 기준으로 메인 페이지에는 73개의 DESIGN.md 파일과 "Last Updated Jun 13, 2026"이 표시되어 있었습니다. Apple, Airbnb, Stripe, Linear, Vercel, Ollama 등 기존 브랜드나 프로덕트에서 영감을 얻은 분석들이 나열되어 있습니다. 예를 들어 Ollama 페이지에는 다음과 같은 도입 명령어가 안내되어 있습니다.

npx getdesign@latest add ollama

npm의 getdesign README에 있는 기본 조작은 다음 두 가지입니다.

npx getdesign list
npx getdesign add {slug}

list는 사용 가능한 템플릿을 표시합니다. add {slug}는 선택한 템플릿을 프로젝트 루트의 DESIGN.md로 작성합니다. 기존에 DESIGN.md가 있는 경우, 덮어쓰기를 피하기 위해 중첩된 폴더에 저장됩니다. 덮어쓰려면 --force를, 출력 경로를 지정하려면 --out {path}를 사용합니다.

도입 후에는 에이전트(Agent)에게 다음과 같은 지시를 내립니다.

UI를 작성하기 전에 프로젝트 루트의 DESIGN.md를 읽어주세요. 그곳에 정의된 토큰 (token), 타입 스케일 (type scale), 간격 (spacing), 컴포넌트 패턴 (component patterns)을 시각적 판단의 기준으로 삼으세요.

getdesign README는 Cursor, Windsurf, Claude Code에서는 이 지시를 프로젝트 규칙(Project Rules)이나 시스템 프롬프트 (System Prompt)에 배치하는 사용법을 보여줍니다. v0, Lovable, Bolt와 같은 웹 기반 AI UI 도구에서는 DESIGN.md 본문을 붙여넣거나 참조 파일로 업로드합니다. ChatGPT나 Claude의 웹 버전에서는 파일을 첨부하고 "이 설계 시스템을 사용하여 pricing page를 만들어줘"라고 요청합니다.

생태계는 3개의 층으로 구분한다

DESIGN.md 주변은 이름이 비슷하거나 목적이 유사한 프로젝트들이 섞이기 쉬운 영역입니다. 이름이 아닌 역할로 구분합니다.

1. 사양과 검증

google-labs-code/design.md는 형식 사양 (formal specification), 예시, CLI를 제공하는 기준 레이어 (layer)입니다. 리포지토리에는 docs/spec.md, examples/, packages/cli/가 포함됩니다. lint나 export는 DESIGN.md를 단순한 설명문이 아니라, 검증 및 변환이 가능한 설계 자산으로 다루기 위한 도구입니다.

2. 카탈로그와 도입

getdesign.md는 기존 브랜드 스타일의 DESIGN.md를 찾아 프로젝트에 넣기 위한 레이어입니다. getdesign npm 패키지는 npx getdesign add {slug}를 통해 템플릿을 배치하는 역할을 합니다. Google CLI가 "사양의 검증 및 변환"을 담당한다면, getdesign CLI는 "파일을 찾아 배치하는" 도구입니다.

관련 프로젝트로 별도의 계통인 DesignMD Directory 리포지토리도 있습니다. 이 프로젝트는 designmd-cli라는 별도의 CLI, 브랜드 참조, 템플릿, 툴 가이드를 내세우고 있습니다. getdesign.md와 유사한 문제를 다루지만, 운영 주체나 CLI가 동일하지는 않습니다.

3. 에이전트 연동

에이전트 연동의 예로, getdesign.md를 Claude Code Skill로 감싼 brand-design-md 리포지토리도 있습니다. 이 README는 브랜드명을 입력받아 npx getdesign@latest add를 실행하고, 토큰과 규칙을 에이전트 작업에 포함시키는 흐름을 설명합니다.

여기서부터는 추측입니다. DESIGN.md는 파일 단일 형태라기보다, "에이전트가 필요할 때 가져와서 읽고, UI 변경에 반영하는" 방식으로 확산될지도 모릅니다.

도입 패턴

작은 프로젝트라면 다음 순서로 충분합니다.

getdesign.md에서 비슷한 분위기의 템플릿을 찾는다
npx getdesign add {slug}로 DESIGN.md를 추가한다
npx @google/design.md lint DESIGN.md로 구조와 참조를 확인한다
브랜드나 프로덕트의 실체에 맞춰 색상, 글자, 여백, 컴포넌트 설명을 다시 작성한다
AGENTS.md나 각 에이전트의 프로젝트 규칙에 "UI 변경 전에 DESIGN.md를 읽을 것"이라고 명시한다
UI 변경 리뷰 시, DESIGN.md와의 괴리가 있는지 확인한다

팀 단위로 사용할 때는 DESIGN.md를 코드와 마찬가지로 리뷰 대상으로 삼습니다. 브랜드 변경, 컴포넌트 방침 변경, Tailwind 테마 업데이트가 있다면 DESIGN.md도 동일한 PR(Pull Request)에서 업데이트합니다. Google CLI의 diff는 토큰(token) 변경을 추적하는 데 사용할 수 있습니다.

강점

먼저, AI UI 생성의 평준화를 피하는 효과를 노릴 수 있습니다. getdesign.md의 설명 페이지는 AI가 둥근 카드, 보라색-파란색 그라데이션, 중앙 정렬된 히어로(hero) 섹션으로 치우치기 쉬운 문제를 언급하며, DESIGN.md를 "에이전트에게 특정 시각 언어를 전달하는" 해결책으로 설명합니다. 색상이나 여백뿐만 아니라, 왜 그런 모습으로 만들어야 하는지에 대한 이유를 전달할 수 있으므로, 에이전트가 미지의 화면을 만들 때 판단 근거를 늘려줍니다.

다음으로, Markdown 형식이기에 도입이 가볍습니다. getdesign.md는 Figma 플러그인이나 JSON 스키마(schema)가 아니라, 에이전트가 읽을 수 있는 Markdown 파일로 다룰 수 있다는 점을 강조합니다. 리포지토리에 파일 하나만 두면 되므로 리뷰, diff, 버전 관리가 용이해집니다.

기존 도구와 연결할 수 있다는 점도 있습니다. Google의 README는 Tailwind v3 JSON, Tailwind v4 CSS, DTCG 토큰(tokens) JSON으로의 내보내기(export)를 설명합니다. 이미 Tailwind나 디자인 토큰을 사용 중인 프로젝트에서도 DESIGN.md를 고립된 문서로 두지 않고 구현 측으로 연결할 수 있습니다.

제약과 주의점

DESIGN.md는 구현체가 아닙니다. 버튼의 외형을 설명하더라도 버튼 컴포넌트는 별도로 구현해야 합니다. getdesign.md의 설명 페이지 역시 DESIGN.md는 사전(dictionary)이며 코드가 아니라고 설명합니다. 파일을 두는 것만으로 모든 화면이 자동으로 정돈되는 것은 아닙니다.

getdesign.md의 템플릿은 공식 브랜드 가이드가 아닙니다. getdesign.md는 각 파일이 공개적으로 관찰 가능한 패턴을 바탕으로 한 교육 및 개발 목적의 출발점이며, 상표나 브랜드 요소는 각 소유자에게 속한다고 명시하고 있습니다. 외부 공개 프로덕트에서 특정 브랜드를 모방할 경우에는 법무 및 브랜드 측면의 확인이 필요합니다.

사양(specification)은 알파(alpha) 단계입니다. Google의 README는 사양, 토큰 스키마(token schema), CLI가 개발 중임을 명시하고 있습니다. 장기적인 운용을 위해서는 @google/design.md의 버전을 고정하고, CI에서의 lint 실행, 사양 변경 시의 마이그레이션 작업이 필요합니다.

또한, DESIGN.md가 있다고 해서 접근성(accessibility)이나 컴포넌트 품질이 보장되는 것은 아닙니다. Google CLI의 대비(contrast) 체크는 일부 확인을 도와줄 뿐이며, 구현 후의 표시 확인, 키보드 조작, 스크린 리더, 실제 기기에서의 반응형(responsive) 확인은 별도의 작업입니다.

실무에서 잘 사용하는 팁

DESIGN.md는 처음부터 완성본을 쓰려고 하지 않는 편이 좋습니다. UI 변경과 함께 키워나가는 것이 더 자연스럽습니다. 처음에는 getdesign.md의 템플릿을 토대로 시작해도 괜찮습니다. 다만, 그대로 계속 사용하는 것이 아니라 빠르게 자신들의 문맥(context)에 맞게 교체해야 합니다.

추상적인 단어로만 끝내지 않는 것도 중요합니다. "premium", "clean", "modern" 같은 단어만으로는 AI가 다시 평균적인 결과물로 돌아가게 만듭니다. 배경색, 글자 크기, 줄 간격(line-height), 모서리 곡률(corner radius), 테두리(border), 그림자(shadow), 호버(hover) 효과, 밀도(density), 중단점(breakpoint), 피해야 할 패턴까지 작성하면 구현에 실질적인 도움이 됩니다. 이러한 권장 사항은 Google의 사양이 "Do's and Don'ts"를 가드레일(guardrails)로 취급하고, getdesign.md의 설명 페이지가 토큰(token), 규칙(rule), 근거(rationale)를 동일한 파일에 두는 가치를 설명하고 있다는 점에 기반한 실무적 해석입니다.

마지막으로, DESIGN.md를 'AI용 브랜드 가이드'로 고립시키지 마십시오. Tailwind 테마, CSS 변수 (CSS variables), Figma 변수 (Figma variables), 기존 컴포넌트와 어긋나게 되면, AI만이 별도의 설계 체계를 보고 작업하게 됩니다. 구현 측의 토큰 (token) 업데이트와 DESIGN.md 업데이트를 동일한 PR (Pull Request)로 처리하면 불일치를 억제할 수 있습니다.

미확인 사항

getdesign.md의 모든 템플릿에 대한 린트 (lint)는 실행하지 않았습니다. 개별 템플릿을 채택하기 전에 @google/design.md lint로 확인할 여지가 있습니다.
DESIGN.md의 유무에 따라 AI 에이전트 (AI agent)의 출력이 어느 정도 변하는지는 이번 조사에서 측정하지 않았습니다. 단일 화면만 동일한 조건으로 생성하게 하는 소규모 실험을 수행하면 도입 효과를 판단하기 쉬워집니다.
Figma 변수 (Figma variables), Style Dictionary, Tailwind 테마 (Tailwind theme), DTCG 토큰 (DTCG tokens) 중 무엇을 신뢰할 수 있는 단일 출처 (source of truth)로 삼을지는 기존 디자인 시스템의 규모에 따라 달라집니다.

시도해 본다면

기존 프로젝트를 하나 선정하여, getdesign.md 템플릿을 기반으로 DESIGN.md를 작성합니다.
@google/design.md lint를 로컬 환경 또는 CI (Continuous Integration)에 포함합니다.
AGENTS.md나 각 에이전트의 프로젝트 규칙에 "UI 변경 전에 DESIGN.md를 읽을 것"이라고 명시합니다.
단일 화면에 대해 DESIGN.md가 있을 때와 없을 때를 동일한 AI 에이전트에게 구현하게 하여 차이점을 비교합니다.
브랜드 모방이 아니라, 자사 및 자사 프로덕트용 토큰 (token)과 근거 (rationale)로 다시 작성합니다.

참고 링크

본문에서 사용한 주요 1차 정보 및 주변 확인 링크입니다. 내용이 길어 접어두었습니다.

참고 링크 목록

Google Labs Code, DESIGN.md repository: https://github.com/google-labs-code/design.md
Google Labs Code, DESIGN.md README: https://raw.githubusercontent.com/google-labs-code/design.md/main/README.md
Google Labs Code, DESIGN.md spec: https://raw.githubusercontent.com/google-labs-code/design.md/main/docs/spec.md
npm, @google/design.md: https://registry.npmjs.org/@google%2Fdesign.md
getdesign.md homepage: https://getdesign.md/
getdesign.md, What is DESIGN.md?: https://getdesign.md/what-is-design-md
getdesign.md, Ollama example: https://getdesign.md/ollama/design-md
npm, getdesign