AI가 디자인 시스템을 잘 쓰게 하려면 — GDS MCP 제작기

들어가며

회사에서 작업하고 있는 것들을 까먹기 전에 정리하는 느낌으로 글을 쓰고 있다.

지금 회사에서는 GDS, 그러니까 게임 디자인 시스템을 만들고 있다. 이걸 만들다 보니 어떤 간극 같은 게 느껴졌다.

1. 실제 디자이너의 가이드대로 구현하는 것
2. 그 가이드는 피그마 시안이고, 이걸 코드로 옮긴 다음,
3. 실제 소비처에서 코드로 만들어진 컴포넌트를 가져다 쓰는 방법

이 셋 사이에 간극이 느껴진다고 해야 하나.

시스템을 만드는 사람과 가져다 쓰는 사람의 차이

예를 들어 시스템을 구현하는 개발자는 프로젝트 시안을 보면 어떤 건 시스템 컴포넌트이고 어떤 건 프로젝트에 국한된 시안(컴포넌트)이구나를 안다. 하지만 시스템을 구현하지 않는 개발자는 그 구분을 할 수 없다.

그 구분을 할 수 없다 보니, 원래 AI가 없으면 개발자는 시안을 하나하나 눌러보면서 "아 이건 디자인 시스템 컴포넌트구나, 이건 아니구나"를 구분하면서 디자인 시스템 md 파일이나 스토리북을 보며 자기가 맥락을 파악하고 1:1 맵핑을 하면서 개발을 할 것이다.

AI에게 일을 시키는 시대의 간극

하지만 이제 우리는 하나하나 코드와 피그마를 보면서 개발하지 않는다. AI에게 프롬프팅을 하고 난 뒤 결과를 컨펌하는 일이 많아졌다.

그러다 보니 AI가 실제로 피그마 시안에서 코드로 옮겨갈 때, 다음을 알아야 한다.

1. 어떤 게 디자인 시스템 컴포넌트인지 알아야 하고
2. 디자인 시스템 컴포넌트를 어떻게 쓸지 알아야 하고
3. 현재 버전에서 지원하는 인터페이스가 뭔지 알아야 하고
4. 개발자가 디자인 시스템에 대한 질문을 할 때 그에 대한 답을 해주려면

단순히 시스템 컴포넌트를 구현하는 것보다 더 많은 간극을 촘촘히 메워줘야 한다고 생각했다.

어떻게 메울까

1번의 경우, 내 생각에는 code connect를 활용하면 AI 에이전트가 피그마 메타데이터를 분석할 때 이미 맵핑된 예제 소스코드를 보고 raw DOM이 아닌 시스템 컴포넌트를 import해서 그릴 수 있다고 생각했다.

나머지의 경우는 LLM(AI 에이전트)에게 맥락을 입혀줘야 한다고 생각했다.

그래서 자체 GDS MCP를 만들어야겠다고 생각했다.

MCP 이전에 — ESLint 룰

물론 MCP를 만들기 전에, 소비처에서 사용할 때 좀 더 잘 사용할 수 있게 하기 위해서 ESLint 룰도 GDS 패키지 안에 같이 포함해서 배포하기도 했다. 소비하는 쪽에서 그 ESLint 룰을 import해서 쓰면 컴파일 타임에 린트 에러나 워닝으로 가이드를 확인할 수 있기 때문에, 어느 정도 사용성을 높일 수는 있다고 생각했다.

하지만 그것보다 에이전트랑 같이 개발할 때 좀 더 개발자 친화적으로 쓸 수 있는 방법을 떠올리니, MCP를 한번 구축해봐야겠다는 생각이 들더라.

MCP 데이터 만들기

그래서 실제로 피그마에 있는 스크린샷과 텍스트들을 정리해서 MCP data를 만들었다.

MCP는 JSON-RPC 프로토콜로 통신을 하는데, 내부에 여러 메소드를 정의할 수 있더라.

내가 생각한 MCP의 역할은 크게 두 가지로 나뉜다.

1. 소비처에서 개발자가 질문하는 것에 대해 응답해주는, 구현된 시스템을 사용할 때 궁금한 점을 긁어줄 수 있는 방안
2. 디자인 시스템을 개발하는 개발자와 티키타카 할 수 있는 맥락을 가진 MCP

만들면서 보이기 시작한 것들

가이드라인을 읽으면서 가이드 데이터를 밀어넣다 보니, 시스템을 개발한 사람으로서 현 GDS의 미비한 사항들이 눈에 보이더라.

예를 들면, 디자이너는 List라는 큰 컴포넌트와 그 List에 들어가는 개별 Item에 대한, 2개의 컴포넌트에 대한 가이던스를 정의해뒀는데 이걸 만들면서 실제로 소비도 했던 나의 입장에서는 일정 안에 빠르게 개발하려면 List 전체를 다듬으면서 만드는 것보다는 그 하위 레벨의 ListItem을 빨리 만들고, 그것만 소비처에서 가져다가 빨리 쓰는 방법을 채택했다.

그러다 보니 List 관점에서 구현된 공통 시스템 컴포넌트가 없어서, 나중에 디자이너의 의도가 제대로 서비스에 녹아들지 않을 수 있겠다는 생각이 들었다. 그래서 List에 대한 개발도 필요하겠구나 하는 생각을 했다.

실제로 만든 GDS MCP

그래서 사내 깃헙 계정에 개인 레포를 만들어서 작업한 걸 올려뒀고, 이걸 쓰고 싶으면 로컬 MCP config에 추가해서 쓸 수 있게 해뒀다.

구조 자체는 생각보다 단순하다. @modelcontextprotocol/sdk로 stdio 기반 서버를 띄우고, 입력 스키마는 zod로 정의했다. 서버는 미리 정리해둔 design-system.json을 읽기만 한다. 즉 서버는 얇게 두고, 데이터를 어떻게 잘 정리하느냐가 핵심이다.

그 JSON은 직접 손으로 채우는 게 아니라 추출 스크립트가 디자인 시스템의 실제 소스(Figma 변수 export 또는 Style Dictionary 산출물)에서 생성한다. 전체 흐름은 이렇다.

GDS 토큰 수정 → release 발행 → CI에서 extract + build → 패키지 publish → 팀원은 npx로 최신 실행

제공하는 도구(tool)

내가 정의한 도구들은 크게 토큰 / 컴포넌트 / 가이드라인 / 통합 검색으로 나뉜다. 전부 "개발자(혹은 에이전트)가 GDS를 쓰다가 궁금해할 법한 질문"을 시나리오로 잡고 만들었다.

특히 find_token_by_value는 #FFF / #FFFFFF / 대소문자 / # 유무를 전부 정규화해서 비교하기 때문에, 시안이나 코드에서 발견한 hex를 그대로 넣어도 매칭된다. 매칭되는 토큰이 없으면 "토큰화되지 않은 값(하드코딩 의심)"이라고 알려주도록 했다.

설계할 때 신경 쓴 것

만들면서 가장 신경 쓴 원칙은 "Figma에서 확인되지 않은 토큰은 데이터에 넣지 않는다" 였다. 예시나 추정값을 토큰처럼 저장하기 시작하면, AI가 그걸 사실처럼 믿고 끌어다 쓰기 때문이다.

MCP가 거짓말을 하면, 차라리 없는 것만 못하다.

또 하나는, 앞에서 List/ListItem 이야기로 느꼈던 그 간극을 그대로 데이터 구조에 녹였다는 점이다. 컴포넌트의 코드 사용 정보(codeUsage)는 디자이너의 구현 가이드가 아니라 실제 소비처에서 GDS를 가져다 쓰는 방법을 우선한다. 응답할 때도 권장 사용법 → 전제 조건(Provider, CSS import 등) → 실제 API → 언제 쓰고 무엇을 피할지 → 복붙 가능한 예시 순으로 내려가도록 했다. 그리고 Figma에서 component property로 확인되지 않은 API는 확정값처럼 쓰지 않고 "구현체와 매핑이 필요한 상태"로 분리해서, 아직 메워지지 않은 간극이 어디인지도 드러나게 했다.

쓰는 법

팀원은 npm registry에서 패키지를 받을 수 있게 .npmrc에 토큰만 세팅하면 되고, MCP 클라이언트(예: Claude Code) 설정에 아래처럼 추가하면 끝이다.

{
  "mcpServers": {
    "gds": {
      "command": "npx",
      "args": ["-y", "@<org>/gds-mcp"]
    }
  }
}

마치며

처음에 느꼈던 간극으로 돌아가 보면, 결국 하려던 건 하나였다. 시스템을 만드는 사람의 머릿속에만 있던 맥락을, 그걸 만들지 않은 사람(과 AI)도 똑같이 쓸 수 있게 하는 것.

그래서 어떤 게 시스템 컴포넌트인지는 code connect로, 어떻게 쓰는지·현재 버전이 뭘 지원하는지·물어봤을 때 답해주는 건 MCP로 메우기로 했다.

물론 아직 끝난 건 아니다. List처럼 상위 레벨에서 비어 있는 컴포넌트는 더 만들어야 하고, code connect도 실제 연결까지 가야 하고, 지금은 손으로 정리한 데이터를 디자인 시스템 소스에서 자동으로 뽑아내는 부분도 더 다듬어야 한다.

그래도 "AI한테 시키고 결과만 컨펌하는" 방식으로 일하는 시간이 늘어날수록, 이런 맥락을 촘촘히 떠먹여 주는 일은 점점 더 중요해질 거라고 생각한다. 까먹기 전에 여기까지 정리해 둔다.