🎯 이번 편에서 배울 내용

자주 발생하는 문제와 해결 방법
고급 프롬프트 기법
워크플로우 최적화
팀 협업 팁
생산성 향상 도구

Part 1: 문제 해결 가이드

문제 1: Figma MCP 연결 실패

증상:

"Failed to connect to MCP server"
"MCP server not found"
도구 목록이 비어있음

해결 단계:

1단계: 기본 확인

체크리스트:
□ Cursor가 최신 버전인가?
□ Node.js가 설치되어 있나?
□ mcp.json 파일이 올바른 위치에 있나?
□ API 토큰이 유효한가?

2단계: mcp.json 검증

.cursor/mcp.json 파일 열기
JSON 문법 검증: https://jsonlint.com
토큰 값 확인 (공백, 줄바꿈 없음)

3단계: 명령 프롬프트에서 직접 테스트

bash

npx figma-developer-mcp --figma-api-key=YOUR_TOKEN --stdio

작동하면 → mcp.json 설정 문제 작동하지 않으면 → Node.js 또는 네트워크 문제

4단계: 완전 초기화

bash

# npm 캐시 삭제
npm cache clean --force

# Cursor 완전 종료
taskkill /F /IM Cursor.exe

# .cursor 폴더 백업 후 삭제
# Cursor 재시작
# mcp.json 다시 생성

문제 2: AI가 Figma 링크를 무시함

증상:

Figma 링크를 제공했는데 AI가 "볼 수 없습니다"라고 응답
MCP 도구를 사용하지 않음

해결 방법:

1) Agent 모드 확인

반드시 Composer 모드 (Ctrl+I)에서:
- Agent 모드 ON
- Tools 아이콘에 Figma 도구가 보임

2) 명시적으로 요청

다음 Figma 링크의 디자인을 get_figma_node 도구를 사용해서 분석해줘:
[링크]

3) 링크 형식 확인 올바른 형식:

✅ https://www.figma.com/design/ABC123/File?node-id=1-2
✅ https://www.figma.com/file/ABC123/File

잘못된 형식:

❌ figma.com/ABC123 (프로토콜 없음)
❌ https://figma.com/ABC (불완전)

문제 3: 생성된 코드가 디자인과 다름

문제 유형별 해결:

A) 색상이 다름

생성된 코드의 색상 값을 Figma와 비교해줘.
차이나는 색상을 다음 값으로 수정해줘:
- 배경: #F8F9FA
- 메인 버튼: #4A90E2
- 텍스트: #1F2937

B) 간격이 다름

레이아웃의 모든 margin과 padding을
Figma 디자인과 정확히 일치하도록 수정해줘.
특히 다음 부분:
- 로고와 입력 필드 사이: 60px
- 입력 필드 간: 16px
- 버튼과 링크 사이: 16px

C) 폰트가 다름

다음 폰트 설정을 정확히 적용해줘:
- 헤딩: Inter Bold 32px
- 바디: Inter Regular 16px
- 캡션: Inter Regular 14px

D) 레이아웃 구조가 다름

Figma의 레이어 구조를 다시 확인하고
HTML 구조를 정확히 매칭해줘:

Figma 레이어:
- Login Screen (Frame)
  - Logo (Group)
  - Email Input (Group)
  - Password Input (Group)
  - Login Button (Group)
  
HTML도 동일한 구조로.

문제 4: 반응형이 제대로 작동하지 않음

해결 전략:

1) 브레이크포인트 추가

다음 브레이크포인트에서 테스트하고 수정해줘:
- 모바일: 393px (Figma 프레임 크기)
- 태블릿: 768px
- 데스크톱: 1440px

각 크기에서:
- 요소들이 화면을 벗어나지 않음
- 터치 타겟이 충분히 큼 (최소 44px)
- 가독성이 유지됨

2) Flexbox/Grid 검증

현재 레이아웃의 flexbox 설정을 검토하고
모든 화면 크기에서 올바르게 작동하도록 수정해줘.

문제 5: 성능 문제

증상:

페이지 로드가 느림
애니메이션이 끊김
Lighthouse 점수 낮음

최적화 체크리스트:

1) 이미지 최적화

모든 이미지를:
1. WebP 형식으로 변환
2. 적절한 크기로 리사이즈
3. lazy loading 적용
4. srcset으로 반응형 이미지 제공

2) CSS 최적화

CSS를:
1. 중요 CSS를 인라인으로
2. 나머지는 비동기 로드
3. 사용하지 않는 CSS 제거
4. CSS 압축

3) JavaScript 최적화

JavaScript를:
1. 코드 스플리팅
2. Tree shaking
3. 압축 및 난독화
4. defer/async 속성 사용

4) 폰트 최적화

웹 폰트를:
1. WOFF2 형식 사용
2. font-display: swap 설정
3. 필요한 글자만 subset으로
4. 로컬 폰트 우선 사용

Part 2: 고급 프롬프트 기법

기법 1: 컨텍스트 제공

나쁜 예 ❌:

이거 React로 만들어줘
[링크]

좋은 예 ✅:

다음 Figma 디자인을 React 컴포넌트로 구현해줘:
[링크]

프로젝트 컨텍스트:
- 프레임워크: React 18 + Vite
- 스타일링: Tailwind CSS
- 상태 관리: Zustand
- 라우팅: React Router v6
- 타입: TypeScript

기존 컴포넌트 패턴:
- 모든 컴포넌트는 src/components/ 폴더에
- Props 타입은 별도 types.ts 파일에
- 스타일은 Tailwind utility 클래스 사용
- 이벤트 핸들러는 handle접두사 사용

참고할 기존 컴포넌트:
[Button.tsx, Input.tsx 파일 첨부]

이 패턴을 따라서 LoginScreen 컴포넌트를 만들어줘.

기법 2: 단계별 요청

한 번에 모든 것 요청 (비효율적):

로그인 화면을 만들고 유효성 검사도 넣고 
애니메이션도 추가하고 API 연동도 하고
테스트 코드도 작성해줘.

단계별 요청 (효율적):

1단계:
기본 로그인 화면 레이아웃만 먼저 구현해줘.
Figma 디자인대로 HTML/CSS만.

[확인 후]

2단계:
이제 입력 유효성 검사를 추가해줘:
- 이메일 형식 확인
- 비밀번호 최소 8자
- 실시간 오류 표시

[확인 후]

3단계:
부드러운 전환 애니메이션을 추가해줘.

[확인 후]

4단계:
API 연동 코드를 추가해줘.

기법 3: 예제 제공

다음과 같은 스타일로 Button 컴포넌트를 만들어줘:

[기존 Button 컴포넌트 코드 첨부]

이와 동일한 패턴으로 Input 컴포넌트도 만들어줘.
Props, 스타일, 타입 정의 방식을 똑같이.

기법 4: 제약 조건 명시

로그인 폼을 구현해줘.

제약 조건:
- 번들 크기: 최대 50KB
- 지원 브라우저: Chrome 90+, Safari 14+
- 접근성: WCAG 2.1 AA 준수
- 외부 라이브러리: 최소화 (필수: React만)
- IE11: 지원 안 함

기법 5: 반복 개선

초안:
로그인 화면의 기본 구조를 먼저 만들어줘.
완벽하지 않아도 돼. 빠르게.

[초안 확인 후]

개선 1차:
이제 간격과 정렬을 Figma와 정확히 맞춰줘.

[확인 후]

개선 2차:
색상을 Figma 디자인 토큰에서 가져와서 적용해줘.

[확인 후]

최종:
마이크로 인터랙션을 추가해서 완성해줘.

Part 3: 워크플로우 최적화

효율적인 작업 순서

1단계: 디자인 준비 (Figma)

시간: 30분
- 컴포넌트 정리
- 명확한 이름 부여
- 색상/폰트 통일
- 주석 추가

2단계: 기본 구조 생성 (Cursor)

시간: 10분
프롬프트:
"이 Figma 디자인의 기본 HTML 구조만 생성해줘.
CSS는 나중에. 시맨틱 태그 사용."

3단계: 스타일링 (Cursor)

시간: 15분
프롬프트:
"이제 Figma 디자인과 정확히 일치하도록
CSS를 작성해줘. 색상, 간격, 폰트 모두."

4단계: 인터랙션 (Cursor)

시간: 15분
프롬프트:
"호버 효과, 포커스 스타일, 클릭 피드백을 추가해줘."

5단계: 반응형 (Cursor)

시간: 10분
프롬프트:
"모바일(393px), 태블릿(768px), 데스크톱(1440px)에서
모두 올바르게 표시되도록 수정해줘."

6단계: 최적화 (Cursor)

시간: 10분
프롬프트:
"성능 최적화: 이미지 lazy load, CSS 압축, 
불필요한 코드 제거."

총 소요 시간: 약 90분

재사용 가능한 컴포넌트 라이브러리 구축

프로젝트를 진행하면서:
1. Button 컴포넌트 생성 → 라이브러리에 추가
2. Input 컴포넌트 생성 → 라이브러리에 추가
3. Card 컴포넌트 생성 → 라이브러리에 추가

다음 프로젝트에서:
"components/library/Button.jsx를 참고해서
새 SubmitButton을 만들어줘."

Part 4: 팀 협업 팁

Figma 디자인 시스템 구축

1) 색상 변수

Figma에서:
Local Variables → New collection → "Colors"
- Primary/500: #4A90E2
- Primary/600: #3A7BC8
- Neutral/50: #F8F9FA
- Neutral/900: #1F2937

Cursor에게:
"Figma의 색상 변수를 CSS 변수로 변환해줘."

2) 타이포그래피 스타일

Figma에서:
Text Styles 정의:
- Heading/H1: Inter Bold 32px
- Body/Regular: Inter Regular 16px
- Caption: Inter Regular 12px

Cursor에게:
"Figma의 텍스트 스타일을 CSS 클래스로 변환해줘."

3) 컴포넌트 라이브러리

Figma에서:
Components → Publish
버튼, 입력 필드 등을 팀 라이브러리로 공유

Cursor에게:
"Figma 팀 라이브러리의 Button 컴포넌트를
React 컴포넌트로 변환해줘."

Git 워크플로우

브랜치 전략:

main (프로덕션)
├── develop (개발)
│   ├── feature/login-screen (기능)
│   └── feature/dashboard (기능)

커밋 메시지 규칙:

feat: Figma 로그인 화면을 React로 구현
style: 로그인 버튼 호버 효과 추가
fix: 입력 필드 간격 수정
refactor: CSS를 Tailwind로 전환

Cursor와 Git 통합:

Cursor에게:
"변경 사항을 검토하고 적절한 커밋 메시지를 작성해줘.
Conventional Commits 규칙을 따라서."

코드 리뷰 프로세스

1) Cursor에게 자가 리뷰 요청

작성한 로그인 컴포넌트 코드를 리뷰해줘:
- 코드 품질
- 성능 이슈
- 접근성 문제
- 보안 취약점
- 개선 제안

2) 리뷰 체크리스트

□ Figma 디자인과 일치
□ 반응형 작동
□ 접근성 준수
□ 성능 최적화
□ 에러 핸들링
□ 주석 충분
□ 테스트 코드 포함

Part 5: 생산성 도구

Cursor 단축키 마스터

필수 단축키:

Ctrl + I        : Composer 열기
Ctrl + L        : Chat 열기
Ctrl + K        : 인라인 편집
Ctrl + Shift + P: 명령 팔레트
Ctrl + P        : 파일 빠른 열기
Ctrl + ,        : 설정
Alt + ↑/↓       : 줄 이동
Ctrl + D        : 같은 단어 선택
Ctrl + /        : 주석 토글

고급 단축키:

Ctrl + Shift + L: 모든 같은 단어 선택
Ctrl + Space    : AI 자동완성 트리거
Alt + Click     : 멀티 커서
Ctrl + Shift + K: 줄 삭제
Ctrl + ]        : 들여쓰기

Figma 플러그인 추천

디자인 → 코드:

Anima: 코드 생성
Figma to Code: HTML/React 생성
Design Lint: 디자인 검증

디자인 시스템:

Design System Manager: 컴포넌트 관리
Style Organizer: 스타일 정리
Figma Tokens: 디자인 토큰 관리

생산성:

Rename It: 일괄 이름 변경
Content Reel: 더미 데이터 생성
Autoflow: 플로우차트 자동 생성

자동화 스크립트

package.json scripts:

json

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview",
    "lint": "eslint src --ext js,jsx --report-unused-disable-directives --max-warnings 0",
    "format": "prettier --write \"src/**/*.{js,jsx,css}\"",
    "test": "vitest",
    "figma:sync": "node scripts/sync-figma-tokens.js"
  }
}

Figma 토큰 동기화 스크립트:

javascript

// scripts/sync-figma-tokens.js
const fs = require('fs');
const fetch = require('node-fetch');

async function syncTokens() {
    const fileKey = process.env.FIGMA_FILE_KEY;
    const token = process.env.FIGMA_TOKEN;
    
    const response = await fetch(
        `https://api.figma.com/v1/files/${fileKey}/variables/local`,
        { headers: { 'X-Figma-Token': token } }
    );
    
    const data = await response.json();
    
    // CSS 변수로 변환
    const css = generateCSSVariables(data);
    fs.writeFileSync('src/styles/figma-tokens.css', css);
}

Part 6: 고급 활용 시나리오

시나리오 1: 대규모 디자인 시스템

구조:

design-system/
├── figma/
│   └── design-tokens.json
├── components/
│   ├── Button/
│   ├── Input/
│   └── Card/
├── tokens/
│   ├── colors.ts
│   ├── typography.ts
│   └── spacing.ts
└── docs/
    └── storybook/

워크플로우:

1. Figma에서 디자인 토큰 업데이트
2. Figma API로 토큰 추출
3. Cursor로 TypeScript 타입 생성
4. 컴포넌트에 자동 적용
5. Storybook 문서 자동 생성

시나리오 2: 다국어 지원

Figma 준비:

각 언어별 프레임 생성:
- Login Screen (EN)
- Login Screen (KO)
- Login Screen (JA)

각 프레임의 링크를 저장

Cursor 작업:

이 Figma 디자인들을 참고해서
i18n을 지원하는 React 컴포넌트를 만들어줘:

영어: [링크1]
한국어: [링크2]
일본어: [링크3]

react-i18next를 사용하고,
각 언어의 텍스트를 추출해서 JSON 파일로 분리해줘.

시나리오 3: A/B 테스트

두 가지 디자인 버전:

Figma:
- Login Screen (Version A)
- Login Screen (Version B)

Cursor에게:
"두 Figma 디자인을 각각 구현하고,
Feature Flag로 전환할 수 있게 해줘.
LaunchDarkly 또는 직접 구현."

마지막 조언

지속적인 학습

Figma 유튜브 채널 구독
Cursor Discord 커뮤니티 참여
GitHub Issues에서 다른 사용자들의 팁 확인
Medium/Dev.to에서 케이스 스터디 읽기

실전 프로젝트

이론만으로는 부족합니다. 다음 프로젝트를 직접 만들어보세요:

포트폴리오 웹사이트
- Figma에서 디자인
- Cursor로 코드 생성
- Vercel에 배포
Todo 앱
- CRUD 기능 전부
- 로컬 스토리지
- 다크 모드
대시보드
- 차트 및 그래프
- 반응형 레이아웃
- 데이터 필터링

커뮤니티 기여

여러분의 경험을 공유하세요:

블로그 포스팅
YouTube 튜토리얼
GitHub 예제 프로젝트
Stack Overflow 답변

최종 체크리스트: 전체 과정 마스터

Cursor 설치 및 설정 완료
Figma 기본 사용법 숙지
API 토큰 발급 및 관리 이해
Node.js 환경 설정 완료
MCP 서버 설치 및 연동 성공
Figma에서 디자인 생성 가능
Cursor로 코드 변환 가능
생성된 코드를 프로젝트에 통합 가능
문제 발생 시 해결 방법 알고 있음
고급 기능 활용 가능

축하합니다! 🎉

10부작 가이드를 모두 완료하셨습니다!

이제 여러분은: ✅ Cursor와 Figma를 자유자재로 다룰 수 있습니다 ✅ 디자인을 코드로 변환하는 워크플로우를 이해했습니다 ✅ 실전 프로젝트에 바로 적용할 수 있습니다 ✅ 문제가 발생해도 스스로 해결할 수 있습니다

다음 단계:

실제 프로젝트에 적용해보세요
자신만의 워크플로우를 개발하세요
배운 내용을 다른 사람들과 공유하세요

질문이나 피드백이 있다면:

Cursor Discord 커뮤니티
Figma 커뮤니티 포럼
Stack Overflow

계속해서 배우고 성장하세요! 🚀

부록: 빠른 참조 가이드

주요 명령어 모음

Cursor 단축키

Ctrl + I : Composer
Ctrl + L : Chat
Ctrl + K : 인라인 편집
Ctrl + P : 파일 열기
Ctrl + , : 설정

NPM 명령어

npm --version        : 버전 확인
npm install -g 패키지 : 글로벌 설치
npx 패키지          : 임시 실행
npm cache clean --force : 캐시 삭제

Git 명령어

git status  : 상태 확인
git add .   : 모든 변경사항 스테이징
git commit -m "메시지" : 커밋
git push    : 푸시

자주 사용하는 프롬프트

디자인 분석

이 Figma 디자인을 분석해줘:
- 레이아웃 구조
- 색상 팔레트
- 타이포그래피
- 간격 시스템
[링크]

코드 생성

이 Figma 디자인을 [프레임워크]로 구현해줘:
[링크]

요구사항:
- [기술 스택]
- [스타일링 방법]
- [특별 요구사항]

코드 개선

이 코드를 개선해줘:
- 성능 최적화
- 접근성 개선
- 코드 가독성
- 에러 핸들링

트러블슈팅 플로우차트

문제 발생
    ↓
MCP 연결 문제?
    예 → 5편 참조
    아니오 ↓
    ↓
코드가 안 맞음?
    예 → 8편 참조
    아니오 ↓
    ↓
반응형 문제?
    예 → 9편 참조
    아니오 ↓
    ↓
성능 문제?
    예 → 10편 참조

유용한 링크 모음

공식 문서:

Cursor: https://cursor.com/docs
Figma: https://help.figma.com
MCP: https://github.com/GLips/Figma-Context-MCP

커뮤니티:

Cursor Discord: https://discord.gg/cursor
Figma Community: https://www.figma.com/community

학습 리소스:

Figma YouTube: https://youtube.com/@figma
MDN Web Docs: https://developer.mozilla.org

'개발환경 구축' 카테고리의 다른 글

Cursor + Figma MCP 가이드 - Cursor와 Figma MCP 연동하기 (0)	2025.10.31
Cursor + Figma MCP 가이드 - Cursor AI 설치 및 기본 설정 (0)	2025.10.27

Cursor + Figma MCP 가이드 - 문제 해결 및 고급 활용법