DESIGN.md로 AI 에이전트 UI 일관성 관리하기

프로젝트마다 달라지는 에이전트 UI를 묶는 텍스트 명세

AI 코딩 에이전트에게 UI를 맡기면 같은 프로젝트 안에서도 색상, 타이포그래피, 간격이 제각각 적용되기 쉽다. DESIGN.md는 이런 분산을 줄이기 위해 프로젝트 루트에 두는 플레인 텍스트 기반 디자인 시스템 명세다. 마크다운 파일 하나에 디자인 언어를 기록해 두면 에이전트가 프로젝트 컨텍스트를 읽을 때 같은 규칙을 참조할 수 있다.

Google Stitch에서 도입한 이 형식은 Figma 내보내기나 JSON 스키마, 별도 도구 없이 디자인 시스템을 기술한다. 색상 값 같은 정량 정보만 적는 문서가 아니다. 디자이너가 전달하던 시각적 분위기, 디자인 철학, 권장 사항과 금지 사항도 담는다.

2026년 3월 VoltAgent가 awesome-design-md 저장소를 공개한 뒤 GitHub 스타는 10일 만에 35,000개를 넘었다. 2026년 4월 기준으로는 66개 이상의 브랜드 디자인 시스템이 DESIGN.md 형식으로 공개됐다.

파일 안에 기록하는 디자인 언어

표준 DESIGN.md는 시각적 분위기부터 반응형 규칙, 컴포넌트 사용 원칙까지 다음 9개 영역을 다룬다.

섹션 구성:
(1) Visual Theme & Atmosphere - 전체 시각적 톤과 분위기 정의
(2) Colors - 기본, 보조, 중립 색상의 Hex 값과 사용 맥락
(3) Typography - 폰트 패밀리, 크기, 가중치, 적용 컨텍스트
(4) Spacing - 그리드 시스템과 간격 규칙
(5) Layout - 레이아웃 패턴과 반응형 동작 규칙
(6) Components - 버튼, 입력, 카드 등 컴포넌트별 스타일 명세
(7) Elevation - 그림자와 깊이 계층 정의
(8) Responsive Behavior - 브레이크포인트별 동작 규칙
(9) Do's and Don'ts - 디자인 권장 사항과 금지 사항

각 항목이 마크다운으로 쓰이므로 LLM은 별도 파서 없이 내용을 해석할 수 있다. 브랜드별 DESIGN.md에는 컴포넌트의 시각 카탈로그를 확인할 수 있는 preview.html 파일도 함께 제공된다.

토큰 값과 사용 맥락을 같이 전달한다

디자인 토큰은 색상, 간격, 타이포그래피 스케일처럼 시스템을 이루는 최소 단위다. DESIGN.md에서는 Hex 값과 해당 값의 사용 맥락을 자연어로 결합한다.

## Colors
- Primary: #0066FF (브랜드 주 색상, CTA 버튼과 핵심 인터랙션에 사용)
- Secondary: #6B7280 (보조 텍스트, 비활성 상태에 사용)
- Background: #FFFFFF (기본 배경)
- Surface: #F9FAFB (카드, 패널 배경)
- Error: #EF4444 (오류 상태, 경고 메시지)

Design Tokens Community Group(DTCG)의 JSON 기반 표준이 구조화된 데이터 교환에 집중한다면, DESIGN.md는 사람이 읽고 에이전트가 그대로 참조하는 방식을 우선한다. designtoken.md는 이 형식을 확장해 150줄 이상의 구조화된 토큰 정의와 컴포넌트 상태별 명세를 제공한다. 토큰 간 참조 관계인 alias도 텍스트로 표현할 수 있어 시맨틱 토큰 체계를 구성할 수 있다.

에이전트 컨텍스트에 디자인 규칙을 넣는 흐름

⤢✕

Google Stitch는 프롬프트를 제출할 때 design.md 전체 내용을 Gemini 컨텍스트로 전달한다. Claude Code는 프로젝트 루트의 DESIGN.md를 자동 인식해 UI 생성 시 참조한다. Cursor와 GitHub Copilot도 프로젝트 컨텍스트 읽기 기능을 통해 같은 파일을 활용할 수 있다.

이 방식의 핵심은 에이전트별로 별도 디자인 규칙을 만들지 않아도 된다는 점이다. 동일한 DESIGN.md를 프로젝트에 두면 에이전트 종류와 무관하게 통일된 디자인 출력을 목표로 할 수 있으며, 별도 플러그인이나 통합 작업 없이 마크다운 파일 하나로 적용한다.

Figma와 JSON 토큰 사이의 다른 선택지

항목	Figma 기반 디자인 시스템	JSON 토큰(DTCG)	DESIGN.md
형식	바이너리/클라우드	JSON	마크다운(텍스트)
AI 에이전트 호환성	낮음(API 필요)	중간(파싱 필요)	높음(직접 읽기)
정성적 맥락 포함	코멘트로 제한적	미지원	Do's/Don'ts, 분위기 기술
도구 의존성	Figma 필수	변환 도구 필요	텍스트 에디터만 필요
학습 곡선	높음	중간	낮음
버전 관리	Figma 자체	Git 호환	Git 네이티브
브랜드 철학 전달	별도 문서 필요	미지원	파일 내 통합 기술

DESIGN.md는 기술적으로 정확한 속성값을 전달하는 데서 멈추지 않고, 실제로 좋은 UI를 만들기 위한 정성적 지침까지 포함한다. Figma와 JSON 토큰이 정량적 값을 전달하는 데 강점이 있다면, DESIGN.md는 디자인 의도와 철학을 에이전트 컨텍스트에 함께 넣는 데 초점을 둔다.

브랜드 시스템을 에이전트 작업에 연결하는 방식

awesome-design-md 컬렉션에는 Vercel, Stripe, Supabase 같은 개발자 도구뿐 아니라 Tesla, BMW 같은 자동차 브랜드와 Notion, Linear 같은 생산성 앱의 디자인 시스템이 66개 이상 수록돼 있다.

Google Stitch는 웹 URL에서 디자인 시스템을 자동 추출해 DESIGN.md로 변환하고, Android, ChromeOS, Web UI 생성에 활용한다. 원하는 브랜드의 DESIGN.md를 프로젝트에 복사한 뒤 에이전트에게 인터페이스 구축을 지시하는 프로토타이핑 흐름도 가능하다. 공개 웹사이트의 디자인 요소를 분석해 DESIGN.md 형식으로 추출하는 디자인 시스템 역공학에도 쓰인다.

Google의 선언적 UI 프로토콜인 A2UI와 결합하면 멀티 에이전트 시스템에서 안전한 UI 렌더링을 구현하는 연결점이 된다. 실행 가능한 디자인 시스템 정의를 둔 뒤 preset AI 코딩 도구가 일관된 프로덕션 코드를 생성하는 활용도 포함된다.

파일을 두기 전에 정할 운영 기준

DESIGN.md가 커질수록 에이전트의 컨텍스트 윈도우를 더 소비하므로 토큰 예산을 관리해야 한다. 복잡한 인터랙션 패턴이나 애니메이션은 텍스트 명세만으로 표현하는 데 한계가 있다.

기존 Figma 워크플로우와 DESIGN.md 사이의 동기화 전략도 필요하다. 디자인 토큰이 바뀌면 DESIGN.md를 수동으로 업데이트해야 하므로 자동화 파이프라인 구축을 검토할 수 있다. designtoken.md 같은 확장 형식을 도입한다면 기존 DESIGN.md와의 호환성도 확인해야 한다.