Figma 데스크톱 UI 개발 규범 (Framelink MCP 버전)
Figma 디자인 시안으로 데스크톱 UI를 개발할 때 재현도가 낮은 문제를 해결합니다. 근본 원인은 Figma의 '캔버스 데이터'(절대 좌표, 인라인 색상 값, 픽셀 레이어 쌓기)를 '구현 데이터'로 간주하고 그대로 복사하여 레이아웃이 경직되고, 색상/글꼴이 정확하지 않으며, 리소스가 누락되기 때문입니다.
왜 데스크톱에서는 공식 Figma MCP 서버 대신 Framelink를 사용하나요? 공식 MCP의 핵심 도구인
get_design_context는 기본적으로 웹 코드(React/Tailwind, Vue/HTML/iOS로 전환 가능)만 생성하며, Qt Widget / QML / WinUI / Flutter를 지원하지 않고 유료입니다. Framelink는 '프레임워크 독립적인 Figma 데이터만 제공하고 번역은 모델에게 맡긴다'는 입장입니다. 이러한 '단점'은 여러 데스크톱 프레임워크 시나리오에서 오히려 장점이 됩니다. 모델이 캔버스 데이터를 가져와서 어떤 대상 프레임워크로든 번역할 수 있기 때문입니다.
본 스킬은 Framelink figma-developer-mcp 의 두 가지 도구를 대상으로 합니다:
| 도구 | 채널 | 역할 |
|---|---|---|
get_figma_data | 정밀 채널 | fileKey + nodeId로 캔버스 데이터(레이아웃, 콘텐츠, 시각적 요소, 컴포넌트 정보)를 가져옴 |
download_figma_images | 시각 채널 | 노드 ID를 기반으로 SVG/PNG/GIF를 로컬 디렉토리로 내보냄 |
대상이 웹 프론트엔드(React/Vue/HTML)인 경우
figma-ui-web스킬을 사용하세요.
핵심 원칙
- 이중 채널 병행, 단일 채널 코딩 금지. 정밀 채널은 정확한 수치를 제공하고, 시각 채널은 전체 레이아웃과 텍스트를 제공합니다. 하나만 사용하면 반드시 재현이 왜곡됩니다.
- 정확한 값을 사용하고, 시각적 추정을 하지 않습니다. 색상, 글꼴 크기, 글꼴 두께, 간격, 둥근 모서리, 테두리, 그림자는 모두 디자인 시안의 정확한 값을 가져옵니다.
- 먼저 디자인 시안을 요청하고, 스스로 UI를 작성하지 않습니다.
- 구현 후 반드시 검증을 완료합니다: 실제 실행 프로그램 스크린샷과 디자인 시안 비교 → 결함 발견 시 자동 수정 → 사람이 직접 꼼꼼히 검토하여 반복 개선.
워크플로우
1단계: 개요 분석 (요구사항 및 구조 이해)
디자인 시안이 너무 클 경우 먼저 개요를 분석하여 한 번에 전체 데이터를 가져와 컨텍스트가 과부하되는 것을 방지합니다:
get_figma_data를 사용하여 최상위 구조를 가져옵니다(depth로 탐색 깊이 제어, 얕은 레벨부터 시작). 어떤 페이지/영역/컨트롤이 있는지 파악합니다.download_figma_images를 사용하여 전체 인터페이스 이미지를 내보내 레이아웃과 텍스트를 이해합니다.
2단계: 정밀 분석 (구현 전 정확한 데이터 확보)
구현할 특정 영역/컨트롤에 대해 동시에 다음을 호출합니다:
get_figma_data(nodeId포함, 노드별 좌표, 색상 값, 글꼴 크기, 간격, 둥근 모서리, 테두리 읽기)download_figma_images(해당 영역 이미지 내보내기, 컨트롤 간 상대적 위치 관계 확인)
데이터를 확보한 후 먼저 구조 분석을 수행한 다음 코드를 작성합니다:
- 어떤 노드가 반복 패턴(목록 항목, 카드, 버튼)인가? → 대상 프레임워크의 사용자 정의 컨트롤/컴포넌트로 추출
- 어떤 절대 위치가 실제로는 레이아웃(가로 배열, 중앙 정렬, 양쪽 정렬, 그리드)인가? → 아래 매핑 테이블에 따라 해당 프레임워크의 레이아웃으로 변환
- 어떤 것이 의미론적 역할(네비게이션/폼/목록)인가? → 대상 프레임워크의 기존 컨트롤 라이브러리로 매핑
- 이미지/아이콘 노드 →
download_figma_images로 원본 파일을 다운로드하여 리소스 디렉토리에 저장하고, 직접 그리지 않음
3단계: 구현 (프레임워크 독립적 번역)
색상/글꼴 크기/간격은 디자인 시안의 정확한 값을 사용합니다. 번역 시 아래 '캔버스 개념 → 대상 프레임워크' 매핑 테이블을 참조하고, 컨트롤을 임의로 만들어내지 마십시오 — 대상 프레임워크에 표준 레이아웃/컨트롤이 있으면 그것을 사용하고, 절대 좌표는 '정말로 정확한 픽셀 위치 지정이 필요한 경우'에만 유지합니다.
4단계: 검증 완료
데스크톱에는 Playwright와 같은 브라우저 자동화 도구가 없으므로, 검증 방법은 다음과 같습니다: 실제 컴파일 및 실행 프로그램 스크린샷을 디자인 시안 스크린샷과 나란히 비교하여 명백한 결함을 발견하면 자동으로 수정합니다. 사람이 직접 더 세밀한 문제(간격, 글꼴 두께, 색상 미세 차이)를 식별하여 AI에게 정확한 수정을 요청하고 다음 반복으로 넘어갑니다.
캔버스 개념 → 대상 프레임워크 매핑 테이블
Figma 캔버스는 절대 좌표 + 픽셀 레이어로 구성되어 있으며, 구현 시 각 프레임워크의 레이아웃 의미로 번역해야 합니다. 번역 시 이 테이블을 참조하세요:
| 캔버스/디자인 개념 | Qt Widget | QML (Qt Quick) | WinUI 3 (XAML) | Flutter |
|---|---|---|---|---|
| 가로 배열 | QHBoxLayout | Row | StackPanel (Orientation=Horizontal) | Row |
| 세로 배열 | QVBoxLayout | Column | StackPanel (Orientation=Vertical) | Column |
| 그리드 레이아웃 | QGridLayout | Grid / GridLayout | Grid | GridView / Table |
| 절대 위치 지정 | setGeometry / move | Item + x/y | Canvas + Canvas.Left/Top | Stack + Positioned |
| 겹침/오버레이 | 자식 위젯 겹침 / raise() | z 속성 / Stack | Canvas.ZIndex | Stack |
| 중앙 정렬 | addStretch / setAlignment | anchors.centerIn | HorizontalAlignment/VerticalAlignment=Center | Center / Align |
| 양쪽 정렬 | 양쪽 addStretch | anchors.left/right + margins | 여백 할당 | MainAxisAlignment.spaceBetween |
| 간격 | QSpacerItem / layout spacing | spacing 속성 | Margin / Padding | SizedBox / Padding / Spacer |
| 색상 | QPalette / stylesheet | Theme / 속성 바인딩 | 리소스 사전 ResourceDictionary | ThemeData / ColorScheme |
| 글꼴 크기/글꼴 | QFont | font.pixelSize | FontSize | TextStyle.fontSize |
| 둥근 모서리 | stylesheet border-radius | Rectangle radius | CornerRadius | BorderRadius |
| 그림자 | QGraphicsDropShadowEffect | DropShadow | ThemeShadow / DropShadow | BoxShadow |
| 아이콘 | QIcon / 리소스 | Image / 아이콘 폰트 | FontIcon / SymbolIcon | Icon |
| 컴포넌트 재사용 | 사용자 정의 QWidget 서브클래스 | 사용자 정의 QML Component | UserControl / 사용자 정의 컨트롤 | Widget |
| 상태/변형 | 열거형 + update() | State / 속성 기반 | VisualStateManager | setState / AnimatedWidget |
게으름 방지 철칙
AI는 한 가지 채널만 사용하여 코드를 작성하려는 경향이 있으므로, 명확하게 요구해야 합니다:
- "
get_figma_data와download_figma_images를 동시에 호출하여 디자인 시안을 읽으세요" - "이미지/스크린샷만으로 디자인 시안을 읽고 코드를 작성하는 것은 허용되지 않습니다"
- "
get_figma_data의 정확한 값을 한 줄씩 읽고, 색상/글꼴 크기/간격을 비교하며 시각적 추정을 하지 마세요" - "매핑 테이블에 따라 대상 프레임워크의 표준 레이아웃/컨트롤로 번역하고, 임의로 만들어내지 마세요"
재현도 자체 점검 목록
생성 후 항목별로 확인합니다('전체적으로 비슷한지'보다 신뢰할 수 있음):
- 색상 (근사치가 아닌 정확한 값을 사용했는가?)
- 글꼴 크기 / 글꼴 두께
- 간격 / 여백 / 안쪽 여백
- 둥근 모서리 / 테두리 / 그림자
- 레이아웃 (절대 좌표를 그대로 복사하지 않고 대상 프레임워크의 표준 레이아웃으로 번역했는가?)
- 계층 / 겹침 순서
- 아이콘/이미지가 직접 그린 것이 아닌 원본 파일을 사용했는가?
- 반복 패턴이 컴포넌트/사용자 정의 컨트롤로 추출되었는가?
참고 출처
방법론은 공식 Figma MCP + Playwright의 UI 개발 프로세스('Figma MCP 및 Playwright MCP를 사용한 UI 개발 및 디버깅 효율성 향상' 참조)에서 차용했습니다. 핵심 아이디어인 '이중 채널 + 검증 완료 + 게으름 방지를 위한 명확한 요구사항'은 유지하고, 도구 이름은 Framelink figma-developer-mcp에 맞게 조정했으며, 매핑 테이블은 데스크톱 다중 프레임워크를 지원하도록 확장했습니다.