awesome-design-md 딥다이브
— AI에게 "이 브랜드처럼 생긴 화면을 만들어줘"를 가능하게 하는 디자인 명세서 모음

VoltAgent가 운영하는 DESIGN.md 큐레이션 모음집. Apple·Stripe·Claude·Nike 같은 유명 사이트의 디자인 언어(색·타이포·간격·컴포넌트)를 AI 코딩 에이전트가 가장 잘 읽는 평문 마크다운 한 장으로 압축해 둔 레포다. 그 DESIGN.md를 프로젝트에 떨궈 두고 "이 룩으로 만들어줘"라고 시키면, 에이전트가 브랜드와 시각적으로 일관된 UI를 뽑아낸다. 코드는 한 줄도 없고 전부 마크다운이다. (저장소: VoltAgent/awesome-design-md · 약 74개 브랜드 · 100% Markdown · MIT · TrendShift 연간 #22 · GitHub 전역 약 150위(README 배지 기준))

1프로젝트 한줄 요약

"유명 사이트의 '디자인 언어'를 AI가 읽는 설명서(DESIGN.md)로 적어 둔 모음집."

핵심은 "디자인을 코드가 아니라 '읽는 문서'로 전달한다"는 점이다. 보통 디자인을 코드와 연결하려면 Figma 익스포트, 디자인 토큰 JSON, 전용 플러그인이 필요했다. 그런데 이 레포는 파일이라곤 마크다운(.md)뿐이다. 빌드 도구도, 자바스크립트도, 설정 파일도 없다. README의 표현을 빌리면 "마크다운은 LLM이 가장 잘 읽는 포맷이라, 파싱하거나 설정할 게 없다"는 게 설계의 출발점이다.

만든 곳은 VoltAgent라는 AI 에이전트 프레임워크 회사다. 라이선스는 MIT이고, README 배지 기준 GitHub 전역 약 150위까지 오른 2026년의 화제작이다(TrendShift 연간 트렌딩 #22). 다만 단순 오픈소스 모음을 넘어, 자사 호스팅 뷰어(getdesign.md)와 유료 우선 생성 서비스로 이어지는 마케팅·리드 퍼널 성격도 함께 가진다는 점은 알고 보면 좋다(2절·6절에서 다룬다).

2왜 주목받는가

"AI가 만든 화면은 왜 늘 밋밋한가?"라는 모두의 불만에, 가장 가벼운 처방을 내놨다.

2026년 개발 생태계의 큰 흐름은 '바이브 코딩(vibe coding)' — AI에게 말로 시켜 앱을 만드는 방식이다. 그런데 모두가 부딪힌 벽이 있다. AI가 만든 UI는 하나같이 비슷하게 생겼고, 브랜드 개성이 없다는 것. awesome-design-md는 이 "AI 디자인의 평준화(generic slop)" 문제에 정확히 꽂힌 처방이라 주목받았다. TrendShift 인기 토픽에서도 #AI coding assistant·#Design system이 늘 상위에 보인다.

세 가지 접근, 무엇이 다른가

또 하나의 매력은 '완성품'으로 바로 쓸 수 있는 큐레이션이라는 점이다. 직접 DESIGN.md를 쓰는 법을 배울 필요 없이, Apple·Stripe·Linear·Vercel 같은 '검증된 디자인'을 골라 떠먹기만 하면 된다. 빈티지 웹(1996년 Dell, 2001년 Nintendo.com)까지 포함한 재미 요소도 화제를 더했다.

3기술 스택 전체 지도

백엔드도 프레임워크도 '없다'. '기술'은 ① 포맷 개념 ② 디자인 토큰 스키마 ③ 두 가지 작성 변종 ④ GitHub 메타다.

이 레포에는 컴파일되는 코드가 한 줄도 없다. package.json도, CI 워크플로우도, 자바스크립트/타입스크립트도 없다. GitHub 언어 막대는 사실상 100% Markdown이다. 그래서 '프론트엔드/백엔드/인프라'로 나누는 대신, ① DESIGN.md라는 포맷 개념 ② 그 안의 디자인 토큰 스키마 ③ 두 가지 작성 변종 ④ 배포·운영용 GitHub 메타로 보는 게 머리에 잘 들어온다.

① 포맷의 뿌리 — Google Stitch의 DESIGN.md

DESIGN.md는 VoltAgent가 발명한 게 아니라 Google Stitch가 제안한 개념이다(README가 출처를 명시). Stitch는 디자인을 코드 에이전트에 넘길 때 "한 사이트의 룩앤필을 마크다운 한 장에 담는다"는 발상을 내놨고, 이 레포는 그 발상을 실제 유명 사이트 74곳으로 채운 라이브러리다.

② 핵심 데이터 — 디자인 토큰(Design Tokens)

DESIGN.md의 알맹이는 디자인 토큰이다. 색 하나하나에 이름을 붙이고(primary, canvas, ink …), 폰트·간격·둥글기·그림자도 모두 '이름 붙은 값'으로 정리한다. 신형 변종에서는 이걸 파일 맨 위 YAML로 적는다.

③ 두 가지 작성 변종 — 산문형 → 토큰형으로 진화

실제 파일을 까 보면 두 가지 포맷이 공존한다. 이 레포가 시간을 두고 성숙해 온 흔적이라 그 자체가 흥미로운 학습거리다(4절에서 자세히).

④ 배포·운영용 GitHub 메타

코드가 없으니 '인프라'랄 게 GitHub 자체 기능뿐이다. LICENSE(MIT), 스폰서 버튼(.github/FUNDING.yml), 그리고 "URL 주면 DESIGN.md 만들어 줌" 이슈 템플릿(.github/ISSUE_TEMPLATE/design-md-request.yml)이 전부다. 이 이슈 템플릿이 곧 신규 요청을 받아 자사 유료 서비스로 잇는 깔때기 역할을 한다.

4아키텍처 심화 분석 — DESIGN.md가 UI가 되는 법

'실제 사이트 CSS → 마크다운 명세서 → 에이전트가 읽음 → 화면'으로 흐르는 단순하지만 영리한 파이프라인.

'아키텍처'라고 하면 서버·DB·API가 떠오르지만, 이 레포에는 그런 게 없다. 대신 데이터가 흐르는 길이 곧 아키텍처다. 그 길을 떠받치는 세 가지 설계 패턴을 먼저 보고, 그다음 흐름 한 줄기를 처음부터 끝까지 따라가 보자.

핵심 패턴 1 — 디자인을 '데이터'가 아니라 '읽는 문서'로

가장 큰 통찰은 "LLM에게는 JSON보다 마크다운이 낫다"이다. 토큰 값만 담은 JSON은 기계엔 깔끔하지만 의도가 빠진다. DESIGN.md는 토큰 옆에 "왜 이렇게 했는지"를 산문으로 같이 적어, 에이전트가 규칙뿐 아니라 분위기까지 잡게 한다.

핵심 패턴 2 — 토큰 '참조'로 컴포넌트를 조립 (단일 진실원)

신형 변종의 백미는 컴포넌트가 색 hex를 직접 박지 않는다는 점이다. 버튼은 backgroundColor: "{colors.primary}"처럼 토큰을 가리키기만 한다. 그래서 primary 한 곳만 바꾸면 그 색을 쓰던 모든 컴포넌트가 한꺼번에 바뀐다 — 이게 디자인 시스템의 단일 진실원(single source of truth) 원리다.

# claude/DESIGN.md 윗부분 (변종 A — YAML 토큰)
---
name: Claude-design-analysis
colors:
  primary: "#cc785c"      # 코랄 — 버튼·강조
  canvas:  "#faf9f5"      # 크림 바탕 (브랜드 정체성)
  ink:     "#141413"      # 본문 글자색
typography:
  display-xl:
    fontFamily: "Copernicus, Tiempos Headline, serif"
    fontSize: 64px
    fontWeight: 400
components:
  button-primary:
    backgroundColor: "{colors.primary}"   # ← hex 직접 X, 토큰 '참조'
    rounded: "{rounded.md}"
---

핵심 패턴 3 — 산문형(B)에서 토큰형(A)으로 진화

구형 10개 파일은 YAML 없이 "## 1. Visual Theme … ## 9. Agent Prompt Guide"처럼 번호 매긴 산문만 있다. 신형 64개는 그 위에 YAML 토큰 + 더 깊은 컴포넌트 분해를 얹었다. 사람이 읽는 문서가 기계가 파싱 가능한 구조로 성숙해 가는 과정이 한 레포 안에 화석처럼 남아 있는 셈이다.

전체 그림 — 한 장으로

흐름 한 줄기 따라가기 — "Claude 룩으로 가격표 카드 만들기"

가장 대표적인 동작 하나를 손으로 추적해 보자(해피패스만, 예외는 생략).

# ① claude/DESIGN.md 를 내 프로젝트 루트에 복사
cp design-md/claude/DESIGN.md ./DESIGN.md

# ② 에이전트에게 지시 (Claude Code 등)
"DESIGN.md를 기준으로 3단 요금제 가격표 섹션을 만들어줘"

# ③ 에이전트 내부 동작 (개념)
#   canvas(#faf9f5) → 섹션 배경
#   button-primary.backgroundColor = {colors.primary} → #cc785c
#   display-xl(Copernicus serif 64px) → 가격 숫자
#   "Do: 카드 사이 충분한 여백" / "Don't: surface 두 번 연속 반복" 적용

여기서 이 레포 특유의 '정상적인 모양새'를 한 줄 짚자면 — 각 폴더의 DESIGN.md만 진짜 내용물이고, 같은 폴더의 README.md는 "내용은 getdesign.md로 옮겼다"는 스텁(껍데기)일 뿐이다. 그러니 학습할 땐 폴더의 DESIGN.md를 열어야 한다.

5디렉토리 구조 해부

핵심은 design-md/ 한 폴더 — 그 아래 브랜드별 폴더가 약 74개 줄지어 있다.

레포 전체가 마크다운 약 149개 + GitHub 메타 몇 개로 끝난다(총 ~2.1MB). 구조는 ① 루트 문서(README·LICENSE·CONTRIBUTING) ② 운영 메타(.github/) ③ 본체(design-md/) 세 덩어리다. 모든 브랜드 폴더가 DESIGN.md + 스텁 README.md의 동일한 모양을 한다.

주목할 점은 빌드 도구가 0개라는 것이다. package.json도 .github/workflows(CI)도 없다. "순수 마크다운 + GitHub 메타"만으로 수만 스타를 받은 레포라는 점 자체가, 콘텐츠(큐레이션)의 힘을 보여주는 사례다.

루트 README가 브랜드를 묶는 9개 카테고리

약 74개 브랜드는 README에서 도메인별로 묶여 있다 — 이 분류만 봐도 어떤 스타일을 고를지 감이 온다.

6학습 포인트 (기술별)

디자인 토큰, 컨텍스트 엔지니어링, '하지 말 것' 명세까지 — 코드가 없어도 배울 게 많다.

① 디자인 토큰 시스템 — 이 레포의 간판 학습거리

colors → typography → spacing → components로 이어지는 토큰 계층과, 컴포넌트가 원시값 대신 {token}을 참조하는 방식은 모든 디자인 시스템의 기본기다. Stripe 파일엔 숫자 정렬용 tnum, 스타일 세트 ss01 같은 OpenType 폰트 피처까지 토큰화돼 있어 고급 사례로 좋다.

② 컨텍스트 엔지니어링 — 마크다운을 'AI 입력'으로 설계

컨텍스트 엔지니어링은 "AI에게 무엇을, 어떤 형태로 보여줄지"를 설계하는 일이다. DESIGN.md는 그 교과서적 사례다 — 디자인을 LLM이 가장 잘 읽는 마크다운으로 인코딩하고, AGENTS.md(빌드)와 DESIGN.md(룩)로 관심사를 분리해 각 에이전트에 알맞은 컨텍스트만 준다.

③ '하지 말 것' 명세 — 가드레일 엔지니어링

각 DESIGN.md의 Do's and Don'ts 섹션은 부정 제약(negative constraints)을 적는 기술이다. "세리프 디스플레이를 굵게 쓰지 마라", "연속한 두 밴드에 같은 surface를 반복하지 마라" 같은 안티패턴을 미리 못 박아 에이전트가 룩을 망치지 않게 한다. 프롬프트·스펙 작성 전반에 통하는 기법이다.

④ 브랜드 의도의 언어화 & ⑤ 정직한 한계 표기

각 Overview는 "왜 이 색인가"를 말로 설명한다(예: Claude의 크림+코랄은 OpenAI의 차가운 슬레이트, Google의 쨍한 블루에 대한 의도적 반대 포지셔닝). 또 Known Gaps 섹션은 "이건 추출 못 했다"(애니메이션 타이밍, 폼 검증 상태, 비공개 폰트 등)를 솔직히 적는다 — 추출 기반 명세의 한계를 숨기지 않는 좋은 문서화 습관이다.

7시스템 요구사항

하드웨어 0. 필요한 건 '마크다운을 읽는 AI 코딩 에이전트'와 '룩을 입힐 프로젝트'뿐.

서버도 GPU도, 심지어 Node나 빌드 도구도 필요 없다. DESIGN.md는 그냥 텍스트 파일이라 다운로드해서 프로젝트에 복사하면 끝이다. 진짜 전제 조건은 마크다운을 읽고 UI 코드를 생성할 줄 아는 에이전트 하나다.

8직접 해볼 수 있는 실습 과제

"떠먹기 → 비교 → 직접 작성 → 토큰 시스템 구축"으로 난이도 상승.

과제 1. DESIGN.md 떠먹어 보기 난이도 ★☆☆☆☆

design-md/stripe/DESIGN.md를 받아 빈 프로젝트 루트에 두고, AI 코딩 에이전트에게 "이 DESIGN.md로 SaaS 랜딩 히어로 섹션을 만들어줘"라고 시켜 보라. 결과가 정말 Stripe 느낌이 나는지 눈으로 확인.

과제 2. A/B 비교로 효과 체감 난이도 ★★☆☆☆

같은 요청을 (a) DESIGN.md 없이, (b) claude/DESIGN.md를 넣고 각각 시켜 두 결과를 나란히 본다. "AI가 만든 밋밋한 화면"과 "브랜드 룩을 입은 화면"의 차이를 직접 느끼는 게 이 과제의 핵심.

과제 3. 변종 A vs 변종 B 뜯어보기 난이도 ★★☆☆☆

YAML 토큰형(예: claude)과 순문형(예: kraken) 파일을 나란히 열어 같은 정보(색·타이포)를 어떻게 다르게 적었는지 비교한다. 어느 쪽이 에이전트가 파싱하기 쉬울지 생각해 보면 포맷 설계 감각이 는다.

과제 4. 내가 좋아하는 사이트의 DESIGN.md 작성 난이도 ★★★☆☆

좋아하는 사이트 하나를 골라, 브라우저 개발자 도구로 색·폰트·간격을 관찰하고 변종 A 형식(YAML 토큰 + Overview/Colors/Typography 산문)으로 한 장 써 본다. Do's and Don'ts와 Known Gaps까지 채우면 진짜 명세서가 된다.

과제 5. 토큰 참조를 CSS 변수로 잇기 난이도 ★★★★☆

DESIGN.md의 토큰을 실제 CSS 커스텀 프로퍼티(:root 변수)로 변환하는 작은 스크립트를 짜 보라. {colors.primary} 참조를 var(--colors-primary)로 바꾸면, 명세서가 곧바로 동작하는 테마가 된다 — '디자인 토큰 파이프라인'을 손으로 구현하는 셈이다.

9관련 기술 심화 학습 로드맵

'디자인 토큰 기초 → DESIGN.md 읽기 → 직접 작성 → AI 워크플로 통합'의 4주 코스.

10핵심 키워드 사전

레포 문서에 반복되는 용어를 한 곳에.

11참고 링크

공식 저장소·개념 출처·문서.