DESIGN.md 작성법, 받은 디자인 문서를 내 사이트에 맞게 고치기

DESIGN.md는 AI 코딩 에이전트가 화면을 만들 때 따를 디자인 규칙을 적어 두는 마크다운 파일입니다. 공개된 DESIGN.md를 받아 붙이는 데서 끝내지 않고, 결과 화면을 평가해 내 서비스에 맞는 규칙으로 고쳐 쓰는 DESIGN.md 작성법을 17단계로 정리했습니다. 파일 형식과 검사 명령, 규칙 문장 예시도 함께 담았습니다.

기능은 되는데 화면이 촌스러운 문제

스킬(AI에게 반복 업무 절차를 알려 주는 작업 매뉴얼)을 붙여 기획과 검증을 통제하면, 검색⁠·필터⁠·데이터 수집 같은 기능은 꽤 안정적으로 만들어집니다. 그런데 막상 화면을 열면 묘하게 촌스럽거나, 글자가 너무 많거나, AI가 만든 티가 나는 경우가 많습니다.

기능은 지시 파일로 통제하는데 화면은 왜 못 할까. 화면에도 같은 방식의 하네스(AI가 정해 둔 규칙 안에서 일하게 하는 장치)를 거는 것이 DESIGN.md입니다.

DESIGN.md란 무엇인가

DESIGN.md는 구글의 AI 디자인 도구 스티치(Stitch)가 도입한 형식입니다. AI 에이전트가 일관된 디자인으로 화면을 만들도록 버튼 스타일, 여백, 색상, 글꼴 같은 디자인 요소를 문서 한 장에 정해 둡니다. 매번 "예쁘게 만들어 줘", "애플처럼 미니멀하게", "좀 더 고급스럽게"라고 말하는 대신, 이 프로젝트의 화면은 앞으로 이런 원칙을 따른다는 규칙을 적어 두고 AI가 그걸 읽은 다음 작업하게 하는 방식입니다.

파일은 에이전트용 지침 파일(AGENTS.md나 CLAUDE.md)과 같은 위치, 보통 프로젝트 맨 위 폴더에 둡니다.

파일 형식: 정확한 값과 이유를 같이 적는다

구글이 공개한 형식 명세(깃허브 google-labs-code/design.md, Apache 2.0 라이선스, 아직 알파 단계)를 보면 DESIGN.md는 두 층으로 이루어집니다.

• 디자인 토큰: 파일 맨 위 --- 사이에 YAML(들여쓰기로 값을 적는 설정 형식)로 색상 코드, 글꼴 크기, 모서리 둥글기, 간격 같은 정확한 값을 적습니다.
• 본문: 그 값을 왜 쓰는지, 어떻게 적용하는지를 ## 구획마다 글로 적습니다.

구획은 Overview(전체 분위기), Colors, Typography, Layout, Elevation & Depth(그림자와 높이), Shapes, Components, Do's and Don'ts(해야 할 것과 하지 말 것) 순서를 권합니다. 토큰이 정확한 값을 주고, 본문이 그 값을 쓰는 이유와 방법을 알려 주는 구조입니다.

백지에서 쓰지 않는다

DESIGN.md는 백지에서 쓰기보다 이미 다듬어진 문서에서 시작하는 편이 낫습니다. 그 대표가 Awesome DESIGN.md입니다. 깃허브 VoltAgent/awesome-design-md 저장소로, 애플⁠·에어비앤비 같은 웹 디자인으로 유명한 서비스의 디자인 시스템을 분석해 DESIGN.md 한 장씩으로 정리해 뒀습니다. 별(관심 표시)은 2026년 10월 기준 약 12만 3천 개이고 MIT 라이선스입니다.

준비물

• 디자인을 바꿀 기존 웹사이트 프로젝트. 아래 예시는 AI 지원 사업⁠·공모전 정보를 모아 보여 주는 한국어 사이트입니다.
• 코덱스(Codex)나 클로드 코드 같은 AI 코딩 에이전트
• 인터넷 연결(깃허브 저장소 열기)

1. 디자인 문서 가져오기

1. 브라우저에서 Awesome DESIGN.md 저장소(github.com/VoltAgent/awesome-design-md)를 엽니다.
   • 확인: 여러 브랜드 이름이 나열된 목록이 보입니다.
2. 목록에서 원하는 디자인의 서비스를 고릅니다. 예시는 애플입니다.
   • 확인: 고른 브랜드의 상세 페이지가 열립니다.
3. 미리보기를 확인합니다.
   • 확인: 이 디자인을 적용하면 어떤 색상과 타이포그래피를 쓰고 버튼을 어떻게 그리는지, 결과가 어떻게 나오는지 볼 수 있습니다.
4. 페이지의 다운로드 항목이나 DESIGN.md 파일을 엽니다.
   • 확인: DESIGN.md 문서 내용이 보입니다.
5. 문서 내용을 전체 복사합니다.

2. 프로젝트에 적용하기

6. 내 프로젝트 맨 위 폴더(AGENTS.md나 CLAUDE.md가 있는 곳)에 DESIGN.md라는 파일을 만듭니다.
7. 복사한 내용을 DESIGN.md에 붙여 넣고 저장합니다.
   • 확인: 파일 맨 위에 색상⁠·글꼴 값이, 아래에 설명 글이 들어 있습니다.
8. 코덱스에 아래 리팩터링 지시를 입력합니다.
   • 주의: 7단계 붙여 넣기와 저장이 끝난 뒤에 지시합니다.

디자인에 대한 방향성이 바뀌었으니 DESIGN.md 파일을 읽고 이에 맞춰서 다시 웹사이트를 리팩토링하라

9. 지시를 보냅니다.
   • 확인: 코덱스가 작업을 마치면 이전 결과물과 비교할 수 있는 새 화면이 나옵니다.

애플 문서를 적용하면 1차 결과는 확실히 애플 웹사이트처럼 나옵니다. 검은 배경에 큰 헤드라인, 넓은 여백, 검정과 밝은 회색 배경을 번갈아 쓰는 구성, 애플 블루 강조색까지 문서에 적힌 대로 따라 합니다.

3. 결과를 평가하고 다듬기

10. 결과 화면에서 아쉬운 점을 찾아 적습니다. 1차 결과에서 흔히 보이는 문제는 이렇습니다.
    • 글이 너무 많아 미니멀하지 않고 화면이 피곤해 보인다
    • 줄바꿈 위치가 이상하다. 한 줄로 이어져야 할 문장이 엉뚱한 곳에서 끊긴다
    • 아래쪽 버튼 위치가 옆 카드들과 맞지 않아 레이아웃이 어수선하다
11. 코덱스에 보정 요청을 입력합니다. 끝의 "바로 수행하지 말고 일단 계획부터 수립하라"가 에이전트가 곧바로 코드를 고치지 못하게 막는 장치입니다.

디자인이 이상하니 좀 더 다듬어 달라. 애플스럽게 만들어 주고 줄바꿈과 버튼의 위치 그리고 글의 양을 다시 조정하고 그때 바로 수행하지 말고 일단 계획부터 수립하라

12. 요청을 보냅니다.
    • 확인: 에이전트가 결과물을 분석해 무엇을 어떻게 고칠지 계획부터 세워 보고합니다.
13. 보고된 계획을 읽고, 빠진 문제가 있으면 덧붙여 달라고 합니다.
14. 계획에 동의하면 구현하라고 지시합니다.
    • 주의: 계획을 먼저 보고받은 뒤에 구현을 지시합니다.
15. 새 결과 화면을 확인합니다. 2차 결과에서 기대할 변화는 이렇습니다.
    • 첫 화면(히어로 섹션)의 문장이 짧게 압축된다
    • 줄바꿈이 낱말 단위로 제대로 된다
    • 글의 양이 확실히 준다
    • 버튼 위치가 들쭉날쭉하지 않고 맞춰진다
    • 검색, 필터, 공고 링크 같은 기능은 그대로 작동한다

4. 고친 점을 DESIGN.md 규칙으로 남기기

처음 받은 DESIGN.md도 색상, 타이포그래피, 레이아웃, 버튼까지 잘 정리된 문서입니다. 그런데 1차 결과가 완벽하지 않았던 이유는 분명합니다. 그 문서는 애플 웹사이트에서 영감을 받은 일반 디자인 시스템이지, 한국어로 된 공모전 정보 사이트에 맞춘 문서가 아니기 때문입니다. 공개 문서는 좋은 출발점이지만, 결과를 평가한 뒤 내 서비스에 맞게 다시 깎는 과정이 꼭 필요합니다.

16. 10단계에서 찾은 문제를 DESIGN.md의 Do's and Don'ts 구획에 규칙 문장으로 적습니다. 위 사례라면 이런 식입니다.
    • 확인: 다음 작업에서 "더 애플스럽게", "글 줄여 줘", "버튼 위치 다시 잡아 줘"를 또 말하지 않아도 되는 상태가 목표입니다.

## Do's and Don'ts

- Do: 한국어 문장은 어절 단위로만 줄을 바꾼다. 본문과 제목에 word-break: keep-all을 적용한다.
- Do: 첫 화면 헤드라인은 한 문장, 설명은 두 줄 안쪽으로 쓴다.
- Do: 카드 안 버튼은 카드 아래쪽에 맞춰 같은 높이에 둔다.
- Don't: 한 구획에 설명 문단을 세 개 넘게 넣지 않는다.
- Don't: 공고 데이터를 꾸미려고 원문에 없는 문구를 지어내지 않는다.

17. 이후 비슷한 작업을 할 때마다 같은 과정(적용 → 평가 → 계획 → 수정 → 규칙 추가)을 되풀이하며 문서를 고쳐 갑니다.
    • 확인: 시간이 지날수록 내가, 또는 우리 팀이 원하는 대로 에이전트를 통제하는 문서가 됩니다.

고친 문서를 검사하는 명령

구글의 DESIGN.md 도구로 고친 문서가 형식에 맞는지 검사할 수 있습니다. Node.js가 설치돼 있으면 프로젝트 폴더에서 실행합니다.

npx @google/design.md lint DESIGN.md

토큰 이름이 잘못 연결된 곳, 글자색과 배경색의 대비가 웹 접근성 기준(WCAG)에 못 미치는 곳 같은 문제를 찾아 줍니다. 고치기 전 파일을 DESIGN-v1.md처럼 남겨 두었다면, 두 버전에서 무엇이 바뀌었는지도 비교할 수 있습니다.

npx @google/design.md diff DESIGN-v1.md DESIGN.md

최종 점검

• 프로젝트에 DESIGN.md 파일이 있고 내용이 들어 있다 (6~7단계)
• 에이전트가 DESIGN.md에 맞춰 화면을 고쳤다 (9단계)
• 계획 보고를 받은 뒤 구현을 지시해 2차 결과를 확인했다 (12~15단계)
• 부족했던 점을 DESIGN.md 규칙으로 남겼다 (16단계)

디자인 하네스는 쌓아 가는 자산

하네스는 클릭 한 번으로 끝나지 않습니다. 검증된 문서에서 시작하되, 반복된 테스트와 피드백으로 개인이나 회사가 쌓은 노하우를 문서에 녹여 넣어야 합니다. 그렇게 자산으로 키운 문서가 있어야 빠르게 달리는 LLM(대규모 언어 모델)을 내가 원하는 방식으로 다룰 수 있습니다. Awesome DESIGN.md나 gstack 같은 공개 자료는 도착점이 아니라 출발점입니다.