DESIGN.md 사용법: AI 에이전트가 읽는 디자인 규칙 파일

버튼 색, 제목 크기, 카드 간격처럼 화면을 만들 때 반복해서 확인하는 기준을 적어요. 사람과 AI가 함께 참고하는 문서이며, 파일명만으로 모든 도구가 자동으로 읽는 표준은 아니에요.

README에는 프로젝트 소개를, CLAUDE.md나 AGENTS.md에는 작업 규칙을, DESIGN.md에는 디자인 기준을 나눠 둘 수 있어요. 작업 규칙에 ‘화면을 수정하기 전에 DESIGN.md를 읽어 주세요’라고 경로와 함께 적어 주세요.

‘좀 더 모던하게’라는 요청은 해석의 폭이 넓어요. 배경색, 제목과 본문의 크기, 모서리 반경, 간격을 구체적으로 알려 주면 원하는 방향을 전달하기 쉬워요.

기존 화면에서 자주 쓰는 값을 먼저 찾아보세요. 모든 값을 새로 정할 필요는 없어요. 이미 있는 규칙을 모으고 예외가 필요한 곳은 이유를 함께 적어요.

색상 코드에는 역할을 붙여 주세요. 같은 회색이라도 본문용인지 테두리용인지 알 수 있어야 해요. 제목과 본문은 크기, 굵기, 줄 간격을 함께 적어요.

간격은 프로젝트에서 실제로 쓰는 단위와 예외를 기록해요. 버튼에는 기본, 마우스 올림, 눌림, 비활성, 로딩 상태를 넣고 키보드 포커스도 빠뜨리지 말아 주세요. 아래는 형식을 보여 주는 예시예요. 값은 우리 제품에 맞게 바꿔 주세요. # DESIGN.md - 배경: #FFFFFF - 본문 글자: #222222 - 본문 크기: 16px, 줄 간격 1.6 - 제목 크기: 28px, 굵기 700 - 기본 간격: 8px 단위, 예외는 이유를 기록 - 버튼: 기본·포커스·비활성·로딩 상태 확인 - 완료 확인: 모바일 화면에서 글자 넘침과 대비 확인

CLAUDE.md나 AGENTS.md에는 개발 명령, 수정 범위, 검증 방법처럼 작업 전반의 규칙을 적어요. 디자인 기준이 길다면 별도 파일로 두고 필요한 작업에서 읽도록 연결하면 관리하기 편해요.

예를 들어 ‘UI를 수정할 때는 frontend/DESIGN.md를 먼저 읽어 주세요’라고 적을 수 있어요. 문서를 나눴다면 실제 경로가 맞는지, 서로 다른 규칙이 중복돼 있지 않은지도 확인해 주세요.

프로젝트 최상위나 해당 제품 폴더처럼 팀이 찾기 쉬운 곳에 두고 저장소에 함께 보관해요. 개인 컴퓨터에만 있으면 다른 팀원의 작업에는 반영되지 않아요.

관리자 화면과 고객 화면의 디자인이 다르면 파일을 나눌 수 있어요. 어느 화면에서 어느 문서를 읽을지는 작업 규칙에 명시해 주세요. 문서와 슬라이드에도 같은 방식으로 디자인 기준을 전달할 수 있어요.

AI가 DESIGN.md를 실제로 읽었는지 먼저 확인해 보세요. 문서와 기존 코드의 값이 다르면 어느 쪽을 따라야 하는지 정하고, 필요한 변경만 요청해요.

‘적당한 여백’처럼 판단하기 어려운 표현에는 값이나 화면 예시를 더해 주세요. 긴 문서는 자주 쓰는 기준과 상세 참고 자료를 나눠 볼 수 있어요. 금지 사항도 도움이 되지만, 적었다고 항상 지켜지는 것은 아니니 결과 화면을 확인해야 해요.

Figma나 코드에 있는 색·글자·간격 값을 가져오고, 각 값의 쓰임을 설명해 주세요. 버튼이나 카드의 동작은 실제 컴포넌트와 맞춰 봐요.

문서를 읽게 한 뒤 화면 하나를 만들어 보세요. 다른 값이 나온 곳을 찾아 문서가 부족했는지, 코드에 예외가 있었는지 확인해요. 이 과정에서 필요한 설명을 보완하면 돼요.

공개된 DESIGN.md를 참고하면 어떤 항목을 적을지 감을 잡기 좋아요. 사용 조건을 확인한 뒤 우리 제품의 값과 규칙으로 바꿔 주세요.

스킬로 배포된 경우에는 문서를 채우는 절차나 검수 방법이 함께 들어 있을 수 있어요. 구성 내용을 확인하고, 복사한 예시 값이 실제 화면에 그대로 들어가지 않도록 살펴봐요.