pixel-loop

한마디로#

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

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

무엇을 해주나요#

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

어떻게 쓰나요#

# 새 화면 구현 (Figma 섹션 주소와 앱 경로)
/pixel-loop loop https://www.figma.com/design/<key>/<name>?node-id=<id> --app <앱 경로>

# 시안에서 어긋난 화면을 다시 맞추기
/pixel-loop loop <figma-url> --mode=repair --app <앱 경로>

# 고치지 않고 판정만 — 섹션의 상태 프레임 전부를 라이트 · 다크로
/pixel-loop verify --section <figma-url> --app <앱 경로>

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

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

• Figma 시안 주소만 주면 자동으로 새 화면을 만드는 모드(--mode=create)로 시작합니다.
• --mode=repair는 이미 있는 화면을 다시 맞추는 모드로, 고치기 전 비교를 한 번 더 남깁니다.
• 기본은 기기 없이 테스트로 화면을 그립니다. 실행 중인 앱으로 맞추려면 --source=device 와 화면 경로(--route, 예: /home) · 기기(--target)를 함께 줍니다.
• 그 밖에 허용 오차(--tolerance), 반복 횟수 제한(--iteration-cap) 같은 옵션을 붙일 수 있습니다.

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

1. 사전 점검 — Figma 시안을 실제로 읽을 수 있는지(연결 목록이 아니라 읽기로) 확인하고, 실행 중인 앱으로 맞출 때는 Dart 연결과 앱과의 연결(Marionette)도 확인합니다. 하나라도 안 되면 멈추고 /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 --source=render

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

# Drift repair
/pixel-loop loop <figma-url> --mode=repair --app <app>

# Verdict for every state frame of a section (no code change)
/pixel-loop verify --section <figma-url> --app <app>

# Diagnostic — one frame against an existing screenshot (the frame's pinned theme only; not the completion gate)
/pixel-loop verify --frame <figma-url> --screenshot .claude/docs/pixel-loop/home_actual.png --scale 2

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

# First-time setup
/pixel-loop setup