AI 시대의 디자인 시스템 문서
DESIGN.md란 무엇이고 어떻게 사용하는가
AI 코딩 에이전트가 기능은 잘 만들지만 화면은 매번 다르게 만든다면, 문제는 프롬프트가 아니라 지속되는 디자인 문맥의 부재일 가능성이 큽니다. DESIGN.md는 그 문맥을 프로젝트 안에 고정하는 작은 Markdown 파일입니다.
1. DESIGN.md의 정의
DESIGN.md는 프로젝트 루트에 두는 디자인 시스템 설명 파일입니다. 보통 README.md가 프로젝트의 목적과 사용법을 설명하고, AGENTS.md가 코딩 에이전트에게 빌드 방식과 개발 규칙을 알려준다면, DESIGN.md는 AI에게 “이 제품은 어떤 화면처럼 보여야 하는가”를 알려줍니다.
Google의 공식 design.md 저장소는 이 파일을 시각 정체성을 코딩 에이전트에게 설명하기 위한 형식 명세로 소개합니다. 핵심 구조는 단순합니다. 파일 상단에는 YAML front matter로 기계가 읽기 좋은 디자인 토큰을 쓰고, 그 아래에는 Markdown 본문으로 사람이 읽기 좋은 디자인 의도와 사용 규칙을 적습니다. 즉, 숫자와 의미가 한 파일에 같이 들어갑니다.
이 방식은 기존 디자인 시스템 문서와 목적이 같습니다. 다만 대상 독자가 조금 다릅니다. 사람이 Figma, Storybook, 브랜드 가이드 PDF를 읽고 구현하던 규칙을 AI 에이전트가 바로 읽을 수 있는 텍스트로 바꾸는 것이 목표입니다. 그래서 DESIGN.md는 특별한 디자인 툴 파일이 아니라 Markdown입니다. Git에서 리뷰할 수 있고, pull request에서 변경 이력을 볼 수 있으며, 텍스트 기반 AI 도구가 컨텍스트로 삼기 쉽습니다.
한 줄로 요약하면, DESIGN.md는 “AI가 참고하는 디자인 시스템의 README”입니다. 색상, 글꼴, 간격, 라운드, 컴포넌트 규칙, 금지 패턴, 반응형 기준을 문서화해 UI 생성의 흔들림을 줄입니다.
Google Keyword 블로그는 Stitch의 DESIGN.md가 프로젝트 사이에서 디자인 규칙을 가져오고 내보내는 데 쓰이며, AI가 색상의 의도를 추측하지 않고 알 수 있게 하는 데 초점이 있다고 설명합니다. 2026년 기준 공개된 명세는 아직 alpha 상태이므로 장기적으로 세부 스키마가 바뀔 수 있지만, 프로젝트 안에 디자인 의사결정을 텍스트로 남긴다는 방향 자체는 이미 실무적으로 유용합니다.
2. 왜 필요한가
AI에게 “예쁘게 만들어줘”, “Apple스럽게 만들어줘”, “Linear 느낌으로 해줘”라고 말하면 빠르게 결과가 나옵니다. 하지만 같은 프로젝트 안에서 여러 화면을 만들수록 문제가 드러납니다. 첫 화면은 어두운 배경에 보라색 그라데이션이고, 두 번째 화면은 흰색 카드 중심이며, 세 번째 화면은 다른 버튼 반경과 다른 폰트 크기를 쓰는 식입니다. 기능은 구현됐지만 제품처럼 보이지 않는 상황이 생깁니다.
DESIGN.md는 이 문제를 “반복 프롬프트”가 아니라 “지속 문서”로 해결합니다. 에이전트가 새 컴포넌트를 만들 때마다 같은 색상 토큰, 같은 타이포그래피 단계, 같은 버튼 상태, 같은 여백 규칙을 참조하게 만듭니다. 특히 팀에서 AI 도구를 함께 쓸 때 효과가 큽니다. 사람마다 프롬프트 문장이 달라도 루트에 있는 디자인 문서가 기준점 역할을 하기 때문입니다.
중요한 점은 DESIGN.md가 디자이너를 대체하는 파일이 아니라는 것입니다. 좋은 디자인 시스템은 여전히 제품 전략, 사용자 맥락, 접근성, 정보 구조, 시각적 우선순위가 필요합니다. DESIGN.md는 그 판단을 AI가 읽을 수 있는 형태로 압축하고 보존하는 파일입니다. 사람이 한 번 정한 규칙을 에이전트가 매번 다시 추측하지 않게 만드는 장치에 가깝습니다.
3. 파일 안에 들어가는 내용
공식 명세에서 가장 중요한 구분은 2개의 층입니다. 첫 번째 층은 YAML front matter입니다. 여기에 색상, 글꼴, 간격, 라운드, 컴포넌트 토큰처럼 정확한 값이 들어갑니다. 두 번째 층은 Markdown 본문입니다. 여기에 브랜드 분위기, 색상의 의미, 버튼을 언제 써야 하는지, 어떤 레이아웃을 피해야 하는지 같은 판단 기준을 적습니다.
| 영역 | 무엇을 쓰는가 | AI에게 주는 효과 |
|---|---|---|
| 색상 | primary, secondary, surface, text, border, success, danger 등의 hex 값과 역할 | 버튼과 배경, 경고, 링크 색상이 화면마다 흔들리지 않음 |
| 타이포그래피 | h1, h2, body, caption, label의 font size, weight, line height | 제목 위계와 본문 밀도가 일정하게 유지됨 |
| 간격과 그리드 | spacing scale, container width, grid column, section padding | 화면이 카드 더미처럼 보이지 않고 리듬을 가짐 |
| 컴포넌트 | button, input, card, nav, modal, table의 기본 상태와 hover 상태 | 새 UI를 만들어도 기존 제품의 부품처럼 보임 |
| 금지 규칙 | 쓰지 말아야 할 색상, 그림자, 라운드, 레이아웃, 장식 | AI가 흔히 만드는 과장된 장식을 줄임 |
여기서 “정확한 값”과 “의도”가 모두 필요합니다. 예를 들어 #0066cc만 적으면 AI는 이 색상이 링크인지, CTA인지, 포커스인지 알기 어렵습니다. 반대로 “파란색을 주요 액션에 사용한다”라고만 쓰면 구현마다 다른 파란색이 나올 수 있습니다. 좋은 DESIGN.md는 #0066cc 같은 값과 “주요 상호작용에만 사용한다”는 문장을 같이 둡니다.
공식 명세에서 제안하는 대표 섹션
Google 저장소의 README는 파일 본문을 Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do's and Don'ts 같은 순서로 정리할 수 있다고 설명합니다. 모든 섹션을 반드시 길게 쓸 필요는 없지만, 팀이 자주 틀리는 영역은 구체적으로 적어야 합니다.
특히 AI 에이전트에게 유용한 부분은 금지 규칙입니다. 사람은 “우리 서비스는 차분한 B2B 도구라서 큰 히어로 그라데이션이 어울리지 않는다”는 맥락을 눈치로 이해할 수 있지만, AI는 그런 맥락을 자동으로 공유하지 않습니다. 그래서 Do not use decorative gradients, Do not nest cards inside cards, Use dense table layouts for admin workflows처럼 단정적인 규칙이 도움이 됩니다.
4. 실무 사용법
가장 단순한 사용법은 프로젝트 루트에 DESIGN.md를 만들고, AI 에이전트에게 “이 파일을 엄격히 따르면서 화면을 구현하라”고 지시하는 것입니다. Cursor, Codex, Claude Code, Gemini CLI, Windsurf처럼 프로젝트 파일을 읽는 도구라면 대체로 이런 문서를 컨텍스트로 사용할 수 있습니다. 다만 도구마다 자동 인식 방식은 다르므로 첫 작업에서는 파일을 명시적으로 언급하는 편이 안전합니다.
- 기존 제품이 있다면 실제 화면에서 색상, 폰트, 간격, 버튼, 카드, 테이블 패턴을 추출합니다.
- 새 제품이라면 먼저 브랜드 톤과 사용 맥락을 정합니다. SaaS 관리 도구인지, 소비자 앱인지, 문서 사이트인지에 따라 밀도와 장식 수준이 달라집니다.
- 상단 YAML에는 토큰을 적고, 본문에는 왜 그렇게 써야 하는지 설명합니다.
- AI에게 새 화면을 맡길 때 “DESIGN.md를 읽고 이 규칙을 우선 적용하라”고 지시합니다.
- 구현 후에는 화면 캡처, 접근성 대비, 토큰 사용 여부를 확인하고 문서를 갱신합니다.
검증 명령
Google의 공식 저장소는 @google/design.md 패키지를 통해 lint, diff, export 같은 명령을 제공합니다. lint는 구조와 토큰 참조, 대비 관련 경고를 확인하는 데 쓰고, diff는 디자인 시스템 변경 전후를 비교하는 데 사용합니다.
npx @google/design.md lint DESIGN.md
npx @google/design.md diff DESIGN.md DESIGN-v2.md
npx @google/design.md export --format css-tailwind DESIGN.md > theme.cssWindows PowerShell에서 패키지 이름의 @ 처리가 문제를 일으키는 환경이라면 설치 시 따옴표를 붙이는 방식이 안전합니다.
npm install "@google/design.md"검증이 중요한 이유는 단순합니다. AI가 읽기 좋은 문서는 사람이 보기에도 질서가 있어야 합니다. 끊어진 토큰 참조, 정의되지 않은 색상, 낮은 텍스트 대비, 순서가 뒤섞인 섹션은 에이전트의 출력 품질을 떨어뜨립니다. DESIGN.md를 코드처럼 관리하려면 변경할 때마다 lint와 리뷰를 거치는 습관이 필요합니다.
5. awesome-design-md 활용법
VoltAgent/awesome-design-md는 여러 유명 브랜드나 개발자 도구 사이트의 시각 스타일을 DESIGN.md 형태로 정리한 큐레이션 저장소입니다. README 기준으로 AI, 개발자 도구, 데이터베이스, 생산성 SaaS, 디자인 도구, 핀테크, 이커머스, 미디어, 자동차 등 다양한 카테고리의 예시가 있습니다. 각 사이트 항목은 해당 스타일의 분위기를 짧게 설명하고, 파일 묶음에는 보통 DESIGN.md, preview.html, preview-dark.html이 포함됩니다.
이 저장소의 가장 좋은 사용법은 “복사해서 그대로 브랜드를 흉내 내기”가 아니라 “AI가 이해하기 쉬운 디자인 서술 방식을 학습하기”입니다. 예를 들어 Vercel 스타일 문서를 보면 흑백 대비, Geist 계열 타이포그래피, 정밀한 레이아웃 같은 언어가 어떻게 문서화되는지 볼 수 있습니다. Linear 스타일 문서를 보면 미니멀한 표면, 보라색 액센트, 작은 인터랙션 밀도가 어떻게 표현되는지 참고할 수 있습니다. 중요한 것은 그 브랜드의 상표를 베끼는 것이 아니라, 내 제품의 규칙을 같은 정도로 명확하게 쓰는 것입니다.
개인 프로젝트나 프로토타입에서는 원하는 분위기와 가까운 파일을 골라 루트에 넣고 빠르게 실험할 수 있습니다. 다만 상용 제품에서는 반드시 조정이 필요합니다. 공개 웹사이트에서 관찰한 색상과 UI 패턴은 참고 자료일 뿐이며, 특정 브랜드의 시각 정체성을 그대로 복제하는 것은 법적, 윤리적 문제가 될 수 있습니다. 안전한 접근은 “Stripe와 똑같이”가 아니라 “결제 인프라 제품처럼 신뢰감 있고 명확하게, 단 우리 색상과 컴포넌트로”입니다.
awesome-design-md를 쓰는 3가지 방식
| 방식 | 언제 쓰는가 | 주의점 |
|---|---|---|
| 레퍼런스 읽기 | 좋은 DESIGN.md 문장 구조를 배우고 싶을 때 | 내 제품 맥락으로 다시 써야 함 |
| 프로토타입 적용 | 빠르게 UI 방향성을 비교하고 싶을 때 | 상표, 로고, 고유 브랜드 요소는 제거해야 함 |
| 팀 템플릿 제작 | 여러 프로젝트에서 공통 디자인 규칙을 재사용할 때 | 토큰 이름과 컴포넌트 키를 팀 표준으로 맞춰야 함 |
6. 바로 쓸 수 있는 예시
아래는 작은 SaaS 제품을 위한 최소 예시입니다. 실제 프로젝트에서는 제품명, 브랜드 톤, 색상 역할, 컴포넌트 상태, 레이아웃 밀도, 반응형 기준을 더 자세히 채워야 합니다. 핵심은 값만 나열하지 말고, 각 값이 어떤 상황에서 쓰이는지 함께 적는 것입니다.
---
version: "alpha"
name: "Atlas Console"
description: "운영팀을 위한 조용하고 밀도 높은 SaaS 관리 도구"
colors:
primary: "#0066cc"
text: "#1d1d1f"
muted: "#7a7a7a"
surface: "#ffffff"
surfaceSubtle: "#f5f5f7"
border: "#e0e0e0"
typography:
h1:
fontFamily: "Inter"
fontSize: "40px"
fontWeight: 600
lineHeight: 1.1
body:
fontFamily: "Inter"
fontSize: "17px"
fontWeight: 400
lineHeight: 1.55
rounded:
sm: "6px"
md: "8px"
spacing:
sm: "8px"
md: "16px"
lg: "24px"
components:
button-primary:
backgroundColor: "{colors.primary}"
textColor: "#ffffff"
rounded: "{rounded.sm}"
padding: "10px 16px"
---
## Overview
Atlas Console은 반복 업무를 처리하는 운영팀용 제품이다.
마케팅 사이트처럼 장식적인 히어로를 만들지 말고, 표와 필터와 상태 정보를 빠르게 스캔할 수 있는 조용한 인터페이스를 우선한다.
## Colors
Primary Blue는 주요 저장, 실행, 연결 액션에만 사용한다.
본문과 테이블은 고대비 검정 계열을 사용하고, 보조 설명에는 muted를 사용한다.
## Components
Primary button은 페이지당 1개 또는 2개로 제한한다.
카드 안에 카드를 중첩하지 말고, 반복 항목은 테이블이나 리스트로 표현한다.
## Do's and Don'ts
Do use dense tables for operational workflows.
Do not use decorative gradients, oversized hero sections, or floating marketing cards.
이 예시를 루트에 저장한 뒤 AI에게 다음처럼 요청할 수 있습니다.
DESIGN.md를 먼저 읽고, 그 규칙을 따라 관리자 대시보드의 사용자 목록 화면을 구현해줘.
새로운 색상이나 임의의 그라데이션을 추가하지 말고, 버튼과 테이블은 DESIGN.md의 컴포넌트 규칙을 따라줘.프롬프트에서 중요한 부분은 “읽어라”와 “따르라”를 함께 말하는 것입니다. 단순히 파일이 존재한다고 해서 모든 도구가 항상 완벽히 우선순위로 삼는 것은 아닙니다. 첫 요청에서 파일명을 명시하고, 결과 리뷰 때 “이 UI가 DESIGN.md의 금지 규칙을 어긴 곳이 있는지 먼저 점검하라”고 지시하면 품질이 안정됩니다.
도입 순서
이미 운영 중인 프로젝트라면 새 디자인을 만들기 전에 현재 UI를 정리하는 편이 낫습니다. 먼저 대표 화면 3개에서 5개를 고르고, 실제 사용 중인 색상과 폰트 크기와 컴포넌트 패턴을 뽑습니다. 그 다음 중복되거나 충돌하는 규칙을 정리합니다. 예를 들어 버튼 반경이 6px, 8px, 12px로 섞여 있다면 하나의 기준을 선택합니다. 이렇게 정리한 뒤 DESIGN.md에 반영해야 AI도 흔들리지 않습니다.
새 프로젝트라면 반대로 너무 많은 토큰을 만들지 않는 것이 좋습니다. 첫 버전에는 색상 6개에서 10개, 타이포그래피 4단계에서 6단계, 간격 5단계 정도면 충분합니다. 실제 화면을 만들면서 부족한 토큰을 추가하는 방식이 유지보수에 유리합니다. 디자인 시스템은 작성으로 끝나는 문서가 아니라, 구현 결과를 보며 계속 다듬는 운영 문서입니다.
실무에서 자주 생기는 오해
첫 번째 오해는 DESIGN.md가 있으면 AI가 자동으로 훌륭한 UI를 만든다는 생각입니다. 실제로는 문서의 품질이 결과를 결정합니다. “모던하고 깔끔하게”처럼 추상적인 문장만 있으면 AI는 다시 흔한 패턴으로 돌아갑니다. 색상 역할, 여백 기준, 컴포넌트 상태, 금지 패턴을 구체적으로 써야 합니다.
두 번째 오해는 DESIGN.md가 Figma를 대체한다는 생각입니다. Figma는 여전히 탐색, 협업, 고해상도 시각 작업, 프로토타이핑에 강합니다. DESIGN.md는 그 결과를 AI가 구현할 수 있는 규칙으로 번역하는 데 강합니다. 따라서 둘은 경쟁 관계보다 연결 관계에 가깝습니다.
세 번째 오해는 유명 브랜드의 DESIGN.md를 그대로 복사하면 제품 품질이 올라간다는 생각입니다. 오히려 제품의 정보 구조와 사용자 과업에 맞지 않는 스타일을 가져오면 사용성이 떨어질 수 있습니다. 예를 들어 영화적이고 어두운 랜딩 페이지 감성은 창작 도구에는 어울릴 수 있지만, 병원 예약 백오피스나 재무 승인 화면에는 방해가 될 수 있습니다.
좋은 기준은 다음과 같습니다. 제품의 사용자가 반복적으로 비교하고 입력하고 승인하는 사람이라면 조용하고 밀도 높은 규칙을 둡니다. 브랜드 인상을 강하게 남겨야 하는 소비자 캠페인이라면 이미지, 큰 타이포그래피, 움직임의 기준을 더 자세히 둡니다. 문서 사이트라면 읽기 폭, 코드 블록, 목차, 검색, 경고 박스의 규칙이 중요합니다. DESIGN.md는 예쁜 화면을 위한 문서가 아니라 목적에 맞는 일관성을 위한 문서입니다.
FAQ
결론
DESIGN.md는 AI 코딩 시대에 디자인 일관성을 지키기 위한 가벼운 프로토콜입니다. 특별한 도구가 아니라 Markdown 파일이고, 핵심은 색상과 글꼴 같은 수치 토큰을 디자인 의도와 함께 보관하는 데 있습니다. 이 파일이 있으면 에이전트는 매번 취향을 새로 추측하지 않고, 프로젝트가 정한 시각 언어를 기준으로 화면을 만들 수 있습니다.
처음 도입할 때는 거대한 문서를 목표로 하지 마세요. 지금 제품에서 반드시 지켜야 할 색상, 제목과 본문 크기, 버튼과 입력창의 모양, 레이아웃 밀도, 하지 말아야 할 장식을 먼저 적으면 충분합니다. 그 다음 AI가 만든 화면을 보며 규칙을 업데이트하면 됩니다. awesome-design-md는 이런 문서를 어떻게 쓰는지 배우기에 좋은 참고 자료이고, Google의 공식 명세와 CLI는 문서를 더 체계적으로 관리하는 출발점입니다.
출처
'AI' 카테고리의 다른 글
| MCP 정확히 이해하기: AI 스킬과 도구 연결 표준의 차이 (0) | 2026.05.28 |
|---|---|
| Superpowers? 그래서 그게 뭔데? AI 코딩 에이전트 스킬 프레임워크 정리 (0) | 2026.05.27 |
| Gemini로 TOEIC 공부하자: YBM 퀴즈와 AI 피드백 루틴 (0) | 2026.05.27 |
| AI Skill 마켓플레이스 SkillsMP 사용법: 검색부터 개발까지 (0) | 2026.05.21 |
| GPT Image 2 프롬프트 스킬 완벽 가이드 - wuyoscar의 162개 프롬프트 라이브러리 분석 (1) | 2026.04.30 |
