문서
DESIGN.md란 무엇인가요?
DESIGN.md는 AI 에이전트를 위해 디자인 시스템을 설명하는 일반 텍스트 파일이에요. 맨 위의 YAML 프런트매터에는 색상, 타이포그래피, 간격, 모서리 둥글기, 컴포넌트 같은 정확한 디자인 토큰이 담겨요. 그 아래 Markdown 본문은 토큰을 어떻게, 왜 적용하는지 설명해요. 사람과 에이전트 모두 읽고, 편집하고, 적용할 수 있어요.
README.md는 프로젝트가 무엇인지 설명해요. AGENTS.md는 코딩 에이전트에게 프로젝트를 빌드하는 방법을 알려 줘요. DESIGN.md는 프로젝트가 어떤 모습과 느낌이어야 하는지 알려 줘서, 에이전트가 만드는 화면들이 제각각 흩어지지 않고 하나의 팔레트, 타입 스케일, 컴포넌트 언어를 공유하게 해요.
DESIGN.md의 기원
Google은 AI 디자인 도구인 Google Stitch와 함께 AGENTS.md의 디자인 버전으로 DESIGN.md를 선보였어요. Google Labs는 이 형식을 google-labs-code/design.md 저장소에 Apache 2.0 라이선스의 오픈 사양으로 공개하고 있어요. DESIGN.md 사양은 알파 단계로 표시되어 있으므로, 형식이 성숙해지면서 바뀔 수 있어요.
같은 저장소에서 npm 패키지 @google/design.md도 제공해요. 구조, 깨진 토큰 참조, WCAG 대비를 검사하는 lint 명령과, 파일의 두 버전을 토큰 단위로 비교하는 diff 명령이 들어 있어요.
DESIGN.md 파일의 구조
모든 DESIGN.md 파일은 두 층으로 되어 있어요. YAML 프런트매터에는 정확한 색상 값, 폰트 속성, 간격 스케일, 컴포넌트 토큰 참조 같은 기계가 읽을 수 있는 디자인 토큰이 담겨요. Markdown 본문은 사람이 읽을 수 있는 디자인 설계 근거를 제공해요.
사양은 토큰을 규범적인 값으로, 설명을 그 값을 적용하기 위한 맥락으로 다뤄요. 토큰은 에이전트에게 정확한 값을 주고, 설명은 그 값이 왜 있는지, 여러 화면에서 어떻게 일관되게 쓸지 알려 줘요.
---
name: DevFocus Dark
colors:
primary: "#2665fd"
secondary: "#475569"
surface: "#0b1326"
on-surface: "#dae2fd"
error: "#ffb4ab"
typography:
body-md:
fontFamily: Inter
fontSize: 16px
fontWeight: 400
rounded:
md: 8px
---
# Design System
## Overview
A focused, minimal dark interface for a developer productivity tool.
Clean lines, low visual noise, high information density.
## Colors
- **Primary** (#2665fd): CTAs, active states, key interactive elements
- **Secondary** (#475569): Supporting UI, chips, secondary actions
- **Surface** (#0b1326): Page backgrounds
- **On-surface** (#dae2fd): Primary text on dark backgrounds
- **Error** (#ffb4ab): Validation errors, destructive actions
## Typography
- **Headlines**: Inter, semi-bold
- **Body**: Inter, regular, 14-16px
- **Labels**: Inter, medium, 12px, uppercase for section headers
## Components
- **Buttons**: Rounded (8px), primary uses brand blue fill
- **Inputs**: 1px border, subtle surface-variant background
- **Cards**: No elevation, relies on border and background contrast
## Do's and Don'ts
- Do use the primary color sparingly, only for the most important action
- Don't mix rounded and sharp corners in the same view
- Do maintain 4:1 contrast ratio for all text8개의 표준 섹션
Markdown 본문은 ## 제목을 사용해요. 관련 없는 섹션은 생략할 수 있지만, 포함한다면 이 순서를 따라야 해요. 같은 제목이 두 번 나오면 파일이 유효하지 않게 되고, 알 수 없는 섹션은 그대로 유지돼요.
- Overview (Brand & Style이라고도 해요). 분위기, 밀도, 개성 등 전체적인 모습과 느낌을 몇 문장으로.
- Colors. 각 색상 토큰과 그 역할 (예: 주요 액션, 페이지 표면).
- Typography. 폰트 패밀리와 디스플레이 헤드라인부터 작은 레이블까지의 타입 스케일.
- Layout (Layout & Spacing이라고도 해요). 간격 스케일, 그리드, 콘텐츠 너비, 거터.
- Elevation & Depth (Elevation이라고도 해요). 그림자, 테두리, 색조 등 표면을 구분하는 방식.
- Shapes. 모서리 반경과 그 밖의 모양 규칙.
- Components. 버튼, 입력 필드, 카드 등 기본 요소와 그 토큰, 상태.
- Do's and Don'ts. 에이전트가 어겨서는 안 되는 규칙.
각 표준 섹션을 순서대로 담은 간결한 Markdown 본문 예시예요. 내용은 제품에 맞게 바꾸고, 제목과 순서는 유지하세요.
## Overview
A minimal dark interface for a developer productivity tool.
Clean lines, low visual noise, high information density.
## Colors
- Primary (#2665fd): CTAs and active states
- Surface (#0b1326): Page backgrounds
- On-surface (#dae2fd): Text on dark backgrounds
## Typography
- Headlines: Inter, semibold
- Body: Inter, regular, 14-16px
- Labels: Inter, medium, 12px, uppercase
## Layout
- 8px base spacing unit, scale: 4 / 8 / 16 / 24 / 32 / 48
- Max content width 720px with 24px gutters on mobile
## Elevation & Depth
- Surfaces rely on background contrast instead of shadow
- Overlays use an 8 percent white tint on dark surfaces
## Shapes
- Rounded 8px for controls, 16px for cards
- Avoid mixing sharp and rounded corners in one view
## Components
- Buttons: 8px rounded, primary filled with brand blue
- Inputs: 1px border, subtle surface-variant background
- Cards: no elevation, rely on border and background contrast
## Do's and Don'ts
- Do use the primary color sparingly, for the most important action
- Don't mix rounded and sharp corners in one view
- Do maintain at least a 4:1 contrast ratio for all text디자인 토큰과 스키마
DESIGN.md는 파일 맨 앞의 YAML 프런트매터에 디자인 토큰을 담아요. 프런트매터 블록은 정확히 ---만 있는 줄로 시작해 같은 구분자로 끝나요.
version: <string>
name: <string>
description: <string>
colors:
<token-name>: <Color>
typography:
<token-name>: <Typography>
rounded:
<scale-level>: <Dimension>
spacing:
<scale-level>: <Dimension | number>
components:
<component-name>:
<token-name>: <string | token reference>흔히 쓰는 스케일 이름은 xs, sm, md, lg, xl, full이지만, 설명적인 키라면 무엇이든 괜찮아요. 간격 토큰은 YAML의 spacing: 아래에 있고, Markdown 본문의 Layout 섹션에서 설명해요.
토큰 유형
- Color
- 유효한 CSS 색상 문자열이라면 무엇이든 돼요. 권장 기본값은
#RRGGBB형식의 hex예요. 예:"#1A1C1E". - Dimension
- 숫자에 px, em, rem 단위를 붙인 값이에요. 예:
48px,-0.02em. - Token Reference
- 중괄호로 감싸며 YAML 트리의 값을 가리켜요. 예:
{colors.primary}. - Typography
- 패밀리, 크기, 굵기, 줄 높이, 자간 같은 폰트 속성을 담은 복합 객체예요. 타이포그래피 속성을 참고하세요.
타이포그래피 속성
- fontFamily
- 폰트 패밀리 이름.
- fontSize
- dimension으로 나타낸 폰트 크기.
- fontWeight
- 400이나 700 같은 숫자 굵기.
- lineHeight
- dimension 또는 단위 없는 배수. 단위 없는 값을 권장해요.
- letterSpacing
- dimension으로 나타낸 자간 조정값.
- fontFeature
- font-feature-settings를 설정해요.
- fontVariation
- font-variation-settings를 설정해요.
토큰 참조
토큰 참조는 중괄호로 감싸며, YAML 트리의 다른 값을 가리키는 객체 경로를 담아요. 대부분의 토큰 그룹에서 참조는 그룹이 아닌 원시 값을 가리켜야 해요. components 섹션 안에서는 타이포그래피 단계 같은 복합 값을 참조할 수 있어요.
components:
button-primary:
backgroundColor: "{colors.primary-60}"
textColor: "{colors.primary-20}"
rounded: "{rounded.md}"
button-primary-hover:
backgroundColor: "{colors.primary-70}"컴포넌트
components 섹션은 버튼, 칩, 목록, 입력 필드, 체크박스, 라디오 버튼, 툴팁 같은 컴포넌트 기본 요소의 스타일 가이드를 담아요. 디자인 시스템은 제품 분야에 중요한 컴포넌트를 추가로 정의할 수 있어요.
hover, active, pressed 상태의 변형은 button-primary-hover처럼 관련된 키 이름을 가진 별도의 컴포넌트 항목으로 정의해요.
- backgroundColor
- Color
- textColor
- Color
- typography
- Typography
- rounded
- Dimension
- padding
- Dimension
- size
- Dimension
- height
- Dimension
- width
- Dimension
권장 토큰 이름
이 이름들은 필수 사항이 아니라 가이드예요. 시스템 간 일관성을 위한 유용한 기본값이에요.
Colors: primary, secondary, tertiary, neutral, surface, on-surface, error
Typography: headline-display, headline-lg, headline-md, body-lg, body-md, body-sm, label-lg, label-md, label-sm
Rounded: none, sm, md, lg, xl, full
AI 에이전트가 DESIGN.md를 쓰는 방법
DESIGN.md를 저장소 루트의 README.md, AGENTS.md 옆에 두세요. 파일에 접근할 수 있는 에이전트라면 누구나 읽을 수 있지만, 대부분은 스스로 불러오지 않아요. 에이전트가 이미 읽는 지침에서 이 파일을 가리키거나, UI 작업을 요청할 때 프롬프트에서 파일 이름을 언급하세요. 짧은 안내면 충분해요:
## Design
Follow DESIGN.md for every UI change: use its color, typography,
spacing and component tokens instead of inventing new values.- Claude Code
- 저장소의 파일을 읽고 시작할 때 CLAUDE.md를 불러와요. 거기에 DESIGN.md를 가리키는 줄을 추가하거나, 프롬프트에서 파일을 언급하세요.
- Cursor
- DESIGN.md를 채팅 컨텍스트에 추가하거나, 프로젝트 규칙에서 참조해 모든 UI 요청에 적용되게 하세요.
- GitHub Copilot
- 저장소의 Copilot 지침 파일에서 DESIGN.md를 가리키거나, UI 작업을 요청할 때 채팅에 첨부하세요.
- Google Stitch
- 이 형식이 시작된 곳이에요. Stitch는 DESIGN.md를 사용해 생성되는 화면들이 하나의 팔레트, 타입 스케일, 컴포넌트 언어를 공유하게 해요.
그러면 에이전트는 토큰에서 정확한 값(primary 버튼의 hex 값, body-md 레이블의 크기)을 가져오고, 설명을 보고 그 값을 어디에 쓸지 판단해요.
DESIGN.md vs AGENTS.md vs README.md
세 파일은 나란히 놓이며 서로 다른 질문에 답해요. DESIGN.md는 AGENTS.md를 대체하지 않고, 둘은 함께 작동해요.
| 파일 | 대상 독자 | 답하는 질문 |
|---|---|---|
README.md | 프로젝트를 사용하거나 기여하는 사람 | 이건 무엇이고, 어떻게 실행하나요? |
AGENTS.md | 코딩 에이전트 | 이 코드를 어떻게 빌드하고, 테스트하고, 수정하나요? |
DESIGN.md | 코딩 및 디자인 에이전트 | 인터페이스는 어떤 모습과 느낌이어야 하나요? |
실제 DESIGN.md 예시
형식을 가장 빨리 이해하는 방법은 실제 파일을 몇 개 읽어 보는 거예요. 각 갤러리 페이지는 브랜드의 공개 웹사이트에서 추출한 DESIGN.md를 팔레트, 타입 견본과 함께 보여 줘요. 공식 브랜드 가이드라인은 아니에요.
DESIGN.md를 얻는 방법
- 직접 작성하기. 사양과 위의 예시에서 시작한 다음, 무료 DESIGN.md 검사기나 Google의
lint명령으로 파일을 검사하세요. - 예시에서 시작하기. 갤러리에서 파일을 복사하고 토큰과 설명을 제품에 맞게 편집하세요.
- 실제 웹사이트에서 생성하기. 공개 URL을 Design Extractor에 붙여 넣으세요. 브라우저에서 사이트를 렌더링하고, 위 사양을 따르는 색상, 타이포그래피, 간격, 컴포넌트가 담긴 DESIGN.md를 돌려줘요. 무엇을 받는지는 DESIGN.md 생성기 페이지에서 설명해요. 같은 추출을 Chrome 확장 프로그램에서, 그리고 MCP 서버를 통해 에이전트에서도 실행할 수 있어요.
FAQ
DESIGN.md FAQ
DESIGN.md 형식, 그 기원, AI 에이전트와 함께 쓰는 방법에 대한 짧은 답변이에요.
DESIGN.md는 AI 에이전트를 위해 디자인 시스템을 설명하는 일반 텍스트 파일이에요. 맨 위의 YAML 프런트매터에는 정확한 토큰(색상, 타이포그래피, 간격, 모서리 둥글기, 컴포넌트)이 담기고, 그 아래 Markdown 본문은 토큰을 어떻게, 왜 적용하는지 설명해요. 에이전트는 값은 토큰에서, 의도는 설명에서 읽어요.
Google이 AI 디자인 도구인 Stitch와 함께 DESIGN.md를 선보였어요. Google Labs가 GitHub(google-labs-code/design.md)에 Apache 2.0 라이선스로 사양을 공개하고 있어요. 형식은 알파 단계로 표시되어 있으므로, 성숙해지면서 바뀔 수 있어요.
AGENTS.md는 코딩 에이전트에게 프로젝트를 빌드하고 작업하는 방법(명령어, 컨벤션, 테스트)을 알려 줘요. DESIGN.md는 제품이 어떤 모습과 느낌이어야 하는지(색상, 타입, 간격, 모양, 컴포넌트)를 알려 줘요. README.md는 프로젝트를 사용하거나 기여하는 사람을 위한 파일이에요. 많은 저장소가 세 파일을 모두 나란히 두고 있어요.
파일에 접근할 수 있는 에이전트가 찾을 수 있도록 저장소 루트의 README.md, AGENTS.md 옆에 두세요. 그런 다음 AGENTS.md, CLAUDE.md, Cursor 규칙, Copilot 지침처럼 에이전트가 이미 불러오는 지침에서 이 파일을 가리키거나, UI 작업을 요청할 때 프롬프트에서 언급하세요.
아니요. 사양상 해당하지 않는 섹션은 생략할 수 있지만, 포함한 섹션은 표준 순서를 따라야 해요: Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do's and Don'ts. 같은 섹션 제목이 두 번 나와서는 안 되며, 알 수 없는 섹션은 거부되지 않고 유지돼요.
Google의 npm 패키지 @google/design.md에는 구조, 깨진 토큰 참조, WCAG 대비를 검사하는 lint 명령이 있어요. Design Extractor에도 무료 DESIGN.md 검사기가 있어서, 파일을 업로드하지 않고 브라우저에서 구조와 토큰을 검사하고 미리 볼 수 있어요.
사양에 따라 직접 작성하거나, 실제 예시 갤러리에서 하나를 복사해 시작점으로 쓰거나, 실제 사이트에서 생성할 수 있어요. Design Extractor는 공개 URL을 받아 브라우저에서 사이트를 렌더링하고, 색상, 타이포그래피, 간격, 컴포넌트가 담긴 DESIGN.md를 저장소에 바로 넣을 수 있게 돌려줘요.
마음에 드는 사이트의 DESIGN.md가 필요하세요?
공개 URL을 붙여 넣고 DESIGN.md를 받아 보세요.