설치가 필요한가

별도 프로그램은 필요 없습니다. 저장소에서 원하는 폴더의 DESIGN.md를 내려받아 프로젝트 루트에 복사합니다.

git clone --depth 1 https://github.com/VoltAgent/awesome-design-md.git

전체 저장소가 필요 없다면 GitHub에서 원하는 파일만 열어 내려받아도 됩니다.

적용 순서

  1. design-md 폴더나 getdesign.md 카탈로그에서 후보를 찾습니다.
  2. DESIGN.md와 preview.html을 함께 확인합니다.
  3. 기존 프로젝트 파일이 있다면 DESIGN-reference.md로 저장합니다.
  4. AI 코딩 도구에 참고 범위와 유지할 기능을 지시합니다.
  5. 한 페이지에 먼저 적용하고 모바일과 접근성을 확인합니다.
DESIGN-reference.md의 색상 위계와 간격 규칙만 참고해줘.
우리 로고와 콘텐츠 구조는 유지하고 홈 화면 한 곳에 먼저 적용해줘.
원본 사이트의 이미지와 고유 문구는 사용하지 마.

파일을 고르는 기준

  • 서비스의 정보 밀도와 비슷한가
  • 모바일 규칙이 충분히 설명돼 있는가
  • 필요한 라이트·다크 테마가 있는가
  • 버튼, 입력창과 표 규칙이 실제 제품에 맞는가
  • 색상 대비와 글자 크기를 그대로 적용해도 읽기 좋은가

후보를 두 개 이상 골랐다면 “멋있어 보이는가”보다 실제 화면 구조와 맞는지를 먼저 비교합니다. 예를 들어 관리 화면에는 표, 필터와 긴 폼의 규칙이 있는 자료가 필요하고, 콘텐츠 사이트에는 본문 폭, 제목 위계와 읽기 간격이 자세한 자료가 더 유용합니다. 필요한 컴포넌트가 없는 자료를 선택하면 AI가 빈 부분을 임의로 채워 결과가 일관되지 않기 쉽습니다.

작은 화면 하나에 적용하는 실전 흐름

먼저 원본 파일을 프로젝트 규칙과 섞지 않고 참고 자료로 둡니다.

docs/design-references/linear/DESIGN.md를 참고하되,
현재 src/styles/tokens.css의 변수 이름과 접근성 기준은 유지해줘.
설정 화면의 헤더와 기본 버튼만 수정하고 다른 화면은 건드리지 마.
적용 전후에 바뀌는 파일과 새 색상 토큰을 먼저 목록으로 보여줘.

수정 뒤에는 설명 문구보다 실제 결과를 확인합니다.

  1. 기존 CSS 변수와 새로 추가된 색상이 중복되지 않는지 봅니다.
  2. 기본, hover, focus, disabled 상태가 모두 구분되는지 확인합니다.
  3. 320px 폭에서 버튼과 긴 제목이 잘리지 않는지 확인합니다.
  4. 키보드만으로 이동했을 때 포커스 표시가 사라지지 않는지 봅니다.
  5. 라이트·다크 테마를 지원한다면 두 테마에서 본문과 버튼 대비를 확인합니다.

이 과정을 통과한 규칙만 프로젝트 고유 DESIGN.md에 “왜 선택했는지”와 함께 옮깁니다. 출처 파일 전체를 계속 주입하는 것보다 사용한 색상, 간격과 컴포넌트 원칙만 정리해야 다음 화면에서도 결과가 안정적입니다.

반드시 지킬 점

저장소는 해당 브랜드의 공식 디자인 시스템이 아니라 공개 화면을 독립적으로 분석한 자료라고 밝힙니다. 따라서 타사의 로고, 사진, 상표와 고유 일러스트는 가져오지 않고 시각 원칙만 참고해야 합니다. 결과가 원본과 혼동될 정도로 비슷하지 않은지도 확인합니다.

저장소 자체는 MIT 라이선스지만, 저장소 설명도 각 브랜드의 시각적 정체성을 소유한다고 주장하지 않습니다. MIT 문구만 보고 제3자의 로고, 상품 사진, 고유 카피까지 재사용할 권리가 생긴다고 해석하면 안 됩니다. 공개 출시 전에는 브랜드명, 이미지, 아이콘과 문구가 남아 있지 않은지 별도로 검색합니다.

DESIGN.md도 외부에서 받은 텍스트 파일입니다. AI 에이전트에 읽히기 전에 쉘 명령 실행, 외부 파일 업로드, 프로젝트 규칙 변경처럼 디자인과 무관한 지시가 들어 있지 않은지 훑어봅니다. 프로젝트의 AGENTS.md, 보안 규칙과 사용자의 명시적 요구가 언제나 참고 문서보다 우선하도록 범위를 프롬프트에 적어 두는 편이 안전합니다.

업데이트와 되돌리기

원본 자료가 바뀌어도 프로젝트의 DESIGN.md를 바로 덮어쓰지 않습니다. 새 버전을 별도 폴더에 받고 현재 기준과 차이를 확인합니다.

git -C awesome-design-md pull --ff-only
git diff --no-index docs/design-references/old/DESIGN.md docs/design-references/new/DESIGN.md

git diff --no-index는 차이가 있으면 종료 코드 1을 반환할 수 있으므로 내용이 표시됐다는 이유만으로 오류라고 판단할 필요는 없습니다. 새 규칙 중 필요한 항목만 프로젝트 토큰에 수동 반영하고 UI 테스트를 다시 실행합니다.

시험 적용을 되돌릴 때는 참고 파일 자체보다 실제로 수정된 컴포넌트와 토큰 파일을 기준으로 복구합니다. 적용 전 작은 커밋이나 새 브랜치를 만들어 두면 해당 변경만 명확히 비교할 수 있습니다. 다른 작업이 섞인 상태에서 전체 작업 트리를 강제로 초기화하지 말고, git diff -- <파일>로 대상 파일을 확인한 뒤 필요한 줄만 되돌리는 편이 안전합니다.

Awesome DESIGN.md는 무엇인가

Awesome DESIGN.md는 여러 유명 웹사이트의 공개된 시각 패턴을 분석해 DESIGN.md 형식으로 정리한 VoltAgent의 GitHub 모음입니다. 색상, 글꼴, 컴포넌트, 레이아웃, 반응형 규칙과 AI 프롬프트 가이드를 한 파일에서 참고할 수 있습니다.

분석 자료 폴더와 README를 확인할 수 있는 Awesome DESIGN.md 공식 GitHub 저장소

getdesign.md와 차이

Awesome DESIGN.md는 파일을 직접 살펴보는 GitHub 저장소입니다. getdesign.md는 같은 자료를 카테고리와 검색으로 둘러보기 쉽게 보여주며 특정 사이트의 맞춤 분석 요청도 안내합니다. 개발자에게는 GitHub 방식이 빠르고, 여러 후보를 비교하려면 웹 카탈로그가 편합니다.

추천 활용법

처음에는 한 자료를 통째로 적용하기보다 마음에 드는 두세 가지 규칙만 선택합니다. 예를 들어 제목 위계, 카드 간격과 주요 버튼 색상만 적용하고 실제 사용자 화면에서 검증한 뒤 프로젝트 고유 DESIGN.md로 다시 정리하는 방식이 가장 안정적입니다.