[번역] 모든 프로젝트를 위한 강력한 DESIGN.md 파일 만들기
Soshy·
AI 코딩 에이전트로 UI를 개발해본 개발자라면 누구나 이 답답함을 알고 있을것이라 생각합니다. Cursor나 Claude Code를 열고 앱의 새 화면을 만들어 달라고 요청하면, 돌아오는 결과물은... 그럭저럭 괜찮습니다. 기술적으로는 맞고, 동작도 합니다. 그런데 버튼 색이 파란색이긴 한데 미묘하게 다른 색조입니다. 폰트 크기도 다르고, 간격도 제품의 나머지 부분과 맞지 않습니다. 그리고 모서리 둥글기는 디자인 시스템에서 지정한 것과 전혀 다른 값이 적용되어 있습니다. 수정하고, 다음 컴포넌트로 넘어가면, 똑같은 일이 반복됩니다.
이건 에이전트의 버그가 아닙니다. 컨텍스트 문제입니다. 언어 모델은 모든 프롬프트를 독립적으로 처리하며, 프로젝트 저장소 안에 영구적인 시각적 레퍼런스가 없으면 생성되는 컴포넌트는 매번 학습 분포의 확률 곡선과 새롭게 협상한 결과물이 됩니다. 다시 말해, 지속적인 진실의 원천(source of truth)이 없으면 AI는 매번 미적(aesthetic) 결정을 처음부터 내리는 것입니다.
DESIGN.md는 이 문제의 해결책입니다. 그리고 생각보다 단순합니다.
DESIGN.md란 무엇인가
DESIGN.md는 AI 코딩 에이전트나 AI 빌더가 일관된 사용자 인터페이스를 구축하는 데 사용하는 시각적 규칙, 즉 색상, 타이포그래피, 간격, 컴포넌트 패턴 등을 담은 마크다운 파일입니다. 매 세션마다 프롬프트로 디자인 시스템을 설명하는 대신, 프로젝트 루트에 파일 하나를 두면 코드베이스를 다루는 모든 AI 에이전트가 무언가를 생성하기 전에 자동으로 이 파일을 읽습니다.
가장 정확한 비유는 이렇습니다. DESIGN.md의 디자인에 대한 역할은 AGENTS.md의 코드 컨벤션에 대한 역할과 같습니다. 에이전트가 모든 상호작용에서 참고하는 지속적인 컨텍스트입니다.
형식은 의도적으로 혼합형으로 설계되었습니다. 상단에는 머신이 읽을 수 있는 디자인 토큰이 YAML 형식으로 작성됩니다. 정확한 hex 코드, 폰트 크기, 간격 값, 모서리 반경, 컴포넌트 스타일이 여기에 담깁니다. 그 아래 마크다운 본문에는 해당 값들이 왜 존재하는지, 어떻게 적용해야 하는지를 사람이 읽기 쉬운 언어로 설명합니다. "무엇"과 "왜"를 분리하는 것이 핵심 설계 아이디어입니다. 토큰은 에이전트에게 정확한 값을 알려주고, 산문(prose)은 그 값의 의도를 설명합니다. 덕분에 파일에서 정의하지 않은 케이스를 만나도 에이전트가 합리적인 판단을 내릴 수 있습니다.
어떤 기술 분석에서 표현했듯, #B8422E라는 값만으로는 "이 색이 인터랙션 전용이다"라는 의도까지 전달할 수 없습니다. "Boston Clay를 유일한 인터랙션 색상으로 사용한다"는 설명이 함께 있어야 모델이 그 의도를 정확히 이해할 수 있습니다.
해결하는 문제: 규모에서의 불일관성
Bolt, Lovable, v0, Cursor, Claude Code 같은 바이브 코딩 도구를 사용해봤다면 이미 경험했을 겁니다. AI 도구는 기본적으로 일반적인 미적 감각에 의존합니다. 둥근 모서리, 파스텔 그라데이션, SaaS 템플릿 분위기. 컨텍스트 없이는 모든 제품이 다른 제품처럼 보이게 됩니다.
문제는 이 도구들에 디자인 감각이 없어서가 아닙니다. 생성할 때마다 브랜드를 기억하지 못하기 때문입니다. 공유된 레퍼런스가 없으면, 화면마다 색상이 조금 다르고, 간격이 조금 다르고, 폰트가 조금 다른 식으로 차이가 쌓여 결국 일관성 없는 UI가 됩니다.
"이 색상은 플로우의 주요 액션에만 사용한다"는 규칙은 토큰 파일로 표현할 수 없습니다. 그건 의미론(semantics)이고, 의미론은 산문 안에 존재하기 때문입니다. DESIGN.md는 YAML 토큰(머신을 위한 정확한 값)과 마크다운 산문(에이전트를 위한 의미론)을 하나의 파일에 결합합니다. 빌드 파이프라인도, 번들러도, 독점 도구도 필요 없습니다. 모델이 읽고 적용하는 단일 파일입니다.
탄생 배경
2026년 3월, Google Stitch는 무한 캔버스, 프로젝트 메모리를 가진 디자인 에이전트, 즉각적인 프로토타이핑, 음성 인터랙션을 포함한 업데이트의 일환으로 DESIGN.md를 도입했습니다. Stitch는 UI 프로토타이핑을 빠르게 진행해야 하는 프로덕트 디자이너와 프론트엔드 개발자를 대상으로 Gemini 기반으로 만들어진 Google Labs의 AI 디자인 도구입니다.
이 형식은 개발자들이 자체 버전을 작성하기 시작하면서 Stitch를 넘어 빠르게 퍼졌습니다. 그리고 2026년 4월 21일, Google은 GitHub에 Apache 2.0 라이선스로 이 스펙을 오픈소스로 공개했습니다. 목표는 DESIGN.md가 특정 도구나 플랫폼에 종속되지 않고 범용적으로 사용되는 것입니다. AI 에이전트는 의도를 추측하는 대신 색상이 어떤 용도인지 정확히 알고, WCAG 접근성 규칙에 따라 선택을 검증할 수 있게 됩니다.
Google이 발표하자 커뮤니티도 빠르게 움직였습니다. 레퍼런스 저장소인 VoltAgent/awesome-design-md에는 이미 Stripe, Vercel, Linear, Notion, Cursor, Anthropic의 Claude, ElevenLabs, Mistral AI 등 주요 테크 브랜드에서 영감을 받은 69개 이상의 DESIGN.md 파일이 올라와 있습니다.
파일 구조
DESIGN.md는 일관된 형식을 따릅니다. 최상단에는 --- 구분자 사이에 YAML 프론트매터 블록이 위치합니다. 머신이 읽을 수 있는 토큰이 여기에 담깁니다. 스키마는 버전, 이름, 설명, 색상, 타이포그래피, 모서리 반경 스케일, 간격 스케일, 컴포넌트 정의를 포함합니다.
YAML 블록 아래 마크다운 본문은 표준 헤딩 마커로 구성된 섹션으로 나뉩니다. 정식 순서에 따라 여덟 개 섹션으로 구성됩니다: 브랜드 아이덴티티, 색상 팔레트(정확한 값과 의미론적 규칙 포함), 타이포그래피(서체, 타입 스케일, 줄 높이), 간격(임의 값 없이 이산적 스케일), 모서리 반경, 그림자, 핵심 컴포넌트(버튼, 카드, 인풋, 모달)와 그 변형, 그리고 파일에서 다루지 않는 케이스를 에이전트가 추론할 수 있도록 선택의 근거를 설명하는 디자인 근거 섹션입니다.
다음은 공식 Google 스펙 예시를 기반으로 한 최소한이지만 완전한 DESIGN.md의 실제 모습입니다:
name: Heritage
colors:
primary: "#1A1C1E"
secondary: "#6C7278"
tertiary: "#B8422E"
neutral: "#F7F5F2"
typography:
h1:
fontFamily: Public Sans
fontSize: 3rem
body-md:
fontFamily: Public Sans
fontSize: 1rem
rounded:
sm: 4px
md: 8px
spacing:
sm: 8px
md: 16px
개요: 건축적 미니멀리즘과 저널리즘적 중후함의 만남. UI는 고급 무광 마감, 즉 고급 광지(broadsheet)나 현대 갤러리를 연상시킵니다.
색상: 팔레트는 고대비 중성색과 단일 액센트 색상을 기반으로 합니다. Primary(#1A1C1E)는 헤드라인과 핵심 텍스트를 위한 진한 잉크색입니다. Tertiary(#B8422E), "Boston Clay"라 명명된 이 색상은 인터랙션의 유일한 구동 색상으로, 버튼과 링크에만 독점적으로 사용됩니다.
이 접근 방식은 단순히 "primary는 #1A1C1E"가 아니라 "이 색은 편집실의 단호함을 담은 진한 잉크색으로 헤드라인에 사용한다"는 방식입니다. 이것이 에이전트가 디자인 의도를 파싱할 수 있게 만드는 핵심입니다.
내장된 접근성
이 형식에서 실용적으로 가장 중요한 특징 중 하나는 접근성이 기본으로 강제된다는 점입니다. 린터는 모든 컴포넌트의 배경색/텍스트색 조합에 대해 WCAG AA를 기본으로 검증합니다. 선택 사항이 아니라 형식의 핵심입니다. AI 에이전트는 별도로 강제하지 않으면 색상 대비를 무시하는 경향이 있기 때문에 이 부분은 특히 중요합니다.
스펙은 접근성을 위해 WCAG AA/AAA 기준에 따라 색상 선택을 검증하도록 요구합니다. 법적 규정 준수가 필요한 프로젝트를 진행 중이라면 든든한 지원군이 생기는 셈입니다. 접근성이 법적 요구 사항인 의료, 금융, 교육, 정부 분야 제품을 만드는 팀에게는 이것만으로도 도입할 충분한 이유가 됩니다.
CLI 툴체인
Google은 스펙과 함께 npm에 @google/design.md로 게시된 커맨드라인 인터페이스를 제공합니다. 모든 것이 npx로 실행되므로 전역 설치가 필요 없습니다. CLI는 네 가지 핵심 명령을 제공합니다:
Lint는 DESIGN.md에 대한 검증을 실행합니다. 깨진 토큰 참조, WCAG 대비율 실패, 누락된 섹션, 사용되지 않는 토큰을 확인합니다. 에이전트가 직접 활용할 수 있는 구조화된 JSON을 반환하며, 오류가 발견되면 코드 1로 종료됩니다.
Diff는 두 버전의 DESIGN.md 파일을 비교하여 추가, 제거, 수정된 토큰을 정확히 보여줍니다. 의도치 않은 디자인 시스템 드리프트를 잡아내기 위한 CI 파이프라인에서 특히 유용합니다. "after" 파일에 "before"보다 더 많은 오류나 경고가 있으면 코드 1로 종료됩니다.
Export는 DESIGN.md를 Tailwind 설정이나 W3C Design Token Community Group(DTCG) 파일 같은 형식으로 변환합니다. 기존 빌드 시스템 및 디자인 툴링과의 상호운용성을 제공합니다.
Spec은 전체 DESIGN.md 형식 스펙을 출력합니다. 에이전트가 파일 형식 자체를 이해하도록 에이전트 프롬프트에 스펙 컨텍스트를 주입할 때 유용합니다.
지원하는 AI 에이전트
프로젝트 파일을 읽을 수 있는 모든 에이전트는 DESIGN.md를 활용할 수 있습니다. Claude Code, Cursor, Kiro, Windsurf, Google Stitch 등이 포함됩니다. 마크다운 형식은 범용적입니다. 플러그인, 통합, 벤더 종속이 필요 없습니다. 프로젝트 루트에 파일을 두면 컨텍스트 파일을 스캔하는 에이전트가 자동으로 인식합니다.
Stitch의 MCP 서버와 SDK를 통해 DESIGN.md는 Claude Code, Cursor, Google의 Antigravity를 포함한 개발 도구와 연결될 수 있습니다. 이는 디자이너가 정의한 시각적 스펙을 개발자가 코드를 작성할 때 자동으로 따르게 됩니다. Cursor의 경우 .cursorrules 설정에서 파일을 참조하고, Claude Code는 CLAUDE.md에서, Kiro는 .kiro/steering 디렉토리에 추가합니다.
이해해야 할 핵심 차이점이 있습니다. JSON 형식의 디자인 토큰은 툴링과 빌드 파이프라인이 필요합니다. DESIGN.md는 순수 마크다운으로, 추가 도구 없이 사람과 LLM 모두 읽을 수 있습니다. 토큰은 빌드 시스템을 위한 것이고, DESIGN.md는 AI 에이전트를 위한 것입니다.
처음부터 작성하지 않고 시작하는 방법
첫 번째 DESIGN.md를 만드는 현실적인 방법은 세 가지입니다.
첫 번째는 Google Stitch를 통해 생성하는 것입니다. Stitch에서 바로 무료로 커스텀 파일을 생성할 수 있으며, 전체 스펙은 Stitch 사이트에 문서화되어 있습니다. 이미 Stitch를 사용하고 있다면 내보내기가 플랫폼에 기본으로 내장되어 있습니다.
두 번째는 기존 라이브러리에서 가져오는 것입니다. designmd.ai와 designmd.app의 커뮤니티 관리 라이브러리에는 미니멀 SaaS, 대시보드 중심 도구, 다크 모드 개발자 제품 등 수십 가지 미적 방향에 대한 사전 제작된 DESIGN.md 파일이 있습니다. 세 단계면 됩니다: 라이브러리를 둘러보고, 원하는 디자인 시스템을 단일 DESIGN.md 파일로 다운로드하고, 저장소 루트에 드래그 앤 드롭합니다.
세 번째는 직접 작성하는 것인데, 생각보다 어렵지 않습니다. 잘 쓰인 DESIGN.md는 시니어 디자이너가 신입에게 첫날 브리핑하는 것처럼 읽힙니다. 제품이 무엇인지, 어떤 개성을 갖는지, 우리가 하는 것과 절대 하지 않는 것. 제품 소개 다섯 문장과 서너 가지 디자인 원칙으로 시작하고, 색상 팔레트에 의미론적 레이블을 붙이고, 타입 스케일을 표로 정의하고, 간격 단위와 스케일을 명시하고, 핵심 컴포넌트를 설명한 뒤 CLI 린터로 검증하면 됩니다. 그게 전부입니다.
Figma를 대체하는가?
아닙니다. Figma, Storybook, 또는 코딩된 컴포넌트 라이브러리에서 관리하는 전통적인 디자인 시스템은 포괄적입니다. Figma는 여전히 결정이 이루어지는 시각적 디자인 도구입니다. DESIGN.md는 그 결정들을 구현하는 에이전트에게 전달하는 방법입니다. 기존 디자인 워크플로우를 대체하는 것이 아니라 보완합니다.
이렇게 생각해보십시오. Figma는 디자이너가 결정을 내리는 곳이고, DESIGN.md는 그 결정을 코드베이스를 다루는 모든 AI 에이전트에게 전달하는 계약입니다. 이 계약이 없으면 막연한 프롬프트에 기대며 에이전트가 알아서 잘 해주기를 바라야 합니다. 반면 이 계약이 있으면 버전 관리가 가능하고, 린팅이 가능하며, 어디서든 쓸 수 있는 스펙이 프로젝트와 함께합니다.
툴링을 넘어선 의미
DESIGN.md가 오픈 스탠다드가 되는 것의 더 깊은 의미는 AI 지원 개발의 방향에 대해 무엇을 시사하는지에 있습니다. 우리는 지금 v0, Bolt, Lovable, Stitch 같은 도구들이 텍스트로 UI를 생성하는 시대를 살고 있습니다. 일관성 문제, 즉 모든 생성이 처음부터 시작된다는 문제는 이 도구들을 실제 제품에 진지하게 사용하는 데 있어 가장 큰 실질적 장애물이었습니다.
어떤 에이전트든 읽을 수 있는, 이식 가능하고 벤더 중립적인 스펙은 이 문제를 구조적으로 해결합니다. DESIGN.md는 또 하나의 도구가 아닙니다. 브랜드와 AI 에이전트 사이의 계약입니다.
특히 Flutter 개발자에게 이 패턴은 AI 지원 기능 개발 전반에 걸쳐 디자인 시스템을 관리하고 싶은 방식과 깔끔하게 맞아떨어집니다. 토큰 구조를 한 번 정의하고, 일관되게 참조하고, 매 세션마다 시각적 결정을 다시 협상하지 않고 에이전트가 구현을 담당하게 하면 됩니다.