name	figma-to-component
description	Figma 디자인을 분석하여 프로젝트 규칙에 맞는 React 컴포넌트를 자동 생성합니다. Figma URL을 받아서 TDD 방식으로 컴포넌트, 스타일, 테스트, Storybook을 생성합니다.

Figma to Component 스킬

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

사용 방법

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

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

워크플로우

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

사용자로부터 다음 정보 수집:
- Figma URL (필수)
- 컴포넌트 이름 (예: ProductCard, UserProfile)
- 생성 위치 (기본값: src/components/)
- 기존 컴포넌트 업데이트 여부
Figma URL에서 fileKey와 nodeId 추출:
- URL 형식: https://figma.com/design/:fileKey/:fileName?node-id=:int1-:int2
- nodeId는 123-456 형식을 123:456으로 변환

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

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

디자인 철저 분석 (이 단계가 중요!):
- 전체 레이아웃 구조 파악 (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 방식으로 테스트 작성

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

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

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

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

데이터 바인딩 테스트 (index.binding.hook.spec.ts):
- Props가 올바르게 표시되는지 확인
- 사용자 상호작용 테스트

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

CSS 규칙 (CLAUDE.md 준수):

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

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

Grid/Flexbox 레이아웃:
- Grid 사용 시 minmax(0, 1fr) 사용 (텍스트 overflow 방지)
- 예: grid-template-columns: 64px minmax(0, 1fr) 100px 100px
고정 높이 vs 동적 높이:
- 리스트 행처럼 균일해야 하는 경우 height 명시
- 예: .listRow { height: 44px; }
텍스트 Overflow 처리:
- 잘려야 하는 텍스트에 필수 3종 세트 적용:
```
overflow: hidden;
white-space: nowrap;
text-overflow: ellipsis;
```
- Grid/Flex 자식에는 min-width: 0 추가
간격 구조 (Gap):
- 부모에 gap 속성 사용 (불필요한 div 제거)
- Figma의 계층 구조 정확히 파악
- 예: main { gap: 8px; } → 자식 간 8px 간격
계층 구조:
- 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단계: 시각적 검증 및 테스트

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

스크린샷 캡처 및 Figma 비교:

# 개발 서버 시작
npm run dev

# Playwright로 스크린샷 캡처
# 임시 테스트 파일 생성 후 실행
npx playwright test screenshot-test.spec.ts

Figma 디자인과 비교 체크리스트:
- ✅ 전체 레이아웃 구조
- ✅ 모든 간격(gap)이 정확한지
- ✅ 텍스트가 칸을 벗어나지 않는지
- ✅ 행 높이가 균일한지 (필요한 경우)
- ✅ 색상, 폰트 크기, 줄 높이
- ✅ 그림자, 둥근 모서리 등 시각적 요소
차이점 발견 시 즉시 수정:
- CSS를 수정하고 다시 스크린샷 캡처
- 완벽히 일치할 때까지 반복

Playwright 테스트 실행:

# 전체 테스트
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"
})

에러 처리

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

성공 기준

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

예시 사용 시나리오

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

스킬 실행 순서:

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

참고사항

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

figma-to-component

Install Skill

SKILL.md