DESIGN.md란 무엇인가요? AI 코딩 에이전트가 읽는 디자인 파일 (무료 모바일 앱 예시 포함)

DESIGN.md는 AI 코딩 에이전트에 제품의 시각적 정체성을 설명하는 Markdown 파일입니다. Google Labs 포맷은 선택적 YAML 디자인 토큰과 이들의 사용 방법에 대한 서면 지침을 결합합니다. 이를 통해 에이전트는 인터페이스를 생성하기 전에 색상, 타이포그래피, 간격, 컴포넌트 규칙을 명확하게 읽고 파악할 수 있습니다.

모바일 앱 개발자에게 가장 유용한 점은 이러한 디자인 선택을 다음 화면으로 그대로 이어서 적용할 수 있다는 것입니다. Sleek의 무료 모바일 DESIGN.md 라이브러리에서 파일을 하나 선택해 함께 제공되는 화면을 살펴보고, 해당 규칙을 자신의 앱에 맞게 조정해 보세요.

DESIGN.md는 누가 만들었나요?

Google Labs는 Stitch에서 사용하는 DESIGN.md 포맷을 발행합니다. Google은 2026년 3월 Stitch 발표에서 DESIGN.md 가져오기 및 내보내기 기능을 처음 소개했고, 이어 4월에 초안 사양을 오픈소스로 공개했습니다. 공식 리포지토리에서는 여전히 이 포맷을 알파 단계로 표시하고 있으므로, 연동 기능을 구축할 때는 현재 최신 사양을 확인하세요.

DESIGN.md라는 이름의 파일이 일반적인 프로젝트 문서일 수도 있습니다. 파일을 공유할 때는 어떤 포맷을 사용하는지 밝히고 원본 텍스트를 바로 확인할 수 있도록 유지하는 것이 좋습니다.

DESIGN.md 파일에는 무엇이 들어가나요?

Google Labs 사양은 선택적 YAML 프론트매터와 Markdown 본문으로 구성된 구조를 설명합니다. 토큰 그룹은 색상, 타이포그래피, 모서리 곡률, 간격, 컴포넌트를 다룹니다. 본문에서는 강조 색상의 위치나 버튼과 카드의 차이점 같은 가이드를 설명합니다. 명확한 수치 값과 서면 가이드는 서로 다른 역할을 수행합니다.

이 사양은 헥스(hex) 값을 포함한 CSS 색상 문자열을 지원합니다. YAML에서 헥스 색상을 작성할 때는 따옴표로 감싸야 합니다. 따옴표가 없으면 샵(#) 기호가 주석 시작으로 인식됩니다. {colors.primary}와 같은 참조는 파일 내의 다른 토큰을 가리킵니다. Sleek 라이브러리는 원본 텍스트와 함께 헥스 색상 스와치를 보여주므로 다운로드 전에 팔레트를 바로 확인할 수 있습니다.

최소한의 DESIGN.md 예시는 어떤 모습인가요?

시작 단계의 DESIGN.md는 팔레트, 본문 스타일, 간격 값, 버튼과 같이 하나의 작은 시각적 시스템을 설명할 수 있습니다. 아래 예시는 이 가이드를 위해 작성되었습니다. 이 내용을 DESIGN.md로 저장한 후 모바일 앱에 필요한 규칙을 추가해 보세요. 이는 시작점일 뿐 완제품 형태의 컴포넌트 라이브러리는 아닙니다.

---
version: alpha
name: Quiet Blue Mobile
colors:
  primary: "#2459C4"
  on-primary: "#FFFFFF"
  surface: "#FAF8F3"
  on-surface: "#20242B"
typography:
  body-md:
    fontFamily: Inter
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.5
rounded:
  md: 12px
spacing:
  md: 16px
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
    rounded: "{rounded.md}"
    padding: "{spacing.md}"
---
## Overview
A quiet mobile interface with cream surfaces and blue actions.

## Colors
Use primary for actions. Keep reading surfaces cream.

## Typography
Use body-md for reading text. Keep labels short.

## Layout
Use spacing.md for screen gutters and related content groups.

## Shapes
Use rounded.md on cards and buttons.

## Components
Primary buttons use button-primary. Keep one main action per view.

## Do's and Don'ts
Keep text readable at larger system font sizes.
Do not use color as the only signal for an error.

작성한 항목은 리포지토리의 lint 명령을 사용해 직접 검사할 수 있습니다. 검사 결과를 통해 잘못된 참조나 색상 대비 문제를 찾아낼 수 있습니다. 다만 텍스트 파일만으로는 텍스트가 잘리거나, 컨트롤이 혼동을 주거나, 키보드가 폼을 가리는 문제를 파악할 수 없으므로 실제 렌더링된 화면을 반드시 직접 확인해야 합니다.

npx @google/design.md lint DESIGN.md

Claude Code에서 DESIGN.md를 어떻게 사용하나요?

DESIGN.md를 프로젝트에 두고 UI 작업 시 Claude Code에 읽도록 요청하세요. Anthropic의 메모리 문서에 따르면 CLAUDE.md에서 가져온 파일은 세션 시작 시 로드됩니다. 필요할 때 읽으려면 일반 경로 참조를 사용하거나 .claude/rules/에 UI 파일과 일치하는 paths 패턴을 지정한 규칙을 만드세요.

예를 들어 @ 가져오기 구문 없이 다음 지침을 CLAUDE.md에 추가하세요.

For UI tasks, read DESIGN.md before creating or changing app screens.

그런 다음 특정 화면과 해당 화면의 상태를 요청하세요. 예를 들어 빈 상태(empty state)와 동기화 실패 상태가 포함된 작업 목록 화면을 요청할 수 있습니다. 생성된 UI가 DESIGN.md의 값을 잘 따르고 있는지 확인하고, 의도적으로 디자인을 변경할 때마다 파일을 업데이트하세요. 전체적인 워크플로는 Sleek의 Claude 디자인 가이드에서 자세히 확인할 수 있습니다.

Cursor나 Stitch에서는 DESIGN.md를 어떻게 사용하나요?

Cursor에서는 프롬프트 작업에 DESIGN.md를 직접 첨부하거나 프로젝트 규칙(project rule)에서 참조하세요. Stitch에서는 DESIGN.md 가져오기 및 내보내기 워크플로를 사용하여 여러 프로젝트 간에 디자인 규칙을 전달할 수 있습니다. 이 차이는 중요합니다. 코딩 에이전트는 컨텍스트 내에 파일이 포함되어야 하는 반면, Stitch는 이 포맷을 중심으로 설계된 워크플로를 제공합니다.

Cursor의 경우 규칙 문서에서 프로젝트 규칙 및 파일 참조 방법을 확인할 수 있습니다. 규칙을 통해 UI 변경 작업 시 에이전트가 DESIGN.md를 읽도록 지시할 수 있습니다. 백엔드 관련 작업에 불필요하게 긴 디자인 문서가 포함되지 않도록 규칙이 적용되는 조건을 적절히 지정하세요.

Stitch의 경우 Google의 DESIGN.md 발표에 명시된 대로 프로젝트 간에 디자인 규칙을 가져오거나 내보낼 수 있습니다. 가져온 후에는 생성된 화면을 원본 파일과 비교하고 필요에 따라 규칙을 조정하세요.

Sleek은 모바일 앱 스타일을 위해 DESIGN.md를 어떻게 활용하나요?

Sleek은 리믹스 가능한 모든 추천 레퍼런스에 디자인 파일을 함께 저장합니다. '이 스타일 사용'을 선택하고 앱 구상을 설명하면, Sleek은 해당 파일과 입력한 브리프(brief)를 생성 프로세스에 함께 전달합니다. 디자인 파일은 미학적 스타일을 정의하고, 브리프는 앱의 목적과 콘텐츠를 결정합니다. 사전에 화면과 디자인 파일을 모두 검토해 볼 수 있습니다.

레퍼런스 갤러리와 DESIGN.md 라이브러리는 동일한 추천 프로젝트를 공유합니다. Sleek은 Google Labs 구조를 사용하고 테두리와 그림자 등의 컴포넌트 속성을 추가하며, 린터는 이러한 속성을 경고로 보고합니다. 아이콘 사용법, 일러스트레이션, 시각적 위계, 고유한 스타일 디테일에 대한 지침도 추가했습니다. 스타일 파일에는 새 앱을 생성할 때 사용할 시각적 선택을 기록합니다.

라이브러리에서 스타일을 열어 DESIGN.md를 복사하거나 다운로드하고, Use this style in Sleek을 선택해 앱 아이디어를 입력해 보세요. 코딩 환경에서 Sleek을 직접 구동하고 싶다면 에이전트 설정 가이드에서 관련 연동 방법을 확인하실 수 있습니다.

DESIGN.md 자주 묻는 질문 (FAQ)