stitch가 유행시킨 DESIGN.md — AI 에이전트용 디자인 시스템 파일 총정리

AI 코딩 에이전트에게 "내 브랜드 느낌대로 만들어줘"라고 말해본 적 있는가? 결과는 언제나 비슷하다. 기술적으로는 정확한데,的品牌 컬러 대신 기본 Tailwind 파란색이 나오고, 컴포넌트마다 시각적 언어가 달라泾은적이다. 문제가 AI가 아닌. AI가 당신의 브랜드가 어떻게 생긴는지, 왜 그렇게 생긴지를 알 방법이 없다는 것이 문제다.

Google Labs가 만든 DESIGN.md가 바로 이 문제를 해결한다. 프로젝트 루트에 하나의 마크다운 파일을 두면, Claude Code든 Cursor든 Copilot이든 어떤 AI 코딩 에이전트든 당신의 디자인 시스템을 읽고 일관된 UI를 생성한다.

DESIGN.md란 무엇인가

DESIGN.md는 Google Labs의 Stitch에서 도입한 새로운 오픈소스 파일 포맷이다. 평문 마크다운으로 작성되며, AI 에이전트가 읽어서 일관된 UI를 생성하는 디자인 시스템 문서다. Figma 내보내기나 JSON 스키마가 아닌, 그냥 마크다운 파일 하나다.

文件的 위치는 README.md와 같다. 다만 대상이 다르다:

| 파일 | 누가 읽는가 | 무엇을 정의하는가 |

|------|------------|-----------------|

| README.md | 개발자 | 프로젝트를 어떻게 빌드하는가 |

| AGENTS.md | 코딩 에이전트 | 프로젝트를 어떻게 만드는가 |

| DESIGN.md | 디자인 에이전트 | 프로젝트가 어떻게 보여야 하는가 |

핵심적인 차이: Figma 컴포넌트 라이브러리는 디자이너에게 "무엇이 무엇인지"를 알려준다. DESIGN.md는 AI 에이전트에게 "그 값이 무엇을 의미하는지"를 알려준다.

예를 들어, 색상 #B8422E는 그냥 숫자일 뿐이다. 하지만 "Boston Clay —sole interaction driver"라고 적혀 있으면, AI는 이것이 인터랙티브 요소에만 사용되어야 한다는 것을 이해한다. 숫자가 아닌 의미(Semantic Role)를 가르치는 것이다.

파일 구조 살펴보기

DESIGN.md는 두 부분으로 구성된다:

• 1. YAML 프론트 매터 (머신 리더블)*

---
name: Heritage
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 3rem
  body-md:
    fontFamily: Public Sans
    fontSize: 1rem
rounded:
  sm: 4px
  md: 8px
spacing:
  sm: 8px
  md: 16px
---

• 2. 마크다운 본문 (휴먼 리더블)*

## Overview
Architectural Minimalism meets Journalistic Gravitas.
The UI evokes a premium matte finish — a high-end broadsheet or contemporary gallery.

## Colors
The palette is rooted in high-contrast neutrals and a single accent.
– Primary (#1A1C1E): Deep ink for headlines and core text.
– Tertiary (#B8422E): "Boston Clay" — the sole interaction driver.

YAML이 정확한 값을 제공하고, 마크다운이 그 값을 왜 사용해야 하는지 설명한다. 둘 다 있어야 완전한 디자인 시스템이 된다.

awesome-design-md: 60개 이상의 디자인 시스템 컬렉션

실제 웹사이트에서 추출한 DESIGN.md 파일을 모아둔 awesome-design-md 저장소가 있다. VoltAgent에서 관리하며, 현재 8.3k 포크, 67.4k 스타를 받았다.

포함된 디자인 시스템 카테고리

• AI & LLM 플랫폼*

Claude, Cohere, ElevenLabs, Minimax, Mistral AI, Ollama, OpenCode AI, Replicate, RunwayML, Together AI, VoltAgent, xAI 등

• 개발도구 & IDE*

Cursor, Expo, Lovable, Raycast, Superhuman, Vercel, Warp

• 베이스, 데이터베이스 & DevOps*

ClickHouse, Composio, HashiCorp, MongoDB, PostHog, Sanity, Sentry, Supabase

• 생산성 & SaaS*

Cal.com, Intercom, Linear, Mintlify, Notion, Resend, Zapier

• 디자인 & 크리에이티브 툴*

Airtable, Clay, Figma, Framer, Miro, Webflow

• 핀테크 & 이커머스*

Binance, Coinbase, Kraken, Mastercard, Revolut, Stripe, Wise, Airbnb

각 디자인 시스템은 브랜드의 컬러 팔레트, 타이포그래피, 컴포넌트 구조를 DESIGN.md 포맷으로 제공한다. 원하는 사이트를 복사해서 프로젝트에 붙여넣기만 하면 된다.

사용법: 3단계로 시작하기

Step 1: 원하는 디자인 시스템 복사

awesome-design-md GitHub 저장소에서 원하는 브랜드의 DESIGN.md 파일을 복사한다.

Step 2: 프로젝트에 붙여넣기

cp DESIGN.md /your-project/

파일 이름은 반드시 DESIGN.md여야 하며, 프로젝트 루트에 위치해야 한다.

Step 3: AI 에이전트에 지시

"build me a page that looks like this"

이 한 줄만 입력하면 된다. AI 에이전트가 DESIGN.md를 읽고 해당 브랜드의 디자인 시스템을 적용하여 UI를 생성한다.

Google 공식 CLI 도구

Google은 DESIGN.md 파일을 다루는 CLI 도구도 제공한다.

설치

npx @google/design.md lint DESIGN.md

LINT — 파일 검증

npx @google/design.md lint DESIGN.md
npx @google/design.md lint --format json DESIGN.md

WCAG 대비 비율을 자동 체크하고, 잘못된 토큰 참조를 찾아낸다. CI에 통합하면 의도치 않은 디자인 시스템 드리프트를 방지할 수 있다.

DIFF — 버전 비교

npx @google/design.md diff DESIGN.md DESIGN.next.md

두 버전 간 토큰 레벨의 변경 사항을 보고한다. Exit code 1은 회귀(regression)가 발견되었음을 의미한다.

EXPORT — 다른 포맷으로 변환

npx @google/design.md export --format tailwind DESIGN.md > tailwind.theme.json
npx @google/design.md export --format dtcg DESIGN.md > tokens.json

DESIGN.md 하나에서 Tailwind 설정이나 W3C DTCG 토큰으로 내보낼 수 있다.

기존 방식과의 차이

기존에는 AI 에이전트에게 일관된 디자인을 요청하려면 매번 프롬프트에 디자인 시스템을 설명해야 했다. 또는 Figma 파일을 연결하는 복잡한 플러그인을 사용해야 했다.

DESIGN.md는 이 모든 것을 단순화한다:

• 플러그인 불필요: 마크다운 파일을 읽기만 하면 된다
• Figma 불필요: 별도 디자인 도구 없이 텍스트로 기술한다
• CI/CD 통합: CLI로 자동 검증하고 diff로 변경사항을 추적한다
• 오픈소스: Apache 2.0 라이선스로 누구나 사용할 수 있다

앞으로의 전망

DESIGN.md 포맷은 아직 초기 단계지만, 이미 다수의 AI 프레임워크와 도구에서 채택이 시작되었다. VoltAgent를 포함한 여러 에이전트 프레임워크가 DESIGN.md를Native로 지원하고 있으며, Google의 공식 CLI와 Stitch 앱 연동으로 생태계가 확대되고 있다.

AI 코딩 에이전트가 개발 프로젝트의 "왼쪽大脑"이라면, DESIGN.md는 개발 프로젝트의 "오른쪽大脑"이다. 논리적 구조와 시각적 정체성을 함께 제공할 때, 비로소 완전한 AI 협업이 가능해진다.

• --

• tags:* DESIGN.md, Google Stitch, AI Agent, Design System, UI Generation, awesome-design-md, 프론트엔드, 개발자 도구, Claude Code, Cursor, Copilot