/pixel-loop compare — 디자인 vs 실제 화면 "다른 점 찾기"#

한마디로#

디자인 시안(Figma)과 실제로 만든 화면(스크린샷)을 나란히 겹쳐 놓고 "어디가 다른지" 찾아주는 검사기입니다. 틀린 그림 찾기처럼, 버튼 위치가 8px 내려갔다거나 글씨 굵기가 다르다거나 하는 차이를 골라냅니다. 단, 고치지는 않고 보고만 합니다.

누가·언제 쓰나요#

• 코드 리뷰나 디자인 QA를 할 때 — "시안대로 잘 나왔나?"를 빠르게 확인하고 싶은 경우
• 직접 화면을 수정하는 작업까지는 필요 없고, 차이만 점검(읽기 전용) 하고 싶을 때

무엇을 해주나요#

검사 결과를 두 가지 형태로 남겨 줍니다.

• 구조화된 리포트 파일 — .claude/docs/pixel-loop/compare_<시각>.yaml (요소별로 무엇이 얼마나 다른지 기록)
• 사람이 읽기 쉬운 요약 — 일치한 항목 / 어긋난 항목 / 허용 오차 안에 든 항목의 개수

예를 들어 "PrimaryButton이 시안보다 8px 아래로 내려감(주요 문제)", "TitleText 글씨 굵기가 600이어야 하는데 500임(사소한 문제)" 처럼 콕 집어 알려 줍니다.

어떻게 쓰나요#

# 기본 사용 (시안 URL + 비교할 스크린샷)
/pixel-loop compare --figma  " < Figma 프레임 URL(node-id 포함) > "   --screenshot  " < PNG 경로 > " 

 # 허용 오차를 직접 지정 (이 정도 차이는 같은 것으로 봄)
/pixel-loop compare --figma  " ... "   --screenshot  " ... "   --tolerance pixel=1,color_delta_e=2

# 리포트를 저장할 위치를 직접 지정
/pixel-loop compare --figma  " ... "   --screenshot  " ... "   --output  " .claude/docs/pixel-loop/my_report.yaml "

• --figma (필수): 비교할 디자인 시안의 Figma 프레임 주소 (node-id 포함)
• --screenshot (필수): 비교할 실제 화면 PNG 경로 (절대경로 또는 .claude/docs/ 아래)
• --tolerance (선택): 픽셀·색상 허용 오차. 기본값은 pixel=1,color_delta_e=2
• --output (선택): 리포트 저장 위치. 기본값은 .claude/docs/pixel-loop/compare_<시각>.yaml

안에서 무슨 일이 벌어지나요#

1. Figma에서 비교 대상 디자인 정보를 가져옵니다.
2. 시안 기준으로 "이렇게 나와야 한다"는 레이아웃·글꼴·색상 기준표를 만듭니다.
3. 실제 스크린샷을 불러와, 요소 하나하나의 위치·크기를 기준표와 대조합니다.
4. 차이점을 정리한 YAML 리포트와 사람이 읽기 쉬운 요약을 작성합니다.

참고: 차이를 직접 고쳐 주길 원한다면 /pixel-loop loop --mode=repair를, 비교 전에 새 스크린샷부터 찍어야 한다면 /pixel-loop capture를 사용하세요.

file: .claude/docs/pixel-loop/compare_ < ts > .yaml
summary:
  matched: 27
  mismatched: 3
  within_tolerance: 1
diff:
  - element: PrimaryButton
    kind: layout
    expected: { x: 24, y: 312, width: 327, height: 48 }
    actual:   { x: 24, y: 320, width: 327, height: 48 }
    delta:    { y: +8 }
    severity: major
  - element: TitleText
    kind: typography
    expected: { weight: 600, size: 22 }
    actual:   { weight: 500, size: 22 }
    severity: minor