AI에게 화면(UI)을 만들어 달라고 하면 그럴듯하게 나오지만, 우리 회사 버튼과 색은 아닌 경우가 많습니다. 그래서 디자인 규칙을 Markdown 문서로 적어 주는 방식이 주목받고 있습니다. 이 글에서는 DESIGN.md가 무엇인지, 그것만으로 충분하지 않은 이유, 기존 디자인 시스템을 AI가 쓰게 하는 순서를 정리합니다.
3줄 요약
- DESIGN.md는 색·글꼴·간격 같은 디자인 토큰(값)과 설명을 한 파일에 담아 코딩 에이전트에게 주는 형식입니다.
- 컴포넌트 구조와 변형(Variant)까지 문서 한 장에 담기는 어렵습니다. 실제 디자인 시스템에 AI가 직접 접근하는 길도 필요합니다.
- Figma MCP, Storybook MCP, 스킬(Skills)을 조합하고, 작은 컴포넌트 하나로 먼저 검증하는 편이 안전합니다.
DESIGN.md는 무엇인가
DESIGN.md는 시각 정체성(브랜드의 색, 글꼴, 분위기)을 코딩 에이전트에게 설명하기 위한 파일 형식입니다. Google Labs의 오픈소스 저장소는 이 파일을 두 부분으로 설명합니다. 앞부분(YAML)에는 기계가 읽는 디자인 토큰이 들어갑니다. 뒷부분(Markdown)에는 그 값이 왜 필요한지, 어디에 쓰는지 사람의 말로 적습니다.
토큰은 이름이 붙은 디자인 값입니다. 예를 들어 primary: "#1A1C1E"처럼 기본 색을 한 곳에 정해 두는 식입니다. 값은 에이전트에게 정확한 수치를 주고, 설명은 판단 기준을 줍니다. 같은 저장소에는 파일을 검사하는 lint 명령도 있어 깨진 참조나 색 대비(WCAG)를 확인할 수 있습니다.
토큰을 도구끼리 주고받는 표준 형식은 별도로 논의 중입니다. W3C 커뮤니티 그룹인 Design Tokens Community Group이 형식 초안을 공개하고 있지만, 해당 문서는 아직 미리보기 초안이며 구현하지 말라고 안내합니다.
문서만으로 부족한 이유
디자인 시스템은 색과 글꼴 목록이 전부가 아닙니다. 컴포넌트가 어떤 변형을 갖는지, 다른 컴포넌트 안에 어떻게 들어가는지, 실제로 어떤 패턴으로 쓰이는지가 함께 있습니다. 이런 정보를 Markdown으로 다시 옮기면 두 가지 문제가 생깁니다. 원본이 바뀔 때마다 문서도 고쳐야 하고, 옮기는 과정에서 정보가 빠집니다.
그래서 최근 실무자 글에서는 질문을 바꿉니다. “AI를 위해 문서를 새로 쓸 것인가”가 아니라 “이미 있는 디자인 시스템을 AI가 직접 읽고 쓰게 할 것인가”입니다. 이때 기존 디자인 시스템이 기준(Source of Truth)으로 남고, DESIGN.md는 프로젝트별 원칙과 맥락을 더하는 보조 수단이 됩니다. 이는 한 실무자의 의견이며, 정답으로 확정된 방법은 아닙니다.
AI가 디자인 시스템에 접근하는 세 가지 길
| 방법 | AI가 얻는 것 | 알아둘 점 |
|---|---|---|
| DESIGN.md | 토큰 값과 디자인 원칙 설명 | 한 장의 문서라 컴포넌트 구조는 담기 어렵습니다. |
| Figma MCP 서버 | 선택한 프레임의 코드 생성, 변수·컴포넌트·레이아웃 데이터, Code Connect로 실제 컴포넌트 재사용 | MCP를 지원하는 클라이언트가 필요합니다. 캔버스에 쓰는 기능은 원격 서버와 Full 좌석이 필요하고, 베타 기간 이후 사용량 기반 유료가 될 예정이라고 안내합니다. |
| Storybook MCP 서버 | 코드 컴포넌트와 문서를 읽고, 스토리를 만들고, 테스트를 돌려 결과로 수정 | AI 기능은 미리보기(preview) 단계라 API가 바뀔 수 있습니다. |
MCP(Model Context Protocol)는 AI 에이전트가 외부 데이터에 접근하는 표준 방식입니다. Figma는 디자인 파일을, Storybook은 코드로 만든 컴포넌트를 AI에게 보여 줍니다. 디자인 시스템을 Figma 중심으로 운영하는지, 코드 중심으로 운영하는지에 따라 알맞은 길이 달라집니다.
여기에 스킬을 더할 수 있습니다. Anthropic 문서에 따르면 Agent Skills는 지침과 메타데이터, 선택적 스크립트·템플릿을 묶은 모듈형 기능으로, 필요할 때 불러와 쓰입니다. 매번 같은 안내를 대화에 붙여 넣지 않아도 되므로 “이 컴포넌트는 이렇게 쓴다”는 규칙을 담기에 알맞습니다. AI에게 규칙과 도구를 함께 주는 접근은 하네스 엔지니어링 정리 글에서 다룬 흐름과도 이어집니다.
단계별로 적용하는 방법
- 기준을 정합니다. Figma, Storybook, 코드 중 어디가 우리 디자인 시스템의 원본인지 정합니다.
- 접근 길을 엽니다. 원본에 맞는 MCP 서버를 에이전트에 연결합니다. Storybook은
npx storybook add @storybook/addon-mcp로 애드온을 설치하고 컴포넌트 매니페스트(componentsManifest)를 켜면 됩니다. 매니페스트를 지원하지 않는 프레임워크도 있으니 공식 문서의 지원 표를 먼저 확인합니다. - 정보를 구조화합니다. 토큰, 컴포넌트, 변형, 속성(props)이 이름 있는 값으로 정리되어 있는지 봅니다. 이름이 제각각이면 AI도 헷갈립니다.
- 규칙을 스킬이나 DESIGN.md에 적습니다. 도구로 알 수 없는 원칙, 예를 들어 “주요 버튼은 화면당 하나”를 여기에 적습니다.
- 작게 검증합니다. 범위가 분명한 컴포넌트 하나로 시작해, AI가 기존 컴포넌트를 제대로 골라 재사용하는지 확인한 뒤 넓힙니다.
자주 묻는 질문
DESIGN.md만 만들면 충분한가요?
디자인 시스템이 작고 토큰 중심이라면 충분할 수 있습니다. 컴포넌트가 많고 변형이 복잡하다면 MCP 같은 직접 접근을 함께 쓰는 편이 낫습니다.
개발자가 아니어도 시도할 수 있나요?
DESIGN.md 작성은 문서 작업에 가까워 비개발자도 할 수 있습니다. MCP 서버 연결은 개발 환경 설정이 필요하므로 개발자와 함께 하는 것이 좋습니다.
디자인 토큰 표준이 확정되었나요?
아직 아닙니다. 커뮤니티 그룹의 형식 초안은 구현에 쓰지 말라는 미리보기 단계입니다. 도구별 형식이 바뀔 수 있다는 전제로 시작하세요.