Figma MCP[1]로 컴포넌트를 구현하게 하면, 언뜻 보기에는 그럴싸한 결과물이 나옵니다. 하지만 자세히 보면, 7종류나 되었던 여백(16/40/32/44/24px…)이 전부 gap-6으로 통일되어 있습니다.

아이콘이 채우기(Fill) 형태여야 하는데 선화(Stroke)로 되어 있습니다. 색상이 디자인 토큰(Design Token) 한 단계만큼 차이가 납니다.

그리고 최악인 것은, 본인(AI)이 「Figma와 일치합니다」라고 자신만만하게 보고해 온다는 점입니다.

언뜻 비슷해 보이지만, 측정하면 차이가 발생한다. 왼쪽은 디자인 참조(재현 작도), 오른쪽은 구현(Storybook). 타이틀의 색상·크기와 여백의 어긋남이 실측을 통해 숫자로 확정된다.

시행착오 끝에 도달한 결론은 다음과 같습니다. Figma to Code의 정밀도 문제의 본질은 생성의 정밀도가 아니라 검증의 정밀도에 있습니다. 「눈으로 봐서 대충 맞다」를 「일치」라고 보고하는 것이 모든 오차의 근원입니다. 그래서 구현 → 촬영 → 화소 측정 → 수정의 폐쇄 루프(Closed Loop)를 구축하고, 「측정하지 않은 항목은 『일치』라고 쓸 수 없다」는 규칙을 세웠습니다. 본 기사에서는 그 메커니즘을 전부 소개합니다.

1. 기존 Figma to Code가 안고 있던 문제

먼저, Figma to Code가 지금까지 무엇에 걸려 넘어졌는지 정리해 두겠습니다.

제1세대: 플러그인을 통한 코드 출력. Figma의 레이어 구조가 그대로 DOM이 되어, 기존의 컴포넌트 규약과는 무관한 코드가 나옵니다. 작동하는 데모는 될 수 있어도, 프로덕트의 코드베이스에는 넣을 수 없었습니다.

제2세대: Figma MCP + 코딩 에이전트(Coding Agent). 에이전트가 Figma로부터 디자인의 수치 정보(색상 코드·크기·여백 등, 구현에 사용하는 값)를 취득하여, 기존의 규약·기존 컴포넌트에 따라 구현할 수 있게 되었습니다. 여기서 「코드로 사용할 수 있는」 수준에는 도달합니다. 하지만 정밀도 문제가 남습니다.

필자의 팀이 실측한 결과(후술할 「실패 빈도 랭킹」)에 따르면, 빈번하게 발생하는 오류는 다음 순서였습니다.

간격의 통일(가장 많음): 서로 다른 7종의 구분을 단일한 gap으로 뭉개버림. 이중 padding. 박스 내부 배치(justify) 간과

텍스트 색상 오인: 인접 요소의 색상을 가져옴. 토큰 표에서 이웃한 색상을 혼동 (red-2 (#FF0033)와 red-3 (#FE5C5C) 등. 이름은 한 단계 차이라도 색상은 별개)

타이포그래피(Typography)의 role 뭉개기: 라벨 12px Bold와 값 14px Bold를 일률적인 variant로 처리

아이콘의 바리언트(Variant): 선화/채우기 차이를 「일치」로 오판정

상태(State) 누락: 대표 바리언트만 구현하고 나머지 상태를 놓침

모두 「전체를 쓱 보면 맞다」라고 느껴지는 유형의 오류입니다. 즉, 육안을 통한 전체 비교로는 원리적으로 검출할 수 없습니다.

또 다른 운영상의 문제가 있습니다. **토큰 비용(Token Cost)**입니다. Figma MCP의 출력은 거대하고, 스크린샷은 이미지 토큰의 덩어리이며, Storybook의 기동 로그는 노이즈의 산입니다. 이것을 전부 메인 세션에 쌓으면, 수정 루프를 돌릴수록 컨텍스트(Context)가 오염되어 비용이 급증합니다.

2. 4단계 폐쇄 루프와 컨텍스트 격리

그래서 플로우를 4단계의 폐쇄 루프로 만들고, 무거운 처리는 서브 에이전트(Sub-agent)로 격리했습니다.

(색상 구분: 파랑=메인 세션의 공정 / 청록=서브 에이전트에 격리한 공정)

제2회에서 소개한 지휘자 패턴의 응용입니다. 신경 쓴 점은 다음 두 가지입니다.

이미지를 Read 하는 것은 비교 서브 에이전트 내부에서만 수행. 메인 세션에는 일절 이미지를 싣지 않습니다. Figma로부터의 취득도 스크린샷을 제외한 텍스트 값 중심으로 수행하며, 비교용 PNG는 curl로 파일 저장만 합니다. 이미지 토큰은 비교를 담당하는 별도의 컨텍스트에 가둡니다.

PNG 재사용 규칙. Figma 측의 PNG는 디자인이 바뀌지 않는 한 유효하므로, 세션 중에는 한 번만 가져와서 재사용합니다. 반면 Storybook 측은 코드 변경 시마다 다시 촬영합니다. 이를 통해 수정 루프의 2회차 이후부터는 비용이 대폭 저렴해집니다.

단, 이 재사용에는 후술할 함정이 있으며, 실제로 사고가 발생했습니다(4장).

핸즈온 ①: 호출부터 Step 1의 출력까지

여기서부터는 ItemCard라는 카드 컴포넌트를 예로 들어 한 바퀴 돌려보겠습니다. 호출은 컴포넌트 이름과 Figma URL(배리언트(variant)가 여러 개 있다면 전부)을 전달하기만 하면 됩니다.

/figma-to-code ItemCard를 다음 Figma 패턴과 비교해줘
- 선택됨 (분홍색 배경): https://www.figma.com/design/xxxx/?node-id=1234-5678&m=dev
- 미선택 (흰색 배경): https://www.figma.com/design/xxxx/?node-id=1234-5679&m=dev

Step 1을 담당하는 figma-fetch 에이전트의 정의는 다음과 같은 지시로 시작됩니다 (실제 내용 발췌 및 마스킹 처리됨).

---
name: figma-fetch
description: Figma MCP로부터 디자인 구현값을 가져와 요약하여 반환한다. 토큰 절감을 위해
...

"gap은 선의 양쪽에 적용된다"와 같은 주의사항이 묘하게 구체적인 이유는, 전부 과거의 실수 흔적입니다(4장). 또한 excludeScreenshot과 같은 인자(argument) 이름은 집필 시점의 환경 기준입니다. Figma MCP는 도구 이름 및 인자 업데이트가 빠르므로, 가지고 계신 버전의 문서를 참고하여 읽어주시기 바랍니다. 이 에이전트가 메인으로 반환하는 "디자인 수치 요약"은 다음과 같은 형태가 됩니다 (샘플).

## ItemCard 디자인 수치 요약 (선택됨 패턴)
- 사이즈: 카드 328×96px / radius 12px
- 배경: #FFF1F4 (token: pink-1) / 테두리 1px #FE5C5C (token: red-3)
...

Step 1 요약의 각 값이 카드의 어느 부분을 가리키는지에 대한 대응 (값은 구현된 CSS 기준). Figma 요약의 각 항목에 1:1로 대응시켜 측정하고 확인한다

구현(Step 2)은 이 요약과 프로젝트의 규약 스킬을 바탕으로 메인 세션이 수행합니다. 여기서 생(raw) HTML/CSS를 쓰는 것이 아니라, 프로젝트 디자인 시스템의 기존 컴포넌트(텍스트, 버튼, 레이아웃 등의 공통 부품)에 맞춰 구현하는 것이 포인트입니다. 예를 들어 텍스트는 폰트 크기나 굵기를 CSS에 직접 쓰지 않고, 공통 AppTypography의 variant에 맡깁니다.

// ✗ 생 스타일 직접 작성: Figma의 어떤 텍스트 스타일에 대응하는지 불분명함.
// 라벨과 값을 동일한 지정으로 뭉뚱그려도 알아차릴 수 없음
<span style={{ fontSize: 14, fontWeight: 700, lineHeight: '20px' }}>제목</span>
...

AppTypography의 variant는 Figma 측에 정의된 텍스트 스타일(타이포그래피의 variant)과 이름 수준에서 대응하도록 설계되어 있습니다. 따라서 구현은 "Figma의 이 스타일 → 코드의 이 variant"라는 매칭이 되므로, 사이즈·굵기·행간을 개별적으로 전기할 필요가 없습니다. 반대로 말하면, 1장에서 언급한 실패 사례인 "타이포그래피의 role 뭉뚱그리기" — 라벨과 값을 일괄적인 variant로 만들어버리는 실수 — 도 variant 명칭의 불일치로서 쉽게 드러나게 됩니다 (variant 명칭은 설명용 샘플입니다). 기존 규약을 무시한 DOM을 뱉어내던 제1세대 플러그인 출력이 해결하지 못했던 부분이 바로 이 부분이었습니다. 하지만 여기까지는 아직 평범한 Figma to Code입니다. 진가는 다음 단계인 "측정하여 검증하기"부터 시작됩니다.

3. 측정 우선(Measurement First) — "일치"라고 쓸 수 있는 조건을 정의한다

이 부분이 본 기사의 핵심입니다. 비교 서브 에이전트의 대원칙은 다음 한 문장으로 요약됩니다.

육안의 인상으로 판정하지 않는다. 측정하여 숫자로 대조한다.

측정은 공유 스크립트로, 매번 같은 결과가 나오도록 수행한다

비교 에이전트는 Python 공유 스크립트로 픽셀을 측정합니다.

python3 measure.py size <img> # 이미지 크기 (크기 기준 맞추기용)
python3 measure.py hex <img> <x> <y> # 지정 좌표 주변의 최빈색 hex
python3 measure.py bands <img> <x0> <y0> <x1> <y1> # 요소의 띠(band) 검출 및 gap 실측
...

에이전트에게 매번 스니펫을 작성하게 버리지 않고, 공유 스크립트에 고정해 두는 것도 포인트입니다. 측정 파라미터(색상 샘플링 반경, 띠 검출 허용 오차)가 매번 바뀌면 측정 결과의 재현성이 떨어지기 때문입니다. 스크립트 자체는 Pillow + numpy를 이용한 단순한 이미지 처리로, hex는 지정 좌표 주변에서 가장 많은 색을 세고, bands는 띠 형태의 범위에서 "배경과 밝기가 다른 행"을 검출할 뿐입니다(전체 약 150행 정도). 좌표는 촬영한 PNG를 열어 "측정하려는 요소를 세로로 관통하는 가는 띠"의 왼쪽 상단과 오른쪽 하단을 읽어서 전달합니다.

측정 전에는 크기 기준 맞추기(스케일 정규화) 단계를 거칩니다. Figma의 PNG와 Storybook에서 촬영한 PNG는 해상도가 다르기 때문에, 양쪽 모두에 찍혀 있는 기준 요소(카드 너비 등)로부터 scale 계수를 산출하고, 모든 거리를 Figma의 px 단위로 변환한 뒤 비교합니다.

핸즈온 ②: ItemCard의 간격과 색상을 실제로 측정하기

앞서 살펴본 ItemCard에서 "제목 $\rightarrow$ 설명 $\rightarrow$ 메타 행"의 세로 간격을 측정해 보겠습니다. 텍스트를 세로로 관통하는 가는 띠(strip)의 좌표를 지정하여 bands를 실행하면, 콘텐츠의 띠와 띠 사이의 gap이 수치로 나옵니다.

$ python3 measure.py bands storybook-selected.png 40 10 60 180
bg_luma=255 bands=3 axis=v
band[0]: 16..36 (h=20)
...

첫 번째 줄의 bg_luma는 배경의 밝기를, axis=v는 세로 방향 스캔을 나타냅니다. band가 3개라는 것은 텍스트 행이 3개라는 뜻입니다. gap_from_prev가 곧 행 간의 실측값입니다. Step 1의 요약은 "제목 $\rightarrow$ 설명 gap 8px / 설명 $\rightarrow$ 메타 행 gap 12px"였습니다. 실측값인 8은 일치합니다. 하지만 두 번째 값은 24입니다. 12px이어야 할 간격이 두 배가 되었습니다. 구현 과정에서 두 곳의 서로 다른 간격을 단일한 gap으로 통일해 버린, 서두에서 언급했던 전형적인 실수가 여기서 처음으로 숫자로서 모습을 드러내는 것입니다. 육안으로는 "왠지 좀 늘어져 보이나?" 정도의 느낌밖에 들지 않습니다.

색상도 같은 방식으로 진행합니다. 글자 선의 중심 좌표를 지정하여 Figma 측과 구현 측 양쪽을 모두 측정합니다.

$ python3 measure.py hex figma-selected.png 52 26 # Figma 측: 제목 글자의 중심
#1A1A1A
$ python3 measure.py hex storybook-selected.png 50 25 # 구현 측: 동일한 위치
...

어디를 측정하고 있는가. bands는 세로로 긴 스트립으로 행 간격을, hex는 글자의 중심에 찍은 점으로 색상을 측정한다. 윤곽선의 블러(blur)를 잡지 않도록 선의 중심을 겨냥한다.

이렇게 측정한 값으로 다음의 대조표를 한 줄씩 채워 나갑니다.

스펙 대조표 — 「거의 일치」 금지

비교 에이전트의 주요 결과물은 스펙 대조표(디자인 값과 구현 값을 한 줄씩 나란히 비교하는 표)입니다.

규칙은 세 가지입니다.

• 판정은 「일치 / 차이(Difference) / 재확인 필요」의 3가지 값으로만 제한한다. 「거의 일치」는 금지한다. 모호하다면 확대하여 재측정하거나 「재확인 필요」로 분류한다.
• 「일치」라고 쓸 수 있는 것은, Figma 값과 구현 실측값 모두 숫자(px / 컬러 코드 / Variant 명)로 채워진 행뿐이다. 숫자를 쓸 수 없는 항목은 「미확인」이지 「일치」가 아니다.
• 값을 얻을 수 없는 행도 생략하지 않는다. 「fetch 재요청」이라고 작성하여 반환한다.

과거의 오판정(gap의 일률적인 공통화, 색상 혼동, 채우기(Fill)/선(Stroke)의 오류)은 예외 없이 「눈으로 봐서 대충 맞다」를 「일치」라고 보고한 것이 원인이었습니다. 그래서 보고 포맷 자체에서 「대충」을 배제하고 있습니다.

측정의 핵심 포인트

실운영에서 쌓인 노하우를 몇 가지 소개합니다.

• 간격은 「경계마다 1행」으로 작성한다. 묶어서 「gap OK」라고 쓰게 하지 않습니다. 구현이 단일 flex gap-N으로 여러 경계를 한꺼번에 처리하고 있다면, 표의 여러 행이 동일한 값을 가지게 되므로 이를 검출할 수 있습니다.
• 텍스트 색상은 글자 선의 중심을 측정한다. 윤곽선의 흐릿한 부분(안티앨리어싱 (Anti-aliasing))을 잡으면 실제로는 존재하지 않는 차이가 발생합니다.
• 40px 이하의 소형 요소 및 아이콘은 양측 모두 4x 확대하여 판정한다. 전체 PNG를 눈으로만 봐서는 선(Stroke)과 채우기(Fill)의 구분이 불가능합니다.
• Figma와 CSS의 「테두리(Border) 적용 방식」 차이를 보정한다. Figma의 stroke는 (기본값인 Inside 설정 시) 테두리 안쪽에 붙지만, CSS의 border는 padding 외부에 붙습니다. 테두리가 있고 높이가 지정되지 않은 박스에 원래 값 그대로 padding을 넣으면 2px 어긋나게 됩니다. — 이러한 구조상 반드시 발생하는 차이는 규칙화하여 흡수합니다.

measure.py 의 실행 예시. bands가 영역(텍스트 행)을 검출하여 gap_from_prev에 행 간의 실측값을 출력한다. hex는 지정된 좌표의 색상을 반환한다 (이 촬영 샘플에서의 실측값)

4x 확대 크롭. 전체 PNG를 눈으로 볼 때는 뭉개져서 「일치」로 오판정되기 쉬운 선(Stroke)/채우기(Fill)의 차이가, 확대하면 명확하게 판별된다

4. Figma 버전의 자기 학습 루프 — 실패 빈도 랭킹

제3회(집필 중)에서 리뷰 지적 사항을 로그에 쌓아 리뷰 에이전트의 체크 배분을 변경하는 메커니즘을 소개했습니다. 동일한 사상이 이 시각 비교에도 포함되어 있습니다.

비교 에이전트의 정의에는 실패 빈도 랭킹이 있으며, 과거의 실수 사례를 카테고리별로 카운트하고 있습니다.

## 실패 빈도 랭킹 (이 순서대로 측정을 중점 배분함)
| 우선순위 | 카테고리 | 횟수 |
|---|---|---|
...

(상위 5개 카테고리 발췌입니다. 그 외에 box-model 차이 등 소수의 카테고리가 있습니다)

그리고 유지보수 규칙은 다음과 같습니다.

새로운 실수가 발생했을 때, 새로운 항목(bullet)을 추가하는 것이 아니라,

해당 카테고리의 「횟수」를 +1 합니다 (대표 사례 교체는 가능). 신규 카테고리 추가는 기존 카테고리에 포함되지 않는 새로운 종류일 때만 수행합니다.

체크리스트의 비대화는 대충 훑어보게 만드는 원인이 됩니다. 항목 수를 고정하고 가중치(Weight)만 이동시킴으로써, 리스트를 짧게 유지하면서도 체크의 노력을 자주 발생하는 실수에 계속 집중시킬 수 있습니다. 「횟수가 많은 카테고리부터 우선적으로·세밀하게 측정한다」 — 리뷰 에이전트의 빈번 위반 랭킹과 동일한 형태의, 시각 버전 자기 학습 루프입니다. 참고로 리뷰 버전과 달리, 이쪽은 건수가 적고 병행 업데이트가 거의 일어나지 않기 때문에, 별도의 추가 전용 로그를 거치지 않고 랭킹 표를 직접 +1 하는 방식으로 운영하고 있습니다 (양이 늘어나면 동일한 로그 방식으로 이행할 예정입니다).

실제 사고가 규칙이 된 사례

이 기술의 규칙 대부분은 실제 인시던트(Incident)로부터 탄생했습니다. 세 가지 사례를 소개합니다.

「PNG가 남아있더라도 Step 1의 『디자인 수치 요약』은 매번 필요하다」. PNG를 재사용할 수 있다고 해서 Step 1을 통째로 건너뛰었더니, 비교 에이전트(Comparison Agent)가 대조표의 「Figma 값」 열을 픽셀 실측치로 채울 수밖에 없게 되었습니다. 그 결과, Figma 측 PNG에 섞여 있던 그리기 노이즈—이때는 Web Font 로딩이 늦어져 다른 폰트로 그려진 상태로 저장되어 있었음—까지 「Figma의 값」으로 취급하여, 본래 올바르게 구현된 부분을 차이점(diff)으로 오보고한 것입니다. 대조표의 Figma 값 원 데이터는 어디까지나 fetch의 요약이며, PNG는 외관 확인용입니다. 이 구분을 놓치면 측정 우선(Measurement-first) 원칙이 오히려 독이 됩니다.

「픽셀 실측으로 얻은 값을 『Figma 상의 본래 값』으로 취급하지 않는다」. 아이콘이 24px인지 28px인지 픽셀만으로는 확정할 수 없는 경우가 있습니다. 실측치 그대로 구현하면 「값은 맞지만 이유를 설명할 수 없는」 부분이 늘어나기 때문에, 확정할 수 없는 값은 fetch를 통해 Figma 상의 정의값을 다시 가져옵니다. 반대로, 그 정의값을 해당 값이 답할 수 있는 범위를 넘어 옆의 요소에 유용해서도 안 됩니다 (이것도 실제로 저질렀던 실수입니다).

「베리언트 망라 게이트 (Variant Coverage Gate)」 (모든 상태가 갖춰져 있는지 사전 체크). 대표적인 상태만 구현하고 나머지 베리언트(Variant)를 놓치는 사고가 있었습니다. 이후 구현에 들어가기 전, 「Figma의 베리언트 목록 N종 ⇔ mock / Story의 N종 커버리지」를 대조하여 일치함을 확인한 뒤 시각 루프(Visual Loop)로 진행하는 게이트를 두고 있습니다.

5. 운영의 핵심

Story화의 판단 기준을 갖는다. 「페이지 하위 요소를 엄격하게 비교하고 싶다」는 요구를 받더라도, 하위의 모든 컴포넌트를 Story화해서는 안 됩니다. 개별 비교할 가치가 있는 것은 「Figma와 1:1 대응하며, 외관 표시만을 담당하는 말단 부품」뿐입니다. 복합 컴포넌트나 hook에 의존하는 것, 레이아웃용 frame은 페이지 단위의 Story로 커버합니다. 무분별하게 전부 Story화하면 시간만 낭비하게 됩니다.

스코프(Scope)를 명시한다. 이 루프가 다루는 것은 「Figma 프레임 너비에서의 정지 상태」 비교뿐입니다. 반응형(Multiple Breakpoints)・다크 모드・hover 등의 인터랙션 상태・애니메이션은 대상에서 제외함을 명시하고 있습니다. 무엇이든 비교하려고 하면 폐쇄 루프(Closed Loop)가 닫히지 않습니다. 스코프를 좁혔기에 폐쇄 루프를 만들 수 있었다는 점은 설계 판단으로서 강조하고 싶은 부분입니다. 또한 대상 컴포넌트도 Storybook을 보유한 프론트엔드로 한정하고 있습니다 (필자의 팀에서는 Storybook이 도입되지 않은 관리 화면은 대상에서 제외합니다).

개발 플로우에 통합한다. 이 루프는 단독으로도 호출할 수 있지만, 제2회 orchestrate의 FE 트랙에 포함되어 있습니다. 설계서에 Figma URL을 적어두면, 구현 단계에서 이 시각 일치 루프가 컴포넌트 단위로 자동적으로 포함됩니다.

차이 제로(Zero diff)의 최종 상태. 대조표의 모든 행이 px / 컬러 코드로 채워져 「일치」 상태가 됨 (「거의 일치」는 없음)

요약 — 시리즈 전체의 회수

Figma to Code의 정밀도 향상이란, 생성을 똑똑하게 만드는 것이 아니라, 검증을 정량화하고 그 검증 자체가 학습하도록 만드는 것이었습니다.

• 비교 판정을 3가지(일치 / 차이 / 재확인 필요)로 나누고, 「거의 일치」를 금지하고 있는가
• 「일치」에 실측치(px / 컬러 코드)의 근거를 요구하고 있는가
• 이미지·거대 출력을 메인 컨텍스트(Main Context)로부터 격리하고 있는가
• 과거의 외관 실수를 카테고리 × 횟수로 관리하여 체크의 중점 배분에 사용하고 있는가
• 모든 베리언트가 갖춰져 있는지 구현 전에 확인하고 있는가
• 루프의 스코프 외(반응형 등)를 명시하고 있는가

마지막으로, 시리즈 전체를 조금 멀리서 바라보겠습니다. 제2회의 개발 플로우, 제3회의 환경 학습, 그리고 본 기사의 시각 일치. 다루는 대상은 제각각이지만, 하고 있는 일은 깔끔하게 동형(Isomorphic)입니다.

닫기 (Close) — 생성하고 끝내는 것이 아니라, 검증과 수정으로 고리를 닫는다 -
측정 (Measure) — 검증을 육안이나 자기 신고가 아닌, 측정과 검증 커맨드에 연결한다 -
학습을 다시 쓰기 (Write back learning) — 실수를 그 자리에서 고치고 끝내는 것이 아니라, 환경(로그·랭킹·DoD·규칙)에 다시 기록한다

이 3가지 세트를 자신의 업무 모든 곳에 배치해 나가는 것. 그것이 우리가 실운영에서 배운 「루프 엔지니어링 (Loop Engineering)」의 실천입니다.

참고 링크

• Figma MCP로 디자인대로 AI 코딩하기 위한 프랙티스 (peoplex_blog) — 구현 전 준비(규약, Code Connect 등)에 초점을 맞춘 좋은 기사입니다. 본 기사의 「구현 후 검증 루프」와 상호 보완적인 관계입니다.

• Figma MCP의 정밀도를 더욱 높이는 팁 (canly)

• Loop Engineering 입문 (suwash)

MCP = Model Context Protocol. AI 에이전트가 외부 도구 및 데이터에 연결하기 위한 표준 규격입니다. Figma MCP는 이를 통해 Figma의 디자인 데이터를 가져올 수 있도록 하는 서버입니다. ↩︎

Discussion