DESIGN.md 작성법
DESIGN.md가 작동하려면 기계가 추측할 필요가 없어야 합니다. 세부보다 방향을 먼저 주고 형용사 대신 값을 쓰며 실제로 만들 컴포넌트를 다뤄야 합니다. 효과적인 구조와 조용히 망치는 실수를 살펴봅니다.
세부가 아니라 방향부터 시작하기
먼저 스타일 이름, 처음 보는 사람에게 설명할 한 문장의 핵심, 라이트 또는 다크처럼 이후 모든 것을 바꾸는 플래그를 제시합니다.
대부분 이를 파일 위의 작은 구조화 블록에 둡니다. YAML frontmatter는 Google의 공개 DESIGN.md 사양도 쓰는 관례입니다. 에이전트가 먼저 읽고 이후 섹션을 해석합니다. 방향 없이 색상 값 50개로 시작하면 의도를 추측하게 됩니다.
형용사가 아니라 값을 명시하기
"Warm, minimal, editorial" means something different to every model on every run. "Background <hex>, ink <hex>, one accent <hex>, body type at <px> with a 1.5 line height, spacing on an <px> rhythm" means the same thing every time. Tokens are the contract; adjectives are decoration.
토큰은 외관이 아니라 역할로 이름 붙입니다. background, ink, accent, line을 쓰고 '연한 회색'이나 '파란색'은 피합니다. 역할 이름은 테마 변경에도 유지되고 값의 위치를 알려 줍니다.
글에도 역할을 주세요. 값의 이유와 결합 방법을 설명합니다. '강조색은 화면당 한 동작에만 사용'은 실행할 수 있지만 '팔레트가 차분하다'는 그렇지 않습니다.
에이전트가 만들 컴포넌트 다루기
토큰만으로는 UI가 결정되지 않습니다. 같은 색상이라도 버튼이 채움인지 테두리인지, 모서리가 각진지 둥근지, 카드가 그림자인지 헤어라인인지, 강조가 굵기·크기·색 중 무엇인지에 따라 달라집니다.
버튼, 카드, 입력, 내비게이션을 짧은 선언형 규칙으로 쓰고 사용 경계도 더합니다. 에디토리얼용임을 알면 에이전트가 밀도 높은 대시보드에 억지로 적용하지 않습니다.
사양을 조용히 망치는 실수
값 없는 형용사. 분위기 설명만 있고 숫자가 없으면 에이전트는 이해한 듯하다가 자체 팔레트를 만듭니다.
브랜드 북 전체를 넣기. DESIGN.md는 작업 사양이지 보관소가 아닙니다. 읽는 시간이 만드는 시간보다 길면 에이전트가 훑어보고 자신 있게 추측합니다. 결과를 바꾸는 내용만 남기세요.
사용 경계 없음. 어디에 쓰면 안 되는지 말하지 않으면 모든 곳에 잘못 적용됩니다.
방치하기. 저장소의 텍스트이므로 코드처럼 다룹니다. 디자인 변경과 같은 커밋에서 DESIGN.md도 바꾸지 않으면 지난 디자인을 충실히 적용합니다.
내부 참조 불일치. 타이포그래피 섹션과 컴포넌트 예시가 다른 체계를 암시하면 에이전트가 임의로 하나를 고릅니다.
직접 쓰지 않고 완성된 파일 고르기
자체 디자인 시스템이라면 DESIGN.md를 작성할 가치가 있습니다. 하지만 Bauhaus, Swiss International, 브랜드급 현대 스타일처럼 확립된 것을 원하면 운동 전체를 직접 역설계해야 하고 미묘하게 틀릴 가능성이 높습니다.
이럴 때 라이브러리를 씁니다. Curio는 수백 가지 실제 스타일을 조사하고 구조화한 완전한 DESIGN.md로 제공하며 AI가 MCP, 공유 링크 또는 다운로드로 적용합니다. 스타일만 고르면 파일은 이미 완성되어 있습니다.
FAQ
DESIGN.md는 얼마나 길어야 하나요?
필요한 시각적 질문에 답하는 범위에서 짧을수록 좋습니다. 보통 1~2페이지로 방향, 핵심 토큰, 반복 컴포넌트 규칙, 사용 경계를 포함합니다. AI 결과를 바꾸지 않는 섹션은 삭제하세요.
프로젝트 어디에 두어야 하나요?
README.md 옆의 프로젝트 루트입니다. 코딩 에이전트가 먼저 보는 곳이며 이름의 관례와도 맞습니다. 명시적 경로나 MCP 가져오기를 지원하는 도구도 있지만 루트 배치가 가장 널리 작동합니다.
파일 하나로 써야 하나요, 여러 개로 나눠야 하나요?
하나입니다. 에이전트가 전체 시스템을 한 번에 읽는 것이 목적입니다. 여러 파일로 나누면 찾아서 조정하는 추측을 다시 도입합니다.
YAML frontmatter가 필요한가요?
Google 공개 사양이 쓰고 기계가 파싱하기 쉬워 좋은 기본값입니다. 다만 핵심은 '방향을 세부보다 먼저'입니다. 문법과 관계없이 값을 나열하기 전에 스타일을 설명해야 합니다.