DESIGN.md : Google Stitch가 도입한 DESIGN.md - DESIGN.md 도입 배경부터 적용해보기(VoltAgent awesome-design-md 컬렉션 활용 가이드)

안녕하세요! 갓대희 입니다.

 

AI 코딩 에이전트에게 "Stripe 스타일로 만들어줘"라고 지시해본 적이 있는데 매번 결과물이 들쭉날쭉하다면, 그 원인은 에이전트가 디자인 의도를 읽을 공통 언어가 없기 때문이다.

Google Stitch는 이 문제를 해결하기 위해 DESIGN.md라는 개념을 도입했다.

마크다운 파일 한 장으로 컬러 팔레트부터 타이포그래피, 컴포넌트 스타일까지 명시해두면, AI 에이전트가 코드를 생성할 때마다 이 파일을 먼저 읽어 일관된 외관을 유지한다.

목차

1. DESIGN.md란 무엇인가 — README.md와 무엇이 다른가
2. 왜 DESIGN.md가 필요한가 — AI UI의 랜덤성 문제
3. DESIGN.md 포맷 상세 — 9개 섹션 구조
4. awesome-design-md 레포지토리 소개
5. DESIGN.md 접근 방법 — getdesign.md 서비스
6. 주요 컬렉션 예시 분석 — Stripe, Vercel, Linear
7. 실전 활용법 — 프로젝트에 적용하기
8. 기술 아키텍처 분석 — DESIGN.md가 LLM에 최적화된 이유
9. 제한사항 및 주의사항
10. 결론 — LLM 시대 디자인 시스템 표준화 방향

이 글의 핵심

• DESIGN.md는 Google Stitch가 도입한 AI 에이전트용 플레인텍스트 디자인 시스템 문서다
• 9개 섹션으로 컬러·타이포·컴포넌트·레이아웃·프롬프트 가이드를 명세한다
• VoltAgent의 awesome-design-md 컬렉션에 69개 브랜드 DESIGN.md가 MIT 라이선스로 제공된다 (getdesign.md 서비스 통해 배포)
• 공개 CSS 추출 기반이므로 공식 디자인 토큰과 동일하다고 보장되지 않는다

 

1. DESIGN.md란 무엇인가 — README.md와 무엇이 다른가

1.1 개념 정의

DESIGN.md는 Google Stitch가 도입한 새로운 개념으로, AI 에이전트가 일관된 UI를 생성하기 위해 읽는 플레인텍스트 디자인 시스템 문서다. awesome-design-md README는 이를 다음과 같이 정의한다.

"DESIGN.md is a new concept introduced by Google Stitch. A plain-text design system document that AI agents read to generate consistent UI."
(DESIGN.md는 Google Stitch에서 도입한 새로운 개념으로, AI 에이전트가 이를 읽어 일관된 사용자 인터페이스(UI)를 생성할 수 있도록 만든 순수 텍스트 기반의 디자인 시스템 문서입니다.)

핵심은 단순함이다 — Figma 익스포트도, JSON 스키마도, 특수 툴링도 필요 없다. 마크다운 파일 한 장을 프로젝트 루트에 넣으면, AI 코딩 에이전트나 Google Stitch가 즉시 UI 외관을 이해할 수 있다.

 

"Markdown is the format LLMs read best, so there's nothing to parse or configure"

(Markdown은 LLM(Large Language Model)이 가장 잘 읽고 이해할 수 있는 포맷이므로, 추가적인 파싱 과정이나 별도의 설정 없이 바로 사용할 수 있습니다.)라는 것이 채택 근거이다.

 

1.2 파일 역할 분리 — AGENTS.md vs DESIGN.md

프로젝트에는 이미 README.md와 AGENTS.md가 있다. DESIGN.md는 이 체계에 세 번째 레이어를 추가한다.

awesome-design-md README가 제시한 역할 비교표는 다음과 같다.

파일	누가 읽는가	무엇을 정의하는가
AGENTS.md	코딩 에이전트	프로젝트 빌드 방법
DESIGN.md	디자인 에이전트	프로젝트의 외관과 느낌

출처: awesome-design-md README

 

한 줄로 요약하면: AGENTS.md가 "어떻게 만드는가"를 정의한다면, DESIGN.md는 "어떻게 보여야 하는가"를 정의한다.

 

2. 왜 DESIGN.md가 필요한가 — AI UI의 랜덤성 문제

AI 코딩 에이전트에게 UI 컴포넌트 생성을 요청할 때, 에이전트가 참조할 디자인 명세가 없으면 출력이 매번 달라진다. 컬러, 폰트, 여백, 그림자 — 모든 요소가 에이전트의 추측에 맡겨진다.

 

DESIGN.md는 이 문제를 텍스트 명세(specification)로 해결한다. awesome-design-md README가 직접 명시하듯, DESIGN.md를 프로젝트 루트에 두면 "AI 코딩 에이전트나 Google Stitch가 즉시 UI 외관을 이해"한다. 에이전트가 파일을 컨텍스트로 읽고 디자인 결정을 따르므로, 임의의 추측이 개입할 여지가 줄어든다.

stitch-skills의 공식 design-md 스킬은 이를 한 단계 더 구체화한다. DESIGN.md 파일이 "기존 디자인 언어와 완벽하게 일치하는 새 화면을 생성하도록 프롬프팅하는 단일 진실의 원천(source of truth)"이 된다는 것이 스킬의 공식 목표로 보인다.

 

3. DESIGN.md 포맷 상세 — 9개 섹션 구조

3.1 섹션 구조 — awesome-design-md 기준 9개 섹션

VoltAgent의 awesome-design-md README가 정의하는 DESIGN.md 포맷은 9개 섹션으로 구성된다. 아래는 README 원문에서 직접 인용한 전체 목록이다.

#	섹션명	담는 내용
1	Visual Theme & Atmosphere	분위기, 밀도, 디자인 철학
2	Color Palette & Roles	시맨틱 이름 + hex + 기능적 역할
3	Typography Rules	폰트 패밀리, 전체 계층 표
4	Component Stylings	버튼, 카드, 입력, 네비게이션(상태 포함)
5	Layout Principles	간격 스케일, 그리드, 여백 철학
6	Depth & Elevation	그림자 시스템, 표면 계층
7	Do's and Don'ts	디자인 가드레일과 안티패턴
8	Responsive Behavior	브레이크포인트, 터치 타겟, 접기 전략
9	Agent Prompt Guide	빠른 컬러 레퍼런스, 즉시 사용 가능한 프롬프트

출처: awesome-design-md README

위 9개 섹션은 VoltAgent의 awesome-design-md 컬렉션이 정의한 확장 구조다.

Google Stitch 공식 design-md SKILL.md의 Output Format에는 1~5번 섹션(Visual Theme & Atmosphere ~ Layout Principles)만 명시되어 있다. 6번(Depth & Elevation)부터 9번(Agent Prompt Guide)은 VoltAgent가 실제 컬렉션 파일 분석을 통해 추가한 항목이다.

9개 전체를 Google 공식 포맷과 동일시하지 않도록 주의가 필요하다.

 

3.2 섹션 9 — Agent Prompt Guide의 역할

9번 섹션 "Agent Prompt Guide"가 이 포맷의 핵심이다. 단순한 토큰 명세를 넘어, AI에게 즉시 전달할 수 있는 프롬프트 예시를 직접 포함한다. Stripe DESIGN.md의 Agent Prompt Guide는 Quick Color Reference와 컴포넌트별 예시 프롬프트를 담고 있다.

 

예를 들어:

"Create a hero section on white background. Headline at 48px sohne-var weight 300, line-height 1.15, letter-spacing -0.96px, color #061b31..."
(화이트 배경의 히어로 섹션을 구성합니다. 헤드라인은 sohne-var 폰트를 사용하고, weight 300, 크기 48px, line-height 1.15, letter-spacing -0.96px, 색상은 #061b31로 설정합니다...)

결국 DESIGN.md는 사람이 읽는 스타일 가이드가 아니라, AI가 직접 소비하는 프롬프트 라이브러리다.

 

4. awesome-design-md 레포지토리 소개

4.1 레포지토리 개요

awesome-design-md는 VoltAgent가 관리하는 큐레이션 컬렉션으로, MIT 라이선스로 배포된다.

 

4.2 9개 카테고리 구성

컬렉션은 현재 9개 카테고리 총 69개 브랜드로 구성된다. 아래는 README 원문 직접 확인 기준이다 (2026-04-22).

카테고리	포함 브랜드	수
AI & LLM Platforms	Claude, Cohere, ElevenLabs, Minimax, Mistral AI, Ollama, OpenCode AI, Replicate, RunwayML, Together AI, VoltAgent, xAI	12
Developer Tools & IDEs	Cursor, Expo, Lovable, Raycast, Superhuman, Vercel, Warp	7
Backend, Database & DevOps	ClickHouse, Composio, HashiCorp, MongoDB, PostHog, Sanity, Sentry, Supabase	8
Productivity & SaaS	Cal.com, Intercom, Linear, Mintlify, Notion, Resend, Zapier	7
Design & Creative Tools	Airtable, Clay, Figma, Framer, Miro, Webflow	6
Fintech & Crypto	Binance, Coinbase, Kraken, Mastercard, Revolut, Stripe, Wise	7
E-commerce & Retail	Airbnb, Meta, Nike, Shopify, Starbucks	5
Media & Consumer Tech	Apple, IBM, NVIDIA, Pinterest, PlayStation, SpaceX, Spotify, The Verge, Uber, Vodafone, WIRED	11
Automotive	BMW, Bugatti, Ferrari, Lamborghini, Renault, Tesla	6

출처: awesome-design-md README 원문

 

5. DESIGN.md 접근 방법 — getdesign.md 서비스

5.1 현재 폴더 구조

현재 GitHub 레포지토리의 각 브랜드 폴더는 GitHub API 직접 조회 기준 README.md 1개만 포함한다. DESIGN.md 본문은 외부 서비스 getdesign.md로 이전되었다.

design-md/stripe/
└── README.md  (113 bytes)
    → "Design system details have been moved to: https://getdesign.md/stripe/design-md"

stripe, vercel, linear.app, supabase 등 모든 브랜드 폴더가 동일한 구조다. DESIGN.md 본문, 라이트/다크 프리뷰는 getdesign.md 웹 서비스에서 제공된다.

 

5.2 getdesign.md 서비스

각 브랜드의 DESIGN.md는 https://getdesign.md/{브랜드명}/design-md 패턴의 URL로 접근한다.

예: getdesign.md/stripe/design-md. 웹 UI에서 열람하거나, 아래 CLI로 프로젝트에 바로 설치할 수 있다.

 

6. 주요 컬렉션 예시 분석 — Stripe, Vercel, Linear

6.1 Stripe — 핀테크 디자인의 기준

 

Stripe DESIGN.md의 Visual Theme 섹션은 커스텀 sohne-var 가변 폰트를 중심으로 서술된다. 원문에서 직접 인용하면:

"The custom sohne-var variable font is the defining element of Stripe's visual identity. Every text element enables the OpenType "ss01" stylistic set... At display sizes (48px-56px), sohne-var runs at weight 300 — an extraordinarily light weight for headlines"
(커스텀 sohne-var variable font는 Stripe의 비주얼 아이덴티티를 규정하는 핵심 요소입니다. 모든 텍스트 요소에는 OpenType의 'ss01' 스타일 세트가 적용되며, 디스플레이 크기(48px~56px) 구간에서는 sohne-var를 weight 300으로 사용합니다. 이는 헤드라인 기준으로 매우 가벼운 두께에 해당합니다.)

헤드라인에 weight 300을 사용한다는 점이 핵심이다. 대부분의 웹사이트가 헤드라인에 굵은 폰트를 쓰는 반면, Stripe는 극단적으로 얇은 웨이트로 고급스러움을 표현한다.

 

Depth & Elevation 섹션에서 Stripe의 그림자 시스템을 확인할 수 있다:

"Rather than the flat or single-layer approach of most sites, Stripe uses multi-layer, blue-tinted shadows: the signature rgba(50,50,93,0.25) combined with rgba(0,0,0,0.1) creates shadows with a cool, almost atmospheric depth"
("일반적인 웹사이트의 단일 레이어 또는 평면적인 그림자 처리와 달리, Stripe는 블루 계열이 반영된 멀티 레이어 그림자 방식을 사용합니다. rgba(50,50,93,0.25)와 rgba(0,0,0,0.1)의 조합을 통해, 차분하면서도 공기감 있는 깊이감을 표현하는 것이 특징입니다.")

대부분의 사이트가 단일 레이어 그림자를 쓰는 것과 달리, Stripe는 블루 틴트 멀티레이어 그림자로 "대기적 깊이감(atmospheric depth)"을 만든다. 이런 결정이 DESIGN.md에 명시되어 있어야 AI가 재현할 수 있다.

 

6.2 Vercel — "shadow-as-border" 기법

Vercel DESIGN.md에서 가장 흥미로운 부분은 CSS border를 대체하는 shadow 기법이다:

"Instead of traditional CSS borders, Vercel uses box-shadow: 0px 0px 0px 1px rgba(0,0,0,0.08) — a zero-offset, zero-blur, 1px-spread shadow that creates a border-like line without the box model implications."
(기존의 CSS border를 사용하는 대신, Vercel은 box-shadow(0px 0px 0px 1px rgba(0,0,0,0.08))를 활용합니다. offset과 blur를 0으로 두고 spread만 1px 적용해, 레이아웃(box model)에 영향을 주지 않으면서도 테두리처럼 보이는 라인을 구현하는 방식입니다.)

offset 0, blur 0, spread 1px의 box-shadow로 CSS border를 대체한다. 박스 모델에 영향을 주지 않으면서 경계선을 표현하는 이 기법은, Geist 커스텀 폰트와 극단적 음수 자간(-2.4px~-2.88px)과 함께 Vercel 특유의 미니멀 UI를 구성한다.

 

6.3 Linear — 다크모드 네이티브 설계

Linear DESIGN.md는 다크모드 퍼스트 설계의 교과서다:

"Linear's website is a masterclass in dark-mode-first product design... Inter Variable with "cv01", "ss03" globally... Signature weight 510 (between regular and medium) for most UI text... Brand indigo-violet: #5e6ad2 (bg) / #7170ff (accent) / #828fff (hover) — the only chromatic color in the system"
("Linear 웹사이트는 다크 모드 중심 제품 디자인의 대표적인 사례입니다. Inter Variable 폰트를 전역적으로 적용하고, 'cv01', 'ss03' 스타일 옵션을 활성화합니다. UI 텍스트 대부분에는 regular와 medium 사이의 중간 두께인 weight 510을 사용하며, 브랜드 컬러는 인디고-바이올렛 계열(#5e6ad2: 배경 / #7170ff: 강조 / #828fff: hover)로 구성되어 있으며, 시스템 내에서 사실상 유일한 컬러 포인트로 활용됩니다.")

배경 #08090a(퓨어 블랙에 가깝지만 완전한 블랙은 아님)에 단 하나의 유채색 계열(인디고-바이올렛)만 사용한다. "시스템에서 유일한 유채색"이라는 명시적 제약이 DESIGN.md에 담겨 있어야 AI가 임의로 다른 색상을 추가하지 않는다.

세 사이트 모두 디자인의 독특한 결정(Stripe의 얇은 헤드라인, Vercel의 shadow-as-border, Linear의 단색 크로마)은 구두 설명 없이는 재현이 어렵다. DESIGN.md는 이런 암묵적 지식을 명문화하는 역할을 한다.

 

7. 활용법 — 프로젝트에 적용하기

7.1 Step 1 — DESIGN.md 다운로드 및 프로젝트 배치

컬렉션에서 원하는 브랜드의 DESIGN.md를 프로젝트 루트에 배치한다. 현재 공식 배포 방식은 getdesign.md 서비스를 통한 CLI 설치다.

 

Stripe를 예로 들면:

# CLI로 설치 (프로젝트 루트에서 실행)
npx getdesign@latest add stripe

# 다른 브랜드 예시
npx getdesign@latest add vercel
npx getdesign@latest add linear.app

명령어 실행 시 DESIGN.md가 프로젝트 루트에 저장된다. 웹에서 미리 확인하려면 getdesign.md/stripe/design-md 에서 라이트·다크 프리뷰를 포함한 전체 내용을 볼 수 있다.

 

다운로드 후 프로젝트 루트 구조:

my-project/
├── AGENTS.md       ← 빌드 방법 정의 (선택)
├── DESIGN.md       ← 디자인 외관 정의
├── src/
└── ...

다른 브랜드를 원하면 stripe 자리에 브랜드명을 넣는다. 예: vercel, linear.app, supabase, cursor. 지원 브랜드 전체 목록은 getdesign.md 또는 GitHub 디렉토리에서 확인할 수 있다.

 

7.2 Step 2 — AI 에이전트에 참조 지시하기

awesome-design-md README는 사용법을 다음과 같이 안내한다:

"Copy a site's DESIGN.md into your project root. Tell your AI agent to use it."
(사용하려는 사이트의 DESIGN.md 파일을 프로젝트 루트 디렉토리에 복사하고, AI 에이전트가 해당 파일을 참조하도록 안내합니다.)

핵심은 에이전트에게 DESIGN.md를 읽도록 명시적으로 지시하는 것이다.

 

상황별 프롬프트 예시:

상황	프롬프트 예시
컴포넌트 생성	DESIGN.md를 먼저 읽고, 이 디자인 시스템에 맞는 가격표(pricing table) 컴포넌트를 React로 만들어줘.
페이지 생성	DESIGN.md의 Color Palette, Typography, Component Stylings 섹션을 참조해서 랜딩 페이지 히어로 섹션을 만들어줘.
기존 코드 수정	현재 버튼 컴포넌트의 스타일을 DESIGN.md의 Component Stylings 섹션에 정의된 값으로 맞춰줘.
전체 프로젝트 스타일 통일	DESIGN.md를 읽고, src/components/ 내 모든 컴포넌트의 컬러와 폰트를 DESIGN.md 기준으로 일괄 수정해줘.

 

7.3 Step 3 — 자체 프로젝트용 DESIGN.md 작성하기

컬렉션에 원하는 사이트가 없거나, 자체 디자인 시스템을 명세해야 할 경우 직접 작성할 수 있다.

awesome-design-md README에서 정의한 9개 섹션을 스켈레톤으로 사용한다:

# My Project — DESIGN.md

## 1. Visual Theme & Atmosphere
<!-- 분위기, 밀도, 디자인 철학 -->

## 2. Color Palette & Roles
<!-- 시맨틱 이름 + hex 값 + 기능적 역할 -->

## 3. Typography Rules
<!-- 폰트 패밀리, 크기/굵기 계층 표 -->

## 4. Component Stylings
<!-- 버튼, 카드, 입력, 네비게이션 (상태별 스타일 포함) -->

## 5. Layout Principles
<!-- 간격 스케일, 그리드, 여백 철학 -->

## 6. Depth & Elevation
<!-- 그림자 시스템, 표면 계층 -->

## 7. Do's and Don'ts
<!-- 디자인 가드레일, 안티패턴 -->

## 8. Responsive Behavior
<!-- 브레이크포인트, 터치 타겟, 접기 전략 -->

## 9. Agent Prompt Guide
<!-- 빠른 컬러 레퍼런스, 즉시 사용 가능한 프롬프트 예시 -->

 

각 섹션에 실제로 무엇을 쓰는지, Stripe DESIGN.md 원문의 섹션 2(Color Palette & Roles)를 예로 보자:

## 2. Color Palette & Roles

**Primary:** Stripe Purple (`#533afd`), Deep Navy (`#061b31`), Pure White (`#ffffff`)
**Accents:** Ruby (`#ea2261`), Magenta (`#f96bee`)
**Interactive:** Purple Hover (`#4434d4`), Purple Deep (`#2e2b8c`)
**Neutrals:** Heading (`#061b31`), Body (`#64748d`)
**Surfaces:** Border Default (`#e5edf5`), Border Purple (`#b9b9f9`)
**Shadows:** Shadow Blue (`rgba(50,50,93,0.25)`), Shadow Black (`rgba(0,0,0,0.1)`)

출처: Stripe DESIGN.md 원문

 

작성 핵심 원칙:

• 구체적 값 — #533afd처럼 hex/rgba 값을 명시한다. "파란색 계열"같은 모호한 표현은 AI가 임의로 해석한다.
• 시맨틱 이름 — Primary, Accent, Interactive 등 역할별로 분리하면 AI가 용도에 맞는 색상을 선택할 수 있다.
• 상태 포함 — 버튼이라면 기본·호버·클릭·비활성 상태 각각의 스타일을 명시한다.
• 섹션 9 활용 — Agent Prompt Guide에 에이전트가 바로 복사해서 쓸 수 있는 프롬프트 조각을 넣으면 효과적이다.

 

7.4 Google Stitch 연동 — stitch-skills

google-labs-code/stitch-skills는 Stitch MCP 서버와 연동하는 에이전트 스킬 라이브러리다.

이 레포지토리는 design-md 스킬을 공식으로 포함한다. 스킬 파일 상단에 명시된 허용 도구 목록은 다음과 같다:

name: design-md
description: Analyze Stitch projects and synthesize a semantic design system into DESIGN.md files
allowed-tools:
  - "stitch*:*"
  - "Read"
  - "Write"
  - "web_fetch"

 

이 스킬의 목표는 DESIGN.md 파일이 Stitch가 기존 디자인 언어와 일치하는 새 화면을 생성하도록 프롬프팅하는 "단일 진실의 원천(source of truth)"이 되는 것이다:

"The DESIGN.md file will serve as the 'source of truth' for prompting Stitch to generate new screens that align perfectly with the existing design language."
(DESIGN.md 파일은 Stitch가 기존 디자인 언어와 정확하게 일관된 새로운 화면을 생성할 수 있도록 프롬프트의 기준이 되는 ‘source of truth(신뢰 가능한 단일 기준)’로 활용됩니다.)

 

설치 및 사용법은 stitch-skills 공식 레포지토리에서 확인할 수 있다. 스킬 파일(SKILL.md) 원문에 따르면, 이 스킬은 Stitch MCP 서버를 통해 프로젝트 화면을 조회하고 HTML/CSS를 분석하여 DESIGN.md를 자동 생성하는 방식으로 동작한다.

 

7.5 "언제 쓰는가 / 언제 쓰지 않는가" 결정 매트릭스

상황	권장 여부	이유
AI 에이전트로 UI 반복 생성	사용	매번 다른 스타일 출력 문제를 DESIGN.md가 해결한다
기존 사이트와 유사한 스타일 구현	사용	컬렉션에서 골라 복사하면 되므로 즉시 적용 가능
팀 내 AI 기반 프론트엔드 개발 표준화	사용	프로젝트 루트 파일 하나로 팀 전체 AI 출력을 통일할 수 있다
공식 디자인 토큰이 정확히 필요한 경우	주의	컬렉션 파일은 공개 CSS에서 추출한 값이며 공식 토큰과 동일하다고 보장되지 않는다
저작권 민감 프로젝트	확인 필요	MIT 라이선스이나, 해당 사이트의 시각적 아이덴티티 소유권은 별개다

 

8. 기술 아키텍처 분석 — DESIGN.md가 LLM에 최적화된 이유

mindstudio.ai 블로그는 DESIGN.md를 "디자인 시스템을 위한 시스템 프롬프트(system prompt for your design system)"이자 "머신이 읽을 수 있는 디자인 시스템(machine-readable design system)"으로 설명한다.

Claude Code, Cursor, Gemini CLI 같은 AI 코딩 에이전트가 프로젝트 루트의 DESIGN.md를 컨텍스트로 직접 읽어 디자인 규칙을 반영한다. (출처: mindstudio.ai blog)

 

DESIGN.md가 마크다운을 채택한 이유는 명확하다:

"Markdown is the format LLMs read best, so there's nothing to parse or configure."
(Markdown은 LLM(Large Language Model)이 가장 잘 읽고 이해할 수 있는 포맷이므로, 추가적인 파싱 과정이나 별도의 설정 없이 바로 사용할 수 있습니다.)

LLM은 구조화된 JSON이나 이진 Figma 파일보다 마크다운을 더 잘 이해한다. Figma 익스포트나 JSON 스키마를 파싱하는 추가 레이어 없이, 에이전트가 파일을 그대로 컨텍스트로 읽을 수 있다.

stitch-skills design-md 스킬은 Stitch MCP 서버를 통해 프로젝트 화면 메타데이터를 조회하고 HTML/CSS를 파싱해 DESIGN.md를 자동 생성하는 방식으로 동작한다. Stitch가 UI를 생성할 때는 Visual Description(구체적 컬러값으로 뒷받침되는 설명)을 통해 디자인을 해석한다.

 

9. 제한사항 및 주의사항

9.1 공개 CSS 추출 값 — 공식 토큰과의 오차

awesome-design-md의 모든 DESIGN.md 파일은 공개 웹사이트에서 추출된 CSS 값을 기반으로 한다. 레포지토리 자체가 이를 명시한다:

"The extracted design tokens represent publicly visible CSS values. We do not claim ownership of any site's visual identity. These documents exist to help AI agents generate consistent UI."
(본 문서에서 추출된 디자인 토큰은 공개적으로 노출된 CSS 값을 기반으로 하며, 특정 사이트의 시각적 아이덴티티에 대한 소유권을 주장하지 않습니다. 이 문서의 목적은 AI 에이전트가 일관된 UI를 생성할 수 있도록 지원하는 데 있습니다.)

공개 CSS에서 추출한 값이므로, 해당 사이트의 내부 디자인 토큰 시스템과 완전히 동일하다고 볼 수 없다. 브랜드 정확성이 중요한 공식 프로젝트에서는 직접 검증이 필요하다.

 

9.2 유지보수 주기와 버전 드리프트

레포지토리가 2026년 3월 31일 생성된 신규 프로젝트라는 점을 고려해야 한다. 각 사이트가 디자인을 업데이트하면 DESIGN.md 파일이 구식이 될 수 있다. 커밋 이력을 보면 현재는 빠른 주기로 업데이트되고 있으나, 장기적인 유지보수 주기는 확인할 수 없다.

 

9.3 저작권 및 라이선스

레포지토리는 MIT 라이선스로 배포되며, 다음 고지가 명시되어 있다:

"MIT License - see LICENSE. This repository is a curated collection of design system documents extracted from public websites. All DESIGN.md files are provided 'as is' without warranty."

추출된 디자인 토큰은 공개 가시 CSS 값을 나타내며, 해당 사이트의 시각적 아이덴티티 소유권을 주장하지 않는다는 점을 레포지토리가 명시한다. 상업적 프로젝트에서 사용 시 해당 브랜드의 가이드라인을 별도로 확인하는 것이 권장된다.

 

10. 결론 — LLM 시대 디자인 시스템 표준화 방향

도입 플레이북

DESIGN.md는 AI 에이전트 기반 UI 개발에서 발생하는 "디자인 일관성 부재" 문제에 대한 마크다운 레이어 해결책이다. 구조는 단순하지만, 9개 섹션이 담는 정보 밀도는 높다.

 

오늘: awesome-design-md 레포지토리에서 원하는 브랜드를 골라 npx getdesign@latest add {브랜드명}으로 프로젝트 루트에 DESIGN.md를 설치한다. AI 에이전트에게 UI 컴포넌트 생성을 요청하면서 DESIGN.md를 참조하도록 지시해 결과를 비교한다.

 

이번 주: Stripe, Vercel, Linear 세 사이트의 DESIGN.md를 읽어보면 디자인 결정의 "왜"가 담겨 있다. 이것을 직접 작성하는 연습을 통해 자체 프로젝트의 DESIGN.md를 만드는 것도 가능하다.

 

운영 반영: Google Stitch 기반 프로젝트에서는 stitch-skills의 design-md 스킬로 DESIGN.md 자동 생성을 고려한다. Claude Code, Cursor 등 AI 코딩 에이전트 환경에서는 AGENTS.md와 DESIGN.md를 함께 관리하면 에이전트가 "빌드 방법"과 "외관"을 모두 이해한 상태로 작업할 수 있다.

 

자주 묻는 질문 (FAQ)

Q. DESIGN.md를 직접 작성해야 하는가, 아니면 컬렉션에서 복사해서 써도 되는가?

두 방법 모두 가능하다. 빠르게 시작하고 싶다면 npx getdesign@latest add {브랜드명} CLI로 원하는 사이트의 DESIGN.md를 프로젝트 루트에 바로 설치할 수 있다(awesome-design-md에서 브랜드 목록 확인). 설치 후 필요에 맞게 수정하면 된다. Google Stitch 환경에서는 stitch-skills design-md 스킬로 기존 프로젝트에서 자동 생성할 수도 있다.

Q. awesome-design-md의 파일이 해당 사이트의 공식 디자인 토큰과 동일한가?

동일하다고 보장되지 않는다. 레포지토리가 명시하듯, 모든 DESIGN.md 파일은 공개 웹사이트에서 추출된 CSS 값 기반이다. 브랜드 정확성이 중요한 공식 프로젝트에서는 직접 검증이 필요하다.

Q. AGENTS.md가 이미 있는 프로젝트에 DESIGN.md를 추가해야 하는가?

역할이 다르므로 함께 관리하는 것이 권장된다. AGENTS.md가 "어떻게 만드는가"를 정의한다면, DESIGN.md는 "어떻게 보여야 하는가"를 정의한다. 두 파일을 프로젝트 루트에 함께 두면 AI 에이전트가 빌드 방법과 외관을 모두 파악한 상태로 작업할 수 있다.

 

현시점의 한계와 전망

컬렉션 파일이 공개 CSS 추출 기반이라는 한계, 유지보수 주기의 불확실성, 사이트 업데이트 시 드리프트 가능성은 실제 운영에서 고려해야 할 요소다. 레포지토리 자체도 2026년 3월 31일 생성된 신규 프로젝트이므로, 장기 안정성은 지켜볼 필요가 있다.

 

그럼에도 이 개념이 주목받는 이유는 명확하다 — AI가 코드를 생성하는 시대에, 코드 규칙(AGENTS.md)과 디자인 규칙(DESIGN.md)을 텍스트 파일로 명시해두는 방향은 자연스러운 표준화 경로다. DESIGN.md가 AGENTS.md처럼 많은 프로젝트의 루트 파일로 자리잡는 것은 시간 문제일 수 있다.

Google Stitch는 이 개념을 공식적으로 "Vibe Design"으로 명명하고 있다. Google Labs 공식 블로그에서 "Introducing 'vibe design' with Stitch" 제목으로 2026년 3월 발표되었다.

(출처: Google Blog — Introducing vibe design with Stitch)

참고자료

• Google Stitch 공식 DESIGN.md 문서 — stitch.withgoogle.com
• Google Blog — Introducing vibe design with Stitch — Google Labs, 2026-03
• awesome-design-md README — VoltAgent, 2026
• VoltAgent/awesome-design-md — GitHub 레포지토리
• GitHub API: stripe 폴더 구조
• GitHub API: linear.app 폴더 구조
• Stripe DESIGN.md 원문
• Vercel DESIGN.md 원문
• Linear DESIGN.md 원문
• google-labs-code/stitch-skills — GitHub 레포지토리
• stitch-skills design-md SKILL.md 원문
• awesome-design-md 커밋 이력
• awesome-design-md Open Issues