DESIGN.md: AI 코딩 에이전트가 브랜드 디자인 규칙을 스스로 따르게 만드는 에이전트 네이티브 파일 포맷

CLAUDE.md나 AGENTS.md를 써보셨다면 개념이 금방 잡힐 겁니다. 그 파일들이 에이전트에게 "이 프로젝트에서 어떻게 코딩해야 해"를 알려준다면, 이제 "어떻게 보여야 해"를 알려주는 시각 설계 전담 레이어가 생겼습니다. 2026년 4월 Google Labs가 DESIGN.md를 Apache 2.0 라이선스로 오픈소스화했는데, 브랜드 색상·폰트·간격·접근성 기준을 한 파일에 담아두면 Claude Code·Cursor·GitHub Copilot·v0 등 주요 AI 코딩 도구에서 같은 파일로 디자인 규칙을 참조할 수 있습니다. 공식 스펙은 아직 Alpha 단계라 변경 가능성이 있지만, 이미 에이전트 생태계에서 사실상의 관례(convention)로 자리잡아가고 있습니다.

저도 이전까지는 UI 작업을 에이전트에게 맡길 때마다 프롬프트에 #1A73E8로 해줘, border-radius는 8px, IBM Plex Sans 써줘를 반복해서 붙여 넣곤 했습니다. 그게 쌓이다 보면 솔직히 지치고, 조금이라도 프롬프트를 바꾸면 에이전트가 자기 마음대로 파란색을 골라오는 경험도 여러 번 했습니다. 이 글에서는 DESIGN.md가 무엇인지, 에이전트가 실제로 어떻게 읽는지, 그리고 색상·타이포·간격·접근성 규칙을 파일 하나로 관리하는 방법을 살펴봅니다.

핵심 개념

YAML 토큰 + 마크다운 산문의 이중 구조

DESIGN.md를 열어보면 두 부분이 나뉩니다. 파일 최상단에 ---로 감싼 YAML 프론트매터가 있고, 그 아래로 일반 마크다운 본문이 이어집니다. YAML 프론트매터가 낯선 분들도 있을 텐데, Jekyll 블로그나 Hugo 사이트에서 페이지 메타데이터를 적던 바로 그 방식입니다. 키: 값 형태에 들여쓰기로 구조를 표현합니다.

yaml

---
name: "MyBrand"
colors:
  primary: "#1A73E8"
  secondary: "#34A853"
  error: "#EA4335"
typography:
  body-md:
    fontFamily: "Google Sans"
    fontSize: "16px"
    fontWeight: "400"
  heading-lg:
    fontFamily: "Google Sans"
    fontSize: "32px"
    fontWeight: "700"
spacing:
  sm: "8px"
  md: "16px"
  lg: "32px"
border-radius:
  button: "8px"
  card: "12px"
---
 
## Color Usage
 
`primary`는 버튼, 링크처럼 인터랙티브한 요소에만 사용합니다.
`secondary`는 성공 상태(success state) 전용입니다. 다른 용도로 쓰지 않습니다.
다크 배경 위에 primary를 올릴 때는 반드시 WCAG 4.5:1 대비율을 확인해야 합니다.
 
## Typography
 
heading은 항상 `heading-lg` 토큰을 사용합니다.
본문 텍스트는 `body-md`가 기본값이며, 보조 설명에는 0.875rem을 허용합니다.

이 구분이 사실 이 포맷의 핵심입니다. YAML 프론트매터는 기계가 읽는 정밀한 값입니다. 에이전트가 여기서 HEX 코드, px 값, 폰트 이름을 그대로 가져다 씁니다. 마크다운 본문은 인간과 AI가 함께 읽는 맥락입니다. "왜 이 색을 쓰는지", "예외는 어떤 상황인지", "접근성 기준이 무엇인지"를 자연어로 설명합니다.

값만 담긴 JSON은 "왜"를 설명하지 못합니다. Figma 링크는 에이전트가 API 없이는 열지도 못합니다. DESIGN.md는 두 가지를 모두 마크다운 한 파일에 담습니다.

에이전트 네이티브 디자인 시스템: 기존 Figma 기반 디자인 시스템이 인간 디자이너를 위한 것이었다면, DESIGN.md는 AI 에이전트가 직접 소비하는 것을 전제로 설계된 '에이전트 네이티브' 포맷입니다. 인간도 읽을 수 있지만, 우선순위는 에이전트입니다.

에이전트가 DESIGN.md를 읽는 방식

한 가지 중요한 사항을 먼저 짚어두겠습니다. DESIGN.md는 현재 관례(convention) 수준의 포맷입니다. "에이전트가 알아서 읽는다"고 표현하지만, 실제 동작 방식은 도구마다 다릅니다.

Claude Code: CLAUDE.md에서 DESIGN.md를 명시적으로 참조하거나, 프롬프트에 파일을 첨부해서 컨텍스트로 주입하는 방식이 일반적입니다. CLAUDE.md에 UI 작업 시 DESIGN.md를 참조하세요라고 적어두면 Claude Code가 해당 파일을 찾아서 읽습니다.
Cursor: 프로젝트 설정에서 컨텍스트 파일로 지정하거나 .cursorrules에서 참조하는 방식으로 활용합니다.
v0 / Lovable: v0는 Vercel의 AI UI 빌더, Lovable은 AI 풀스택 앱 빌더입니다. 두 도구 모두 DESIGN.md를 인식하는 자체 메커니즘을 갖추고 있거나, 파일 첨부 방식으로 동작합니다.

"자동으로 읽는다"는 말이 모든 도구에서 동일하게 작동한다는 뜻은 아닙니다. 하지만 어느 도구든 DESIGN.md를 컨텍스트로 넣어주면 같은 파일 형식으로 브랜드 규칙을 전달할 수 있다는 점이 툴 중립적 관례로서의 가치입니다.

메타파일 생태계 속 DESIGN.md의 위치

AI 코딩 도구들이 보편화되면서 "에이전트에게 이 프로젝트의 규칙을 알려주는 파일"들이 생태계를 이루고 있습니다. 이런 파일들을 통칭해서 '메타파일'이라고 부릅니다. 코드 자체가 아니라 코드를 어떻게 작성할지, 어떻게 보여줄지에 대한 규칙을 담는 파일들입니다.

이 개념을 처음 접했을 때 퍼즐 조각 하나가 딱 맞춰지는 느낌이었는데, 아래 디렉터리 구조를 보면 왜 그런 느낌이 드는지 이해가 됩니다.

프로젝트 루트/
├── CLAUDE.md       ← 코딩 컨벤션, 아키텍처 규칙 (Claude Code용)
├── AGENTS.md       ← GitHub Copilot 전용 설정
├── GEMINI.md       ← Gemini CLI 전용 설정
├── DESIGN.md       ← 시각 설계 규칙 (색상, 타이포, 간격)
└── src/

CLAUDE.md가 "어떻게 코딩할지"를 담는다면, DESIGN.md는 "어떻게 보여줄지"를 담습니다. 이제 에이전트는 두 파일을 모두 참조해서 "올바른 아키텍처로, 올바른 디자인 규칙을 따라" 컴포넌트를 만들 수 있게 됩니다.

실전 적용

예시 1: 신규 대시보드 컴포넌트를 브랜드에 맞게 생성하기

가장 기본적인 사용 패턴입니다. DESIGN.md를 프로젝트 루트에 두고 에이전트에게 컴포넌트 생성을 요청하면, 프롬프트에 색상값을 따로 넣지 않아도 됩니다.

먼저 DESIGN.md를 프로젝트 루트에 이렇게 작성해둡니다.

yaml

---
name: "Acme Dashboard"
colors:
  primary: "#0F62FE"
  surface: "#F4F4F4"
  text-primary: "#161616"
  text-secondary: "#525252"
  success: "#24A148"
  danger: "#DA1E28"
typography:
  heading-sm:
    fontFamily: "IBM Plex Sans"
    fontSize: "20px"
    fontWeight: "600"
  body:
    fontFamily: "IBM Plex Sans"
    fontSize: "14px"
    fontWeight: "400"
spacing:
  xs: "4px"
  sm: "8px"
  md: "16px"
  lg: "24px"
  xl: "40px"
border-radius:
  sm: "4px"
  md: "8px"
---
 
## Color Usage
 
`primary`는 주요 액션 버튼과 활성 상태 표시에만 사용합니다.
`surface`는 카드 배경색입니다. 순수 흰색(#FFFFFF) 대신 `surface`를 사용합니다.
`danger`는 에러 상태와 삭제 액션 전용입니다. 경고(warning)에는 사용하지 않습니다.
 
## Accessibility
 
모든 텍스트-배경 조합은 WCAG AA 기준(4.5:1)을 충족해야 합니다.
`text-secondary`를 `surface` 위에 올릴 때는 반드시 대비율을 검증하세요.

이 파일이 있는 상태에서 Claude Code에 이렇게 요청해볼 수 있습니다.

DESIGN.md 규칙에 따라 사용자 통계를 보여주는 대시보드 카드 컴포넌트 만들어줘

아래는 이 DESIGN.md를 컨텍스트로 제공했을 때 기대할 수 있는 결과의 이상적인 예시입니다. 실제 에이전트 출력은 프로젝트의 CSS 환경(CSS 모듈, Tailwind, styled-components 등)에 따라 스타일 표현 방식이 달라질 수 있습니다.

tsx

// DESIGN.md 토큰을 참조한 컴포넌트 이상적 결과 예시
// 실제 출력은 프로젝트 CSS 환경에 따라 CSS 변수나 Tailwind 클래스로 나올 수 있습니다
const StatsCard = ({ title, value, trend }: StatsCardProps) => {
  return (
    <div style={{
      backgroundColor: '#F4F4F4',   // surface 토큰
      borderRadius: '8px',          // border-radius.md 토큰
      padding: '24px',              // spacing.lg 토큰
    }}>
      <h3 style={{
        fontFamily: 'IBM Plex Sans', // typography.heading-sm
        fontSize: '20px',
        fontWeight: '600',
        color: '#161616',           // text-primary 토큰
      }}>
        {title}
      </h3>
      <span style={{
        color: trend > 0 ? '#24A148' : '#DA1E28', // success/danger 토큰
      }}>
        {trend > 0 ? '▲' : '▼'} {Math.abs(trend)}%
      </span>
    </div>
  );
};

처음에 "에이전트가 정말 파일을 읽고 이 값들을 쓸까?" 반신반의했는데, 컨텍스트로 명확히 제공하면 색상 토큰 이름까지 주석으로 달아주는 경우가 많아서 꽤 인상적이었습니다. Vue, Svelte, 또는 순수 CSS 환경에서도 동일한 DESIGN.md를 쓸 수 있습니다. 어떤 스타일 방식을 쓰는지만 에이전트에게 알려주면 같은 토큰 값을 해당 환경에 맞게 적용해줍니다.

예시 2: 팀 환경 — Google Stitch 핸드오프 파이프라인과 접근성 자동 검증

디자이너와 함께 일하는 팀이라면 Stitch → DESIGN.md → 에이전트 파이프라인이 특히 유용합니다. 혼자 개발하는 상황이라면 이 섹션은 참고 수준으로 봐도 좋습니다.

1. 디자이너: Google Stitch에서 UI 시안 탐색
            ↓
2. Stitch에서 DESIGN.md로 내보내기
            ↓
3. 개발자: DESIGN.md를 프로젝트 루트에 커밋
            ↓
4. Claude Code에 컴포넌트 생성 요청
            ↓
5. 코드 리뷰 & 병합

Stitch가 생성한 DESIGN.md는 기본 구조에 비해 components 섹션이 추가되어 컴포넌트별 기본 스타일도 포함됩니다.

yaml

---
name: "Stitch Export"
generated-by: "Google Stitch"
generated-at: "2026-04-15T09:30:00Z"
colors:
  brand-blue: "#1A73E8"
  brand-green: "#34A853"
  neutral-100: "#F8F9FA"
  neutral-900: "#202124"
typography:
  display:
    fontFamily: "Google Sans"
    fontSize: "57px"
    lineHeight: "64px"
  body-large:
    fontFamily: "Google Sans"
    fontSize: "16px"
    lineHeight: "24px"
components:
  button-primary:
    backgroundColor: "brand-blue"
    textColor: "#FFFFFF"
    borderRadius: "24px"
    padding: "10px 24px"
---

기존 Figma → Zeplin → 개발자 수작업 구현 방식과 비교하면 핸드오프 중 발생하는 값 오타나 해석 차이가 줄어드는 효과가 있습니다.

DESIGN.md에 접근성 기준을 함께 명시해두면 추가 효과도 있습니다. WCAG(Web Content Accessibility Guidelines)는 웹 접근성 국제 표준으로, AA 기준은 일반 텍스트에서 배경 대비율 4.5:1 이상을 요구합니다. 국내 공공기관 웹사이트는 이 기준 준수가 법적으로 요구되기도 합니다.

yaml

---
name: "AccessibleUI"
colors:
  background: "#FFFFFF"
  text-default: "#212121"
  text-muted: "#757575"
  interactive: "#0063B1"
---
 
## Accessibility Requirements
 
이 프로젝트는 WCAG 2.1 AA 기준을 준수합니다.
 
- 본문 텍스트(`text-default` on `background`): 대비율 15.8:1 ✓
- 보조 텍스트(`text-muted` on `background`): 대비율 4.6:1 ✓ (최소 기준 통과)
- 인터랙티브 요소(`interactive` on `background`): 대비율 7.2:1 ✓
 
새 색상 조합을 추가할 때는 반드시 대비율 4.5:1 이상을 확인한 뒤 이 파일에 결과를 기록해두는 것을 권장합니다.
에이전트가 색상 조합을 제안할 때도 동일한 기준이 적용됩니다.

대비율 값을 파일에 명시해두면 에이전트가 새로운 색상 조합을 제안할 때 "이 조합은 대비율이 낮아 WCAG를 위반할 수 있습니다"라는 피드백을 함께 주는 경우가 많아집니다. 매번 별도로 체크 도구를 돌리는 수고를 줄일 수 있습니다.

장단점 분석

팀에서 실제로 써보면서 느낀 것들을 정리해봤습니다.

장점

항목	내용
툴 중립성	Claude Code, Cursor, Copilot, v0, Lovable — 어떤 AI 도구를 쓰든 같은 파일 하나로 동작
Git 버전 관리	순수 텍스트라 코드와 함께 형상 관리 가능. 디자인 변경 이력이 PR에 남음
정밀도 + 맥락 동시 제공	YAML 토큰(정확한 값)과 Markdown 산문(이유·예외)이 한 파일에 공존
반복 프롬프트 감소	디자인 규칙을 매번 프롬프트에 넣을 필요 없이 파일로 영구 참조
접근성 자동화	WCAG 기준을 파일에 명시하면 에이전트가 스스로 준수 여부를 검토
낮은 진입 장벽	JSON 스키마나 Figma 토큰 익스포트 포맷과 달리 마크다운이라 누구나 편집 가능

단점 및 주의사항

항목	내용	대응 방안
완전한 디자인 시스템이 아님	컴포넌트 로직·인터랙션·상태 전이 등은 포함되지 않음	Storybook, Figma 등 기존 시스템과 병행 사용 권장
사양이 아직 Alpha	공식 스펙이 알파 단계라 파괴적 변경 가능성 있음	중요 프로젝트에서는 변경 로그 모니터링 권장
자동 읽기가 보장되지 않음	에이전트가 DESIGN.md를 자동으로 컨텍스트에 포함하는지는 도구별로 다름	CLAUDE.md에서 명시적으로 참조하거나 프롬프트에 파일 첨부
초기 구성 비용	기존 Figma 시스템에서 DESIGN.md로 수동 변환 작업 필요	자동 생성 도구 활용 가능. 단 Alpha 스펙 변경 시 동작 여부 재확인 권장
AI 해석 편차	에이전트마다 Markdown 해석 방식이 달라 엣지 케이스에서 불일치 가능	산문 설명을 구체적으로 작성하고 예외 케이스를 명시
팀 규율 필요	파일이 코드와 함께 최신 상태로 유지되지 않으면 신뢰도 하락	디자인 변경 PR에 DESIGN.md 업데이트 필수 포함 규칙 설정
복잡한 브랜드의 한계	아이덴티티가 복잡할수록 파일이 방대해지고 에이전트 컨텍스트 한계에 부딪힘	핵심 토큰만 포함하고 컴포넌트별 세부 파일로 분리 고려

실무에서 가장 흔한 실수

YAML 프론트매터만 채우고 마크다운 산문을 비워두는 경우 — 토큰 값만 있고 "왜"가 없으면 에이전트가 예외 상황에서 엉뚱한 판단을 내립니다. "이 색은 이 상황에서만 쓴다"는 제약 조건을 산문으로 기술해두면 효과가 훨씬 높아집니다.
처음 만들고 업데이트하지 않는 경우 — 브랜드 색상이 바뀌었는데 DESIGN.md는 옛날 값 그대로인 상황이 생길 수 있습니다. 에이전트가 낡은 규칙을 충실히 따라서 더 큰 혼란이 생기는 경우도 있습니다. 디자인 변경 PR에 DESIGN.md 업데이트를 체크리스트 항목으로 포함시켜두면 좋습니다.
너무 많은 토큰을 한 파일에 넣는 경우 — 100개 이상의 색상 토큰, 50가지 타이포그래피 변형을 한 파일에 담으면 에이전트 컨텍스트 창에서 후반부가 잘려나갑니다. 실제로 에이전트가 자주 참조하는 핵심 토큰 20~30개에 집중하는 것이 현실적입니다.

마치며

"코딩 규칙은 CLAUDE.md로, 디자인 규칙은 DESIGN.md로." 이 발상 자체는 단순하지만 영향은 꽤 실질적입니다. 매 프롬프트마다 색상값을 붙여 넣던 반복 작업이 사라지고, 브랜드 규칙이 코드와 동일한 Git 히스토리로 추적됩니다. 팀 전체가 서로 다른 AI 도구를 쓰더라도 같은 디자인 기준을 공유할 수 있게 됩니다. 아직 Alpha 스펙이라 변경될 수 있고, 모든 도구가 완전히 동일하게 동작하지는 않습니다. 그럼에도 DESIGN.md는 AI 에이전트에게 브랜드 규칙을 한 번만 알려주면 계속 기억하게 만드는 가장 단순하면서도 Git 친화적인 방법입니다.

지금 바로 시작해볼 수 있는 3단계가 있습니다.

기존 프로젝트의 핵심 토큰 파악 — 지금 쓰고 있는 주요 색상 3~5개, 폰트 패밀리, 기본 간격 값을 먼저 적어보시면 됩니다. Figma나 CSS 파일에서 찾을 수 있고, design.dev의 DESIGN.md Generator에 사이트 URL을 입력하면 자동으로 추출해주기도 합니다. 다만 Alpha 스펙 단계의 생태계 도구들은 스펙 변경 시 동작이 달라질 수 있으니 공식 저장소도 함께 확인해두시면 좋습니다.
DESIGN.md 파일 생성 후 프로젝트 루트에 배치 — getdesign.md나 awesome-design-md에서 비슷한 브랜드의 예시 파일을 참고해서 시작해볼 수 있습니다. YAML 프론트매터에 토큰 값을 채우고, 마크다운 본문에 "왜 이 값인지"를 두세 줄이라도 적어두시면 충분합니다.
AI 에이전트에게 DESIGN.md를 참조하도록 요청 — Claude Code라면 CLAUDE.md에 UI 작업 시 DESIGN.md를 참조하세요라고 적어두거나, 직접 DESIGN.md 규칙에 따라 로그인 폼 컴포넌트를 만들어줘처럼 요청해볼 수 있습니다. Cursor라면 프로젝트 설정에서 컨텍스트 파일로 지정하는 방식이 자연스럽습니다. 첫 결과물과 이전 방식의 결과물을 비교해보시면 차이를 바로 체감하실 수 있습니다.

참고 자료

DESIGN.md: AI 코딩 에이전트가 브랜드 디자인 규칙을 스스로 따르게 만드는 에이전트 네이티브 파일 포맷 | DEV BAK - 기술블로그

DESIGN.md: AI 코딩 에이전트가 브랜드 디자인 규칙을 스스로 따르게 만드는 에이전트 네이티브 파일 포맷

핵심 개념

YAML 토큰 + 마크다운 산문의 이중 구조

yaml

---
name: "MyBrand"
colors:
  primary: "#1A73E8"
  secondary: "#34A853"
  error: "#EA4335"
typography:
  body-md:
    fontFamily: "Google Sans"
    fontSize: "16px"
    fontWeight: "400"
  heading-lg:
    fontFamily: "Google Sans"
    fontSize: "32px"
    fontWeight: "700"
spacing:
  sm: "8px"
  md: "16px"
  lg: "32px"
border-radius:
  button: "8px"
  card: "12px"
---
 
## Color Usage
 
`primary`는 버튼, 링크처럼 인터랙티브한 요소에만 사용합니다.
`secondary`는 성공 상태(success state) 전용입니다. 다른 용도로 쓰지 않습니다.
다크 배경 위에 primary를 올릴 때는 반드시 WCAG 4.5:1 대비율을 확인해야 합니다.
 
## Typography
 
heading은 항상 `heading-lg` 토큰을 사용합니다.
본문 텍스트는 `body-md`가 기본값이며, 보조 설명에는 0.875rem을 허용합니다.

에이전트 네이티브 디자인 시스템: 기존 Figma 기반 디자인 시스템이 인간 디자이너를 위한 것이었다면, DESIGN.md는 AI 에이전트가 직접 소비하는 것을 전제로 설계된 '에이전트 네이티브' 포맷입니다. 인간도 읽을 수 있지만, 우선순위는 에이전트입니다.

에이전트가 DESIGN.md를 읽는 방식

Claude Code: CLAUDE.md에서 DESIGN.md를 명시적으로 참조하거나, 프롬프트에 파일을 첨부해서 컨텍스트로 주입하는 방식이 일반적입니다. CLAUDE.md에 UI 작업 시 DESIGN.md를 참조하세요라고 적어두면 Claude Code가 해당 파일을 찾아서 읽습니다.
Cursor: 프로젝트 설정에서 컨텍스트 파일로 지정하거나 .cursorrules에서 참조하는 방식으로 활용합니다.
v0 / Lovable: v0는 Vercel의 AI UI 빌더, Lovable은 AI 풀스택 앱 빌더입니다. 두 도구 모두 DESIGN.md를 인식하는 자체 메커니즘을 갖추고 있거나, 파일 첨부 방식으로 동작합니다.

메타파일 생태계 속 DESIGN.md의 위치

이 개념을 처음 접했을 때 퍼즐 조각 하나가 딱 맞춰지는 느낌이었는데, 아래 디렉터리 구조를 보면 왜 그런 느낌이 드는지 이해가 됩니다.

프로젝트 루트/
├── CLAUDE.md       ← 코딩 컨벤션, 아키텍처 규칙 (Claude Code용)
├── AGENTS.md       ← GitHub Copilot 전용 설정
├── GEMINI.md       ← Gemini CLI 전용 설정
├── DESIGN.md       ← 시각 설계 규칙 (색상, 타이포, 간격)
└── src/

실전 적용

예시 1: 신규 대시보드 컴포넌트를 브랜드에 맞게 생성하기

먼저 DESIGN.md를 프로젝트 루트에 이렇게 작성해둡니다.

yaml

---
name: "Acme Dashboard"
colors:
  primary: "#0F62FE"
  surface: "#F4F4F4"
  text-primary: "#161616"
  text-secondary: "#525252"
  success: "#24A148"
  danger: "#DA1E28"
typography:
  heading-sm:
    fontFamily: "IBM Plex Sans"
    fontSize: "20px"
    fontWeight: "600"
  body:
    fontFamily: "IBM Plex Sans"
    fontSize: "14px"
    fontWeight: "400"
spacing:
  xs: "4px"
  sm: "8px"
  md: "16px"
  lg: "24px"
  xl: "40px"
border-radius:
  sm: "4px"
  md: "8px"
---
 
## Color Usage
 
`primary`는 주요 액션 버튼과 활성 상태 표시에만 사용합니다.
`surface`는 카드 배경색입니다. 순수 흰색(#FFFFFF) 대신 `surface`를 사용합니다.
`danger`는 에러 상태와 삭제 액션 전용입니다. 경고(warning)에는 사용하지 않습니다.
 
## Accessibility
 
모든 텍스트-배경 조합은 WCAG AA 기준(4.5:1)을 충족해야 합니다.
`text-secondary`를 `surface` 위에 올릴 때는 반드시 대비율을 검증하세요.

이 파일이 있는 상태에서 Claude Code에 이렇게 요청해볼 수 있습니다.

DESIGN.md 규칙에 따라 사용자 통계를 보여주는 대시보드 카드 컴포넌트 만들어줘

tsx

// DESIGN.md 토큰을 참조한 컴포넌트 이상적 결과 예시
// 실제 출력은 프로젝트 CSS 환경에 따라 CSS 변수나 Tailwind 클래스로 나올 수 있습니다
const StatsCard = ({ title, value, trend }: StatsCardProps) => {
  return (
    <div style={{
      backgroundColor: '#F4F4F4',   // surface 토큰
      borderRadius: '8px',          // border-radius.md 토큰
      padding: '24px',              // spacing.lg 토큰
    }}>
      <h3 style={{
        fontFamily: 'IBM Plex Sans', // typography.heading-sm
        fontSize: '20px',
        fontWeight: '600',
        color: '#161616',           // text-primary 토큰
      }}>
        {title}
      </h3>
      <span style={{
        color: trend > 0 ? '#24A148' : '#DA1E28', // success/danger 토큰
      }}>
        {trend > 0 ? '▲' : '▼'} {Math.abs(trend)}%
      </span>
    </div>
  );
};

예시 2: 팀 환경 — Google Stitch 핸드오프 파이프라인과 접근성 자동 검증

1. 디자이너: Google Stitch에서 UI 시안 탐색
            ↓
2. Stitch에서 DESIGN.md로 내보내기
            ↓
3. 개발자: DESIGN.md를 프로젝트 루트에 커밋
            ↓
4. Claude Code에 컴포넌트 생성 요청
            ↓
5. 코드 리뷰 & 병합

Stitch가 생성한 DESIGN.md는 기본 구조에 비해 components 섹션이 추가되어 컴포넌트별 기본 스타일도 포함됩니다.

yaml

---
name: "Stitch Export"
generated-by: "Google Stitch"
generated-at: "2026-04-15T09:30:00Z"
colors:
  brand-blue: "#1A73E8"
  brand-green: "#34A853"
  neutral-100: "#F8F9FA"
  neutral-900: "#202124"
typography:
  display:
    fontFamily: "Google Sans"
    fontSize: "57px"
    lineHeight: "64px"
  body-large:
    fontFamily: "Google Sans"
    fontSize: "16px"
    lineHeight: "24px"
components:
  button-primary:
    backgroundColor: "brand-blue"
    textColor: "#FFFFFF"
    borderRadius: "24px"
    padding: "10px 24px"
---

기존 Figma → Zeplin → 개발자 수작업 구현 방식과 비교하면 핸드오프 중 발생하는 값 오타나 해석 차이가 줄어드는 효과가 있습니다.

yaml

---
name: "AccessibleUI"
colors:
  background: "#FFFFFF"
  text-default: "#212121"
  text-muted: "#757575"
  interactive: "#0063B1"
---
 
## Accessibility Requirements
 
이 프로젝트는 WCAG 2.1 AA 기준을 준수합니다.
 
- 본문 텍스트(`text-default` on `background`): 대비율 15.8:1 ✓
- 보조 텍스트(`text-muted` on `background`): 대비율 4.6:1 ✓ (최소 기준 통과)
- 인터랙티브 요소(`interactive` on `background`): 대비율 7.2:1 ✓
 
새 색상 조합을 추가할 때는 반드시 대비율 4.5:1 이상을 확인한 뒤 이 파일에 결과를 기록해두는 것을 권장합니다.
에이전트가 색상 조합을 제안할 때도 동일한 기준이 적용됩니다.

장단점 분석

팀에서 실제로 써보면서 느낀 것들을 정리해봤습니다.

장점

항목	내용
툴 중립성	Claude Code, Cursor, Copilot, v0, Lovable — 어떤 AI 도구를 쓰든 같은 파일 하나로 동작
Git 버전 관리	순수 텍스트라 코드와 함께 형상 관리 가능. 디자인 변경 이력이 PR에 남음
정밀도 + 맥락 동시 제공	YAML 토큰(정확한 값)과 Markdown 산문(이유·예외)이 한 파일에 공존
반복 프롬프트 감소	디자인 규칙을 매번 프롬프트에 넣을 필요 없이 파일로 영구 참조
접근성 자동화	WCAG 기준을 파일에 명시하면 에이전트가 스스로 준수 여부를 검토
낮은 진입 장벽	JSON 스키마나 Figma 토큰 익스포트 포맷과 달리 마크다운이라 누구나 편집 가능

단점 및 주의사항

항목	내용	대응 방안
완전한 디자인 시스템이 아님	컴포넌트 로직·인터랙션·상태 전이 등은 포함되지 않음	Storybook, Figma 등 기존 시스템과 병행 사용 권장
사양이 아직 Alpha	공식 스펙이 알파 단계라 파괴적 변경 가능성 있음	중요 프로젝트에서는 변경 로그 모니터링 권장
자동 읽기가 보장되지 않음	에이전트가 DESIGN.md를 자동으로 컨텍스트에 포함하는지는 도구별로 다름	CLAUDE.md에서 명시적으로 참조하거나 프롬프트에 파일 첨부
초기 구성 비용	기존 Figma 시스템에서 DESIGN.md로 수동 변환 작업 필요	자동 생성 도구 활용 가능. 단 Alpha 스펙 변경 시 동작 여부 재확인 권장
AI 해석 편차	에이전트마다 Markdown 해석 방식이 달라 엣지 케이스에서 불일치 가능	산문 설명을 구체적으로 작성하고 예외 케이스를 명시
팀 규율 필요	파일이 코드와 함께 최신 상태로 유지되지 않으면 신뢰도 하락	디자인 변경 PR에 DESIGN.md 업데이트 필수 포함 규칙 설정
복잡한 브랜드의 한계	아이덴티티가 복잡할수록 파일이 방대해지고 에이전트 컨텍스트 한계에 부딪힘	핵심 토큰만 포함하고 컴포넌트별 세부 파일로 분리 고려

실무에서 가장 흔한 실수

YAML 프론트매터만 채우고 마크다운 산문을 비워두는 경우 — 토큰 값만 있고 "왜"가 없으면 에이전트가 예외 상황에서 엉뚱한 판단을 내립니다. "이 색은 이 상황에서만 쓴다"는 제약 조건을 산문으로 기술해두면 효과가 훨씬 높아집니다.
처음 만들고 업데이트하지 않는 경우 — 브랜드 색상이 바뀌었는데 DESIGN.md는 옛날 값 그대로인 상황이 생길 수 있습니다. 에이전트가 낡은 규칙을 충실히 따라서 더 큰 혼란이 생기는 경우도 있습니다. 디자인 변경 PR에 DESIGN.md 업데이트를 체크리스트 항목으로 포함시켜두면 좋습니다.
너무 많은 토큰을 한 파일에 넣는 경우 — 100개 이상의 색상 토큰, 50가지 타이포그래피 변형을 한 파일에 담으면 에이전트 컨텍스트 창에서 후반부가 잘려나갑니다. 실제로 에이전트가 자주 참조하는 핵심 토큰 20~30개에 집중하는 것이 현실적입니다.

마치며

지금 바로 시작해볼 수 있는 3단계가 있습니다.

기존 프로젝트의 핵심 토큰 파악 — 지금 쓰고 있는 주요 색상 3~5개, 폰트 패밀리, 기본 간격 값을 먼저 적어보시면 됩니다. Figma나 CSS 파일에서 찾을 수 있고, design.dev의 DESIGN.md Generator에 사이트 URL을 입력하면 자동으로 추출해주기도 합니다. 다만 Alpha 스펙 단계의 생태계 도구들은 스펙 변경 시 동작이 달라질 수 있으니 공식 저장소도 함께 확인해두시면 좋습니다.
DESIGN.md 파일 생성 후 프로젝트 루트에 배치 — getdesign.md나 awesome-design-md에서 비슷한 브랜드의 예시 파일을 참고해서 시작해볼 수 있습니다. YAML 프론트매터에 토큰 값을 채우고, 마크다운 본문에 "왜 이 값인지"를 두세 줄이라도 적어두시면 충분합니다.
AI 에이전트에게 DESIGN.md를 참조하도록 요청 — Claude Code라면 CLAUDE.md에 UI 작업 시 DESIGN.md를 참조하세요라고 적어두거나, 직접 DESIGN.md 규칙에 따라 로그인 폼 컴포넌트를 만들어줘처럼 요청해볼 수 있습니다. Cursor라면 프로젝트 설정에서 컨텍스트 파일로 지정하는 방식이 자연스럽습니다. 첫 결과물과 이전 방식의 결과물을 비교해보시면 차이를 바로 체감하실 수 있습니다.

핵심 개념

YAML 토큰 + 마크다운 산문의 이중 구조

에이전트가 DESIGN.md를 읽는 방식

메타파일 생태계 속 DESIGN.md의 위치

실전 적용

예시 1: 신규 대시보드 컴포넌트를 브랜드에 맞게 생성하기

예시 2: 팀 환경 — Google Stitch 핸드오프 파이프라인과 접근성 자동 검증

장단점 분석

장점

단점 및 주의사항

실무에서 가장 흔한 실수

마치며

참고 자료

핵심 개념

YAML 토큰 + 마크다운 산문의 이중 구조

에이전트가 DESIGN.md를 읽는 방식

메타파일 생태계 속 DESIGN.md의 위치

실전 적용

예시 1: 신규 대시보드 컴포넌트를 브랜드에 맞게 생성하기

예시 2: 팀 환경 — Google Stitch 핸드오프 파이프라인과 접근성 자동 검증

장단점 분석

장점

단점 및 주의사항

실무에서 가장 흔한 실수

마치며

참고 자료

추천 포스트

AI 에이전트에 코딩 규칙과 디자인 규칙을 동시에 적용하는 Claude Code 팀 설정 — CLAUDE.md와 DESIGN.md 병용법

Figma MCP로 디자인-코드 반복 주기 최대 80% 단축하기: Model Context Protocol과 AI 코딩 에이전트 실전 연동

Figma Code Connect로 AI 컴포넌트 재사용률 높이기 — 대규모 디자인 시스템에서 매핑하고 측정하기까지

MCP와 A2A로 멀티에이전트 시스템 구축하기 — Model Context Protocol·Agent-to-Agent Protocol 실전 통합 가이드

MCP 보안과 지연형 러그 풀 (Post-Approval Toxicity) — 승인한 AI 도구가 조용히 돌변하는 공급망 공격 실전 가이드

MCP 멀티에이전트 파이프라인 보안: 프롬프트 인젝션 전파를 차단하는 신뢰 체인 설계 패턴 5가지