Figma to Component 스킬

이 스킬은 Figma 디자인 URL을 받아서 프로젝트 규칙에 맞는 완전한 React 컴포넌트를 생성합니다.

사용 방법

사용자가 다음과 같은 요청을 할 때 이 스킬을 실행합니다:

• •"이 Figma 디자인으로 컴포넌트 만들어줘"
• •"Figma URL로 UI 구현해줘"
• •"[Figma URL]을 컴포넌트로 변환해줘"

워크플로우

1단계: Figma 분석 및 디자인 검증

1. •

   사용자로부터 다음 정보 수집:

   • •Figma URL (필수)
   • •컴포넌트 이름 (예: ProductCard, UserProfile)
   • •생성 위치 (기본값: src/components/)
   • •기존 컴포넌트 업데이트 여부
2. •

   Figma URL에서 fileKey와 nodeId 추출:

   • •URL 형식: https://figma.com/design/:fileKey/:fileName?node-id=:int1-:int2
   • •nodeId는 123-456 형식을 123:456으로 변환
3. •

   Figma 데이터 가져오기 (병렬 실행):

   typescript

   // mcp__figma__get_screenshot - 시각적 디자인 확인
   // mcp__figma__get_design_context - 코드 및 스타일 정보
   // mcp__figma__get_metadata - 구조 및 계층 파악
   

4. •

   디자인 철저 분석 (이 단계가 중요!):

   • •전체 레이아웃 구조 파악 (flexbox/grid)
   • •모든 간격(gap) 명시적으로 확인
   • •고정 높이 vs 동적 높이 구분
   • •텍스트 overflow 처리 필요 위치 체크
   • •계층 구조 (어느 요소가 어디 안에 있는지)
   • •그림자, 둥근 모서리 등 시각적 요소

2단계: 컴포넌트 구조 생성

생성할 디렉토리 구조:

component-name/
├── index.tsx                    # 컴포넌트 구현
├── styles.module.css            # CSS Modules 스타일
├── tests/
│   ├── index.binding.hook.spec.ts   # 데이터 바인딩 테스트
│   └── index.ui.spec.ts             # UI 렌더링 테스트
└── stories/
    └── index.stories.tsx        # Storybook 스토리

3단계: TDD 방식으로 테스트 작성

먼저 테스트를 작성합니다 (프로젝트 규칙):

1. •

   UI 렌더링 테스트 (index.ui.spec.ts):

   • •Figma 디자인의 주요 요소들이 렌더링되는지 확인
   • •data-testid 속성 사용
   • •예시:
   typescript

   test('컴포넌트가 올바르게 렌더링됨', async ({ page }) => {
     await page.goto('http://localhost:3000/test-page')
     await expect(page.locator('[data-testid="component-title"]')).toBeVisible()
   })
   

2. •

   데이터 바인딩 테스트 (index.binding.hook.spec.ts):

   • •Props가 올바르게 표시되는지 확인
   • •사용자 상호작용 테스트

4단계: CSS 작성 (일반적인 함정 방지)

CSS 규칙 (CLAUDE.md 준수):

• •✅ CSS Modules만 사용
• •✅ Flexbox 레이아웃만 사용
• •❌ position: absolute 금지
• •❌ :global, :root, !important 금지
• •❌ 요구사항에 없는 애니메이션 금지

필수 체크리스트 (이번 작업에서 발생한 문제 방지):

1. •

   Grid/Flexbox 레이아웃:

   • •Grid 사용 시 minmax(0, 1fr) 사용 (텍스트 overflow 방지)
   • •예: grid-template-columns: 64px minmax(0, 1fr) 100px 100px
2. •

   고정 높이 vs 동적 높이:

   • •리스트 행처럼 균일해야 하는 경우 height 명시
   • •예: .listRow { height: 44px; }
3. •

   텍스트 Overflow 처리:

   • •잘려야 하는 텍스트에 필수 3종 세트 적용:
   css

   overflow: hidden;
   white-space: nowrap;
   text-overflow: ellipsis;
   

   • •Grid/Flex 자식에는 min-width: 0 추가
4. •

   간격 구조 (Gap):

   • •부모에 gap 속성 사용 (불필요한 div 제거)
   • •Figma의 계층 구조 정확히 파악
   • •예: main { gap: 8px; } → 자식 간 8px 간격
5. •

   계층 구조:

   • •Figma에서 어떤 요소가 어디 안에 있는지 정확히 파악
   • •예: 페이지네이션이 main 안에 있는지 밖에 있는지

TypeScript 컴포넌트:

/**
 * [컴포넌트명] - Figma 디자인 기반 컴포넌트
 *
 * @description Figma 디자인을 구현한 컴포넌트입니다.
 * @param props - 컴포넌트 속성
 */
export default function ComponentName(props: IComponentProps) {
  // 구현
}

/** 컴포넌트 Props 인터페이스 */
interface IComponentProps {
  // Figma 디자인에서 추출한 props
}

주석 작성 규칙:

• •모든 주석은 한국어로 작성
• •함수/컴포넌트: JSDoc 형식으로 기능, 파라미터, 반환값 설명
• •복잡한 로직: 동작 원리와 구현 이유 설명
• •수정 사항: // 수정 이유: [구체적인 이유] 형식으로 기록

5단계: Storybook 스토리 생성

import type { Meta, StoryObj } from '@storybook/react'
import Component from '../index'

const meta: Meta<typeof Component> = {
  title: 'Components/ComponentName',
  component: Component,
}

export default meta
type Story = StoryObj<typeof Component>

/** 기본 상태 */
export const Default: Story = {
  args: {
    // Figma에서 추출한 기본 props
  },
}

6단계: 시각적 검증 및 테스트

중요: 코드 작성 후 반드시 시각적 검증을 수행합니다.

1. •

   스크린샷 캡처 및 Figma 비교:

   bash

   # 개발 서버 시작
   npm run dev
   
   # Playwright로 스크린샷 캡처
   # 임시 테스트 파일 생성 후 실행
   npx playwright test screenshot-test.spec.ts
   

2. •

   Figma 디자인과 비교 체크리스트:

   • •✅ 전체 레이아웃 구조
   • •✅ 모든 간격(gap)이 정확한지
   • •✅ 텍스트가 칸을 벗어나지 않는지
   • •✅ 행 높이가 균일한지 (필요한 경우)
   • •✅ 색상, 폰트 크기, 줄 높이
   • •✅ 그림자, 둥근 모서리 등 시각적 요소
3. •

   차이점 발견 시 즉시 수정:

   • •CSS를 수정하고 다시 스크린샷 캡처
   • •완벽히 일치할 때까지 반복
4. •

   Playwright 테스트 실행:

   bash

   # 전체 테스트
   npx playwright test src/components/component-name/tests/
   
   # 개별 테스트
   npx playwright test src/components/component-name/tests/index.ui.spec.ts
   

테스트가 통과하고 시각적으로도 Figma와 일치할 때까지 수정합니다.

프로젝트 규칙 준수 체크리스트

디자인 정확도:

• • Grid/Flexbox에 minmax(0, 1fr) 사용 (텍스트 overflow 방지)
• • 고정 높이가 필요한 요소에 height 명시
• • 모든 텍스트 컬럼에 overflow 처리 (3종 세트)
• • 간격을 CSS gap으로 제어 (불필요한 div 제거)
• • Figma 계층 구조 정확히 반영
• • 시각적으로 Figma와 100% 일치

코드 품질:

• • CSS Modules 사용 (position-absolute 없음)
• • Flexbox 레이아웃
• • 한국어 주석 작성
• • TypeScript 타입 정의
• • data-testid 속성 추가
• • Playwright 테스트 작성 (TDD)
• • Storybook 스토리 작성
• • 테스트 통과 확인 (2000ms 미만)
• • 독립적이고 재사용 가능한 컴포넌트

Figma MCP 도구 사용 가이드

스크린샷 가져오기

mcp__figma__get_screenshot({
  fileKey: "extracted-file-key",
  nodeId: "123:456",
  clientLanguages: "typescript",
  clientFrameworks: "react,nextjs"
})

디자인 컨텍스트 가져오기

mcp__figma__get_design_context({
  fileKey: "extracted-file-key",
  nodeId: "123:456",
  clientLanguages: "typescript",
  clientFrameworks: "react,nextjs",
  disableCodeConnect: false
})

메타데이터 가져오기 (구조 파악용)

mcp__figma__get_metadata({
  fileKey: "extracted-file-key",
  nodeId: "123:456",
  clientLanguages: "typescript",
  clientFrameworks: "react,nextjs"
})

에러 처리

1. •Figma URL 형식 오류: 올바른 URL 형식 안내
2. •권한 오류: mcp__figma__whoami 로 사용자 확인
3. •테스트 실패: 디버그 정보 제공 및 수정

성공 기준

1. •✅ Figma 디자인과 시각적으로 일치
2. •✅ 모든 Playwright 테스트 통과
3. •✅ CSS 규칙 준수 (no position-absolute)
4. •✅ 한국어 주석 완성
5. •✅ Storybook에서 정상 렌더링
6. •✅ TypeScript 타입 에러 없음

예시 사용 시나리오

사용자: "https://figma.com/design/abc123/Product?node-id=1-2 이 디자인으로 ProductCard 컴포넌트 만들어줘"

스킬 실행 순서:

1. •URL 파싱 → fileKey: "abc123", nodeId: "1:2"
2. •Figma 데이터 가져오기
3. •src/components/product-card/ 디렉토리 생성
4. •테스트 작성 (TDD)
5. •컴포넌트 구현
6. •Storybook 스토리 생성
7. •테스트 실행 및 검증
8. •사용자에게 결과 보고

참고사항

• •프로젝트의 기존 컴포넌트 스타일과 일관성 유지
• •src/commons/constants/url.ts의 라우팅 규칙 활용
• •GraphQL이 필요한 경우 graphql/ 폴더 생성
• •폼 컴포넌트는 react-hook-form + zod 사용