DESIGN.md

파일의 생김새

Google DESIGN.md 스펙(새 탭) 형식이에요. 파일 맨 위의 YAML 머리말에 토큰(정확한 값)을, 본문 글에 그 값을 고른 이유를 적어요.

효과

DESIGN.md가 결과를 얼마나 바꾸는지 쟀어요. 앱 화면 서비스 중 4개(고루, 핏슬롯, Uptrail, 하루공부)의 리디자인 전 첫 판을 같은 PRODUCT.md와 브리프로 두 번씩 만들었어요.

• A: 카탈로그에서 고른 DESIGN.md를 함께 줬어요.

• B: "토스 느낌으로, 대표 색은 #12805C"처럼 브랜드 이름과 대표 색만 말로 줬어요.

두 조건 모두 프로킷의 prokit-ui 규칙을 따랐고, 두 번째 화면은 새 세션에서 만들었어요(neon 템플릿, claude -p, Opus 5.5, 2026-09-30). 일치율은 두 조건 모두 A가 저장한 DESIGN.md의 토큰과 비교했어요.

%%{init: {"themeVariables": {"xyChart": {"plotColorPalette": "#2a78d6, #8c929b"}}}}%%
xychart-beta
  title "DESIGN.md 있음(파랑)과 브랜드 이름·대표 색만(회색) (%)"
  x-axis ["팔레트 일치", "글자 크기 일치", "반경 일치", "두 번째 화면 색 일관성", "블라인드 종합 승률"]
  y-axis "%" 0 --> 100
  bar [99, 100, 100, 95, 75]
  bar [71, 77, 88, 97, 25]

같은 서비스(같이살림)의 첫 화면을 나란히 본 비교 그림(새 탭)이 있어요. 왼쪽은 DESIGN.md가 있는 쪽, 오른쪽은 브랜드 이름과 대표 색만 준 쪽이에요.

• 품질: DESIGN.md가 있으면 고른 디자인 시스템을 거의 그대로 재현해요. B도 깔끔했지만 화면에 쓴 색의 약 29%가 목표 밖 색이었고, 서체와 글자 크기도 에이전트가 새로 정했어요. 블라인드 평가에서는 A가 충실도 8전 8승, 종합 6승 2패였어요. B가 이긴 Uptrail은 상태가 나빠진 서비스를 표 맨 위로 올리는 등 해야 할 일이 더 빨리 읽혔어요.

• 일관성: 두 번째 화면의 일관성은 차이가 없었어요. B도 새 세션에서 첫 화면 코드를 읽고 따라갔어요. 색 코드를 직접 쓴 곳과 임의 색 클래스는 두 조건 모두 0이었어요(템플릿의 토큰 규칙).

• 효율: 비용은 A가 44% 더 들었어요. 차이는 추천 단계($0.95, 1분)와 첫 화면의 원문 받기·lint·토큰 옮기기에서 났어요. 두 번째 화면은 비슷했어요($3.05, $2.74). B를 목표에 맞추려면 고치는 라운드가 더 필요하겠지만, 그 비용은 재지 않았어요.

• 한계: 서비스 4개를 조건마다 한 번씩, 리뷰와 polish 없이 쟀어요. 평가자도 Claude예요. 측정 중 찾은 결함 2건(추천 글이 대표 색을 원문과 다르게 적음, cn()이 새 글자 크기 토큰을 지움)은 고쳤어요.

측정 방법, 서비스별 수치, 블라인드 평가 이유, 결함은 DESIGN.md 효과 측정 보고서(새 탭)(claude.ai 게시본(새 탭), 공유받은 계정만 열려요)와 neon 검증 기록(새 탭)에 있어요.

자세히

만드는 두 가지 길

• 카탈로그에서 고르기: 스타일 1~3위 중 하나를 고르면 그 원문을 받아 DESIGN.md로 저장하고 lint로 확인해요. getdesign.kr과 awesome-design-md는 curl로, Refero는 agent-browser로 페이지의 다운로드 버튼을 눌러 받아요. Refero 원문은 Google 스펙 형식이 아니라서(표와 글뿐이고 맨 위의 YAML 토큰 머리말이 없어요) 본문 표의 값을 그대로 옮겨 토큰 머리말을 붙여요. 다른 브랜드 이름(Similar Brands)과 새 토큰을 만드는 예시(Quick Start)는 지우고, robots.txt가 막은 사이트 검색과 /api/는 쓰지 않아요.

• 직접 정하기: "카탈로그 없이 impeccable로 정하기"를 고르면 시작 전에 DESIGN.md를 지어내지 않아요. 만든 화면을 바탕으로 마감 때 impeccable document로 기록해요.

고칠 때

• 토큰이나 컴포넌트가 바뀌면 impeccable document로 갱신해요. 덮어쓰기 전에 사용자에게 물어요.

• 카탈로그에서 들여온 DESIGN.md는 덮어쓰지 않고 merge로 바뀐 토큰만 더한 뒤 diff로 지워진 토큰이 없는지 봐요.

근거 자료

관련 문서

• UI/UX 흐름

• 검증 결과

• 처음 보는 용어