DESIGN.md 형식 명세: YAML 토큰 + 마크다운으로 코딩 에이전트에 시각적 아이덴티티 설명

Google Labs에서 DESIGN.md를 출시했습니다. 이는 코딩 에이전트에게 시각적 아이덴티티를 설명하기 위한 형식 사양입니다. 이 파일은 기계가 읽을 수 있는 디자인 토큰(YAML 프론트 매터)과 사람이 읽을 수 있는 디자인 근거(마크다운 산문)를 결합합니다. 토큰은 에이전트에게 정확한 값을 제공하고, 산문은 해당 값이 존재하는 이유와 적용 방법을 설명합니다.

형식 개요

DESIGN.md 파일은 상단에 --- 구분선으로 구분된 두 개의 레이어로 구성됩니다: 토큰을 위한 YAML 프론트 매터와 ## 섹션이 있는 마크다운 본문입니다. 예시 발췌:

---
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"
  label-caps:
    fontFamily: "Space Grotesk"
    fontSize: "0.75rem"
rounded:
  sm: "4px"
  md: "8px"
spacing:
  sm: "8px"
  md: "16px"

토큰은 규범적 값입니다. 산문은 적용 맥락을 제공합니다.

주요 기능

토큰 유형: 색상(hex sRGB), 타이포그래피 객체(fontFamily, fontSize, fontWeight, lineHeight, letterSpacing, fontFeature, fontVariation), 치수(숫자+단위), 토큰 참조({path.to.token}).
컴포넌트: 이름을 하위 토큰 속성에 매핑합니다. 예: components.button-primary.backgroundColor: "{colors.tertiary}".
섹션 순서(선택 사항이지만 권장): 개요, 색상, 타이포그래피, 레이아웃 및 간격, 입체감 및 깊이, 형태, 컴포넌트, 권장 사항 및 금지 사항.

CLI 도구

린터로 DESIGN.md를 검증하세요:

npx @google/design.md lint DESIGN.md
{
  "findings": [
    {
      "severity": "warning",
      "path": "components.button-primary",
      "message": "textColor (#ffffff) on backgroundColor (#1A1C1E) has contrast ratio 15.42:1 — passes WCAG AA."
    }
  ],
  "summary": { "errors": 0, "warnings": 1, "info": 1 }
}

버전 간 회귀 감지:

npx @google/design.md diff DESIGN.md DESIGN-v2.md
{
  "tokens": {
    "colors": {
      "added": ["accent"],
      "removed": [],
      "modified": ["tertiary"]
    },
    "typography": { "added": [], "removed": [], "modified": [] }
  },
  "regression": false
}