Figma 도면을 서비스 데이터로 연결하기
도면 관리 개선기 · 2 / 3목차
이전 글에서는 도면 요소의 좌표를 하나씩 옮겨 적던 작업을 줄이기 위해 기존 플러그인과 정제 스크립트를 시험한 과정을 정리했습니다. 그 결과를 바탕으로 팀에서 직접 관리하는 Figma 플러그인을 만들기 시작했습니다.
첫 번째 목표는 선택한 도면에서 필요한 정보를 추출하고 JSON으로 복사하는 것이었습니다. 하지만 도면을 화면에 정확히 렌더링하려면 데이터 추출만으로는 부족했습니다. 제작할 때부터 어떤 레이어가 공간이고 기기인지 구분할 수 있어야 했고, 중첩된 레이어의 좌표도 하나의 도면을 기준으로 변환해야 했습니다.
이번 글에서는 플러그인의 실행 구조를 시작으로 도면 제작 규칙, 좌표 변환, 서버 반영까지 연결한 과정을 정리합니다.
먼저 데이터를 추출하고 복사할 수 있게 만들기
처음 구현한 사용 흐름은 단순했습니다.
- 사용자가 Figma에서 도면을 선택합니다.
- 플러그인의 추출 버튼을 누릅니다.
- 선택한 도면에서 필요한 정보를 가져옵니다.
- 정리된 JSON을 화면에서 확인하고 복사합니다.
사용자에게 버튼과 결과를 보여주는 화면은 iframe에서 실행됩니다. 반면 Figma 문서의 레이어에 접근하는 코드는 별도의 샌드박스 환경에서 Figma Plugin API를 사용합니다. Figma 공식 문서에서도 iframe은 브라우저 API에 접근하고, 메인 스레드의 샌드박스는 Figma의 레이어 구조에 접근하는 형태로 두 환경을 설명합니다.
따라서 UI에서 버튼을 눌렀다고 바로 선택된 레이어의 속성을 읽을 수 있는 것은 아닙니다. 두 실행 환경은 메시지를 주고받으며 동작합니다.
데이터 추출은 다음 순서로 이어집니다.
- 사용자가 UI에서 추출을 요청합니다.
- UI가 샌드박스에서 실행되는 코드에 메시지를 보냅니다.
- 샌드박스가 현재 선택된 도면과 하위 레이어에 접근합니다.
- 필요한 값을 JSON으로 정리해 UI로 돌려보냅니다.
이 구조를 만든 뒤에는 어떤 레이어를 가져올지 정해야 했습니다.
필요한 요소만 찾기 위해 디자인 규칙 정하기
Figma에서 작업한 도면에는 여러 종류의 레이어가 들어갑니다. 배경을 그리는 도형, 공간을 나타내는 영역, 기기 아이콘, 이름을 표시하는 텍스트가 하나의 프레임 안에 섞여 있습니다.
플러그인이 여기에서 공간과 기기만 찾으려면 구분할 기준이 필요합니다. 공간을 나타내는 도형과 이름 텍스트를 하나의 데이터로 묶어야 하고, 기기 아이콘이 서비스의 어떤 기기를 가리키는지도 알아야 합니다.
그래서 디자인팀과 다음 항목을 중심으로 제작 규칙을 정했습니다.
- 공간과 기기를 표현하는 레이어의 이름 형식
- 공간 도형과 이름 텍스트를 묶는 방법
- 서비스 데이터와 연결할 식별 정보를 두는 위치
- 추출 과정에서 유지해야 하는 레이어 구조
이 규칙은 플러그인이 데이터를 찾는 기준이면서 디자인팀이 도면을 제작할 때 지켜야 하는 기준이 되었습니다.
규칙을 문서로 전달하는 데서 한 단계 더 나아가, 규칙에 맞는 요소를 플러그인이 직접 만들어주도록 기능을 확장했습니다.
규칙에 맞는 공간과 기기 요소 생성하기
플러그인에 도면 작업 대상을 입력하면 서비스에 등록된 공간과 기기의 목록을 불러옵니다. 이어서 목록을 바탕으로 디자인 작업에 사용할 기본 요소를 생성합니다.
공간 요소에는 공간을 나타내는 도형과 이름이 들어갑니다. 기기 요소에는 아이콘과 이름이 들어갑니다. 서비스 데이터와 연결하는 데 필요한 식별 정보와 레이어 구조도 정해진 규칙에 맞춰 플러그인이 준비합니다.
디자인팀은 이렇게 생성된 요소를 가져와 실제 공간 구조에 맞게 모양과 크기를 조정하고, 기기를 알맞은 위치에 배치합니다. 도면의 시각적인 표현은 디자인팀이 결정하고, 데이터 추출에 필요한 기본 구성은 플러그인이 준비하는 방식입니다.
이렇게 제작 단계와 추출 단계가 같은 규칙을 사용하게 됐습니다. 디자인팀이 서비스에 등록된 공간과 기기를 바탕으로 작업할 수 있었고, 플러그인은 완성된 도면에서 필요한 레이어를 같은 기준으로 찾을 수 있었습니다.
레이어 이름이나 구조를 임의로 바꾸면 추출 결과에 영향을 줄 수 있다는 제약은 남았습니다. 그래서 플러그인이 요소를 생성하는 것과 함께, 도면을 수정할 때 지켜야 할 규칙도 팀 안에서 공유했습니다.
중첩된 레이어의 좌표를 도면 기준으로 맞추기
데이터 추출 과정에서 까다로웠던 문제 중 하나는 좌표의 기준이었습니다.
Figma 도면은 프레임과 그룹을 여러 겹 중첩해 구성할 수 있습니다. 이때 요소의 x, y는 해당 요소를 감싸는 부모를 기준으로 합니다. 이 값을 그대로 서비스의 도면 좌표로 사용하면 실제와 다른 위치에 그려질 수 있습니다.
회전과 크기 변환이 없는 간단한 예를 들어보겠습니다. 도면 안의 그룹이 (100, 80)에 있고, 그룹 안의 도형이 (20, 10)에 있다면 도면 기준에서 도형의 위치는 (120, 90)입니다. 도형의 값 (20, 10)만 가져오면 부모 그룹의 위치가 빠집니다.
이를 해결하기 위해 absoluteBoundingBox의 값을 사용했습니다. 이 속성의 x, y는 Figma 페이지를 기준으로 한 위치를 나타냅니다. 추출할 요소와 도면 배경의 좌표를 같은 기준으로 가져온 뒤 두 값을 빼면, 도면 배경을 기준으로 한 상대 위치를 구할 수 있습니다.
const relativePosition = {
x: targetX - referenceX,
y: targetY - referenceY,
};
여기서 targetX, targetY는 추출할 요소의 페이지 기준 좌표이고, referenceX, referenceY는 도면 배경의 페이지 기준 좌표입니다.
이 계산은 좌표 기준을 맞추는 핵심만 단순화한 것입니다. 실제 추출에서는 도면 안에서 배경이 놓인 위치, 요소의 종류, 선의 두께와 정렬 방식도 함께 고려했습니다. absoluteBoundingBox는 선과 그림자 같은 렌더링 속성을 포함하지 않으므로, 화면에 같은 모습으로 표시하려면 필요한 보정을 별도로 적용해야 했습니다.
제작한 도면을 서버에 반영하기
도면 제작과 추출을 연결한 뒤에는 결과를 서버로 보내는 기능을 추가했습니다. 플러그인은 추출한 JSON을 확인하고 복사하는 기능과 함께, 도면을 등록하거나 수정하는 요청도 처리합니다.
이전에는 프론트엔드가 값을 정리해 전달하고 백엔드가 다시 수기로 반영했습니다. 개선 후에는 플러그인이 정해진 규칙으로 필요한 데이터를 추출하고 기존의 API를 통해 전달합니다. 백엔드에서 도면마다 전달받은 값을 다시 입력하던 단계가 줄었습니다.
전체 흐름은 다음과 같이 바뀌었습니다.
디자인 요소 생성 → 디자인팀의 도면 제작 → 같은 규칙으로 데이터 추출 → 서버에 등록 → 서비스 화면에서 렌더링
처음에는 좌표를 옮겨 적는 작업을 줄이는 데서 출발했습니다. 그 결과를 실제 서비스에서 사용하려고 하니 디자인 규칙과 서버 반영까지 연결해야 했습니다. 한 사람의 반복 작업을 줄이는 도구가 팀의 제작 흐름을 이어주는 도구로 확장된 셈입니다.
자동화 이후에 보이기 시작한 문제
도면을 제작해 처음 등록하는 과정은 간단해졌습니다. 하지만 운영을 이어가면서 새로운 문제가 보였습니다.
도면 요소를 만들 때 연결한 공간과 기기의 식별 정보가 시간이 지나 실제 데이터와 맞지 않는 경우가 생겼습니다. 플러그인으로 다시 추출하는 일은 쉬워졌지만, 그 전에 누군가는 변경 요청을 받아 Figma 도면의 정보를 고쳐야 했습니다.
등록 과정을 자동화해도 운영팀이 알고 있는 변경을 개발팀에 전달하는 흐름은 남아 있었습니다. 다음 글에서는 도면의 형태와 연결 정보를 분리하고, 운영팀이 백오피스에서 공간과 기기의 연결을 직접 관리하도록 바꾼 과정을 정리하겠습니다.