KEZ-ProductPage-skill

커머스 상세페이지를 Figma 캔버스에 직접 제작·수정하는 Claude Code 스킬 (detail-page-core)

말로 요청하면("리뷰 섹션 만들어줘") Claude Code가 Figma 공식 MCP를 통해 실제 Figma 파일에 오토레이아웃 프레임을 생성·편집합니다. 디자인 규칙을 측정값이 아니라 원리로 정리한 디자인 시스템이 내장되어 있어, 어느 브랜드에든 그 브랜드의 색·서체를 꽂아 재사용할 수 있습니다.

▲ 이 히어로를 포함한 데모 페이지 전체를 본 스킬 자신이 Figma에 제작했습니다 (브랜드 프로파일: demo-browser-ui). 섹션별 해설은 아래 데모 참조.

최근 업데이트

업데이트 카드는 docs/update-card/update-card.html 양식으로 만듭니다 — 텍스트만 바꿔 재렌더하면 됩니다(렌더 명령은 파일 상단 주석).

데모 — 이 스킬로 만든 페이지

아래 3섹션 페이지(860px 캔버스)는 스킬의 표준 절차 — 브랜드 프로파일 확정 → 스켈레톤 → 섹션별 빌더 병렬 제작 → 스크린샷 자가 검수 — 그대로 제작되었습니다. 카피는 한/영 병기.

모든 프레임은 오토레이아웃

이 시스템의 핵심입니다. 절대좌표로 흩뿌리지 않고 섹션(column) ⊃ 카드(column) ⊃ row 3단 중첩으로 쌓기 때문에, 카피가 늘거나 항목이 추가돼도 레이아웃이 스스로 재계산됩니다. 아래 다이어그램 자체도 실제 오토레이아웃 중첩으로 만들어졌습니다.

텍스트 박스는 카피의 역할로 사이징을 배치 전에 판정합니다 — 타이틀·배지는 hug width(폭 = 텍스트 + 패딩), 본문은 fixed width + hug height(폭 고정, 아래로 성장). 그리고 텍스트가 든 컨테이너는 캔버스폭의 84%를 넘지 않습니다(국내 상위 상세페이지 실측 기반 모바일 가독 규칙 — 본문 ≥ 폭의 4.5%, 캡션 ≥ 3%).

사용 흐름 미리보기

핵심 설계 — 2층 구조

이 스킬의 모든 규칙은 새 제품·새 브랜드에서 재사용 가능해야 한다는 원칙으로 만들어졌습니다.

색·서체를 정할 땐 항상 패턴 문서 + 브랜드 문서를 합쳐 결정합니다. 브랜드 값이 미정이면 패턴만으로 지어내지 않고 유저에게 확인받습니다.

요구사항

• Claude Code (CLI 또는 데스크톱 앱)
• Figma 계정 + Figma 공식 원격 MCP 등록:

claude mcp add --scope user --transport http figma https://mcp.figma.com/mcp

--scope user로 등록해야 모든 세션에서 자동 로드됩니다. 등록 후 첫 사용 시 브라우저에서 Figma OAuth 인증이 필요합니다. 스킬은 Figma MCP의 use_figma 도구(Plugin API 실행)를 사용합니다. 이 도구는 베타이므로 결과물은 스크린샷으로 재검증합니다(스킬에 검증 절차 내장).

설치

git clone https://github.com/HarinJin/KEZ-ProductPage-skill.git
cp -r KEZ-ProductPage-skill/detail-page-core ~/.claude/skills/

Claude Code 재시작 후, "상세페이지"가 들어간 요청을 하면 스킬이 자동 발동합니다.

사용 방법

1) 브랜드 프로파일 온보딩 (브랜드당 최초 1회)

작업할 브랜드의 프로파일이 없으면 스킬이 온보딩을 안내합니다:

1. references/brands/_template.md를 references/brands/<브랜드이름>.md로 복사
2. 기존 상세페이지가 있으면 Figma에서 실측해 슬롯(중립축/액센트/의미색/서체/규격)을 채움
3. 실측만으로 안 정해지는 값(브랜드 대표 색조·톤·서체)은 유저에게 확인받아 확정
4. 값이 미정인 슬롯은 "미정"으로 표기하고 해당 부분 제작은 보류 — 지어내지 않음

완성 예시: references/brands/demo-browser-ui.md — 위 데모 페이지가 이 프로파일로 제작되었습니다.

2) 제작 요청

브랜드/제품을 지정해 요청합니다. 트리거 예시:

• "○○ 제품 상세페이지 만들어줘"
• "리뷰 섹션 / FAQ 섹션 / 장점 요약 섹션 / 성분표 섹션 만들어줘"
• "피그마 상세페이지 이 부분 수정해줘"

3) 작업 흐름 (스킬이 강제하는 절차)

1. 인터뷰 선행 — 착수 전 브랜드·범위·카피 소스·자산을 확인 (00-interview.md). 법정 고지문·리뷰 콘텐츠·미확정 카피는 추측 금지
2. 전체 신규는 스켈레톤 우선 — placeholder 프레임으로 전체 구성 승인 후 세부 제작
3. 한 번에 한 구간만 — 섹션 단위 제작 → 스크린샷 검증 → 유저 확인 → 다음
4. 구조 정돈 없이 완료 보고 금지 — 역할 한글명, 의미단위 그룹화, 중첩 오토레이아웃

이 절차의 실제 결과물은 데모 섹션에서 볼 수 있습니다.

4) 대량 제작 — 병렬 오케스트레이션

섹션이 많을 때(예: 크라우드펀딩 페이지 13섹션)는 orchestration.md의 감독-빌더 패턴을 사용합니다: 감독이 폰트 전수검증·공용 조형 고정·카피 소스 고정을 1회 준비 → 빌더 에이전트들에게 복붙 프롬프트 템플릿으로 배분 → 웨이브마다 재배치(re-flow)와 검수 체크리스트 실행.

문서 구조 (13파일, 약 1,500줄)

detail-page-core/
├── SKILL.md                        ← 라우터: 상황→문서 매핑 + 절대 규칙. 전부 미리 읽지 않음
└── references/
    ├── 00-interview.md             ← 착수 전 확인 체크리스트, 추측 금지 3종
    ├── design-dna/                 ← 브랜드 무관 패턴 (값 없음, 원리만)
    │   ├── 01-color.md             ← 색 3층 구조(중립축/액센트/의미색), 배경별 대비, 신규 브랜드 실측 절차
    │   ├── 02-grouping-layout.md   ← 오토레이아웃 계층, 의미단위 그룹화, 조형=역할 신호, 폭 체계
    │   ├── 03-typography.md        ← 크기 4단 서열, 굵기=강조 세기, 서체 3역할, 최소 텍스트 크기
    │   ├── 04-copy.md              ← 역할별 카피 목적·길이, 넘침 시 대응, 이모지 용법
    │   ├── 05-page-purpose.md      ← 섹션 카탈로그(심리 과업 기반), 순서 표준, 펀딩 페이지 변주
    │   └── 06-image-treatment.md   ← 사진 역할 판정→삽입 4방식, 블렌드, 그림자 언어
    ├── brands/
    │   └── _template.md            ← 브랜드 프로파일 템플릿 (온보딩 절차 포함)
    ├── build-recipes.md            ← 제작 5단계 순서, 재사용 코드(말풍선·형광펜·격리카드·블렌드)
    ├── figma-mcp.md                ← use_figma API 규칙 (폰트 로딩, 연산 분할, 원자성)
    ├── orchestration.md            ← 병렬 섹션 제작 감독 절차
    └── troubleshooting.md          ← 증상→해법 색인 T1~T14 (전부 실전 실측 검증)

알려진 한계

• use_figma는 베타 — 생성 결과는 항상 스크린샷으로 재검증 필요 (스킬이 절차로 강제)
• 벡터/마스크 path 데이터는 MCP로 추출 불가 → 복잡한 장식 벡터는 기존 노드 clone 재사용이 실질 해법
• 저해상도 미리보기에서 겹침이 과장돼 보일 수 있음 (고해상도 재조회로 판별)

개발 배경

실제 운영 중인 커머스 브랜드들의 상세페이지 수십 장을 Figma에서 실측해 패턴을 도출하고, 크라우드펀딩 상세페이지 13섹션 병렬 제작 실전에서 나온 함정·낭비를 역주입해 강화한 뒤, 브랜드 고유 값(HEX·서체·노드ID)을 전부 제거해 추출한 공용판입니다. troubleshooting.md의 T1~T14는 전부 실전에서 재현·검증된 항목입니다.

라이선스

MIT