DESIGN.md로 AI가 읽을 디자인 기준 정리하기

같은 역할의 버튼이 화면마다 다르게 구현되지 않도록 색상, 크기와 상태 규칙을 공유해야 합니다. DESIGN.md에 기준값과 적용 조건을 적으면 구현자가 기존 CSS 토큰과 컴포넌트를 대조할 수 있습니다.

DESIGN.md는 색상, 글자, 간격, 구성요소와 사용 규칙을 마크다운 문서로 정리하는 방식입니다. designmd.sh 공식 안내는 이런 문서를 찾아보고 프로젝트에 가져오는 공개 레지스트리를 설명합니다. 구현자는 가져온 문서를 현재 제품의 기준과 비교해 적용할 부분을 정합니다. 이 글에서는 버튼 기준을 문서와 코드에서 대조하는 예시를 설명합니다.

구현자가 대조할 디자인 값

주요 버튼의 기준을 남긴다면 색상, 최소 높이, 안쪽 간격, 초점 표시, 비활성 상태를 적습니다. 구현자는 이 항목을 실제 CSS와 대조할 수 있습니다.

각 값에는 역할을 함께 씁니다. 강조 색상은 주요 행동에 사용할지 선택 상태에 사용할지 구분합니다. 버튼의 기본·사용 중·비활성·오류 상태도 각각 정의할 수 있습니다.

다음은 직접 작성한 버튼 기준의 예시입니다. 제시한 색상과 크기는 확정된 프로젝트 값이나 접근성 검증 결과가 아닙니다.

항목	예시 기준	코드에서 대조할 부분
주요 행동 색상	배경 #2457c5, 글자 #fff	공통 색상 변수
버튼 높이와 간격	최소 높이 2.75rem, 좌우 간격 1rem	버튼 클래스의 높이와 padding
키보드 초점	2px 외곽선, 3px 간격	:focus-visible
비활성 상태	불투명도 0.55	:disabled

:root {
  --action-bg: #2457c5;
  --action-text: #fff;
}

.action {
  min-height: 2.75rem;
  padding: 0.5rem 1rem;
  background: var(--action-bg);
  color: var(--action-text);
}

.action:focus-visible {
  outline: 2px solid #242424;
  outline-offset: 3px;
}

.action:disabled {
  opacity: 0.55;
}

버튼 요소에 .action을 적용했다고 가정하면 문서의 색상과 크기를 CSS 선언에 하나씩 대조할 수 있습니다. 기존 토큰이나 컴포넌트가 있다면 새 값을 추가하기 전에 그 기준을 참조합니다.

직접 만든 버튼 기준 예시입니다. 문서의 값과 CSS 토큰, 포커스·진행·비활성 상태를 대조할 위치를 표시했습니다. 실제 제품 값이 아닙니다.

작업 절차와 화면 기준의 연결

스킬 문서에는 작업 절차와 참고 자료를, DESIGN.md에는 결과물의 색상·글자·간격과 구성요소 기준을 적습니다. 구현 요청에서 두 문서를 참조하면 에이전트가 따를 절차와 결과를 검사할 값을 함께 지정할 수 있습니다.

에이전트가 해당 문서를 읽도록 프로젝트 지침이나 작업 요청에서 참조합니다. 루트 기준과 특정 화면의 추가 기준이 있다면 어느 부분에 무엇을 적용할지도 적습니다.

문서를 수정했는데 화면은 전과 같다면, 문서에 적은 값이 실제 CSS 토큰이나 컴포넌트에 반영됐는지 확인해야 합니다. 코드와 문서의 색상 값이 다르면 어느 쪽이 현재 정본인지 확인합니다. 문서만 수정하고 실제 토큰을 바꾸지 않았다면 화면이 바뀌지 않습니다. 반대로 코드만 바꾸고 문서를 갱신하지 않으면 다음 구현자가 문서에 남은 이전 기준을 사용할 수 있습니다.

레지스트리에서 채택할 문서

designmd.sh에서 발견한 파일은 참고할 디자인 기준의 후보입니다. 다른 제품의 분석 문서나 예시가 자신의 제품에도 그대로 맞는지는 확인해야 합니다. 브랜드 이름과 이미지 사용 조건, 외부 링크, 필요한 자산도 살펴봅니다.

문서에 실행 명령이나 외부 전송 지시가 포함돼 있다면 디자인 기준과 구분합니다. 공개 파일을 읽었다고 설치, 로그인, 권한 변경, 게시까지 승인받은 것은 아닙니다. 자동 감사 표시가 있더라도 구현자는 실제 내용을 읽고 현재 작업에서 사용할 범위를 정해야 합니다.

기존 DESIGN.md와 가져온 문서를 비교해 채택할 항목을 정합니다. 주요 버튼 기준을 추가하는 작업이라면 현재 색상 토큰과 상태 규칙을 보존할지 먼저 판단합니다.

화면과 코드에 적용된 기준

문서를 적용한 뒤에는 대표 화면에서 같은 역할의 버튼이 같은 방식으로 표시되는지 확인합니다. 기본·키보드 초점·비활성 상태를 각각 열어 보고, 대비와 키보드 조작을 검사합니다. 긴 문구와 좁은 화면에서도 높이와 간격이 유지되는지 확인한 뒤 문서와 코드의 값을 함께 갱신합니다.

확인한 기준은 문서와 코드에 함께 반영합니다. 아직 검증하지 못한 대비나 상태 조건은 확정값과 구분해 남겨 다음 구현에서 다시 확인할 수 있게 합니다.