google-labs-code/design.md 딥다이브
— 디자인 시스템을 코딩 AI에게 "말로" 전달하는 포맷

DESIGN.md 한 장 직접 읽어보기 (2층 구조)

가장 먼저 할 일은 실제 파일을 눈으로 보는 것이다. 위가 기계용 토큰(YAML), 아래가 사람용 설명(Markdown)으로 깔끔히 나뉘는 걸 확인하자.

# ── 기계가 읽는 층: front matter ──
---
name: Heritage
colors:
  primary: "#1A1C1E"      # deep ink (깊은 잉크색)
  surface: "#F2EFE9"      # warm limestone (따뜻한 석회색)
typography:
  headline-lg:
    fontFamily: Public Sans
    fontSize: 32px
    lineHeight: 1.2         # 단위 없으면 fontSize의 배수
components:
  button-primary:
    backgroundColor: "{colors.primary}"   # 토큰 참조
    textColor: "{colors.surface}"
---

# ── 사람이 읽는 층: prose ──
## Overview
Heritage는 1970년대 유서 깊은 대학의 강의 유인물 같은 느낌이다.

## Colors
primary 색은 화면당 가장 중요한 행동 하나에만 쓴다.

실습 아이디어: 위 {colors.primary}처럼 값을 직접 쓰지 않고 토큰 이름을 가리키는 방식(참조)이 왜 좋은지 — 색 하나 바꿀 때 몇 군데를 고쳐야 하는지 세어보라.

unified / remark로 .md를 트리로 다루기

design.md의 파서는 .md를 글자가 아니라 AST(구문 트리)로 바꿔 다룬다. 이 생태계(unified·remark)는 블로그 빌더부터 문서 도구까지 두루 쓰여, 한 번 배워두면 활용처가 넓다.

# 개념만: .md 문자열이 이런 트리로 바뀐다
root
├─ yaml      (front matter 토큰)
├─ heading   "## Overview"
├─ paragraph "Heritage는 ..."
└─ heading   "## Colors"

실습 아이디어: unified().use(remarkParse).use(remarkFrontmatter)로 아무 마크다운이나 파싱해 트리를 콘솔에 찍어보면 구조가 손에 잡힌다.

한 파일에서 Tailwind · W3C 표준으로 변환

토큰을 한 곳(DESIGN.md)에 적어두면, CLI가 여러 형식으로 뽑아준다. "한 번 정의, 어디서나 사용"이라는 디자인 토큰의 정수를 체험할 수 있다.

npx @google/design.md export DESIGN.md --format tailwind
# → Tailwind 테마 (v3 json 또는 v4 @theme 블록)

npx @google/design.md export DESIGN.md --format dtcg
# → W3C 표준(DTCG) 토큰 JSON — Figma/Style Dictionary 호환

실습 아이디어: 같은 DESIGN.md를 두 형식으로 뽑아 차이를 비교하고, Tailwind 출력을 실제 페이지에 적용해보라.

"형용사가 아니라 구체적 레퍼런스"

이건 코드보다 사고방식의 교훈이다. AI에게 "모던하고 깔끔하게"라고 하면 매번 다른 게 나온다. 대신 "1970년대 대학 강의 유인물"처럼 한 점을 정확히 찍는 레퍼런스를 주면, 모델이 '하지 말 것'까지 알아서 추론한다.

실습 아이디어: 어떤 UI든 프롬프트를 ① 형용사만, ② 구체적 레퍼런스로 두 번 줘서 결과 차이를 직접 보라.

규칙 하나 = 코드 .ts + 테스트 .test.ts 페어

9개 린트 룰이 각각 구현 파일과 테스트 파일로 짝지어 있다(broken-ref.ts ↔ broken-ref.test.ts). TDD(테스트를 먼저 쓰고 통과시키는 개발법)의 교과서적 사례라, 작은 규칙 하나를 읽으면 패턴이 보인다.

# 9룰 요약 (괄호 = 심각도)
broken-ref(error)        존재하지 않는 토큰을 참조
missing-primary(warn)    primary 색이 없음
contrast-ratio(warn)     글자/배경 대비가 WCAG AA(4.5:1) 미만
section-order(warn)      섹션이 정해진 순서를 어김
unknown-key(warn)        colours: 같은 오타 감지
# + orphaned-tokens, missing-typography, token-summary, missing-sections

프로그램에서 직접 부를 수도 있다: import { lint } from '@google/design.md/linter' → report.findings / .summary / .designSystem.

1. 예제 파일 검사하기 난이도 ★☆☆ 입문

레포의 examples/totality-festival/DESIGN.md를 골라 검사기를 돌린다. 어떤 경고가 나오는지, JSON 결과를 어떻게 읽는지 익힌다.

npx @google/design.md lint examples/totality-festival/DESIGN.md

2. 내 브랜드 DESIGN.md 쓰기 난이도 ★☆☆ 입문

name + colors(primary 필수) + typography 최소 세 가지만으로 파일을 만들고, lint가 경고 0개로 통과하게 다듬어 본다. primary가 없으면 어떤 경고가 뜨는지도 확인.

3. Tailwind로 뽑아 실제 적용 난이도 ★★☆ 중급

2번에서 만든 파일을 export --format tailwind로 변환해, 간단한 HTML/React 페이지의 테마로 붙여본다. "한 곳 정의 → 여러 곳 사용"을 체감하는 단계.

4. prose 있/없 A·B 비교 난이도 ★★☆ 중급

같은 토큰을 가진 DESIGN.md 두 개를 만들되, 하나엔 ## Overview/## Do's and Don'ts prose를 풍부히, 다른 하나엔 토큰만. 둘을 각각 Claude·Cursor에 주고 같은 화면을 만들게 해 결과 차이를 관찰한다 — 이 레포의 핵심 주장을 직접 검증.

5. 새 린트 룰 추가 (TDD) 난이도 ★★★ 고급

linter/rules/에 규칙 하나를 더한다(예: "폰트 패밀리는 3개 이하"). 먼저 이름.test.ts에 실패하는 테스트를 쓰고(Red), 통과하도록 이름.ts를 구현(Green)한 뒤 정리(Refactor)하는 TDD 흐름을 그대로 따라가 본다.