AI가 화면마다 다른 파란색과 간격을 만들 때 “일관되게 해 줘”를 반복하면 기준이 대화 안에만 남습니다. 필요한 것은 예쁜 예시 모음이 아니라 값, 적용 이유, 변경 증거를 연결한 디자인 계약입니다. DESIGN.md는 그 계약을 한 파일로 표현하는 선택지입니다. 다만 2026년 8월 31일 기준 Google Labs 공식 규격은 현재 버전을 alpha로 표시합니다. 확정된 업계 표준이나 모든 에이전트가 자동 발견하는 파일로 소개하면 안 됩니다.
계약은 세 가지 산출물로 나눈다
1. 토큰 원본: 색, 글꼴, 간격, 모서리처럼 코드가 재사용할 값을 YAML 전면부에 둡니다.
---
version: alpha
name: CHAI NUP UI
colors:
primary: "#2B1238"
surface: "#F7F5F2"
typography:
body-md:
fontFamily: Pretendard
fontSize: 16px
fontWeight: 400
lineHeight: 1.6
spacing:
sm: 8px
md: 16px
rounded:
md: 8px
---공식 형식은 YAML 토큰을 규범 값으로, Markdown 본문을 적용 맥락으로 구분합니다. 위 값은 예시이므로 실제 브랜드 원본과 코드의 기존 토큰을 대조해 바꿉니다.
2. 판정 가능한 규칙: 본문에는 “현대적으로” 대신 “primary는 화면의 최우선 행동 하나에만 사용”, “본문은 body-md보다 작게 만들지 않음”처럼 위반 여부를 확인할 수 있는 문장을 둡니다. 기본·hover·focus·disabled 상태, 허용 조합과 금지 조합을 함께 적습니다. 그림자를 쓰지 않는다면 빈 항목을 채우지 말고 omitted에 섹션과 이유를 기록할 수 있습니다.
3. 변경 증명 묶음: 토큰을 바꾼 PR에는 변경 이유, 영향받는 컴포넌트, 전후 화면, 키보드 포커스·명암 확인, 되돌릴 커밋을 붙입니다. 문서만 바꾸거나 코드만 바꾸지 않고 같은 변경 단위에서 검토합니다.
에이전트 연결은 명시한다
파일 이름만 맞춘다고 Codex가 항상 읽는 것은 아닙니다. OpenAI의 AGENTS.md 공식 안내에 따르면 Codex는 프로젝트 루트에서 현재 작업 디렉터리까지 AGENTS.md 계열 지침을 탐색하고 더 가까운 지침을 우선 적용합니다. 저장소 지침에 다음과 같은 연결 문장을 둡니다.
프론트엔드 변경 전 DESIGN.md를 읽고 적용할 토큰 3개와 금지 규칙을 요약한다.작은 버튼 변경을 맡기기 전에 에이전트가 읽은 파일 경로, 적용 토큰, 예외 상태를 먼저 출력하게 합니다. 요약이 틀리면 UI를 생성하기 전에 지침의 위치와 범위를 고칩니다. 이 연결은 여러 모델의 결과를 같게 보장하지 않지만 어떤 규칙이 누락됐는지 추적하게 합니다.
CLI가 확인하는 것과 못 하는 것
Google Labs 공식 저장소는 다음 명령을 안내합니다.
npx @google/design.md lint DESIGN.md
npx @google/design.md diff DESIGN.md DESIGN-v2.mdlint는 구조, 깨진 토큰 참조와 일부 명암 관련 항목을 점검하고, diff는 토큰 변화와 전후 검사 결과를 비교합니다. 두 명령이 통과해도 문구의 적절성, 실제 렌더링, 모든 접근성 요구를 보증하지는 않습니다. 알파 규격이므로 도구 업데이트 전에 별도 브랜치에서 검사하고 결과가 달라지면 스키마 변경부터 확인합니다.
15분 도입 완료 기준
- 실제 코드에서 반복되는 토큰만 전면부에 옮겼다.
- 본문 규칙마다 위반 사례를 하나 적었다.
AGENTS.md가DESIGN.md경로를 명시한다.- lint 결과와 모바일·데스크톱 화면을 함께 확인했다.
- 토큰 변경 PR에 영향 화면과 되돌리기 지점을 남겼다.
이 다섯 항목을 통과하면 파일의 길이보다 강한 계약이 됩니다. 새 화면 한 장으로 먼저 시험한 뒤 범위를 넓히는 편이 안전합니다. 목적은 AI가 취향을 추측하지 않게 하고, 사람이 값의 이유와 변경 영향을 다시 검증할 수 있게 만드는 것입니다.