DESIGN.md: Codex에 디자인 시스템 알려 주기.

DESIGN.md는 AI 에이전트에게 디자인 시스템을 설명하는 텍스트 파일입니다. 정확한 색상, 타이포그래피, 간격, 컴포넌트와 그 배경이 되는 이유까지 담습니다. 저장소에 하나 넣어 두면 Codex가 새로 디자인하는 모든 화면이 같은 시각 언어를 따릅니다.

2026년 11월 2일 업데이트 · 8분 분량

DESIGN.md란?

DESIGN.md는 코딩 에이전트에게 비주얼 아이덴티티를 설명하기 위해 Google Labs가 만든 공개 형식입니다. Google Stitch에서 시작되었고 Apache 2.0 라이선스로 공개되어 있으며, 명세는 아직 alpha 단계라 바뀔 수 있습니다.

DESIGN.md 파일은 두 층으로 이루어집니다.

• YAML로 쓴 디자인 토큰. 색상, 타이포그래피, 모서리 반경, 간격, 컴포넌트 스타일처럼 기계가 읽을 수 있는 정확한 값입니다. 토큰이 기준값입니다.
• Markdown 본문. 제품이 어떤 느낌이어야 하는지, 각 색상을 언제 쓰는지, 무엇을 피해야 하는지 같은 이유를 설명합니다. 본문은 에이전트에게 토큰을 어떻게 적용할지 알려 줍니다.

이런 파일이 없으면 에이전트는 화면을 요청할 때마다 새로운 파란색과 새로운 버튼 스타일을 고릅니다. 파일이 있으면 50번째 화면도 첫 화면과 어울립니다.

DESIGN.md에 들어가는 내용

토큰은 파일 맨 위의 YAML 프런트매터에 두거나, 각 섹션 안의 yaml 코드 블록에 넣을 수 있습니다. 스키마에는 다섯 가지 토큰 그룹이 있습니다.

본문은 ## 섹션을 씁니다. 어떤 섹션이든 생략할 수 있지만, 넣는 섹션은 Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do’s and Don’ts 순서를 따라야 합니다.

전체 예시

이 DESIGN.md는 모바일 앱 프롬프트 페이지에 나오는 독서 앱을 설명합니다. 저장소 루트에 DESIGN.md로 저장하세요.

---
version: alpha
name: Pagely
description: Calm, bookish UI for a reading-habit app.
colors:
  primary: '#1F3D2B'
  on-primary: '#FAF6EE'
  secondary: '#E8735A'
  tertiary: '#F2C14E'
  neutral: '#FAF6EE'
  surface: '#FFFFFF'
  on-surface: '#1F2A22'
typography:
  headline-lg:
    fontFamily: Georgia
    fontSize: 32px
    fontWeight: 400
    lineHeight: 1.15
  body-md:
    fontFamily: system-ui
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.5
  label-caps:
    fontFamily: system-ui
    fontSize: 13px
    fontWeight: 500
    letterSpacing: 0.12em
rounded:
  md: 16px
  lg: 22px
  full: 9999px
spacing:
  sm: 8px
  md: 16px
  lg: 24px
components:
  button-primary:
    backgroundColor: '{colors.primary}'
    textColor: '{colors.on-primary}'
    rounded: '{rounded.md}'
    padding: 18px
---

## Overview

Quiet, warm, and bookish, like a café with good light. Screens feel spacious and
unhurried; one clear next step per screen.

## Colors

- **Primary (#1F3D2B):** Deep forest green for primary actions and the streak card.
- **Secondary (#E8735A):** Coral for progress and small highlights only.
- **Tertiary (#F2C14E):** Warm yellow for streak and goal indicators.
- **Neutral (#FAF6EE):** Cream background for every screen, never pure white.

## Typography

Georgia for headlines gives a literary voice. System UI for everything else keeps
body text crisp. Labels are uppercase with wide letter spacing.

## Layout

24px side margins on phones. Spacing follows an 8px scale. Primary actions sit in
the lower half of the screen, within thumb reach.

## Elevation & Depth

No heavy shadows. Depth comes from white cards with a 1px warm border on the cream
background.

## Shapes

Soft and rounded: 16px for buttons and inputs, 22px for cards.

## Components

Primary buttons are full-width, deep green, 18px padding. One primary button per screen.

## Do's and Don'ts

- Do keep text contrast at WCAG AA or better.
- Do use coral sparingly: progress bars and one highlight per screen.
- Don't use pure black or pure white.
- Don't put more than two type sizes in a single card.

Codex가 DESIGN.md를 따르게 하는 방법

Codex는 AGENTS.md를 자동으로 읽습니다. 저장소 루트에서 시작해 작업 중인 폴더까지 내려가며 읽습니다. DESIGN.md는 스스로 찾지 않으므로 AGENTS.md에서 가리켜 주세요.

## Design

- Before any UI work, read DESIGN.md and use only its tokens.
- If a screen needs a value that DESIGN.md doesn't define, ask before inventing one.
- After editing DESIGN.md, run `npx @google/design.md lint DESIGN.md` and fix any errors.

그다음 평소처럼 화면을 요청하세요. 프롬프트에서 파일을 언급하면 더 확실합니다.

DESIGN.md를 따라서 [설정] 화면을 390×844 크기의 단일 HTML 파일로 디자인해 줘. 색상, 글자 크기, 모서리 반경, 간격은 DESIGN.md에 있는 것만 쓰고, DESIGN.md에 정의되지 않은 값이 필요했다면 알려 줘.

Codex로 DESIGN.md 작성하기

파일을 직접 손으로 쓸 일은 거의 없습니다. 이미 제품이 있다면 Codex에 코드에서 추출해 달라고 하세요.

우리 Tailwind 설정, 전역 CSS, 가장 많이 쓰는 컴포넌트 5개를 읽고 저장소 루트에 DESIGN.md를 작성해 줘. 먼저 `npx @google/design.md spec`을 실행해서 그 형식을 따라 줘: YAML 프런트매터에 토큰, 그다음 Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do's and Don'ts 섹션. 코드에 실제로 있는 값만 써 줘. 마지막으로 `npx @google/design.md lint DESIGN.md`를 실행해서 오류를 모두 고쳐 줘.

새 제품이라면 캔버스에서 승인한 목업이나 레퍼런스 스크린샷처럼 마음에 드는 방향에서 출발하세요.

우리가 승인한 화면 디자인이야 [스크린샷을 첨부하거나 HTML 파일 이름을 적기]. 이 디자인의 색상, 타이포그래피, 간격, 모서리 반경, 버튼 스타일을 담은 DESIGN.md를 작성해 줘. 어떤 느낌이어야 하는지 짧은 Overview와 Do's and Don'ts 5개도 넣어 줘. 형식은 `npx @google/design.md spec`의 DESIGN.md 형식을 따라 줘.

@google/design.md 명령줄 도구는 lint로 명도 대비와 깨진 토큰 참조를 검사하고, diff로 두 버전을 비교하고, export로 토큰을 Tailwind 테마나 W3C 디자인 토큰으로 변환합니다.

DESIGN.md vs SKILL.md vs AGENTS.md

이 세 파일은 같은 저장소에 함께 있는 경우가 많지만 하는 일이 다릅니다.

셋은 함께 쓸 때 잘 작동합니다. 디자인 스킬에 “디자인하기 전에 DESIGN.md를 읽을 것”이라고 적을 수 있고, AGENTS.md는 스킬이 없어도 그렇게 되도록 보장합니다. 스킬에 대해 더 알고 싶다면 Codex 플러그인과 스킬의 차이를 참고하세요.

예시를 찾을 수 있는 곳

오픈소스 컬렉션 awesome-design-md에는 유명 웹사이트의 디자인 시스템을 설명한 DESIGN.md 파일이 미리보기 페이지와 함께 모여 있습니다. 다른 팀이 색상, 타이포그래피, 컴포넌트를 어떻게 설명하는지 배우기에 좋습니다. 다른 회사의 브랜드를 베끼는 용도가 아니라 구조를 참고하는 용도로 쓰세요.

자주 묻는 질문

DESIGN.md는 공식 표준인가요?

Google Labs가 만든 공개 명세로, Google Stitch에서 쓰이고 GitHub에 공개되어 있습니다. 명세는 아직 alpha 단계이며, 공식 문서에서도 형식이 바뀔 것이라고 밝히고 있습니다.

Codex가 DESIGN.md를 지원하나요?

Codex는 저장소 안의 어떤 파일이든 읽고 따를 수 있습니다. 특별한 설정은 없습니다. 위에서 본 것처럼 AGENTS.md나 프롬프트에서 DESIGN.md를 언급하면 됩니다.

DESIGN.md가 Figma나 디자인 시스템을 대체하나요?

아니요. 에이전트가 읽을 수 있도록 디자인 시스템을 텍스트로 요약한 것입니다. Figma나 코드를 기준으로 관리하는 팀은 거기서 DESIGN.md를 생성하고, 시스템이 바뀔 때 업데이트하면 됩니다.

더 읽어 보기

• UI 디자인에 좋은 Codex 스킬 추천Codex에 디자인 감각을 더하는 스킬과 우리 디자인 시스템용 스킬을 만드는 법.
• 모바일 앱 UI 디자인 프롬프트디자인 시스템을 화면 단위로 적용하는 프롬프트.