/pixel-loop — 디자인 똑같이 맞추기 자동 루프#

한마디로#

Figma 디자인 시안과 실제 앱 화면을 나란히 놓고 틀린 곳을 찾아 자동으로 고치기를 반복해, 화면을 시안과 픽셀 단위로 똑같이 맞춰 주는 기능입니다. "시안 보고 → 코드 고치고 → 앱 새로고침하고 → 화면 찍어서 → 시안과 비교"를 사람이 만족할 때까지 알아서 돌려 주는 자동 검수 루프예요.

누가·언제 쓰나요#

• 새 화면을 디자인 시안 그대로 만들고 싶을 때 ("이 Figma 화면을 픽셀 퍼펙트로 구현해 줘")
• 만들어 둔 화면이 시안에서 어긋났을 때 다시 맞추고 싶을 때 ("이 화면이 디자인이랑 달라졌어 — 고쳐 줘")
• 특정 화면이 시안과 얼마나 다른지 점검(audit) 하고 싶을 때

무엇을 해주나요#

• 앱 화면을 Figma 시안과 픽셀 단위로 비교해 차이 나는 부분을 찾아내고, 코드를 고쳐 시안에 가깝게 맞춰 줍니다.
• 비교에 쓴 스크린샷과 비교 결과 파일이 .claude/docs/pixel-loop/<날짜-시각>/ 폴더에 정리되어 남습니다.
• 처음 쓰는 경우엔 필요한 연결 도구(Figma / Maestro / Dart)를 한 번에 설치·등록해 줍니다.

어떻게 쓰나요#

# 새 화면 구현 (Figma 시안 주소만 주면 시작)
/pixel-loop loop https://www.figma.com/design/ < key > / < name > ?node-id= < id > 

 # /home 화면이 시안에서 어긋난 것을 다시 맞추기
/pixel-loop loop  < figma-url >   --mode=repair --route=/home

# 한 번만 비교해서 점검 (기존 스크린샷 vs 시안)
/pixel-loop compare --figma= < figma-url >   --screenshot=.claude/docs/pixel-loop/home_actual.png

# 화면 스크린샷만 한 장 찍기
/pixel-loop capture --route=/home --label=baseline

# 처음 쓸 때 도구 설치·등록
/pixel-loop setup

• Figma 시안 주소만 주면 자동으로 새 화면을 만드는 모드(--mode=create)로 시작합니다.
• --mode=repair는 이미 있는 화면을 다시 맞추는 모드로, 어떤 화면인지 --route(예: /home)를 같이 알려 줘야 합니다.
• 그 밖에 허용 오차(--tolerance), 반복 횟수 제한(--iteration-cap), 비교에 쓸 기기 선택(--target) 같은 옵션을 붙일 수 있습니다.

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

본격적으로 돌기 전에 먼저 준비 상태부터 확인합니다.

1. 사전 점검 — Dart 연결, 화면을 띄울 기기(Maestro) 연결, Figma 시안 접근이 모두 가능한지 확인합니다. 하나라도 안 되면 멈추고 /pixel-loop setup을 먼저 돌리라고 안내합니다.
2. 반복 루프 — 시안을 읽고(Read) → 코드를 고치고(Write) → 앱을 새로고침하고(Reload) → 화면을 찍어(Capture) → 시안과 비교(Compare)하는 과정을, 차이가 허용 오차 안에 들 때까지 반복합니다.
3. 결과 정리 — 비교에 쓴 스크린샷과 결과를 .claude/docs/pixel-loop/<날짜-시각>/ 폴더에 저장합니다.

/pixel-loop  < subcommand >   [args...]

/pixel-loop loop  < figma-url >   --mode=create --target=auto

# New screen implementation
/pixel-loop loop https://www.figma.com/design/ < key > / < name > ?node-id= < id > 

 # Drift repair on /home
/pixel-loop loop  < figma-url >   --mode=repair --route=/home

# One-shot audit
/pixel-loop compare --figma= < figma-url >   --screenshot=.claude/docs/pixel-loop/home_actual.png

# Just grab a screenshot
/pixel-loop capture --route=/home --label=baseline

# First-time setup
/pixel-loop setup