What is DESIGN.md?
DESIGN.md는 프로젝트 루트에 두는 단일 마크다운 파일로, 브랜드의 시각·언어·움직임을 한 곳에 모은 디자인 스펙입니다. AI coding agent가 UI를 만들 때 가장 먼저 읽는 권위 있는 컨텍스트로 동작하며, 토큰뿐 아니라 voice·persona·motion까지 포함합니다.
- • 색·타이포·컴포넌트·레이아웃·반응형 (Google Stitch 9-섹션, base layer)
- • Voice·tone·narrative·principles·persona·states·motion (OmD §10–15, 철학 layer)
- • 사람과 agent 모두 읽을 수 있는 markdown 한 파일
- • Git에 그대로 commit되며, 직접 수정한 부분은 보존되고 agent가 갱신한 부분만 변합니다
기원 — Google Stitch부터 OmD까지
DESIGN.md라는 이름과 9-섹션 토큰 포맷은 Google이 발표한 Stitch가 처음 제안했습니다. Visual Theme & Atmosphere · Color · Typography · Component Stylings · Layout · Depth · Do/Don'ts · Responsive · Agent Prompt Guide — 컴포넌트 라이브러리 한 세트를 만들기에 충분한 토큰 문서입니다.
하지만 AI agent가 토큰만 보고 UI를 만들면 결과물은 일관되긴 하지만 누구의 브랜드도 아닌 학습 분포의 평균값으로 회귀합니다. gradient · Inter on white · purple on white · 정당화되지 않은 emoji. oh-my-design (OmD) v0.1은 이 공백을 메우기 위해 Stitch의 9-섹션 위에 6개 브랜드 철학 섹션 (§10 Voice & Tone, §11 Brand Narrative, §12 Principles, §13 Personas, §14 States, §15 Motion & Easing)을 더한 15-섹션 superset을 정의합니다. Stitch가 만든 DESIGN.md는 OmD에서도 그대로 valid합니다 — 철학 layer는 additive입니다.
전체 스펙은 spec/omd-v0.1.md에서 읽을 수 있고, 100+ 실제 회사의 DESIGN.md 예시는 /design-systems에 있습니다.
비슷한 것들과의 비교
DESIGN.md는 흔히 tailwind.config.js, 디자인 토큰 JSON, Figma tokens와 혼동됩니다. 핵심 차이는 무엇을 담느냐와 누가 읽느냐입니다.
| 기준 | DESIGN.md | tailwind.config.js | Design tokens JSON | Figma tokens |
|---|---|---|---|---|
| 포맷 | Markdown | JS object | JSON | Figma plugin/JSON |
| 주 독자 | AI agent + 사람 | Tailwind 컴파일러 | Style Dictionary 등 변환기 | 디자이너 |
| 토큰 포함 | Yes | Yes | Yes | Yes |
| Voice·persona·motion | Yes (§10–15) | No | No | Partial (motion만) |
| 코드 산출물 | No (spec only) | CSS classes | CSS/JS/iOS/Android 변환 | Figma 스타일 |
| 스택 의존성 | Stack-agnostic | Tailwind 종속 | 변환기 종속 | Figma 종속 |
| 수명 | 스택보다 길게 유지 | Tailwind 버전 따라감 | 툴체인 따라감 | Figma 따라감 |
최소 DESIGN.md 예시
frontmatter + 첫 3개 섹션. 실제 100+ 레퍼런스는 §1–15를 모두 채웁니다 — 전체 예시는 /design-systems 각 카드를 클릭하세요.
---
id: acme
name: Acme
country: KR
primary_color: "#5546ff"
verified: true
---
# DESIGN.md — Acme
## 1. Visual Theme & Atmosphere
Calm B2B fintech. Soft neutrals, one electric indigo accent, generous
whitespace. Avoids gradient washes, decorative emoji, and saturated
illustration. The product should feel quiet enough to use for eight
hours straight.
## 2. Color Palette & Roles
- **Indigo / brand** (`#5546ff`) — primary CTA, links, focus rings.
- **Slate 950** (`#0a0a0f`) — primary text on light.
- **Off-white** (`#fafafa`) — page background.
- **Slate 200** (`rgba(0,0,0,0.08)`) — hairline borders.
- Accent indigo (`#a89cff`) reserved for $-prompts and code highlights.
## 3. Typography Rules
- **Primary**: `Geist`, system-ui fallback.
- **Monospace**: `Geist Mono`, ui-monospace fallback.
- H1 `clamp(2.5rem, 6vw, 4.25rem)`, weight 700, tracking -0.02em.
- Body 15-16px, leading 1.6. No uppercase headings.
내 프로젝트에 적용하려면
한 줄로 skill + 16개 sub-agent를 설치하고 자연어로 DESIGN.md를 부트스트랩합니다.
npx oh-my-design-cli install-skills