디자인 구현하기
개요
이 스킬은 Figma 디자인을 픽셀 단위로 정확하게 프로덕션 준비가 완료된 코드로 변환하는 구조화된 워크플로우를 제공합니다. Figma MCP 서버와의 일관된 통합, 디자인 토큰의 적절한 사용, 그리고 디자인과 1:1 시각적 일치를 보장합니다.
스킬 경계
- 사용자의 저장소에 코드를 제공해야 하는 경우 이 스킬을 사용하세요.
- 사용자가 Figma 내부에서 노드를 생성/편집/삭제하도록 요청한 경우, figma-use로 전환하세요.
- 사용자가 코드나 설명으로부터 Figma에서 전체 페이지 화면을 빌드하거나 업데이트하도록 요청한 경우, figma-generate-design로 전환하세요.
- 사용자가 Code Connect 매핑만 요청한 경우, figma-code-connect-components로 전환하세요.
- 사용자가 재사용 가능한 에이전트 규칙(
CLAUDE.md/AGENTS.md)을 작성하도록 요청한 경우, figma-create-design-system-rules로 전환하세요.
전제 조건
- Figma MCP 서버가 연결되어 있고 접근 가능해야 함
- 사용자는
https://figma.com/design/:fileKey/:fileName?node-id=1-2형식의 Figma URL을 제공해야 함:fileKey는 파일 키1-2는 노드 ID (구현할 특정 컴포넌트 또는 프레임)
- 또는
figma-desktopMCP 사용 시: 사용자가 Figma 데스크톱 앱에서 직접 노드를 선택할 수 있음 (URL 불필요) - 프로젝트에 확립된 디자인 시스템 또는 컴포넌트 라이브러리가 있는 것이 좋음
필수 워크플로우
다음 단계를 순서대로 따르세요. 단계를 건너뛰지 마십시오.
1단계: 노드 ID 가져오기
옵션 A: Figma URL에서 파싱
사용자가 Figma URL을 제공하면, 파일 키와 노드 ID를 추출하여 MCP 도구에 인수로 전달합니다.
URL 형식: https://figma.com/design/:fileKey/:fileName?node-id=1-2
추출:
- 파일 키:
:fileKey(/design/다음 세그먼트) - 노드 ID:
1-2(node-id쿼리 파라미터 값)
참고: 로컬 데스크톱 MCP(figma-desktop)를 사용할 때는 도구 호출에 fileKey를 파라미터로 전달하지 않습니다. 서버가 자동으로 현재 열려 있는 파일을 사용하므로 nodeId만 필요합니다.
예시:
- URL:
https://figma.com/design/kL9xQn2VwM8pYrTb4ZcHjF/DesignSystem?node-id=42-15 - 파일 키:
kL9xQn2VwM8pYrTb4ZcHjF - 노드 ID:
42-15
옵션 B: Figma 데스크톱 앱의 현재 선택 항목 사용 (figma-desktop MCP 전용)
figma-desktop MCP를 사용하고 사용자가 URL을 제공하지 않은 경우, 도구는 데스크톱 앱에서 열린 Figma 파일의 현재 선택된 노드를 자동으로 사용합니다.
참고: 선택 기반 프롬프트는 figma-desktop MCP 서버에서만 작동합니다. 원격 서버는 컨텍스트를 추출하기 위해 프레임 또는 레이어에 대한 링크가 필요합니다. 사용자는 Figma 데스크톱 앱이 열려 있고 노드가 선택되어 있어야 합니다.
2단계: 디자인 컨텍스트 가져오기
추출된 파일 키와 노드 ID로 get_design_context를 실행합니다.
get_design_context(fileKey=":fileKey", nodeId="1-2")
이것은 다음을 포함한 구조화된 데이터를 제공합니다:
- 레이아웃 속성 (Auto Layout, 제약 조건, 크기 조정)
- 타이포그래피 사양
- 색상 값 및 디자인 토큰
- 컴포넌트 구조 및 변형
- 간격 및 패딩 값
응답이 너무 크거나 잘린 경우:
get_metadata(fileKey=":fileKey", nodeId="1-2")를 실행하여 상위 수준 노드 맵을 가져옵니다.- 메타데이터에서 필요한 특정 자식 노드를 식별합니다.
get_design_context(fileKey=":fileKey", nodeId=":childNodeId")로 개별 자식 노드를 가져옵니다.
3단계: 시각적 참조 캡처
시각적 참조를 위해 동일한 파일 키와 노드 ID로 get_screenshot을 실행합니다.
get_screenshot(fileKey=":fileKey", nodeId="1-2")
이 스크린샷은 시각적 검증의 기준이 됩니다. 구현 내내 접근 가능하도록 유지하세요.
4단계: 필요한 자산 다운로드
Figma MCP 서버가 반환한 모든 자산(이미지, 아이콘, SVG)을 다운로드합니다.
중요: 다음 자산 규칙을 따르세요:
- Figma MCP 서버가 이미지 또는 SVG에 대해
localhost소스를 반환하는 경우, 해당 소스를 직접 사용하세요. - 새로운 아이콘 패키지를 가져오거나 추가하지 마세요. 모든 자산은 Figma 페이로드에서 제공되어야 합니다.
localhost소스가 제공된 경우 플레이스홀더를 사용하거나 생성하지 마세요.- 자산은 Figma MCP 서버의 내장 자산 엔드포인트를 통해 제공됩니다.
5단계: 프로젝트 규칙으로 변환
Figma 출력을 이 프로젝트의 프레임워크, 스타일 및 규칙으로 변환합니다.
핵심 원칙:
- Figma MCP 출력(일반적으로 React + Tailwind)을 디자인과 동작의 표현으로 취급하고, 최종 코드 스타일로 취급하지 마세요.
- Tailwind 유틸리티 클래스를 프로젝트가 선호하는 유틸리티 또는 디자인 시스템 토큰으로 대체하세요.
- 기능을 복제하는 대신 기존 컴포넌트(버튼, 입력, 타이포그래피, 아이콘 래퍼)를 재사용하세요.
- 프로젝트의 색상 시스템, 타이포그래피 규모 및 간격 토큰을 일관되게 사용하세요.
- 기존 라우팅, 상태 관리 및 데이터 가져오기 패턴을 존중하세요.
6단계: 1:1 시각적 일치 달성
Figma 디자인과 픽셀 단위로 완벽한 시각적 일치를 위해 노력하세요.
지침:
- 디자인을 정확하게 일치시키기 위해 Figma 충실도를 우선시하세요.
- 하드코딩된 값을 피하고 가능한 경우 Figma의 디자인 토큰을 사용하세요.
- 디자인 시스템 토큰과 Figma 사양 사이에 충돌이 발생하면 디자인 시스템 토큰을 선호하되, 시각적 일치를 위해 간격이나 크기를 최소한으로 조정하세요.
- 접근성을 위한 WCAG 요구 사항을 따르세요.
- 필요에 따라 컴포넌트 문서를 추가하세요.
7단계: Figma에 대해 검증
완료로 표시하기 전에 최종 UI를 Figma 스크린샷과 대조하여 검증하세요.
검증 체크리스트:
- 레이아웃 일치 (간격, 정렬, 크기)
- 타이포그래피 일치 (글꼴, 크기, 두께, 줄 높이)
- 색상이 정확히 일치
- 상호작용 상태가 설계대로 작동 (호버, 활성, 비활성)
- 반응형 동작이 Figma 제약 조건을 따름
- 자산이 올바르게 렌더링됨
- 접근성 표준 충족
구현 규칙
컴포넌트 구성
- UI 컴포넌트를 프로젝트의 지정된 디자인 시스템 디렉토리에 배치하세요.
- 프로젝트의 컴포넌트 명명 규칙을 따르세요.
- 동적 값에 꼭 필요하지 않은 한 인라인 스타일을 피하세요.
디자인 시스템 통합
- 가능하면 항상 프로젝트 디자인 시스템의 컴포넌트를 사용하세요.
- Figma 디자인 토큰을 프로젝트 디자인 토큰에 매핑하세요.
- 일치하는 컴포넌트가 있으면 새로 만들지 말고 확장하세요.
- 디자인 시스템에 추가된 모든 새 컴포넌트를 문서화하세요.
코드 품질
- 하드코딩된 값을 피하고 상수 또는 디자인 토큰으로 추출하세요.
- 컴포넌트를 합성 가능하고 재사용 가능하게 유지하세요.
- 컴포넌트 props에 TypeScript 타입을 추가하세요.
- 내보낸 컴포넌트에 JSDoc 주석을 포함하세요.
예시
예시 1: 버튼 컴포넌트 구현
사용자가 말합니다: "이 Figma 버튼 컴포넌트를 구현하세요: https://figma.com/design/kL9xQn2VwM8pYrTb4ZcHjF/DesignSystem?node-id=42-15"
작업:
- URL을 파싱하여 fileKey=
kL9xQn2VwM8pYrTb4ZcHjF및 nodeId=42-15추출 get_design_context(fileKey="kL9xQn2VwM8pYrTb4ZcHjF", nodeId="42-15")실행- 시각적 참조를 위해
get_screenshot(fileKey="kL9xQn2VwM8pYrTb4ZcHjF", nodeId="42-15")실행 - 자산 엔드포인트에서 버튼 아이콘 다운로드
- 프로젝트에 기존 버튼 컴포넌트가 있는지 확인
- 있으면 새 변형으로 확장하고, 없으면 프로젝트 규칙을 사용하여 새 컴포넌트 생성
- Figma 색상을 프로젝트 디자인 토큰에 매핑 (예:
primary-500,primary-hover) - 패딩, 테두리 반경, 타이포그래피에 대해 스크린샷과 대조하여 검증
결과: Figma 디자인과 일치하고 프로젝트 디자인 시스템에 통합된 버튼 컴포넌트.
예시 2: 대시보드 레이아웃 구축
사용자가 말합니다: "이 대시보드를 구축하세요: https://figma.com/design/pR8mNv5KqXzGwY2JtCfL4D/Dashboard?node-id=10-5"
작업:
- URL을 파싱하여 fileKey=
pR8mNv5KqXzGwY2JtCfL4D및 nodeId=10-5추출 - 페이지 구조를 이해하기 위해
get_metadata(fileKey="pR8mNv5KqXzGwY2JtCfL4D", nodeId="10-5")실행 - 메타데이터에서 주요 섹션(헤더, 사이드바, 콘텐츠 영역, 카드)과 해당 자식 노드 ID 식별
- 각 주요 섹션에 대해
get_design_context(fileKey="pR8mNv5KqXzGwY2JtCfL4D", nodeId=":childNodeId")실행 - 전체 페이지를 위해
get_screenshot(fileKey="pR8mNv5KqXzGwY2JtCfL4D", nodeId="10-5")실행 - 모든 자산(로고, 아이콘, 차트) 다운로드
- 프로젝트의 레이아웃 기본 요소를 사용하여 레이아웃 구축
- 가능한 경우 기존 컴포넌트를 사용하여 각 섹션 구현
- Figma 제약 조건에 대해 반응형 동작 검증
결과: 반응형 레이아웃을 갖춘 Figma 디자인과 일치하는 완전한 대시보드.
모범 사례
항상 컨텍스트로 시작
가정에 기반하여 구현하지 마세요. 항상 먼저 get_design_context와 get_screenshot을 가져오세요.
점진적 검증
구현 중에 자주 검증하고, 마지막에만 하지 마세요. 이렇게 하면 문제를 조기에 발견할 수 있습니다.
이탈 기록
Figma 디자인에서 이탈해야 하는 경우(예: 접근성 또는 기술적 제약으로 인해), 코드 주석에 이유를 문서화하세요.
재사용 우선, 새로 만들기 지양
새 컴포넌트를 만들기 전에 항상 기존 컴포넌트가 있는지 확인하세요. 코드베이스 전체의 일관성이 정확한 Figma 복제보다 더 중요합니다.
디자인 시스템 우선
의심스러울 때는 문자 그대로의 Figma 변환보다 프로젝트의 디자인 시스템 패턴을 선호하세요.
일반적인 문제 및 해결 방법
문제: Figma 출력이 잘림
원인: 디자인이 너무 복잡하거나 중첩된 레이어가 많아 단일 응답으로 반환할 수 없습니다.
해결 방법: get_metadata를 사용하여 노드 구조를 가져온 다음, get_design_context로 개별 노드를 각각 가져오세요.
문제: 구현 후 디자인이 일치하지 않음
원인: 구현된 코드와 원본 Figma 디자인 간의 시각적 차이. 해결 방법: 3단계의 스크린샷과 나란히 비교하세요. 디자인 컨텍스트 데이터에서 간격, 색상 및 타이포그래피 값을 확인하세요.
문제: 자산이 로드되지 않음
원인: Figma MCP 서버의 자산 엔드포인트에 접근할 수 없거나 URL이 수정되고 있습니다.
해결 방법: Figma MCP 서버의 자산 엔드포인트에 접근 가능한지 확인하세요. 서버는 localhost URL로 자산을 제공합니다. 수정 없이 직접 사용하세요.
문제: 디자인 토큰 값이 Figma와 다름
원인: 프로젝트의 디자인 시스템 토큰이 Figma 디자인에 지정된 값과 다릅니다. 해결 방법: 프로젝트 토큰이 Figma 값과 다른 경우, 일관성을 위해 프로젝트 토큰을 선호하되 시각적 충실도를 유지하기 위해 간격/크기를 조정하세요.
디자인 구현 이해하기
Figma 구현 워크플로우는 디자인을 코드로 변환하는 신뢰할 수 있는 프로세스를 확립합니다:
디자이너를 위해: 구현이 디자인과 픽셀 단위로 정확하게 일치할 것이라는 확신. 개발자를 위해: 추측을 없애고 수정을 위한 왕복을 줄이는 구조화된 접근 방식. 팀을 위해: 디자인 시스템 무결성을 유지하는 일관되고 고품질의 구현.
이 워크플로우를 따르면 모든 Figma 디자인이 동일한 수준의 주의와 세부 사항으로 구현되도록 보장합니다.