Figma To Component

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 속성 사용
   • 예시:

   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종 세트 적용:

   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 비교:

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

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

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

3. 차이점 발견 시 즉시 수정:

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

4. 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"
})

에러 처리

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 사용