용어 메모

Storybook: UI 컴포넌트를 하나씩 단독으로 표시·확인할 수 있는 개발 도구. 표시 패턴의 정의를 「Story」라고 부름 -
배리언트 (Variant): 동일한 컴포넌트의 상태 차이 (선택 중·완료·에러 등) -
화소 계측 (Pixel Measurement): 스크린샷을 픽셀 단위로 측정하여 색상이나 간격을 수치로 추출하는 것 -
디자인 토큰 (Design Token): 색상이나 크기에 이름을 붙여 일원 관리하는 체계 (예: primary-500)

Figma MCP를 통해 컴포넌트를 구현하게 하면, 언뜻 보기에는 그럴싸한 결과물이 나옵니다. 하지만 자세히 살펴보면, 7종류나 되었던 여백(16/40/32/44/24px…)이 전부 gap-6으로 통일되어 있습니다. 아이콘이 채우기(Fill) 형태여야 하는데 선화(Stroke)로 되어 있습니다. 색상이 디자인 토큰 한 단계만큼 차이가 납니다.

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

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

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

먼저, Figma to Code가 지금까지 무엇 때문에 난관에 부딪혀 왔는지 정리해 두겠습니다.

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

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

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

간격의 통일 (가장 많음): 서로 다른 7종의 구분을 단일 gap으로 뭉뚱그림. 이중 padding. 박스 내부 배치(justify) 간과 -
텍스트 색상 오인: 인접 요소의 색상을 가져옴. 토큰 표에서 인접한 색상을 혼동 (red-2 (#FF0033)와 red-3 (#FE5C5C) 등. 이름은 한 단계 차이지만 색상은 별개) -
타이포그래피의 role 뭉뚱그림: 라벨 12px Bold와 값 14px Bold를 일괄적인 variant로 처리함 -
아이콘의 배리언트 (Variant): 선화/채우기 차이를 「일치」로 오판정 -
상태 누락: 대표 배리언트만 구현하고 나머지 상태를 놓침

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

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

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

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

제2회에서 소개한 지휘자 패턴의 응용입니다. 공을 들인 부분은 다음 두 가지입니다.

이미지를 읽는 것은 비교 서브 에이전트(Comparison Sub-agent) 내부에서만 수행합니다. 메인 세션에는 이미지를 일절 올리지 않습니다. Figma로부터의 데이터 취득도 스크린샷을 제외한 텍스트 값 중심으로 수행하며, 비교용 PNG는 curl을 통해 파일로 저장할 뿐입니다. 이미지 토큰은 비교를 담당하는 별도의 컨텍스트(Context)에 가둡니다.

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

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

여기서부터는 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)은 이 요약과 프로젝트의 규약 스킬을 바탕으로 메인 세션이 수행합니다. 여기서 순수 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입니다. 진가는 다음 단계인 "측정하여 검증하기"부터 시작됩니다.

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

눈으로 본 인상으로 판단하지 않는다. 측정하고, 숫자로 대조한다.

비교 에이전트(Comparison Agent)는 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를 열어 "측정하려는 요소를 세로로 관통하는 가는 띠"의 왼쪽 상단과 오른쪽 하단을 읽어서 전달합니다.

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

앞서 살펴본 ItemCard에서 "제목 → 설명 → 메타 행"의 세로 간격을 측정해 보겠습니다. 텍스트를 세로로 관통하는 가는 띠(스트립, 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의 요약은 "제목 → 설명 gap 8px / 설명 → 메타 행 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의 일률적 공통화, 색상 혼동, 채우기/선화 오류)은 예외 없이 「눈으로 봐서 대충 맞다」를 「일치」라고 보고한 것이 원인이었습니다. 그래서 보고 포맷 자체에서 「대충」을 배제하고 있습니다.

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

간격은 「경계마다 1행」. 묶어서 「gap OK」라고 쓰게 하지 않습니다. 구현이 단일한 flex gap-N으로 여러 경계를 뭉뚱그려 처리하고 있다면, 표의 여러 행이 동일한 값을 가지게 되므로 이를 검출할 수 있습니다 -

• 텍스트 색상은 글자 선의 중심을 측정한다. 윤곽선의 흐릿한 부분(안티앨리어싱 (Anti-aliasing))을 잡으면 실제로는 존재하지 않는 차이가 발생합니다 -
• 40px 이하의 소형 요소·아이콘은 양측 모두 4x 확대 후 판정한다. 전체 PNG를 눈으로 봐서는 선화(Line art)와 채우기(Fill)의 구분이 되지 않습니다 -
• Figma와 CSS의 「테두리(Border) 적용 방식」 차이를 보정한다. Figma의 stroke는 (기본값인 Inside 설정 시) 테두리 안쪽에, CSS의 border는 padding 외측에 붙습니다. 테두리가 있고 높이가 지정되지 않은 박스의 경우, 원래 값대로 padding을 넣으면 2px 어긋나게 됩니다 — 이러한 메커니즘상 반드시 발생하는 오차는 규칙화하여 흡수합니다

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

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

제3회에서 리뷰 지적 사항을 로그에 쌓아 리뷰 에이전트(Review Agent)의 체크 배분을 바꾸는 메커니즘을 소개했습니다. 동일한 사상이 이 시각적 비교에도 담겨 있습니다.

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

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

(상위 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 상의 정의값(Definition value)을 다시 가져옵니다. 반대로, 그 정의값을 그 값이 답할 수 있는 범위를 넘어 옆의 요소에 유용해서도 안 됩니다(이 또한 실제로 저질렀던 실수입니다).

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

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

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

개발 플로우(Development Flow)에 통합한다. 이 루프는 단독으로도 호출할 수 있지만, 제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의 정밀도를 더욱 높이는 Tips (canly)

• Loop Engineering 입문 (suwash)

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