DESIGN.md는 Google Labs의 Stitch가 개발한 오픈 표준으로, AI 에이전트가 브랜드의 디자인 시스템 규칙을 명시적으로 파악할 수 있도록 프로젝트에 포함하는 구조화된 파일 형식이다. 2026년 4월 21일 오픈소스로 공개되었으며, GitHub에서 초안 스펙에 기여할 수 있다.

등장 배경

AI 에이전트가 UI를 생성할 때 가장 큰 문제는 “의도를 추측해야 한다”는 점이다. 특정 색상이 왜 그 용도로 쓰이는지, WCAG 접근성 규칙이 어떻게 적용되어야 하는지, 어떤 컴포넌트가 어떤 상황에 맞는지 — 이 모든 맥락이 사라진다.

DESIGN.md는 이 맥락을 명시적으로 기록해 에이전트가 추측 대신 알고 선택할 수 있게 한다.

핵심 개념

• 색상 의미 문서화: #1B365D가 단순히 “파란색”이 아니라 “기본 CTA 컬러”임을 명시
• 접근성 규칙: WCAG 규칙을 에이전트가 선택을 검증할 수 있는 형태로 인코딩
• 컴포넌트 가이드라인: 어떤 상황에 어떤 컴포넌트를 써야 하는지 기술
• 플랫폼 독립: Stitch뿐 아니라 모든 AI 코딩 도구에서 사용 가능

파일 형식

DESIGN.md는 두 레이어로 구성된다:

1. YAML 프론트매터 — 머신이 읽는 디자인 토큰 (--- 펜스 안)
2. Markdown 본문 — 사람이 읽는 디자인 의도 (## 섹션 구조)

토큰은 정규값이고, 본문은 그 값을 언제·왜 쓰는지 맥락을 제공한다.

name: Heritage
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 3rem
rounded:
  sm: 4px
  md: 8px
spacing:
  sm: 8px
  md: 16px

## Colors

- **Primary (#1A1C1E):** 헤드라인·핵심 텍스트용 딥 잉크
- **Tertiary (#B8422E):** "Boston Clay" — 상호작용 전용 유일한 강조색

토큰 스키마

version: <string>           # 선택, 현재: "alpha"
name: <string>
description: <string>       # 선택
colors:
  <token-name>: <Color>     # "#RRGGBB" 16진수 sRGB
typography:
  <token-name>:
    fontFamily, fontSize, fontWeight, lineHeight, letterSpacing, ...
rounded:
  <scale>: <Dimension>      # px · em · rem 단위
spacing:
  <scale>: <Dimension>
components:
  <component-name>:
    <property>: <value | {token.reference}>

토큰 참조는 {colors.primary} 형식으로 다른 토큰을 가리킬 수 있다.

섹션 순서

## 섹션은 아래 순서를 준수해야 하며, 생략은 허용되지만 순서는 지켜야 한다.

CLI 도구

npm install @google/design.md
# 또는 npx로 바로 실행

# 구조 검증 + WCAG 대비율 체크
npx @google/design.md lint DESIGN.md

# 두 버전 간 토큰 차이 비교
npx @google/design.md diff DESIGN.md DESIGN-v2.md

lint는 구조 오류·깨진 토큰 참조·WCAG 대비율을 JSON으로 반환한다. diff는 추가·삭제·수정된 토큰을 비교하고 회귀 여부를 표시한다.

사용 방법

Stitch에서 프로젝트의 디자인 규칙을 설정하면 DESIGN.md로 내보낼 수 있다. 이 파일을 저장소에 포함하면 다음 프로젝트나 다른 도구에서 동일한 디자인 규칙을 재사용할 수 있다.

project/
├── DESIGN.md      ← 디자인 시스템 규칙 (AI 가독 형태)
├── CLAUDE.md      ← Claude Code 프로젝트 지시 파일
└── src/

GitHub 저장소

초안 스펙과 CLI는 github.com/google-labs-code/design.md에서 확인하고 기여할 수 있다.

관련 문서

• design-md-tips-pm-workflow — PM이 DESIGN.md로 AI 에이전트 UI 일관성을 지키는 실천 워크플로
• impeccable — DESIGN.md 기반 AI 프론트엔드 디자인 스킬 시스템
• awesome-design-md — Claude·Nike·Tesla 등 69개 브랜드 DESIGN.md 큐레이션
• a2ui — 에이전트가 기존 디자인 시스템으로 UI를 생성하는 표준
• gpt-5-4-tips-frontend — GPT-5.4를 활용한 프론트엔드 설계

참고 자료

• Stitch’s DESIGN.md format is now open-source — Google Blog (2026-04-21)