inspector:visual-verify

Runtime visual verification: Maestro screenshot + Figma diff (no code edits).

항목	내용
Invoke	/inspector:visual-verify
Category	cocode-flutter
Complexity	moderate
MCP Servers	flutter-inspector, maestro, figma, dart

/inspector/visual-verify — 화면이 디자인대로 나왔는지 "사진 찍어 대조"#

한마디로#

실제로 돌아가는 앱 화면을 사진으로 찍어, Figma 디자인 원본과 나란히 놓고 "다른 점"을 찾아주는 검사기입니다. 코드를 고치지는 않고, 어디가 어떻게 다른지 리포트만 만들어 줍니다.

누가·언제 쓰나요#

디자이너·기획자: "지금 앱 화면이 우리 Figma 시안과 정말 똑같이 나왔나?"를 확인하고 싶을 때
개발자: 코드를 직접 건드리지 않고, 화면과 디자인의 차이만 빠르게 점검하고 싶을 때
화면 한 개뿐 아니라 여러 화면(/home, /settings, /profile 등)을 한 번에 점검하는 "회귀 검사"가 필요할 때

무엇을 해주나요#

지정한 화면을 실제로 띄워 사진을 찍고, Figma 시안과 비교해 다른 점을 정리한 리포트 파일을 만들어 줍니다.

찍은 화면 사진 (예: screens/after.png)
차이 리포트 파일: .claude/docs/inspector/visual-verify/<실행ID>/diff.yaml
- 예: 글자 굵기 500 → 600, 배경색 #F9FAFB → #FFFFFF 처럼 "무엇이 어떻게 달라졌는지" 목록
여러 화면을 검사하면 화면별 리포트와 전체 요약까지 함께 만들어 줍니다

차이를 자동으로 "고쳐주지는 않는다"는 점이 핵심입니다. 고치는 작업은 별도 명령(/pixel-loop)에 넘깁니다.

어떻게 쓰나요#

# 기본: 화면 하나를 Figma 시안과 비교
/inspector/visual-verify \
  --figma=https://www.figma.com/design/AbCd/Home?node-id=12-345 \
  --route=/home

# 여러 화면을 한 번에 점검 (회귀 검사)
/inspector/visual-verify --figma= < file-url >   \
  --routes=/home,/settings,/profile \
  --mode=regression

--figma (필수): 비교 기준이 되는 Figma 시안 주소 (node-id 포함)
--route (필수): 검사할 앱 화면 경로 (/home, /posts/123 등)
--mode: verify(기본) / verify-after-reload(방금 고친 화면을 다시 불러와 찍기) / regression(여러 화면 한 번에)
--routes: --mode=regression일 때 검사할 화면 목록을 쉼표로 나열
--target: 어느 기기에서 찍을지 (ios/android/macos/linux/windows/auto)
--tolerance: 어느 정도까지 "같다"고 봐줄지 허용 오차 (기본 pixel=1,color_delta_e=2)

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

Figma 시안을 불러와 "이렇게 나와야 한다"는 기준을 정합니다.
앱을 실행해 지정한 화면으로 이동한 뒤, 그 화면의 사진을 찍습니다.
화면의 구성 요소(위젯 구조)도 함께 살펴 비교 정확도를 높입니다.
시안과 사진을 대조해 다른 점을 골라내고, 차이 리포트 파일(diff.yaml)로 저장합니다.
verify-after-reload 모드면 사진 찍기 전에 방금 고친 내용을 다시 불러와(핫 리로드) 최신 화면을 찍습니다.
regression 모드면 화면 목록을 하나씩 돌며 모두 찍고, 화면별 리포트 + 전체 요약을 만듭니다.

이 명령은 한 번 검사해 리포트만 남기고 끝납니다. 차이를 실제로 맞춰 고치고 싶다면 /pixel-loop로 넘겨주세요.

⚙️ 상세 옵션·실행 명세 (개발자 / AI 에이전트용)

Parameters#

Parameter	Required	Description
`--figma`	✅	Figma frame URL (with `node-id`)
`--route`	✅	In-app route to verify (`/home`, `/posts/123`, …)
`--mode`	❌	`verify` (default), `verify-after-reload`, or `regression`
`--routes`	conditional	Comma-separated list for `--mode=regression`
`--target`	❌	`ios`/`android`/`macos`/`linux`/`windows`/`auto`
`--tolerance`	❌	`pixel=N,color_delta_e=N` (default `pixel=1,color_delta_e=2`)

Phase Flow#

`verify` (default)#

figma.getNode(nodeId) → expected spec.
Maestro: launch (no clearState) → navigate → screenshot.
flutter-inspector.ui_get_widget_tree for structural context.
Agent diffs and writes .claude/docs/inspector/visual-verify/<run_id>/diff.yaml.

`verify-after-reload`#

Adds a dart.hotReload() step before Maestro launches, so the freshly edited UI is captured. Use after a single-line tweak when you don't want to relaunch the app.

`regression`#

/inspector/visual-verify --figma= < file-url >   \
  --routes=/home,/settings,/profile \
  --mode=regression

Iterates each route, captures each screenshot, and writes a per-route diff plus an aggregate summary.

Example#

/inspector/visual-verify \
  --figma=https://www.figma.com/design/AbCd/Home?node-id=12-345 \
  --route=/home

Output:

[1/1] Capture  ✓ screens/after.png (iOS Simulator)
[1/1] Diff     2 deltas (TitleText weight 500→600, BG #F9FAFB→#FFFFFF)
Report: .claude/docs/inspector/visual-verify/20260511-1132/diff.yaml

Convergence#

This command does not loop or edit. It produces a single report. If you want the agent to converge the deltas, hand off to /pixel-loop loop <figma-url> --mode=repair --route=<route>.

Skill: cc-flutter-inspector:visual-verify
Edit loop: cc-flutter-pixel-loop:pixel-loop
Generic UI introspection: cc-flutter-inspector:inspector/ui