UI 클론: 참조 측정, 재구축, 일치 증명
모든 작업은 하나의 루프를 따릅니다: 참조 캡처 → 측정 (가능하면 정확한 값을 읽고, 그렇지 않으면 픽셀 측정) → 사양 작성 → 사용자 스택으로 빌드 → 동일한 방식으로 우리 것 캡처 → 비교 → 수정, 사양이 통과할 때까지 반복. 결과물은 사용자 프로젝트의 코드 더하기 증거(숫자, 차이 이미지, 나란히 비교 시트)이며, 절대 "대충 맞는 것 같습니다"가 아닙니다. 방법은 NiazMorshed2007/reanimate 및 rossark0/rossark-motion-skill(MIT)에서 적용했습니다. 모든 스크립트는 자체 제작입니다.
<skill> = 이 스킬의 폴더. 작업은 프로젝트의 ./ui-clone/<name>/ 디렉토리에 넣습니다: ref/, ours/, figma/, compare-N/, diff-N/, spec.md. 사용자가 증거 커밋을 원하지 않는 한 ui-clone/을 .gitignore에 추가하세요.
설정 (머신당 한 번)
- Python (numpy + Pillow):
~/.ui-clone/venv/bin/python(없으면python3 -m venv ~/.ui-clone/venv && ~/.ui-clone/venv/bin/pip install numpy pillow로 생성). 스크립트는-I플래그와 함께 실행하세요. - 브라우저 캡처 (Playwright + Chromium, 약 250 MB, URL/개발 서버 입력 전용):
~/.ui-clone/runner에 러너 설치 (npm i [email protected] && npx [email protected] install chromium)..mjs스크립트는node <skill>/scripts/<script>.mjs로 실행합니다 (Playwright를~/.ui-clone/runner또는UICLONE_RUNNER환경 변수에서 로드함; Playwright 자체 Chromium이 설치되지 않은 경우 Playwright 캐시의 모든 Chromium을 사용하거나UICLONE_CHROMIUM환경 변수를 사용). - ffmpeg/ffprobe가 PATH에 있어야 함. Figma 전용:
FIGMA_TOKEN=...을 환경 변수, 프로젝트의keys.env, 또는~/.ui-clone/keys.env에 설정 (읽기 전용 개인 액세스 토큰). 토큰을 절대 출력하거나 커밋하지 마세요. 없는 것은 설치하기 전에 물어보세요.
0. 범위 (spec.md 상단, 캡처 전)
- 대상: 정확히 클론할 대상 (URL + 선택자, 파일 + 시간 범위 + 자르기, Figma 노드) 그 이상도 이하도 아닙니다.
- 충실도 (첫 응답에 명시; 검증 수준 결정):
수준 사용 시기 일치해야 하는 것 다를 수 있는 것 motion-faithful (타인 작업의 기본값) "우리 것을 그들의 것처럼 느끼고 움직이게" 구조와 비율, 순서, 타이밍 ±0.08초, 이징 패밀리, 오버슈트, 크기 대비 이동 거리, 스태거 카피, 색상, 글꼴, 이미지, 브랜드 pixel-faithful 사용자 자신의 디자인 (Figma → 코드), 자신의 사이트, 권리가 있는 클라이언트 작업, 또는 개인 연습 위 모든 것 + 글꼴, 크기, 간격, 색상, 반경, 그림자, 에셋; 스크린샷 불일치 ≤ 2% (정지 상태에서 ≤ 0.5%), 측정된 이동 없음 변경 요청하지 않은 것은 없음 mixed "X를 클론하고 Y를 추가" 클론된 부분은 위 중 하나의 수준 추가 부분 (분리하여 표시, 클론을 깨뜨리지 않는지 확인) - 권리: 다른 회사 UI, 로고, 일러스트레이션, 글꼴 및 카피의 픽셀 완벽 복사본은 해당 회사의 것입니다. 학습 목적으로만 또는 허가를 받아 사용하고, 사용자 자신의 작업으로 게시하지 마세요. 참조가 타사 제품이고 사용자가 출시하려는 경우, 기본적으로 motion-faithful을 사용하고 그 이유를 설명하세요.
- 대상: 코드가 들어갈 위치와 스택.
package.json, 기존 컴포넌트, 스타일링 시스템(Tailwind 설정, CSS 변수, 디자인 토큰) 및 이미 사용 중인 애니메이션 라이브러리를 읽고, 새 라이브러리를 추가하기보다 일치시키세요.
1. 입력 방법 선택 (가장 정확한 방법을 사용하고 어떤 방법을 사용하는지 명시)
| 입력 | 캡처 | 얻는 것 |
|---|---|---|
| 라이브 URL | inspect_web.mjs + capture_web.mjs | 정확한 CSS 값, 글꼴, 선언된 지속 시간/지연/이징, 키프레임; 가상 시계를 사용한 프레임 정확 녹화 |
| 로컬 개발 서버 (우리 것) | http://localhost:…에 동일한 스크립트 | 모든 비교의 "our" 측, 참조와 동일하게 캡처 |
| 비디오 / GIF / 화면 녹화 (웹 or 앱) | ref_frames.py | 소스 fps의 모든 프레임 + 타이밍/포즈 시트; 픽셀에서 측정된 값 |
| Figma | figma_fetch.py (토큰) 또는 내보낸 PNG 프레임 | 정확한 크기, 간격, 자동 레이아웃, 타이포그래피, 색상, 효과, 프로토타입 전환 + 참조 PNG |
| 모바일 앱 | 화면 녹화 (참조); 우리 것: xcrun simctl io booted recordVideo ours.mp4 (iOS 시뮬레이터) 또는 adb shell screenrecord (Android) | 비디오; 우리 것도 동일한 방식으로 캡처 |
| 결합: URL 값 + 트리거하기 어려운 상호작용(로그인된 흐름, 드래그)을 위한 녹화; Figma 값 + "내 빌드가 디자인과 일치하는지" 확인하기 위한 개발 서버; 비디오 참조 + 우리 것 캡처를 위한 개발 서버. 로그인이 필요한 페이지: 화면 녹화 또는 사용자 로그인 요청; 절대 비밀번호를 처리하지 마세요. |
2. 참조 캡처 및 측정
URL:
inspect_web.mjs --url URL --selector "<section>" --out ui-clone/<name>/ref [--state hover --target "<btn>"]→inspect.md: 요소별 박스 + 계산된 스타일, 선언된 트랜지션, 실행 중인 애니메이션(키프레임 포함), @keyframes, 글꼴, 감지된 라이브러리(GSAP, Framer Motion, Lottie, three.js, Lenis...), 캔버스(2d/WebGL), 호버/포커스 차이. 선언된 값이 측정된 값보다 우선합니다: 복사하세요.capture_web.mjs --url URL --selector "<section>" --trigger load|hover|click|scroll|none --duration 2 --fps 30 --out ui-clone/<name>/ref→ frames/, video.mp4, frames.json, animations.json. 기본--mode seek(가상 시계: Playwright 시계의 JS 타이머 및 requestAnimationFrame, CSS/Web 애니메이션은 일시 중지되고 각 프레임에서 탐색: 동일한 캡처). 가상 시계가 깨지는 페이지(비디오 요소, 일부 WebGL/캔버스 라이브러리)에는--mode realtime을 사용하고 그 이유를 명시하세요.--still은 픽셀 작업을 위한 하나의 안정된 스크린샷 제공;--dpr 2는 레티나 선명 비교용 (작은 요소는--dpr 3: 12px 호버 증가는 1x에서 이징을 맞추기에는 픽셀이 너무 적음);--pad 12는--selector주위에 여백을 추가하여 호버/스케일 효과가 정지 박스 밖으로 커지는 것을 프레임 안에 잡음;--viewport 390x844는 휴대폰용. 탐색 모드는 실행 간 프레임 동일성이 검증됨.--mode realtime은 머신이 허용하는 만큼 빠르게 실제 스크린샷을 찍고(일반 노트북에서 ~19/초) 리샘플링; 달성된 속도를 출력: 타이밍은 그 속도만큼 정확합니다. 비디오 / GIF / 녹화:ref_frames.py REF.mp4 --out ui-clone/<name>/ref [--start --end --crop x:y:w:h]. Figma:figma_fetch.py --url "<figma link with node-id>" --out ui-clone/<name>/figma --scale 2→ design.md/json + frame.png. 그런 다음 모션 측정 (프레임이 있는 모든 입력):- 컷 및 섹션:
motion_compare.py <ref> <ref> --out <ref>/self --no-align. - 색상:
track_motion.py <ref>/frames --sample X,Y --at T. - 각 움직이는 요소:
track_motion.py <ref>/frames --name el --colors HEX,HEX --tol 35 --region x,y,w,h(복잡한 참조에는 항상 영역 지정). - 각 이동:
fit_easing.py <ref>/track_el.json --prop cx|cy|w|h|aspect|presence --from A --to B→ 타이밍, 이징, 오버슈트, 및 붙여넣기 준비된 CSS / WAAPI / Framer Motion / GSAP / Remotion 코드. 오류 ≤ 0.03 = 근접 적합; "단일 이징으로 맞지 않음" = 윈도우 분할 또는 키프레임 체인. 차점자의 오차가 최적의 오차와 약 0.003 이내이면 동점으로 처리 (예: easeOutQuad 0.58초 vs easeOutCubic 0.80초가 동일한 프레임에 적합): 명시하고,inspect.md, 소스 코드 또는 시트의 선언된 값을 선호하여 결정하세요. 추적은 색상으로만 요소를 보므로 이동하면서 페이드 인하는 요소는 늦게 시작하는 것처럼 보입니다: 웹 입력의 경우 선언된 값을 대신 사용하세요. 모든 시트(sheets/poses.png,sheets/timing_NN.png)를 직접 읽으세요: 숫자는 그것을 말하고, 시트는 무엇을 말합니다.
3. 사양 작성 (ui-clone/<name>/spec.md; 모든 행은 검사 항목이 됨)
- 구조 및 정적 스타일 (pixel-faithful): 요소 → 박스, 글꼴(패밀리/크기/두께/줄 높이/자간), 색상, 반경, 그림자, 간격; 출처 (
inspect.json/design.json/ 측정값). - 타임라인 (motion):
| # | 요소 | 속성 | 시작 → 끝 | 시작 ms | 지속 시간 ms | 이징 | 스태거 / 반복 | 트리거 | 출처 |. - 움직이지 않는 것을 기록하세요. "?"는 참조가 아직 읽히지 않았음을 의미합니다. 큰 빌드 전에 사양을 보여주세요.
4. 빌드
사용자의 스택 및 디자인 시스템에서. 선언된 값을 정확히 복사(pixel-faithful)하거나 상대적 비율(motion-faithful)로 복사하세요. 이징은 inspect.json 또는 fit_easing.py의 라이브러리별 라인에서 가져오고; 참조가 오버슈트 후 안정되면 스프링 사용; 스태거는 base + index × step으로. prefers-reduced-motion을 존중하세요 (최종 상태 표시). 추가 사항은 별도 컴포넌트에 유지하세요. 우리 것에 참조 뷰포트와 동일한 트리거로 컴포넌트를 렌더링하는 경로/페이지를 제공하여 동일하게 캡처할 수 있도록 하세요. WebGL 효과: 참조가 보여주는 것(또는 사용자가 사용할 수 있는 읽을 수 있는 소스)에서 셰이더 재구축; 시간에서 고정 타임스텝, 시드된 무작위성.
5. 검증, 수정, 반복 (2-5회; 각 회차 폴더 유지)
- 참조와 동일한 명령어로 우리 것을 캡처합니다 (
--url/입력 및--out만 변경), 또는 비디오 입력의 경우ref_frames.py OURS.mp4 --out ui-clone/<name>/ours --like <ref>/frames.json. - 픽셀:
screenshot_diff.py <ref>/still.png <ours>/still.png --out ui-clone/<name>/diff-N [--strict] [--max 0.02] [--mask x,y,w,h](pixel-faithful: 항상--strict사용: 픽셀당 임계값 0.03, 최대 0.5%, 색상이 RGB 레벨 3 이상 변하는 모든 영역은 실패; 기본값은 관대하여 작은 패딩과 색상 변화를 허용함) → 불일치 %, 최악 영역, 전체 이미지 또는 요소별 이동 ("영역 ...에서 +0px x, +6px y 이동"), 색상 드리프트,side_by_side.png. 이동을 먼저 수정하고 (모든 것을 잘못 보이게 만듦), 그 다음 크기, 그 다음 색상. Pixel-faithful은 측정된 이동이 있으면 실패; motion-faithful은--allow-shift와 더 느슨한--max를 사용합니다. - 모션:
motion_compare.py <ref> <ours> --out ui-clone/<name>/compare-N(컷, 이동, 오프셋; PASS ±0.08초;activity.png,sheets/compare_NN.png) 및 사양 행별로fit_easing.py REF_TRACK --prop P --from A --to B --vs OUR_TRACK. - 매 회차 시트를 읽으세요. 증거가 가리키는 가장 작은 것을 변경하고; 다시 캡처; 다시 비교.
- 5회 후에도 여전히 실패하는 모든 행을 해당 숫자와 이유(글꼴 라이선스, 근사된 WebGL 효과, 눈으로 조정된 스프링)와 함께 보고하세요. 절대 임계값을 조용히 완화하지 마세요.
| 증상 | 일반적인 원인 | 수정 |
|---|---|---|
| 전체 이미지 Npx 이동 | 다른 스크롤/오프셋/자르기 또는 누락된 래퍼 마진 | 뷰포트, dpr, 자르기 일치; 외부 간격 수정 |
| 요소 이동 | 마진/패딩/줄 높이/간격 차이 | inspect.json / design.json으로 박스 비교 |
| 텍스트 전체가 약간 어긋남 | 대체 글꼴, 다른 두께 또는 자간 | 동일한 글꼴(또는 사용자의 라이선스된 등가물) 로드, 크기/두께/추적 일치 |
| 모든 곳에서 색상이 약간 어긋남 | 색상 공간, 불투명도 스태킹, 그라데이션 중단점 | 계산된 색상/그라데이션 복사; 상위 요소의 불투명도 확인 |
| 모션이 한 오프셋만큼 이동 | 트리거 지연 또는 지연 누락 | 첫 번째 지연 수정 |
| 우리 것이 앞당겨짐 / 너무 빠름 | 더 강한 이징 (expo vs cubic) | 피팅된 베지어 또는 선언된 이징 사용 |
| 참조는 오버슈트, 우리 것은 아님 | 스프링/백 vs 베지어 | 측정된 오버슈트 및 안정화에 맞게 조정된 스프링/백 |
| 스크롤 애니메이션이 일찍/늦게 시작 | 트리거 임계값/오프셋 | 모션이 시작되는 스크롤 위치 일치 |
| 우리 것에 추가 이동 발생 | 잘못된 트랜지션 (예: transition: all) | 애니메이션되어야 하는 속성으로만 트랜지션 제한 |
6. 보고서 (단독으로 완전해야 함)
충실도 수준 및 클론/추가된 내용; 변경된 파일 및 모션 트리거 방법; 마지막 회차 표 (픽셀 불일치 및 이동; 컷/이동 타이밍; 요소별 이징), side_by_side.png, activity.png 및 비교 시트 경로; 남아 있는 모든 차이점과 숫자 및 이유; 측정된(스크립트가 생성) 검사와 육안으로 확인된(시트를 본) 검사 구분.
한계
- 가상 시계 캡처는
<video>재생 또는 일부 GPU/물리 라이브러리를 제어할 수 없음:--mode realtime을 사용하고 ±1-2프레임 지터 예상; 명시할 것. - 교차 출처 스타일시트 및 글꼴은 @keyframes/@font-face 규칙을 검사에서 숨길 수 있음; 계산된 스타일 및 실행 중인 애니메이션은 여전히 읽힘.
- 비디오에서 3D는 카메라/객체 모션으로 일치되며, 모델이나 재질이 아님; 바쁜 라이브 액션은 정확한 요소 값이 아닌 리듬을 제공.
- 모바일: 값은 녹화에서 가져옴 (소스 없음); 우리 것의 시뮬레이터 캡처도 동일한 방식으로 비교.