Cafe24 UI 업데이트 (Figma → 브라우저 라이브 확정 → 코드 반영)

Overview

Cafe24 기반 프로젝트는 HMR이 없고 Cafe24 관리자 배포를 거쳐야만 반영된다. 따라서 코드를 먼저 고치고 확인하는 순서가 아니라, 라이브 페이지에 CSS/JS를 주입해 UI를 확정한 뒤 그 확정본을 코드에 옮긴다.

Inputs

시작 전에 확보 (없으면 AskUserQuestion으로 요청):

1. 테스트 서버 URL — 대상 페이지
2. Figma 노드 링크 (node-id 포함) 또는 텍스트 설명/스크린샷
3. 대상 뷰포트 — 명시 없으면 데스크탑(1280px)

Workflow

1. 배포 상태 검증. 로컬 최신 코드에만 있는 셀렉터/규칙이 라이브 <style>·CSS에 존재하는지 evaluate_script로 확인. 없으면 사용자에게 배포 요청 후 진행하거나, 로컬 수정분 전체를 주입해 기준 상태를 만든 뒤 진행.
2. 뷰포트 설정. 먼저 프로젝트 CSS의 미디어쿼리에서 모바일↔데스크탑 전환 경계를 확인하고, 경계값에 정확히 걸치는 폭은 피한다. (예: max-width:1024px 기준 스킨이면 뷰포트 1024px는 모바일 레이아웃이 렌더링됨 — 데스크탑 검증은 1280px 권장.) 모바일 = 375px.
3. Figma 스펙 확보. get_screenshot + get_design_context로 수치(폰트/간격/색상) 추출.
4. 라이브 수정 루프. 수정안 CSS를 <style>로 주입 → 스크린샷 + getBoundingClientRect 측정 → Figma 수치와 대조 → 반복.
   • 주입은 반드시 document.body 끝에 append (Cafe24 스킨은 본문 모듈 안에 인라인 <style>을 두는 경우가 많아 <head> 주입은 cascade에서 밀림).
   • 기존 규칙 삭제 시뮬레이션은 CSSOM deleteRule로 실제 삭제 (높은 특이도 오버라이드로 덮으면 상속 경로가 왜곡되어 검증이 틀어짐).
5. 안 먹는 스타일은 매칭 규칙 스캔으로 진단. Cafe24 스킨 코드는 레거시 규칙이 많아 새 규칙이 조용히 지는 일이 잦다. 요소에 매칭되는 전체 규칙을 나열해 어떤 규칙(!important/높은 특이도)이 이기는지 확인:

   for (const sheet of document.styleSheets) {
     let rules; try { rules = sheet.cssRules; } catch(e) { continue; }
     for (const r of rules)  // type 4(media)는 r.cssRules 재귀
       if (r.type === 1 && el.matches(r.selectorText))
         console.log(sheet.href ?? 'inline', r.cssText);
   }
   

6. 사이드이펙트 스코프 점검 (확정본을 파일에 옮기기 전). 내가 추가/수정한 셀렉터가 지금 보는 화면 밖 어디에 닿는지 조사하고, 닿는 곳은 주입 상태로 실측한다:
   • 같은 스코프의 기존 규칙을 grep — 내 셀렉터의 조상 스코프(예: #optionG, .xans-...layer)를 원본 CSS에서 검색하면 그 스코프가 쓰이는 다른 상태·화면이 드러난다 (상태 클래스 .active/.fixed, 스크롤 고정 패널, 클릭 시 뜨는 레이어 등).
   • 숨은 렌더 지점 확인 — Cafe24 옵션선택 레이어처럼 iframe으로 뜨는 화면은 부모 주입이 안 닿는다. iframe 문서가 같은 번들을 쓰면 배포 후 적용되므로, iframe 문서에 직접 주입해 확인한다.
   • 번들 내 속성 충돌 grep — 내 규칙이 덮거나 나를 덮을 동일 속성 규칙이 다른 파일에 있는지 확인.
   • 반대 케이스 회귀 — 문제 상품/페이지만 보지 말고, 원래 정상이던 대표 케이스도 주입 상태로 재확인.
7. 확정본을 로컬 파일에 반영. 프로젝트의 코드 수정 규칙(CLAUDE.md의 블록 주석 규칙 등)이 있으면 준수. 오버라이드를 쌓지 말고 레거시 규칙 자체를 수정/삭제. cascade 위치 주의: 본문 인라인 블록은 <head> 외부 CSS보다 뒤라 동일 특이도면 이긴다.
   • 검증은 파일 수정 "전" 4~5단계 주입 상태에서 끝낸다. 파일 반영(6단계)은 이미 확정된 것을 옮겨 적는 단계일 뿐, 그 자체로 다시 확인할 대상이 아니다.
   • 파일을 고친 뒤 라이브 새로고침으로 확인하려 하지 마라. HMR이 없으므로 새로고침은 (a) 주입한 <style>을 전부 날리고 (b) 여전히 배포본(옛 코드) 만 렌더한다 → 내 수정이 반영된 것처럼 착각하기 쉽다. 굳이 재확인이 필요하면 새로고침이 아니라 확정본과 동일한 규칙을 다시 주입해서 본다.
8. 보고. 원인(어떤 규칙이 왜 이겼는지) + 수정 파일/위치 + 사이드이펙트 점검 결과 + "Cafe24 관리자 배포 필요" 안내. 최종 확인은 사용자가 배포한 후. 주입해둔 작업 탭은 닫지 말고 주입 상태 그대로 남겨둔다 — 사용자가 미리보기를 직접 확인하는 용도.

Common Mistakes

실수	결과
배포 상태 확인 없이 라이브와 시안 비교	이미 고친 문제를 다시 진단 (실제 발생)
브레이크포인트 경계값(예: 1024px) 뷰포트로 데스크탑 검증	모바일 레이아웃을 보고 엉뚱한 수정
<head>에 스타일 주입	본문 인라인 스타일에 밀려 "수정이 안 먹는" 것처럼 보임
오버라이드로 삭제 흉내	특이도가 검증을 왜곡 — 실배포와 다른 결과 (실제 발생)
확정 없이 파일부터 수정	배포 없이는 확인 불가 → 배포 왕복 낭비
파일 수정 후 라이브 새로고침으로 최종 확인	HMR 없음 → 새로고침은 주입 스타일을 날리고 배포본(옛 코드)만 보여줌. 반영된 걸로 착각 (실제 발생)
보이는 화면만 검증하고 셀렉터 스코프 미조사	고정 패널·옵션 레이어(iframe)·다른 상태 클래스에서 깨져도 배포 후에야 발견 (실제 발생 — 사용자 지적으로 뒤늦게 점검)