시각 검토 계약

1. 구조 검사: CoUI 인스턴스·토큰·레지스트리·L0.
2. 동작 검사: 상태 전이·라우트·저장·런타임 스모크.
3. 시각 검토: 실제 PNG를 열어 위계·구성·타이포·밀도·도메인 표현을 비평한다.

1·2가 통과해도 3의 통과로 기록하지 않는다. 이미지 파일 생성, 픽셀 차이 수치, 자동 미학 점수만으로 3을 판정하지 않는다. 리뷰어가 열지 못한 화면은 미검토다.

대표 화면 먼저#

전체 프레임/상태를 복제하거나 구현 그룹을 시작하기 전에 각 surface(site/app/console)의 진입 화면, 핵심 행동 화면, 가장 조밀한 화면을 고른다. 같은 화면이면 중복하지 않는다. 서비스 고유 데이터의 관계를 무엇으로 표현할지 적는다: 시간축, 추이, 일정, 개체 비교, 진료 기록, 주문 이행 등. 제목만 바꾼 동일 카드 목록은 선택의 근거가 될 수 없다.

CoUI는 부품/토큰 계약이다. 모든 화면에 KPI 4개와 흰 카드 더미를 요구하지 않는다. 대표 화면 실제 PNG를 cc-designer:critique-screen의 독립 리뷰어에게 브리프·결정 정보와 함께 전달한다. 저작자의 변명/DDR은 첫 크리틱에 주지 않는다. 이 계약은 독립 검토를 위한 서브에이전트 위임을 허용한다. 독립 리뷰어를 사용할 수 없으면 실제 작성자 ID를 유지하고 review_mode: separate_pass, independence_limitation, review_method를 기록한다. 이 경우 새 검토 단계에서 렌더와 브리프를 다시 열어 관찰→지적→수정→재검토를 수행한다. 역할 이름만 바꿔 별도 사람/에이전트인 것처럼 기록하지 않는다. 독립 검토와 동일한 보증으로 보고하지 않으며, 가능한 환경에서는 독립 리뷰어를 우선한다. 위계·고유성·밀도·타이포·행동 발견성을 구체적으로 지적하고 고친 PNG를 다시 본다. 대표 화면 통과 시각을 기록한 후 나머지 화면을 확장한다. 이미 승인된 대표 화면을 재사용하면 그 리뷰와 이미지 해시를 연결한다. 단순 증분 변경은 영향받는 대표 화면만 다시 검토하되 생략 이유를 남긴다. 새 승인 질문을 요구하는 절차가 아니다.

PRD 화면 목록에서 검토 대상표를 먼저 만든다. required_cases는 이 표의 고정 ID다. 모든 화면의 Default, 주요 결정/검증/오류 상태, 지원하는 모바일·데스크톱·Light/Dark, 긴 번역/긴 데이터 경계값을 포함한다. 플랫폼 또는 상태가 적용되지 않는 경우 근거를 표에 적는다. 리뷰어는 표를 PRD/레지스트리와 대조한다. 코드 검증기는 심미성이나 표의 의미를 추론하지 않는다.

구현·배포는 같은 화면의 Figma PNG와 실제 앱 PNG를 나란히 열어 비교한다. viewport(가로/세로), state, theme, locale, fixture(같은 데이터·선택·스크롤 위치)가 같아야 한다. 폰트 로딩·아이콘·이미지·줄바꿈·정보 순서·빈 공간·주 행동 위치·가로 넘침을 확인한다. 차이를 고치거나 디자인 변경을 정식 반영해 새 PNG 쌍으로 재검토한다. 구현에 맞춰 증거 이미지만 바꾸거나 기존 골든을 무조건 갱신하지 않는다. 배포 PNG는 서빙된 source SHA의 실제 화면이다.

모든 지적에 case·문제·수정·재검토 증거를 연결한다. 미해결 지적이 있으면 quality 완료 금지. 범위 밖 제안은 지적과 분리해 설명할 수 있지만 발견된 결함을 제안으로 바꿔 통과시키지 않는다. 수정 예산을 소진하면 미완료를 보고한다. 관찰에 기반한 판정만 남기며 객관적 미학 점수는 만들지 않는다.

실행용 시작 양식#

templates/visual-review.{design,implement,publish}.example.json을 새 run의 evidence에 복사한다. 초기 verdict는 pending이라 그대로는 pass할 수 없다. 대표 세 surface 행을 실제 PRD ID로 바꾸고, 전체 화면·상태 검토 표에 맞춰 required_cases/cases를 늘린다. 실제 PNG를 연 뒤 관찰/비교와 reviewer를 기입하고 발견 지적을 기록한다. 재검토가 끝난 뒤에만 passed로 바꾼다. 과거 완료 run의 파일을 덮어쓰지 않는다.

receipt의 visual_review는 아래 보고서 경로다. 모든 경로는 run-dir 기준이며 PNG를 사용한다. source는 Figma node URL 또는 runtime URL+source SHA를 식별한다.

{
  "schema_version": 1,
  "stage": "implement",
  "verdict": "passed",
  "author": "screen-author",
  "reviewer": "independent-reviewer",
  "required_cases": ["APP-001-mobile-default-light-ko"],
  "cases": [{
    "id": "APP-001-mobile-default-light-ko",
    "screen_id": "APP-001", "surface": "app",
    "domain_composition": "오늘 일정과 완료 기록을 시간순으로 연결",
    "observation": "다음 일정의 시각과 행동이 기록 목록보다 먼저 읽힘",
    "comparison": "두 캡처에서 제목 위계·행 높이·CTA 위치 확인",
    "figma": {"source": "Figma node URL", "screenshot": "evidence/figma.png", "viewport": [390, 844], "state": "default", "theme": "light", "locale": "ko", "fixture": "pet-a-today-scroll-top"},
    "runtime": {"source": "runtime URL + source SHA", "screenshot": "evidence/runtime.png", "viewport": [390, 844], "state": "default", "theme": "light", "locale": "ko", "fixture": "pet-a-today-scroll-top"}
  }],
  "findings": [{"case": "APP-001-mobile-default-light-ko", "issue": "일정 시각이 본문에 묻힘", "fix": "시각과 다음 행동을 첫 행에 배치", "status": "resolved", "recheck": "evidence/recheck.md"}]
}

design은 runtime/comparison 대신 아래 필드가 추가된다. cases의 Figma 캡처는 최종 화면이다. 대표 검토 보고서/PNG는 representative_review.evidence에 포함해 해시를 고정한다.

{"representative_review": {"verdict": "passed", "cases": ["APP-001-mobile-default-light-ko"], "evidence": ["evidence/representative-review.md", "evidence/representative.png"], "reviewed_at": "2026-10-22T01:00:00+00:00"}, "expanded_at": "2026-10-22T01:10:00+00:00"}