DESIGN.md는 무엇인가

DESIGN.md는 AI 코딩 도구가 프로젝트의 시각 규칙을 계속 참고할 수 있도록 만든 일반 텍스트 파일입니다. 색상과 글꼴처럼 값이 분명한 항목은 YAML 토큰으로, 브랜드 분위기와 사용 원칙처럼 설명이 필요한 항목은 Markdown 문장으로 작성합니다.

공식 명세가 제시하는 핵심은 두 가지입니다.

  • 정확한 값: 색상, 타이포그래피, 간격, 모서리와 컴포넌트 토큰
  • 적용 이유: 어떤 상황에서 무엇을 사용하고 피해야 하는지에 대한 설명

현재 공식 명세는 alpha 단계라서 형식과 도구가 달라질 수 있습니다. 프로젝트에 도입한 뒤에는 공식 저장소의 변경사항을 가끔 확인하는 것이 좋습니다.

설치가 필요한가

단순히 사용하는 데는 설치가 필요하지 않습니다. 프로젝트 최상위 폴더에 DESIGN.md 파일을 두는 것으로 시작할 수 있습니다.

my-project/
├─ src/
├─ package.json
├─ README.md
└─ DESIGN.md

공식 CLI는 파일 구조 검사, 버전 비교 또는 Tailwind·디자인 토큰 형식으로 내보낼 때만 선택적으로 설치하면 됩니다.

1단계: DESIGN.md 만들기

처음부터 모든 컴포넌트를 적으려고 하지 말고 현재 서비스에서 반복되는 기본 규칙부터 기록합니다.

---
version: alpha
name: Lootnary
colors:
  primary: "#3949AB"
  surface: "#FFFFFF"
  text: "#202436"
typography:
  body:
    fontFamily: Noto Sans KR
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.7
rounded:
  sm: 4px
  md: 8px
spacing:
  sm: 8px
  md: 16px
---

## Overview

정보를 빠르게 찾을 수 있는 차분하고 읽기 쉬운 화면을 만든다.

## Components

- 주요 버튼은 한 화면에 하나만 강조한다.
- 본문 카드는 장식보다 제목과 요약의 위계를 우선한다.

## Do's and Don'ts

- 모바일에서 본문 글자를 지나치게 작게 만들지 않는다.
- 같은 화면에서 서로 다른 모서리 스타일을 섞지 않는다.

색상 이름만 나열하기보다 실제 값과 사용 위치를 함께 적는 것이 중요합니다. 예를 들어 primary가 링크인지 주요 버튼인지 설명하면 AI가 모든 요소를 같은 색으로 칠하는 실수를 줄일 수 있습니다.

2단계: AI 코딩 도구에 적용하기

파일을 만들었다고 모든 도구가 자동으로 읽는 것은 아닙니다. 처음 작업할 때는 파일 경로와 적용 범위를 명확히 알려주는 것이 좋습니다.

프로젝트 루트의 DESIGN.md를 먼저 읽어줘.
색상, 타이포그래피, 간격과 컴포넌트 규칙을 기준으로 이 페이지를 수정하고,
기존 기능과 모바일 레이아웃은 유지해줘.

새 화면을 만들 때도 “예쁘게 만들어줘”라고만 요청하기보다 DESIGN.md 준수, 모바일 확인, 기존 컴포넌트 재사용을 함께 지정하면 결과가 안정적입니다.

3단계: 공식 CLI로 검사하기

Node.js와 npm을 사용하는 환경이라면 설치 없이 npx로 검사할 수 있습니다.

npx @google/design.md lint DESIGN.md

Windows PowerShell에서 패키지 이름 처리 문제가 생기면 따옴표를 사용해 설치합니다.

npm install "@google/design.md"
npx @google/design.md lint DESIGN.md

검사는 끊어진 토큰 참조, 기본 색상 누락, 낮은 명암 대비와 섹션 순서 등을 알려줍니다. 경고가 나왔다고 무조건 실패한 것은 아니므로 결과의 경로와 메시지를 읽고 실제 화면에 필요한 항목인지 판단합니다.

4단계: 변경 전후 비교하기

디자인 규칙을 크게 수정할 때는 이전 파일을 보관하고 공식 diff 명령으로 차이를 확인할 수 있습니다.

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

Tailwind나 다른 디자인 토큰 형식이 필요하면 export를 사용할 수 있습니다.

npx @google/design.md export --format css-tailwind DESIGN.md > theme.css

명령 결과를 바로 덮어쓰기 전에 별도 파일로 생성하고 기존 CSS와 충돌하는 값이 없는지 검토하는 편이 안전합니다.

실제 적용 순서

제가 적용한다면 다음 순서로 진행합니다.

  1. 기존 화면에서 반복되는 색상과 글꼴, 간격을 조사합니다.
  2. 최소한의 토큰과 사용 원칙으로 DESIGN.md를 만듭니다.
  3. 영향이 작은 한 페이지에 먼저 적용합니다.
  4. PC와 모바일 화면을 비교합니다.
  5. 버튼, 입력창과 링크의 명암 대비를 확인합니다.
  6. 결과가 괜찮으면 공통 컴포넌트로 범위를 넓힙니다.

한 번에 전체 사이트를 다시 디자인하면 어디서 문제가 생겼는지 찾기 어렵습니다. 작은 화면부터 적용하고 확인한 규칙만 파일에 남기는 편이 실제 운영에 유리합니다.

사용할 때 주의할 점

  • DESIGN.md는 완성된 UI 코드가 아니라 디자인 판단 기준입니다.
  • AI가 만든 결과는 모바일 레이아웃과 접근성을 직접 확인해야 합니다.
  • 브랜드 사이트에서 가져온 규칙은 로고와 이미지까지 복제해도 된다는 의미가 아닙니다.
  • 공식 형식이 아직 발전 중이므로 CLI 버전과 명세를 함께 확인합니다.
  • 토큰이 너무 많으면 서로 충돌할 수 있으므로 실제 사용하는 값부터 기록합니다.

이런 사람에게 유용하다

  • AI 코딩을 할 때 페이지마다 디자인이 달라지는 사람
  • 여러 명이 같은 프로젝트의 UI를 수정하는 팀
  • 색상과 간격 값을 코드와 문서에서 함께 관리하고 싶은 사람
  • 기존 디자인을 유지하면서 새 페이지를 빠르게 추가하려는 사람

디자인을 자동으로 잘 만들어주는 마법 파일은 아니지만, AI에게 매번 같은 설명을 반복하지 않게 해주는 실용적인 기준점으로 사용할 수 있습니다.