뿌클로드 개발 가이드

사용 시점

새 뿌클로드 venue 페이지 추가
기존 venue 이미지/데이터 수정
Figma 디자인 반영
CSS/레이아웃 디자인 차이 수정

1. Figma 구조 파악

1.1 메타데이터 가져오기

mcp__figma-dev-mode-mcp-server__get_metadata로 전체 페이지 구조 확인

1.2 섹션별 노드 ID 매핑 테이블 작성

섹션	Figma 노드 ID	설명
헤더 배경
타이틀 이미지
한눈에보기
교통정보 탭별
매표정보
시야정보
근처맛집		(여러 개일 수 있음)

2. 합성 프레임 vs 단순 이미지 판별

2.1 각 노드에 대해 getdesigncontext 호출

자식 요소가 있으면 → 합성 프레임 (마커, 경로 등 포함)
자식 요소가 없으면 → 단순 이미지

2.2 합성 프레임 확인

배경 이미지 (bg, image) 있는가?
경로 라인 (route) 있는가?
번호 마커 (map_number, poi+label) 있는가?

합성 프레임이면 → 부모 프레임 ID로 export해야 함

3. 이미지 데이터 비교

bbucleRoadData.ts의 이미지 URL 필드들과 Figma 노드 비교 테이블 작성.

4. CSS/레이아웃 스타일 검증

이미지뿐만 아니라 CSS 스타일 차이도 확인.

4.1 Figma에서 스타일 값 추출

getdesigncontext로 Desktop 노드와 Mobile 노드 각각 확인:

font-size, line-height, font-weight
padding, margin, gap
border-radius
width, height

4.2 CSS 비교 테이블 작성

항목	Figma Desktop	Figma Mobile	현재 코드	수정 필요
(항목별 작성)

4.3 확인해야 할 컴포넌트

bbucleRoadData.ts의 descriptionHtmls - HTML 인라인 스타일
섹션 컴포넌트의 styled-components - 부모 컴포넌트 스타일
HtmlContentWrapper - CSS 변수 (반응형 스타일용)

5. 레이아웃 문제 진단

"박스가 width를 안 채움", "간격이 다름" 같은 문제 발생 시:

5.1 문제 유형별 진단

증상	원인 가능성	해결 방법
박스가 100% 안 채움	`flex: 1 0 0` 사용	`width: 100%`로 변경
모바일에서 width 안 맞음	styled-component에 width 미지정	명시적 width 추가
간격(gap) 다름	gap 값 하드코딩	Figma 값으로 수정

5.2 동작하는 섹션과 비교 (IMPORTANT)

문제가 있는 섹션이 있으면 동작하는 다른 섹션과 비교:

같은 구조의 다른 섹션 찾기
descriptionHtml 구조 차이 확인
styled-components 차이 확인

5.3 부모 컴포넌트도 확인

HTML 스타일만 수정해도 안 되면 부모 styled-component 확인:

flex-basis만으로는 실제 width 보장 안 됨
명시적 width 필요할 수 있음

6. 이미지 Export & 업로드

6.1 이미지 Export

curl -s -H "X-Figma-Token: $TOKEN" \
  "https://api.figma.com/v1/images/${FILE_KEY}?ids=${NODE_IDS}&format=png&scale=2"

6.2 S3 업로드

aws-vault exec swann-scc -- aws s3 cp image.png \
  s3://scc-dev-accessibility-images-2/$(date +%Y%m%d%H%M%S)_filename.png \
  --acl public-read

7. 검증

yarn web
# http://localhost:3000/bbucle-road/{venue-id}

모든 섹션 이미지 표시 확인
모바일 뷰포트에서 width/gap/font 확인
descriptionHtml 박스가 제대로 채워지는지 확인

흔한 실수 방지

하지 말 것

개별 배경 이미지(bg)만 export → 마커/경로 누락됨
하나의 mapImageUrl만 있다고 가정 → 여러 지도가 있을 수 있음
데스크탑만 확인 → 모바일용 별도 이미지/스타일 필요할 수 있음
CSS 문제를 이미지 문제로 오해 → 레이아웃/스타일 먼저 확인
HTML만 수정하고 부모 컴포넌트 무시 → styled-component도 확인
flex: 1 0 0 사용 → 모바일에서 width 문제 발생 가능

해야 할 것

항상 전체 구조 먼저 파악 (get_metadata)
각 노드가 합성인지 확인 (getdesigncontext)
현재 데이터와 Figma 비교 테이블 작성
합성 프레임은 부모 프레임 ID로 export
데이터 타입이 부족하면 타입부터 수정
CSS 비교 테이블 작성 - Desktop/Mobile 값 모두 확인
동작하는 섹션과 비교 - 문제 진단 시 필수

bbucle-road-dev

Installation

Also in this package

Agent compatibility

Package contents

History

SKILL.md