@gangnamunni/figma-sites-kit

v0.5.0

Published

5 days ago

Figma Sites code component용 완성 컴포넌트 킷. Figma에는 thin wrapper만 남긴다.

Downloads

1,863

0High
0Medium
0Low

@gangnamunni/figma-sites-kit

Figma Sites/Make용 코드 컴포넌트 킷이에요. 로직은 패키지가 가지고, Figma에는 얇은 wrapper만 남겨요.

코드 컴포넌트를 복사·붙여넣기로 관리하면 같은 코드가 수십 곳에 흩어지고, 잘못 건드리면 앱이 바로 깨져요. 이 킷은 로직을 패키지 하나로 모아 테스트·버전 관리하고, Figma에는 import와 props 배선만 남겨요. 고칠 곳은 한 군데뿐이고, Figma에서 건드릴 수 있는 범위가 props 값으로 좁아져요.

컴포넌트

| 컴포넌트 | 용도 | props | | --- | --- | --- | | CouponCta | 쿠폰 다운로드 CTA — 앱 웹뷰는 딥링크로 직행, 웹은 앱 안내 모달 | promotionCode, amount, description, onTrack? | | Timer | 카운트다운 타이머 — 남은 일/시간/분/초 표시 | targetDate, titleText, descriptionText | | Banner | 이미지 캐러셀 — 무한 루프·스와이프/드래그·자동 재생·페이지 인디케이터 | image1~image12, aspectRatio, mode, autoplayInterval, numberOfImages, onTrack? | | ProductUnit | 시술 상품 카드 섹션 — id/태그로 큐레이션한 상품을 캐러셀(Vertical) 또는 리스트(Horizontal)로. 데이터는 컴포넌트가 직접 조회 | title, moreLabel, moreLink, layout, eventIds, treatmentTagIds, onTrack? |

onTrack?은 코드 사용 전용 트래킹 주입점이에요(미지정 시 window.trackContent 위임). Figma props 패널에는 함수를 배선할 수 없어요.

ProductUnit은 두 가지를 알아두세요.

eventIds로 상품을 지정해 쓰세요. 비워두면 여러 언어권 상품이 섞여서, 한국어 페이지에 일본어·중국어 제목과 외화 가격 카드가 나올 수 있어요. treatmentTagIds만 쓰는 것도 마찬가지예요.
편집기·프리뷰에서도 운영 상품이 보여요. 조회 실패나 0건이면 unni.app 게시본은 섹션이 사라지고, *.figma.site에서는 안내 문구가 떠요 — 원인은 콘솔의 [ProductUnit] 로그로 확인하세요. test 상품은 test.unni.app 게시본에서만 볼 수 있어요.

Figma에서 쓰기

Figma에 넣는 건 아래 wrapper뿐이에요 — import + defineProperties(props 패널 배선) + props 전달. 컴포넌트명·props만 위 표대로 바꾸면 돼요.

import { defineProperties } from 'figma:react'
import { CouponCta } from '@gangnamunni/[email protected]'

function CouponCtaComponent(props: { promotionCode: string; amount: string; description: string }) {
  return <CouponCta {...props} />
}
defineProperties(CouponCtaComponent, {
  promotionCode: { label: '쿠폰 식별자 (promotionCode)', type: 'string', defaultValue: '' },
  amount: { label: '할인 금액 (예: 35,000)', type: 'string', defaultValue: '35,000' },
  description: { label: '설명 (예: 최소 주문 금액 50,000원)', type: 'string', defaultValue: '최소 주문 금액 50,000원' },
})
export default CouponCtaComponent

버전은 import에 박아요(@0.5.0). 새 버전이 나오면 이 @버전만 바꾸세요.
wrapper에 state·effect·이벤트 핸들러·조건 분기가 생기면 경계 위반이에요. 그런 로직은 패키지로 내려요.
figma/ 아래 사본은 각 컴포넌트가 Figma에 실제로 붙어 있는 버전이라 최신을 따라가지 않아요. 실측하고 교체할 때만 올려요.

유저 로그 남기기

페이지 조회·스크롤 깊이·컴포넌트 클릭을 Amplitude에 쌓으려면, 사이트 설정의 커스텀 <head>에 아래 두 줄을 넣으세요.

<script src="https://cdn.amplitude.com/libs/analytics-browser-2.17.8-min.js.gz" defer></script>
<script src="https://raw.esm.sh/@gangnamunni/[email protected]/dist/tracking.global.js" defer></script>

view_content(페이지 조회)와 scroll_content(25·50·75·100% 도달)가 쌓이고, 모든 이벤트에 콘텐츠 식별 정보와 스크립트 버전이 붙어요. 로그인한 유저는 회원 id로 연결돼요. 코드 컴포넌트가 쓰는 window.trackContent도 이 스크립트가 만들어요.

두 줄을 그대로 쓰세요. defer를 지우면 페이지가 늦게 뜨고, async로 바꾸면 실행 순서가 뒤집혀 로그가 전부 사라질 수 있어요(에러도 안 나요).
기존에 붙여둔 긴 스니펫이 있으면 Amplitude 줄까지 통째로 지우고 이 두 줄만 남기세요. 겹쳐 두면 SDK가 두 번 로드되면서 로그가 조용히 사라져요.
이 @버전은 위 wrapper의 @버전과 별개라, 한쪽만 올려도 돼요.
로그가 안 보이면 보고 있는 프로젝트를 먼저 확인하세요. unni.app/discovery/site/<slug>는 운영, *.figma.site 프리뷰는 개발 프로젝트예요 — 프리뷰로 열어놓고 운영 대시보드를 보면 정상인데도 안 들어온 것처럼 보여요. 그다음 콘솔에서 typeof window.amplitude와 window.__contentTrackingInit을 확인하세요(undefined면 각 줄이 실행되지 않은 거예요).

되돌리려면 위 두 줄을 먼저 지운 뒤 예전 스니펫(legacy/head-snippet.html)의 <script> 두 개를 붙이고 재게시하세요. 두 벌을 함께 두면 SDK가 두 번 로드돼 로그가 사라져요. 롤백하면 아래 iOS 18 이미지 우회도 함께 사라져요.

iOS 18 이미지 깨짐 방지

iOS 18.x에는 Figma에서 잘라 쓴 이미지가 잘리지 않고 원본째 그려지는 브라우저 버그가 있어요. 작은 배지 자리에 앱 스크린샷 전체가 화면을 덮는 식이에요. iPhone XS·XR은 iOS를 더 못 올려서 이 사용자가 계속 남아요.

우회는 위 트래킹 스크립트에 들어 있어요(0.5.0부터). 두 줄을 쓰는 사이트는 head의 @버전을 0.5.0 이상으로 올려 재게시하면 끝이에요. 재게시한 뒤 페이지가 평소대로 보이는지 한 번 훑어보세요.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@gangnamunni/figma-sites-kit

컴포넌트

Figma에서 쓰기

유저 로그 남기기

iOS 18 이미지 깨짐 방지