Figma MCP 기반 디자인 엔지니어링 — 설계 데이터로 여는 디자인-투-코드

요약

• 디자인 엔지니어링 — 디자인과 코드가 같은 약속(토큰·컴포넌트)을 공유하게 만드는 일. 스펙 문서와 스크린샷으로 넘기던 정보를 구조화된 데이터로 코드에 옮기면, 같은 값을 손으로 다시 맞추는 일이 사라진다
• Figma MCP 서버 — Figma의 변수와 컴포넌트, 레이아웃, 디자인에 적힌 값, 이미지를 AI 에이전트가 읽을 수 있게 열어 주는 통로. 에이전트는 스크린샷을 눈대중으로 보는 대신 설계 데이터를 근거로 코드를 만든다
• 자동화의 4원칙
  • 토큰이 기준 — 색·간격·타이포는 토큰에서만
  • 디자인은 그대로, 마크업은 역할에 맞게
  • AI에게 맡길 일과 사람이 판단할 일을 구분
  • 검사마다 강도를 다르게 — 반드시 고칠 것과 알고 넘어갈 것을 구분
• 전제 조건 — 변수가 적용되고 컴포넌트가 정리된 파일일수록 효과가 크며, AI의 작업 보고를 결과로 확인하는 절차가 필요

1. 서론 — 핸드오프의 손실

1.1 왜 디자인-투-코드가 어려운가

디자인을 개발에 넘기는 핸드오프는 보통 스펙 문서와 이미지, 구두 설명으로 이뤄지는데, 이 과정에서 토큰과 상태(hover/focus/disabled), 반응형 규칙, 접근성 의도가 사라진다. 개발자는 화면을 눈대중으로 재현하게 되고, 값은 코드 안에 그대로 박히며, 디자인이 바뀌면 양쪽을 따로 고쳐야 한다. 이 일이 반복되면서 디자인과 코드는 조금씩 서로 어긋난다.

1.2 디자인 엔지니어링이라는 해법

디자인 엔지니어링은 이 간극을 개인의 성실함이 아니라 시스템으로 메운다. 디자인과 코드가 같은 토큰과 컴포넌트를 공유하게 만들고, Figma MCP는 AI 에이전트가 그 약속을 읽어 약속에 맞는 코드를 만들도록 이어 준다.

2. Figma MCP 서버 개요

2.1 MCP란

Model Context Protocol(MCP) 은 AI 에이전트가 외부 도구와 데이터에 표준 방식으로 접근하게 해 주는 개방형 프로토콜이다. Figma MCP 서버가 Figma의 기능을 열어 주면, Claude Code나 Cursor, VS Code 같은 MCP 클라이언트가 그 기능을 불러 쓴다.

2.2 핵심 도구

2.3 연결과 조건

원격 서버 https://mcp.figma.com/mcp 에 연결하는 방식을 권장한다. 캔버스 쓰기 기능은 유료 요금제의 Full·Dev 시트에서 쓸 수 있고 베타 기간에는 무료이지만, 조건이 바뀔 수 있으니 도입 전에 공식 문서를 한 번 확인하는 편이 좋다.

3. 디자인 엔지니어링의 네 축

MCP는 연결 통로일 뿐이고, 자동화의 품질은 디자인과 코드가 맺은 약속에서 나온다.

3.1 토큰 — AI가 색을 채워 넣지 못하게 한다

색과 간격, 타이포, 반경은 토큰으로 정의하고, Figma 변수와 코드가 같은 값을 바라보게 만든다. 표준 포맷은 W3C DTCG의 $type/$value 구조이며, SDS는 토큰 JSON에 Figma 변수 ID(figmaId) 까지 적어 두어 코드 토큰이 어느 Figma 변수에서 왔는지 따라갈 수 있게 했다.

SDS의 토큰은 절대값 → 역할 → 컴포넌트 순서로 참조가 이어진다.

/* 절대값 (theme.css) */
--sds-color-brand-800: #2c2c2c;

/* 역할 — 절대값을 참조 (theme.css) */
--sds-color-background-brand-default: var(--sds-color-brand-800);

/* 컴포넌트 — 토큰만 참조, 직접 쓴 값 없음 (button.css) */
.button {
  background: var(--button-background-color);
  gap: var(--sds-size-space-200);
  border-radius: var(--sds-size-radius-200);
}

컴포넌트 CSS에 hex나 px 값이 직접 들어가지 않으니, 하드코딩 여부를 도구로 걸러낼 수 있다.

반대로 변수 없이 화면에서 색을 긁어모으면 어떻게 될까. 실제 상품 상세 페이지 작업에서 변수가 없는 파일을 추출했더니 #88816d와 #88816f처럼 눈으로는 구분할 수 없는 색이 서로 다른 토큰으로 갈라졌고, 회색 계열만 열 개가 넘게 나왔다. 변수가 갖춰진 파일일수록 결과가 정확해지는 이유다.

3.2 컴포넌트 — 빠짐없이 찾고, 재사용한다

get_metadata로 화면에 쓰인 공통 컴포넌트를 먼저 정리한 다음, 화면은 그 컴포넌트를 조립해 만든다. 폼 인풋이나 페이지네이션, 푸터처럼 눈에 덜 띄는 요소가 특히 자주 빠지므로 목록을 먼저 만들어 두는 편이 안전하다.

코드 컴포넌트 라이브러리가 이미 있다면 Code Connect로 Figma 컴포넌트와 연결해 재사용률을 높일 수 있다. SDS는 Figma의 Variant 속성을 코드의 variant prop에 이렇게 이어 두었다.

// Button.figma.ts (SDS, 일부)
const variant = instance.getEnum("Variant", {
  Primary: "primary",
  Neutral: "neutral",
  Subtle: "subtle",
});

이렇게 연결해 두면 AI는 새 버튼 마크업을 짓는 대신 기존 <Button>을 가져다 쓴다. 다만 필수는 아니어서, 매핑이 없어도 디자인에 적힌 값만으로 컴포넌트를 만들 수 있다.

3.3 디자인과 마크업 — 똑같아 보이는 것과 똑같이 동작하는 것은 다르다

스타일은 get_design_context 값에 맞추되, 태그는 겉모습이 아니라 역할을 따라 고른다.

SDS는 이 원칙을 컴포넌트 구조에 못 박아 두어, 버튼처럼 보이는 요소라도 href가 있으면 링크로, 없으면 버튼으로 그린다.

// AnchorOrButton.tsx (SDS, 요약)
return isAnchorProps(props)
  ? <RACLink {...sharedProps}>{props.children}</RACLink>      // href 있음 → 링크
  : <RACButton {...sharedProps}>{props.children}</RACButton>; // href 없음 → 버튼

AI에게 어디까지 맡길지도 같은 관점으로 나눌 수 있다.

• 디자인에 적힌 것(색·간격·문구) — 그대로 옮기기. 비슷한 값이나 샘플 문구로 대신하지 않기
• 디자인에 적히지 않은 것(태그 선택·제목 순서) — 규칙을 미리 정해 두고 AI에게 판단을 맡기기
• 사업 정보(가격·재고·브랜드) — AI가 채우지 않고 담당자가 확인

같은 작업에서도 화면에 가격이 없어, 그 자리는 빈칸으로 두고 담당자에게 넘겼다.

접근성 기준은 국내 서비스라면 KWCAG 2.2(WCAG 2.1 기반 국내 표준)를 따르는데, 도구로 검사할 수 있는 항목과 사람이 내용을 읽어 봐야 하는 항목, 스크린리더로 직접 들어 봐야 하는 항목을 나눠 관리하면 빠뜨리는 것이 줄어든다.

3.4 검증 — 검사마다 강도를 다르게 둔다

모든 항목을 똑같이 엄격하게 막으면 AI는 검사를 통과하는 데만 매달리므로, 항목의 성격에 따라 강도를 나눈다.

• 반드시 고칠 것 — 하드코딩된 색, 부족한 색 대비, 제목·대체 텍스트·폼 라벨 누락, 타입 오류처럼 명확히 틀린 것
• 알리고 넘어갈 것 — 디자인에 없는 FAQ나 리뷰 영역을 넣으라는 요구처럼, 디자인만으로는 채울 수 없는 것

넘어간 항목도 기록으로 남겨 사람이 판단할 수 있게 한다. 디자인 의도와 접근성 기준이 부딪히면 담당자가 결정하고 그 이유를 적어 두되, 검사를 통과하려고 없는 정보를 지어내는 일만은 막아야 한다.

4. 실전 워크플로우

4.1 준비 — 디자인 파일 점검

• 컴포넌트와 변수, 스타일에 일관된 이름이 붙어 있는가
• 간격과 정렬이 오토레이아웃으로 잡혀 있는가
• 변수가 정의돼 있고, 레이어에 실제로 적용돼 있는가
• 반복되는 UI가 컴포넌트로 만들어져 있는가

4.2 흐름

코드 값만 맞춰 놓고 끝내서는 안 된다. CSS 값이 전부 맞아떨어져도 페이지 경로가 깨졌거나 폰트가 뜨지 않으면 실제 화면이 달라지므로, 실제로 띄운 화면을 캡처해 Figma와 겹쳐 보면서 팀이 정한 허용 오차 안에 들어올 때까지 다듬어야 한다.

4.3 프롬프트 패턴

이 Figma 노드를 우리 디자인 시스템 규칙으로 구현해줘.
- 링크: https://www.figma.com/design/FILE?node-id=NODE
- 스타일은 get_design_context 값 기준, 색·간격은 토큰만 사용
- 문구는 디자인에 적힌 그대로 사용
- 링크는 a, 제목은 h1~h3 등 역할에 맞는 태그 사용
- 상태(hover/focus/disabled)와 반응형 포함
- 디자인에 없는 정보는 채우지 말고 확인 필요로 표시
- 작업이 끝나면 만든 것과 못 만든 것을 구분해서 알려줘

5. 품질·운영 기준

AI의 "끝났습니다"는 결과로 확인해야 한다. 일부만 만들어 놓고도 작업을 마쳤다고 말하는 경우가 있으므로, 디자인에서 찾은 컴포넌트 수와 실제로 만든 수를 맞춰 보고 확인하지 못한 항목은 따로 남겨 둔다.

상품 상세 페이지(모바일) 확인 결과
- 컴포넌트: 디자인에서 6개 확인, 6개 모두 구현
- 가격 정보: 화면에 없어 비워 둠
- 남은 확인: 스크린리더 실기기 테스트

• 접근 범위와 보안 — 디자인 파일 접근 범위와 캔버스 쓰기 권한을 팀 정책에 맞게 제한
• 실행할 때마다 달라지는 결과 — 같은 입력에도 결과가 달라질 수 있으므로 리뷰와 테스트를 거쳐 PR(변경 요청)로 기록
• 비용 — 캔버스 쓰기처럼 기능별 요금 조건은 팀에 미리 공유

6. 한계와 안티패턴

7. 어디에 효과적인가

디자인 시스템이 잘 잡힌 팀에서 MCP는 큰 힘이 되지만, 그렇지 않은 팀에서는 정리되지 않은 상태를 코드로 옮기는 데 그친다.

실행 체크리스트

• Figma 변수 정의 및 레이어 적용 완료
• 코드 토큰이 Figma 변수와 같은 값을 참조
• 토큰 사용·태그 선택·사업 정보 확인에 대한 규칙 수립
• 반드시 고칠 항목과 기록만 할 항목 구분
• 코드 값 비교와 화면 비교를 함께 진행
• 접근성 기준(KWCAG 2.2) 확정
• 캔버스 쓰기 권한과 요금 조건을 공식 문서로 확인

참고 자료