| name | visual-verdict |
| description | 스크린샷 vs 레퍼런스 이미지 비교를 통한 시각적 QA 판정 스킬.
디자인 시안(Figma export 등)과 실제 구현 스크린샷을 비교하여
score/verdict/differences/suggestions를 구조화된 JSON으로 반환한다.
Ralph 루프와 통합하여 90+ 점수까지 반복 개선할 수 있다.
Use when: "/visual-verdict", "비주얼 체크", "디자인 비교", "스크린샷 비교",
"visual check", "visual QA", "디자인이랑 비교해줘", "구현 확인",
"이거 디자인대로야?", "화면 비교", "UI 검증", "design diff".
Also use PROACTIVELY after writing HTML/CSS/frontend code when a reference
design image exists in the project.
|
| allowed-tools | ["Read","Bash","Glob","Write"] |
/visual-verdict — 시각적 QA 판정 루프
레퍼런스 이미지(디자인 시안)와 현재 구현 스크린샷을 비교하여
구조화된 판정을 내린다. Ralph 루프 안에서 매 iteration마다 실행하여
시각적 품질이 목표 점수에 도달할 때까지 반복한다.
Why This Exists
코드만 봐서는 UI가 디자인대로 구현됐는지 알 수 없다. 이 스킬은 Claude의
멀티모달 능력을 활용하여 두 이미지를 직접 비교하고, 차이점을 구조화된
피드백으로 변환한다. "눈으로 확인" 단계를 자동화하는 것이다.
When to Use
| 상황 | 사용? |
|---|
| 디자인 시안이 있고 구현 스크린샷이 있음 | YES |
| Ralph 루프 안에서 visual iteration | YES |
| HTML/CSS 작성 후 디자인 대조 | YES |
| 백엔드 API 코드 리뷰 | No — /pr-reviewer 사용 |
| 디자인 시안 분석 (구현 없이) | No — /figma-analyzer 사용 |
Input
두 가지 이미지가 필요하다:
| 이미지 | 설명 | 형식 |
|---|
| Reference | 디자인 시안 (목표 상태) | PNG/JPG 파일 경로 또는 Figma export |
| Current | 현재 구현 스크린샷 | PNG/JPG 파일 경로 또는 브라우저 캡처 |
입력 파싱
/visual-verdict <reference_path> <current_path>
/visual-verdict --ref design.png --current screenshot.png
/visual-verdict (인자 없으면 프로젝트에서 자동 탐색)
자동 탐색 모드 (인자 없을 때):
.dev/designs/ 또는 designs/ 또는 assets/ 에서 레퍼런스 이미지 검색.dev/screenshots/ 또는 /tmp/ 에서 최근 스크린샷 검색- 매칭되는 쌍이 있으면 사용, 없으면 사용자에게 경로 질문
Protocol
Step 1: 이미지 로드 및 비교
두 이미지를 Read tool로 읽는다 (Claude는 이미지를 직접 볼 수 있다).
비교 관점 (5개 축):
- Layout: 요소 배치, 간격, 정렬
- Typography: 폰트 크기, 굵기, 색상, 행간
- Colors: 배경색, 텍스트 색, 브랜드 컬러 일치
- Components: 버튼, 입력 필드, 카드 등 UI 컴포넌트 형태
- Content: 텍스트 내용, 아이콘, 이미지 일치
Step 2: 점수 산출
각 축별 점수 (0-20, 총합 100):
| 축 | 가중치 | 채점 기준 |
|---|
| Layout | 20점 | 요소 위치/크기가 레퍼런스와 일치 |
| Typography | 20점 | 폰트 스타일이 레퍼런스와 일치 |
| Colors | 20점 | 색상 팔레트가 레퍼런스와 일치 |
| Components | 20점 | UI 컴포넌트 형태/상태가 일치 |
| Content | 20점 | 텍스트/아이콘/이미지 내용 일치 |
Step 3: Verdict 판정
| Score | Verdict | 의미 |
|---|
| 90-100 | PASS | 디자인과 충분히 일치. 반복 종료 가능. |
| 70-89 | ITERATE | 대부분 일치하지만 개선 필요. 다음 iteration 진행. |
| 50-69 | MAJOR_DIFF | 상당한 차이. 여러 항목 수정 필요. |
| 0-49 | REDESIGN | 근본적 차이. 접근 방식 재검토 필요. |
Step 4: 구조화된 출력
{
"score": 75,
"verdict": "ITERATE",
"breakdown": {
"layout": { "score": 18, "max": 20, "notes": "헤더 높이 4px 차이" },
"typography": { "score": 15, "max": 20, "notes": "본문 폰트 크기 14px → 16px 필요" },
"colors": { "score": 20, "max": 20, "notes": "일치" },
Step 5: 피드백 파일 저장
결과를 .dev/visual-verdicts/ 에 저장하여 iteration 히스토리를 추적한다:
mkdir -p .dev/visual-verdicts
파일명: {component}-verdict-{iteration}.json
Step 6: Ralph 루프 연동 (선택)
Ralph 루프 안에서 사용할 때:
- 매 iteration 후
/visual-verdict 실행
- Score ≥ 90 → PASS → Ralph 루프 DoD 충족
- Score < 90 →
suggestions 기반으로 코드 수정 → 재스크린샷 → 재판정
Ralph 통합 출력:
Visual Verdict: ITERATE (75/100)
- Layout: 18/20
- Typography: 15/20 ← 본문 폰트 크기 수정 필요
- Colors: 20/20 ✓
- Components: 12/20 ← 버튼 border-radius 불일치
- Content: 10/20 ← placeholder 누락
다음 iteration에서 수정할 항목:
1. font-size: 14px → 16px (Typography +5)
2. border-radius: 4px → 8px (Components +4)
3. placeholder 텍스트 추가 (Content +6)
예상 점수: 90/100 → PASS 가능
마크다운 출력 (대화용)
JSON 출력과 함께, 사용자에게는 읽기 쉬운 마크다운으로도 결과를 보여준다:
## Visual Verdict: {verdict} ({score}/100)
### 점수 상세
| 축 | 점수 | 비고 |
|----|------|------|
| Layout | 18/20 | 헤더 높이 4px 차이 |
| Typography | 15/20 | 본문 폰트 크기 불일치 |
| Colors | 20/20 | 일치 |
| Components | 12/20 | 버튼 border-radius 불일치 |
| Content | 10/20 | placeholder 텍스트 누락 |
### 차이점
1. **헤더 영역**: 높이 64px → 60px, 로고 정렬 불일치
2. ...
### 수정 제안
1. `font-size: 16px` 적용
2. `border-radius: 8px` 적용
3. placeholder 텍스트 추가
Checklist Before Stopping
