AI 코딩 에이전트에게 “Vercel처럼 깔끔하게”, “Stripe 느낌으로”, “Cursor 스타일로”라고 말하면 어느 정도 분위기는 따라오지만, 결과는 자주 흔들린다. 모델은 브랜드의 색, 간격, 타입 스케일, 카드 밀도, 버튼 반경 같은 세부 규칙을 즉석에서 추측하기 때문이다.
VoltAgent/awesome-design-md는 이 문제를 DESIGN.md 파일로 풀어보려는 컬렉션이다. Claude, Vercel, Stripe, Cursor, Raycast, Supabase, VoltAgent 같은 웹사이트의 시각 언어를 마크다운 문서로 정리해두고, AI 에이전트가 UI를 만들 때 그 문서를 참고하도록 하는 방식이다.
핵심은 복잡한 디자인 툴 연동이 아니다. 원하는 사이트 폴더에서 DESIGN.md를 가져와 프로젝트 루트에 놓고, 에이전트에게 “이 DESIGN.md를 기준으로 페이지를 만들어줘”라고 말하는 것이다. AGENTS.md가 코딩 에이전트에게 “어떻게 빌드할지”를 알려준다면, DESIGN.md는 “어떻게 보이고 느껴져야 하는지”를 알려주는 보조 문서에 가깝다.
Awesome DESIGN.md 개요
이 저장소는 실행형 앱이나 CLI가 아니라, 바로 복사해 쓸 수 있는 디자인 문서 모음이다. 루트의 README.md는 컬렉션을 카테고리별로 나누고, 실제 자료는 design-md/<site>/DESIGN.md 형태로 들어 있다.
조사 시점의 checkout 기준으로는 design-md 아래에 71개의 사이트 폴더가 있었고, 각 폴더는 대체로 다음 구조를 가진다.
design-md/
stripe/
DESIGN.md
README.md
vercel/
DESIGN.md
README.md
claude/
DESIGN.md
README.md
README의 컬렉션 목록은 AI/LLM 플랫폼, 개발자 도구, 백엔드·DevOps, 생산성 SaaS, 디자인·크리에이티브 툴, 핀테크, 이커머스, 미디어, 자동차 등으로 나뉜다. 예를 들어 AI 쪽에는 Claude, Cohere, ElevenLabs, Mistral AI, Ollama, Replicate, Together AI, xAI가 있고, 개발자 도구 쪽에는 Cursor, Expo, Lovable, Raycast, Superhuman, Vercel, Warp가 있다.
DESIGN.md가 담는 정보
각 DESIGN.md는 단순한 컬러 목록보다 훨씬 구체적이다. Vercel 예시는 흰 캔버스, Geist 계열 타이포그래피, shadow-as-border 패턴, 워크플로별 액센트 색상을 설명한다. Claude 예시는 크림색 캔버스, 따뜻한 코럴 CTA, 세리프 계열 디스플레이 헤드라인을 정리한다. VoltAgent 예시는 거의 검은 배경, 에메랄드 액센트, 터미널/IDE 느낌의 개발자 브랜드 언어를 문서화한다.
README가 안내하는 확장 섹션은 다음 흐름이다.
- 시각적 분위기와 테마
- 색상 팔레트와 역할
- 타이포그래피 규칙
- 버튼, 카드, 입력창, 내비게이션 같은 컴포넌트 스타일
- 레이아웃 원칙과 간격 체계
- 그림자, 표면, elevation 규칙
- 해야 할 것과 피해야 할 것
- 반응형 동작
- 에이전트에게 바로 넣을 수 있는 프롬프트 힌트
이 정도로 써두면 에이전트에게 “예쁘게”라고 말하는 대신 “이 색상 역할, 이 폰트 스케일, 이 카드 규칙을 지켜라”라고 말할 수 있다. 특히 랜딩 페이지, 대시보드, 문서 사이트, 제품 소개 페이지처럼 브랜드 분위기가 중요한 UI 작업에서 효과가 크다.
사용법
공식 README 기준 사용법은 매우 단순하다.
# 1. 원하는 사이트 폴더에서 DESIGN.md를 고른다.
# 예: design-md/vercel/DESIGN.md
# 2. 내 프로젝트 루트로 복사한다.
cp design-md/vercel/DESIGN.md ./DESIGN.md
# 3. AI 코딩 에이전트에게 이 파일을 참고하라고 지시한다.
# 예: "DESIGN.md를 기준으로 pricing page를 만들어줘."
실제로는 전체 저장소를 clone한 뒤 필요한 파일만 가져오거나, GitHub에서 특정 DESIGN.md를 열어 복사해도 된다. README의 각 항목은 getdesign.md/<site>/design-md 페이지로 연결되어 있어, 웹에서 바로 내용을 보고 다운로드하는 흐름도 가능하다.
git clone https://github.com/VoltAgent/awesome-design-md.git
이 저장소에는 package.json이나 별도 실행 바이너리가 없었다. 따라서 “설치해서 쓰는 도구”라기보다 “에이전트에게 먹일 디자인 컨텍스트 라이브러리”로 보는 것이 맞다.
활용 포인트
첫째, AI 에이전트 UI 작업의 시작점을 빠르게 잡을 수 있다. 빈 화면에서 “SaaS 랜딩 페이지를 만들어줘”라고 요청하는 대신, “design-md/vercel/DESIGN.md의 레이아웃 밀도와 타이포그래피를 참고해 제품 소개 페이지를 만들어줘”처럼 지시할 수 있다.
둘째, 스타일 수정 루프를 줄이는 데 좋다. 에이전트가 매번 다른 보라색, 다른 카드 반경, 다른 버튼 높이를 고르는 대신, 문서에 적힌 디자인 토큰과 컴포넌트 규칙을 반복해서 참조하게 만들 수 있다.
셋째, 팀 내부 디자인 가이드의 초안으로도 쓸 수 있다. 특정 브랜드를 그대로 복제하는 목적이 아니라, “우리 서비스는 어떤 밀도, 어떤 대비, 어떤 타입 스케일을 선호하는가”를 논의할 때 샘플 문서로 삼기 좋다. 특히 자체 DESIGN.md를 만들기 전 구조 참고용으로 유용하다.
넷째, 에이전트별 컨텍스트 파일과 함께 쓰기 쉽다. AGENTS.md, CLAUDE.md, .cursorrules가 코드 품질과 작업 방식에 대한 지침이라면, DESIGN.md는 UI 결과물의 표면 품질에 대한 지침이다. 둘을 같이 두면 “이 프로젝트는 이렇게 만들고, 이렇게 보여야 한다”를 동시에 전달할 수 있다.
주의할 점
첫째, 이 문서들은 각 브랜드의 공식 디자인 시스템이 아니다. README도 “공개 웹사이트에서 추출한 디자인 시스템 문서”이며 “as is, without warranty”라고 설명한다. 색상과 패턴은 참고용으로 쓰되, 특정 회사의 공식 가이드라인이나 상표 사용 허가처럼 다루면 안 된다.
둘째, 브랜드 모방과 영감의 경계를 구분해야 한다. 내부 프로토타입이나 개인 실험에서는 빠른 레퍼런스로 유용하지만, 공개 제품에서 특정 서비스의 시각 정체성을 지나치게 베끼면 법무·브랜드 리스크가 생길 수 있다. 완성본에는 자기 제품의 색, 타이포그래피, 아이콘, 카피를 다시 입히는 편이 안전하다.
셋째, 컬렉션 수와 웹 미리보기 상태는 빠르게 바뀔 수 있다. README에는 DESIGN.md count 배지와 preview.html, preview-dark.html 언급이 있지만, 조사 시점의 GitHub checkout에서는 per-site DESIGN.md와 README.md 중심으로 확인됐다. 미리보기와 다운로드는 getdesign.md 웹 페이지에서 함께 제공되는 흐름으로 보는 것이 좋다.
넷째, DESIGN.md를 에이전트 컨텍스트에 넣는다고 해서 결과가 자동으로 픽셀 퍼펙트가 되지는 않는다. 모델과 프레임워크, 기존 컴포넌트 구조, CSS 리셋, 이미지 자산 유무에 따라 결과가 달라진다. 실제 프로젝트에서는 한 번 생성한 뒤 스크린샷 비교, 접근성 체크, 모바일 반응형 확인을 추가로 해야 한다.
다섯째, 외부 문서를 그대로 프로젝트 루트에 넣기 전에는 내용을 읽어야 한다. 이 저장소의 DESIGN.md들은 디자인 설명 중심이지만, 에이전트가 읽는 컨텍스트 파일은 곧 행동 지침이 된다. 다른 출처에서 가져온 DESIGN.md나 AGENTS.md를 섞을 때는 숨은 명령, 외부 링크, 불필요한 브랜드 지시가 없는지 확인하는 습관이 필요하다.
내 판단
awesome-design-md는 AI 코딩 에이전트 시대의 “디자인 프롬프트 레퍼런스 북”에 가깝다. Figma 파일이나 토큰 패키지처럼 엄격한 소스 오브 트루스는 아니지만, 에이전트에게 UI 감각을 전달하는 텍스트 컨텍스트로는 충분히 실용적이다.
가장 좋은 사용처는 빠른 프로토타이핑과 스타일 방향성 탐색이다. “이 제품은 Vercel처럼 절제된 개발자 인프라 톤”, “이 대시보드는 Stripe처럼 부드러운 금융 SaaS 톤”, “이 AI 도구는 Claude처럼 따뜻한 editorial 톤”처럼 초반 방향을 잡을 때 효과가 있다.
반대로 운영 중인 제품의 최종 디자인 시스템으로 그대로 채택하기에는 부족하다. 실서비스라면 이 문서를 출발점으로 삼되, 실제 브랜드 자산, 접근성 기준, 컴포넌트 구현, 토큰 네이밍, 라이선스·상표 검토까지 거쳐 자기 프로젝트의 DESIGN.md로 다시 정리하는 편이 좋다.