By name: bbucle-road-dev description: 뿌클로드 페이지 개발. 새 venue 추가, 기존 venue 수정, Figma 디자인 반영 시 사용.
뿌클로드 개발 가이드
사용 시점
- 새 뿌클로드 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 각 노드에 대해 get_design_context 호출
자식 요소가 있으면 → 합성 프레임 (마커, 경로 등 포함)
자식 요소가 없으면 → 단순 이미지
2.2 합성 프레임 확인
- 배경 이미지 (bg, image) 있는가?
- 경로 라인 (route) 있는가?
- 번호 마커 (map_number, poi+label) 있는가?
합성 프레임이면 → 부모 프레임 ID로 export해야 함
3. 이미지 데이터 비교
bbucleRoadData.ts의 이미지 URL 필드들과 Figma 노드 비교 테이블 작성.
4. CSS/레이아웃 스타일 검증
이미지뿐만 아니라 CSS 스타일 차이도 확인.
4.1 Figma에서 스타일 값 추출
get_design_context로 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)
- 각 노드가 합성인지 확인 (get_design_context)
- 현재 데이터와 Figma 비교 테이블 작성
- 합성 프레임은 부모 프레임 ID로 export
- 데이터 타입이 부족하면 타입부터 수정
- CSS 비교 테이블 작성 - Desktop/Mobile 값 모두 확인
- 동작하는 섹션과 비교 - 문제 진단 시 필수