oh-my-design
Home
Definition · DefinedTerm

What is DESIGN.md?

Definition

DESIGN.md는 프로젝트 루트에 두는 단일 마크다운 파일로, 브랜드의 시각·언어·움직임을 한 곳에 모은 디자인 스펙입니다. AI coding agent가 UI를 만들 때 함께 읽는 portable contract로 동작하며, 토큰뿐 아니라 experience·state·locale·asset·governance까지 포함할 수 있습니다.

  • • Experience·foundations·typography/assets·components/states
  • • Layout/platforms·content/locales·governance
  • • 사람과 agent 모두 읽을 수 있는 markdown 한 파일
  • • 선택적 System Graph와 provenance는 sidecar에 두고, visible file에는 도구 메타데이터를 두지 않음

기원과 호환성 — Google 규격과 Core v2

Google은 DESIGN.md를 사람이 읽는 prose와 구조화된 design decisions를 함께 담는 공개 규격으로 발전시키고 있습니다. 원문과 도구는 Stitch에서 확인할 수 있습니다. OmD는 이 규격을 공식 소유하거나 동일 규격이라고 주장하지 않습니다. 대신 legacy Google/Stitch 문서를 읽고 내보낼 수 있는 compatibility profile로 취급합니다.

DESIGN.md Core v2는 특정 도구의 이름이나 검증 메타데이터를 visible file에서 제거하고, 7개의 stable semantic anchor로 제품 의도와 실행 가능한 시스템 결정을 정리합니다. 정밀한 token, component, evidence, coverage는 선택적 System Graph에 두되 DESIGN.md 한 파일만 전달해도 Claude Design, Open Design, generic chat이 이해할 수 있어야 합니다.

전체 스펙은 spec/design-md-core-v2.md에서 읽을 수 있고, 440 실제 회사의 DESIGN.md 예시는 /design-systems에 있습니다.

비슷한 것들과의 비교

DESIGN.md는 흔히 tailwind.config.js, 디자인 토큰 JSON, Figma tokens와 혼동됩니다. 핵심 차이는 무엇을 담느냐와 누가 읽느냐입니다.

기준DESIGN.mdtailwind.config.jsDesign tokens JSONFigma tokens
포맷MarkdownJS objectJSONFigma plugin/JSON
주 독자AI agent + 사람Tailwind 컴파일러Style Dictionary 등 변환기디자이너
토큰 포함YesYesYesYes
Experience·states·localesYesNoNoPartial
코드 산출물No (spec only)CSS classesCSS/JS/iOS/Android 변환Figma 스타일
스택 의존성Stack-agnosticTailwind 종속변환기 종속Figma 종속
수명스택보다 길게 유지Tailwind 버전 따라감툴체인 따라감Figma 따라감

최소 DESIGN.md 예시

Visible YAML이나 vendor metadata가 없는 7-section Portable Core 예시입니다. 현재440개 catalog 원본은 migration window 동안 legacy reader로도 보존되며, Builder download는 Core v2로 투영됩니다. 형식은 Core이지만 primary task 근거가 없는 reference는 validator에서 structural-only로 남습니다. 전체 예시는 /design-systems 각 카드를 클릭하세요.

# Acme Design System

<!-- design-md:section experience -->
## 1. Experience
Help operations teams review consequential changes without losing context.

<!-- design-md:section foundations -->
## 2. Foundations
- **Action:** `#2457e6` — interactive emphasis only.
- **Text:** `#17181c` on `#ffffff` — at least 4.5:1 contrast.

<!-- design-md:section typography-assets -->
## 3. Typography & Assets
- Body: 16px / 1.5. Do not present an unverified font as the project font.

<!-- design-md:section components-states -->
## 4. Components & States
- Commit actions support default, focus-visible, disabled, loading, error, and success.

<!-- design-md:section layout-platforms -->
## 5. Layout & Platforms
- Preserve task order at 320px and 200% reflow.

<!-- design-md:section content-locales -->
## 6. Content & Locales
- Name the affected object and the recovery action.

<!-- design-md:section governance -->
## 7. Governance
- Omit the smallest unresolved value; never replace it with a plausible default.

에이전트가 바로 fetch하는 공개 .md

카탈로그의 모든 레퍼런스는 raw 마크다운으로 공개돼 있어, AI 코딩 에이전트(Claude Code 등)가 JS 렌더링 없이 DESIGN.md를 그대로 가져올 수 있습니다. URL 규칙은 oh-my-design.kr/<id>/design.md — vercel.com/design.md와 같은 형태입니다.

전체 목록(머신리더블 인덱스)은 /llms.txt에 있고, 사람이 보는 페이지는 /design-systems입니다.

내 프로젝트에 적용하려면

한 줄로 skill + specialist roles를 설치하고 자연어로 Core v2 디자인 시스템을 부트스트랩합니다.

$npx oh-my-design-cli@latest
DocsTry the builderFAQ npm