Figma Web UI 개발 규범 (Framelink MCP 버전)
Figma 디자인 시안으로 Web 프론트엔드 UI를 개발할 때 발생하는 구현 품질 저하 문제를 해결합니다. 근본 원인은 Figma의 '캔버스 데이터'(절대 좌표, 인라인 색상 값, 픽셀 레이어 쌓기)를 '구현 데이터'로 간주하여 그대로 복사하면 반응형이 깨지고, 색상과 글꼴이 부정확하며, 리소스가 누락되기 때문입니다.
본 skill은 **Framelink figma-developer-mcp**의 두 가지 도구를 대상으로 합니다:
| 도구 | 채널 | 역할 |
|---|---|---|
get_figma_data | 정확 채널 | fileKey + nodeId로 캔버스 데이터(레이아웃, 콘텐츠, 시각, 컴포넌트 정보)를 가져옴 |
download_figma_images | 시각 채널 | 노드 ID로 SVG/PNG/GIF를 로컬 디렉토리로 내보냄 |
참고: 이는 Framelink 버전이며, 공식 Figma MCP Server(공식 도구는
get_design_context/get_variable_defs/download_assets)가 아닙니다. 본 skill의 방법론은 두 버전에 공통적으로 적용되지만, 도구 이름은 Framelink 기준으로 작성되었습니다.대상이 데스크톱(Qt Widget / QML / WinUI / Flutter)이라면
figma-ui-desktop을 사용하고 본 skill을 사용하지 마세요.
핵심 원칙
- 듀얼 채널 병행, 단일 채널 코드 작성 금지. 정확 채널은 정확한 값을 제공하고, 시각 채널은 전체 레이아웃과 텍스트를 제공합니다. 하나만 사용하면 반드시 구현 왜곡이 발생합니다. 특히 시각 채널만 사용(스크린샷을 보고 추측하는 것과 같음)하거나 데이터 채널만 사용(맹목적으로 작성하는 것과 같음)하는 경우가 그렇습니다.
- 정확한 값을 사용하고, 시각적 추정을 하지 않습니다. 색상, 글자 크기, 줄 높이, 글자 굵기, 간격, 모서리 둥글기, 테두리, 그림자는 모두 디자인 시안의 정확한 값을 가져옵니다.
- 먼저 디자인 시안을 요청하고, 스스로 UI를 작성하지 않습니다.
- 구현 후 반드시 검증 루프 실행: 스크린샷을 디자인 시안과 비교 → 결함 발견 시 자동 수정 → 수동 검수 후 반복 개선. 한 번에 100% 완벽을 기대하는 마법은 없습니다. 70~80%는 프로세스로, 나머지는 검증 루프로 채웁니다.
작업 흐름
단계 1: 대략적 읽기 (요구 사항 및 구조 이해)
디자인 시안이 너무 클 경우 먼저 대략적으로 읽어 한 번에 전체 데이터를 가져와 컨텍스트가 과부하되는 것을 방지합니다:
get_figma_data를 사용하여 최상위 구조를 가져옵니다(depth로 탐색 깊이를 제어하며, 얕은 수준부터 시작). 어떤 페이지/블록/컴포넌트가 있는지 파악합니다.download_figma_images를 사용하여 전체 페이지 이미지를 내보내 레이아웃과 텍스트를 이해합니다.
단계 2: 정밀 읽기 (구현 전 정확한 데이터 확보)
구현하려는 특정 컴포넌트/블록에 대해 동시에 호출합니다:
get_figma_data(nodeId포함, 노드별로 좌표, 색상 값, 글자 크기, 간격, 모서리 둥글기, 테두리 읽기)download_figma_images(해당 블록 이미지를 내보내 컴포넌트 간 상대적 위치 관계 확인)
데이터를 확보한 후 구조 분석을 먼저 수행하고 코드를 작성합니다:
- 어떤 노드가 반복 패턴(카드, 목록 항목, 버튼)인지 → 컴포넌트로 추출
- 어떤 절대 위치가 사실상 레이아웃(가로 정렬, 중앙 정렬, 양쪽 정렬)인지 → flex/grid로 변환
- 어떤 것이 의미적 역할(네비게이션/폼/목록)인지 → 대상 프레임워크의 기존 컴포넌트 라이브러리 매핑
- 이미지/아이콘 노드 →
download_figma_images로 원본 파일을 다운로드하여 assets에 배치, 직접 그리지 않음
단계 3: 구현
- 색상/글자 크기/간격은 디자인 시안의 정확한 값을 사용하고, '비슷해 보인다'는 태도를 취하지 않음
- 프로젝트의 기존 컴포넌트 라이브러리를 우선 사용하고, 먼저 컴포넌트 props(theme/size/variant)를 확인하여 스타일 중복 정의를 방지함
- 아이콘은 프로젝트 아이콘 라이브러리를 사용하고, 타사 아이콘을 사용하지 않음
- 스타일 파일 이름, CSS 클래스 이름 규칙, 중첩 깊이는 프로젝트 규칙을 따름
단계 4: 검증 루프
Playwright MCP를 사용하여 로컬 페이지 스크린샷을 열고, 디자인 시안 스크린샷과 나란히 비교합니다. 명백한 결함은 자동으로 수정합니다. 수동 검수: 사람이 더 세밀한 문제(간격, 글자 굵기, 색상 미세 차이)를 식별하고, 적극적으로 AI에 전달하여 정밀하게 수정한 후 다음 반복으로 넘어갑니다.
게으름 방지 철칙
AI는 한 가지 채널만 사용하여 코드를 작성하는 경향이 있으므로, 명확히 요청해야 합니다:
- 「
get_figma_data와download_figma_images를 동시에 호출하여 디자인 시안을 읽으세요」 - 「이미지/스크린샷만으로 디자인 시안을 읽고 코드를 작성하는 것은 허용되지 않습니다」
- 「
get_figma_data의 정확한 값을 한 줄씩 읽고, 색상/글자 크기/간격을 비교하며, 시각적 추정을 하지 마세요」
컴포넌트 규칙 (프로젝트에 따라 교체)
다음은 템플릿이며, 실제 프로젝트에 적용할 때는 해당 프로젝트의 규칙으로 교체하세요:
- 프로젝트 컴포넌트 라이브러리(예:
@notta/components)를 우선 사용하고, 의문이 있으면 적극적으로 사용자에게 문의 - 먼저 컴포넌트 라이브러리 props를 확인하여 스타일 중복 정의를 방지
- 아이콘은 프로젝트 아이콘 라이브러리 사용
- 스타일 파일 이름, CSS 클래스 이름 규칙, 중첩 레벨은 프로젝트 규칙을 따름
구현 일치도 자체 점검 목록
생성 후 항목별로 확인합니다('전체적으로 비슷한가'보다 신뢰할 수 있음):
- 색상 (근사치가 아닌 정확한 hex를 사용했는지)
- 글자 크기 / 줄 높이 / 글자 굵기
- 간격 / 여백 / 내부 여백
- 모서리 둥글기 / 테두리 / 그림자
- 레이아웃 (flex/grid가 디자인 시안 배열과 동등한지)
- z-index / 계층
- 아이콘/이미지가 원본 파일을 사용했는지, 직접 그리지 않았는지
참고 출처
방법론은 공식 Figma MCP + Playwright의 UI 개발 프로세스('Figma MCP와 Playwright MCP를 사용한 UI 개발 및 디버깅 효율성 향상' 참조)에서 차용했습니다. 핵심 개념은 '듀얼 채널 + 검증 루프 + 게으름 방지를 위한 명확한 요청'이며, 도구 이름은 Framelink figma-developer-mcp에 맞게 조정되었습니다.