Sik.limited Logo

AI가 만든 화면의 일관성을 높이는 DESIGN.md 작성법

색상과 간격부터 적용 원칙까지 AI와 공유할 디자인 기준을 정리해요.

·

AI에게 ‘브랜드에 맞는 화면을 만들어 달라’고 했는데 결과마다 색과 간격이 달라진다면, 프롬프트보다 먼저 공유할 디자인 기준이 필요할 수 있어요. DESIGN.md는 기계가 읽을 수 있는 토큰과 사람이 읽을 수 있는 디자인 설명을 한 파일에 담아, 코딩 에이전트가 프로젝트의 시각적 방향을 계속 참고하도록 돕는 형식입니다.

이 글에서는 Google Labs의 공개 형식을 따라 실무에서 바로 채울 수 있는 문서 구조를 만들고, 어디까지 믿어야 하는지도 함께 짚어봅니다.

디자인 토큰과 브랜드 원칙

색상 토큰에 primary: '#2457D6'라고 적으면 에이전트는 정확한 색을 알 수 있습니다. 하지만 이 파랑이 기본 버튼에만 쓰이는지, 링크와 배지에도 쓰이는지, 어두운 배경에서는 어떻게 바꿔야 하는지는 알 수 없어요. 값만 전달했을 때 화면이 ‘정확하지만 어색한’ 이유입니다.

Google의 DESIGN.md는 YAML 형식의 토큰과 Markdown 설명을 함께 둡니다. 토큰은 색·글꼴·간격처럼 재사용할 값을 제공하고, 설명은 그 값이 어떤 인상을 만들며 어떤 상황에 적용되는지 알려줘요. 예를 들면 ‘따뜻한 종이색 배경은 긴 글을 읽는 화면에 사용하고, 강조색은 주요 행동 하나에만 쓴다’처럼 맥락까지 적는 방식입니다.

DESIGN.md 목적과 대상 정의

파일 맨 앞에는 디자인 시스템 이름을 적고, 본문 첫 섹션에는 제품과 사용자를 설명합니다. 화면의 목적도 구체적으로 쓰는 편이 좋아요. ‘모던하고 세련된 서비스’보다 ‘운영자가 매일 주문 상태를 확인하는 관리 화면이며, 장식보다 빠른 스캔과 오류 예방이 우선’이라는 설명이 더 많은 결정을 안내합니다.

---
name: Northstar Console
colors:
  primary: "#2457D6"
  ink: "#172033"
  surface: "#FFFFFF"
  canvas: "#F4F6FA"
  muted: "#667085"
  border: "#D8DEE9"
typography:
  heading:
    fontFamily: Inter
    fontSize: 1.5rem
    fontWeight: 650
  body:
    fontFamily: Inter
    fontSize: 1rem
    lineHeight: 1.5
rounded:
  control: 8px
  panel: 12px
spacing:
  xs: 4px
  sm: 8px
  md: 16px
  lg: 24px
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "#FFFFFF"
    rounded: "{rounded.control}"
    padding: 10px
---

## Overview

운영자가 주문 상태를 빠르게 찾고 실수를 줄이는 업무용 콘솔입니다.
화면은 차분하고 정보 밀도가 높아야 하며, 강한 색은 주요 행동과
선택 상태에만 사용합니다.

예시는 시작점일 뿐입니다. 토큰 이름과 계층을 팀의 언어에 맞춰 정하고, 실제 코드의 CSS 변수나 컴포넌트 이름과 연결해 두세요. 기존 디자인 시스템에 --color-action이나 Button/Primary 같은 이름이 이미 있다면 문서에서도 같은 의미를 유지해야 합니다.

색상·타이포그래피·간격 토큰

색상 팔레트를 blue-500, gray-100처럼 색조로만 나누면 사용처가 다시 구현자에게 맡겨집니다. primary, surface, border, muted처럼 역할 중심으로 이름을 붙이면 화면 요소에 연결하기 쉬워져요. 색의 원래 값과 쓰임을 본문에도 설명하고, 상태별 색상(성공·경고·오류)이나 배경과 글자 조합이 필요한 제품은 그 규칙을 함께 정의합니다.

타이포그래피도 글꼴 하나만 기록하지 마세요. 제목, 본문, 보조 문구처럼 실제 위계로 나누고 크기·굵기·행간을 같이 적습니다. 레이아웃은 기준 간격과 콘텐츠 폭을, 모양은 버튼과 카드의 모서리 반경을 정리하면 화면마다 임의의 수치가 생기는 일을 줄일 수 있어요.

컴포넌트 디자인 규칙

모든 컴포넌트를 한 번에 규정하려고 하면 문서가 금방 커집니다. 우선 자주 쓰이고 화면의 인상을 좌우하는 기본 버튼, 입력창, 카드, 내비게이션부터 시작해 보세요. 버튼은 높이와 안쪽 여백, 라운드, 텍스트 색, 포커스 표시를 정합니다. 입력창은 기본·오류·비활성 상태와 도움말 배치까지 적을 수 있습니다.

문서의 규칙은 코드에서 구현 가능한 수준이어야 합니다. ‘가벼운 느낌’만으로는 충분하지 않아요. ‘카드 그림자는 기본 상태에서 사용하지 않고, 선택된 카드에만 2px 강조 테두리를 표시한다’처럼 관찰하고 확인할 수 있는 문장으로 바꿉니다. 반대로 모든 픽셀과 예외를 DESIGN.md에 복제하기보다 실제 컴포넌트 API와 디자인 시스템 문서로 연결하세요. 이 파일은 구현 설명서 전체가 아니라 생성과 수정에 필요한 핵심 디자인 맥락입니다.

권장 사항과 금지 사항

Do’s and Don’ts 섹션에는 에이전트가 반복해서 실수하는 선택을 기록합니다. 예를 들어 ‘주요 행동 버튼은 화면마다 하나를 강조한다’, ‘비활성 상태를 색상만으로 구분하지 않는다’, ‘본문에서 회색 텍스트 대비를 낮추지 않는다’처럼 작성할 수 있어요. 왜 피해야 하는지도 짧게 붙이면 예외 상황에 판단 근거로 활용할 수 있습니다.

특정 브랜드나 외부 디자인 시스템을 참고했다면 출처와 적용 범위를 구분하세요. 공식 문서가 직접 정의한 값, 공개 화면에서 관찰한 값, 자체적으로 조정한 값은 같은 종류의 사실이 아닙니다. 문서가 독립적인 재구성이라면 공식 구현이나 완전한 준수처럼 표현하지 않는 것이 중요해요.

DESIGN.md 적용과 검증

프로젝트 루트에 DESIGN.md를 두고 에이전트에게 파일을 읽으라고 요청한 뒤, 동일한 화면을 한 번에 전부 만들기보다 작은 과제로 확인합니다. 예를 들어 ‘이 규칙에 맞춰 로그인 폼의 버튼과 입력창만 구현하고, 사용한 토큰을 알려줘’라고 시켜 보세요. 결과의 색상·간격·포커스 상태가 기대와 다르면 문서의 모호한 규칙을 수정합니다.

Google Labs에서 공개한 CLI는 문서의 구조를 검사하고 토큰 참조가 끊겼는지 확인하며, 일부 텍스트·배경 조합의 WCAG AA 대비 비율도 경고합니다. 프로젝트에서 실행하려면 다음 명령을 사용할 수 있어요.

npx @google/design.md lint DESIGN.md

이 검사는 문서의 유효성과 일부 규칙을 살피는 단계입니다. 화면이 의도대로 구현됐는지, 상호작용이 접근 가능한지, 모든 시각 규칙이 완벽히 준수됐는지를 보증하지는 않아요. 실제 페이지를 열어 데스크톱과 모바일, 키보드 조작, 대비와 상태 변화를 함께 확인해야 합니다.

알파 사양과 문서 유지관리

DESIGN.md는 에이전트에게 구체적인 시각 맥락을 전달하고 여러 생성 결과의 편차를 줄이는 데 쓸 수 있습니다. 다만 Google이 공개한 이 형식은 현재 alpha 상태이며, 저장소의 사양과 토큰 구조, CLI가 발전 중입니다. 정식 국제 표준이나 어떤 코딩 에이전트에서나 자동으로 읽히는 보편 규칙이라고 부르기는 이릅니다. 사용 중인 도구가 파일을 읽는지 확인하고, 필요하면 작업 프롬프트나 AGENTS.md, CLAUDE.md에서 참조하도록 안내하세요.

좋은 문서는 토큰 수를 늘리는 문서가 아닙니다. 디자이너와 개발자가 같은 결정을 같은 말로 설명하도록 돕고, 에이전트가 화면을 만들 때 그 결정을 재사용할 수 있게 하는 문서예요. 핵심 화면 몇 개에서 먼저 써보고, 실제 리뷰에서 발견한 모호함을 다음 버전에 반영해 보세요.

참고 자료

최신 글