피그마 디자인을 페이지빌더 위젯으로 바로 가져오는 파이프라인 구축

피그마 디자인을 페이지빌더에서 그냥 쓸 수 있게 만드는 파이프라인을 이번 스프린트에 한 번에 밀어 넣었다.

왜 이게 필요했나

디자이너가 피그마에서 작업을 마치면, 그 결과물이 실제 페이지에 반영되기까지 개발자 손을 반드시 거쳐야 했다. 디자이너 → 개발자 → 퍼블리셔 → 운영자 순으로 이어지는 이 흐름이 병목이었고, 특히 이벤트 페이지나 콘텐츠 블록처럼 자주 바뀌는 영역에서는 매번 티켓을 열고 PR을 올리는 게 현실적으로 너무 느렸다.

팀에서 "피그마 산출물을 바로 페이지빌더 위젯으로 import할 수 있으면 어떨까"라는 아이디어가 나왔을 때, 내가 직접 파이프라인 설계를 맡겠다고 했다. 기술적으로 풀어야 할 문제가 세 덩어리로 나뉘었다.

1. 피그마에서 뽑아낸 HTML이 항상 깨끗하지 않다 → 정제(cleaning) 레이어 필요
2. 색상·폰트·간격 같은 디자인 토큰이 하드코딩으로 박혀 있다 → 토큰 엔진 필요
3. import한 위젯을 인스턴스별로 자유롭게 편집할 수 있어야 한다 → 위젯 인스턴스 분리 모델 필요

이 세 가지를 한 흐름으로 연결하는 게 이번 작업의 핵심이었음.

파일별로 뭘 했나

HtmlCleaner와 WidgetTokenEngine이 유틸 레이어로 분리된 건 의도적인 설계다. 컨트롤러에 로직을 때려 넣으면 단기적으론 빠르지만, 토큰 규칙이 바뀔 때마다 컨트롤러를 건드려야 하고 테스트도 짜기 어려워진다. 팀원들한테도 "이 두 클래스는 순수 유틸이니까, 컨트롤러 맥락 없이 단독 테스트 먼저 짜라"고 얘기해뒀다.

HtmlCleaner — 피그마 HTML은 생각보다 지저분하다

피그마에서 Export하거나 플러그인으로 뽑은 HTML에는 다음 같은 게 섞여 들어온다.

// 제거 대상 패턴 예시 (실제 구현 아님, 개념 설명용)
// 1. 피그마 내부 data-* 어트리뷰트
// 2. width/height 픽셀 인라인 스타일 (반응형 깨짐)
// 3. position: absolute 남발 (레이아웃 흐름 무시)
// 4. 빈 span / 중첩 div 레이어

이걸 그냥 위젯으로 집어넣으면 페이지빌더의 그리드 시스템과 충돌하고, 모바일에서 레이아웃이 터진다. HtmlCleaner는 이 정제 규칙을 한 곳에 모아두는 역할이다. 규칙이 추가될 때 이 클래스만 열면 되는 구조.

WidgetTokenEngine — 하드코딩을 토큰으로 되돌리기

피그마에서 #3B82F6이나 font-size: 14px처럼 박혀 나오는 값들을 시스템 디자인 토큰(--color-primary, --font-size-sm)으로 역매핑하는 게 토큰 엔진의 일이다.

// 개념적 흐름
rawHtml
  → HtmlCleaner.clean(rawHtml)         // 피그마 메타 제거
  → WidgetTokenEngine.tokenize(cleaned) // 값 → 토큰 치환
  → widgetRepository.save(tokenized)   // 위젯으로 저장

이 흐름이 파이프라인의 전체 뼈대다. 토큰 매핑 테이블을 외부 설정으로 뺄 수 있게 설계해뒀기 때문에, 디자인 시스템이 바뀌어도 엔진 코드를 건드리지 않고 매핑만 업데이트하면 된다.

인스턴스 자유 편집 — 왜 이게 어려운 문제인가

위젯을 import하면 여러 페이지에서 같은 위젯을 끌어다 쓸 수 있다. 그런데 페이지마다 텍스트나 이미지를 조금씩 다르게 쓰고 싶은 경우가 생긴다. 이때 "원본 위젯 정의"와 "인스턴스별 오버라이드"를 분리하지 않으면, 한 페이지에서 편집한 게 다른 페이지에도 반영되는 문제가 발생한다.

이번에 인스턴스 편집 API를 추가하면서 오버라이드 값을 인스턴스 단위로 따로 저장하는 구조를 잡았다. 원본 위젯 정의는 건드리지 않고, 인스턴스가 자기 오버라이드 레이어를 갖는 방식. 이 개념은 피그마의 컴포넌트-인스턴스 모델에서 그대로 차용했다.

SiteControllerAdvice에 예외 케이스를 추가한 것도 이 흐름에서 나왔다. HTML 파싱 실패, 토큰 매핑 누락, 인스턴스 오버라이드 충돌 같은 상황을 전역 어드바이스에서 일관되게 처리하지 않으면, 컨트롤러마다 try-catch가 난무하게 된다. 팀 코드리뷰에서 "예외는 어드바이스에서 한 번에"를 원칙으로 잡고 있어서 여기도 동일하게 적용했음.

이 파이프라인이 안정화되면 디자이너가 피그마 작업을 마치고 운영자가 직접 페이지빌더에 올릴 수 있는 흐름이 가능해진다. 개발자 의존도를 줄이는 게 목표였고, 일단 뼈대는 올라갔다. 토큰 매핑 정확도와 HtmlCleaner 규칙 커버리지는 실제 사용 데이터가 쌓이면서 계속 다듬어야 할 부분으로 남겨뒀다.

끝.