UI diff은(는) 무엇을 하나요?
리뷰어는 CSS diff를 읽을 수 있지만, 직접 볼 수는 없습니다. 이 스킬은 PR의 기본(base)과 헤드(head)에서 앱을 렌더링하고 비교하여 before/after 이미지를 PR에 게시합니다. 이미지와 함께 측정된 값을 기반으로 사용자에게 변경된 내용을 간략히 요약하여 제공합니다.
기계적인 작업은 단일 스크립트가 담당합니다. 여러분의 역할은 판단이 필요한 부분, 즉 확인할 페이지, 변경 사항의 의미, 게시 위치를 결정하는 것입니다.
$SKILL은 이 SKILL.md가 포함된 디렉터리를 나타냅니다. 예를 들어 SKILL=/path/to/skills/ui-diff와 같이 한 번 설정하면 됩니다. 모든 출력은 리포지토리 루트의 .ui-diff/에 기록되며, 스크립트가 로컬에서 git-ignore 처리하므로 추적되는 변경 사항은 없습니다.
1. 컨텍스트
gh pr view --json number,url,baseRefName,headRefOid,body 2>/dev/null; git status --short
리포지토리 루트에 .ui-diff.json이 있다면 읽습니다. 여기에는 라우트, 개발 명령어, 마스크, 인증 정보가 포함될 수 있습니다(references/config.md 참조).
렌더링할 헤드는 사용자가 무엇을 하고 있는지에 따라 달라집니다:
- PR에 게시:
--head <headRefOid>를 전달하여 정확히 푸시된 상태를 렌더링합니다. 그렇지 않으면 커밋되지 않은 로컬 편집 내용이 PR을 보여준다고 주장하는 보고서에 포함됩니다. 작업 트리가 더티(dirty) 상태이거나 푸시되지 않은 커밋이 있는 경우 해당 변경 사항이 표시되지 않을 것임을 언급하세요. - 작업 중인 내용 확인("이게 맞나요?"): 작업 트리(기본값,
--head없음)를 사용합니다. 보고서에는 "+ 커밋되지 않은 변경 사항"이라고 표시됩니다.
2. 페이지 선택
node $SKILL/scripts/routes.cjs --base <base> --log # run.sh에 전달할 경우 --head <sha> 추가
변경된 파일을 라우트에 매핑합니다: 페이지 파일, 변경된 레이아웃 아래의 라우트, 변경된 컴포넌트를 임포트하는 페이지(별칭 및 워크스페이스 패키지 추적), 앱 전체 스타일을 위한 홈 및 몇 가지 잘 연결된 페이지. 각 라우트의 이유와 신뢰도, needsExample(채울 수 없는 동적 라우트), unmatched(배치할 수 없는 UI 파일)를 JSON으로 출력합니다. 이를 시작 목록으로 간주하고 references/route-mapping.md를 사용하여 판단을 적용합니다: diff가 지원하지 않는 낮은 신뢰도의 선택은 제거하고, needsExample의 ID를 찾고, unmatched 파일은 직접 배치합니다. UI와 관련된 변경 사항이 없는 경우(모든 파일이 ignored), 그렇게 말하고 중단합니다. 빈 보고서를 생성하지 마세요.
Storybook 프로젝트(.storybook/ 폴더 또는 storybook 스크립트): 변경 사항이 주로 컴포넌트에 있는 경우 run.sh --storybook을 사용하여 페이지 대신 스토리를 diff합니다. 스토리는 변경된 파일에서 자동으로 선택됩니다. 라우트, 레이아웃 및 앱 수준 스타일의 경우 페이지를 계속 사용하세요. references/route-mapping.md의 Storybook 섹션을 참조하세요.
캡처할 라우트와 그 이유를 한두 줄로 사용자에게 알린 후 계속 진행하세요. 라우트를 전혀 찾을 수 없거나 동적 라우트에 찾을 수 없는 ID가 필요한 경우에만 질문하세요. 영향을 받지만 캡처되지 않은 라우트(확인하기 너무 많음, 로그인 필요, 모달 상태)를 추적하세요. 이들은 요약에 포함되어 "시각적 변경 없음"이 완전한 안전 신호로 오해되지 않도록 합니다.
3. 실행
bash $SKILL/scripts/run.sh --routes "/,/pricing" [--head <sha>] [--base <ref>] \
[--viewports "desktop:1440x900,mobile:iPhone 13"] [--schemes light,dark] [--dev "<cmd with {port}>"]
(--auto-routes는 routes.cjs가 선택한 라우트를 이유와 함께 추가합니다. 수정할 사항이 없을 때 사용하세요.)
한 번에 다음을 수행합니다:
- 첫 사용 시 도구 설치(Playwright + Chromium,
~/.cache/ui-diff에, 약 1분 소요; 프로젝트 종속성은 건드리지 않음); - 기본(base)과
--head가 제공된 경우 헤드(head)를 git 워크트리(worktree)에서 체크아웃하고, 추적되지 않은.env*파일을 복사; - lockfile이 일치하면 설치된 종속성을 재사용하고(체크아웃별 빌드 캐시 포함), 그렇지 않으면 설치;
- 두 dev 서버를 각각의 프로세스 그룹에서 사용 가능한 포트로 시작. 이후 해당 서버만 중지되므로 사용자의 다른 서버는 영향을 받지 않음;
- 모든 라우트 × 뷰포트를 캡처. 모바일은 실제 디바이스 에뮬레이션(터치, 모바일 UA)을 사용. 애니메이션은 고정되고 프레임워크 dev 오버레이는 숨겨짐;
- 스크린샷을 픽셀 diff(
results.json, 전체 페이지 및 확대 이미지)하고 계산된 스타일 diff(measured.md)를 실행.
Storybook 모드(--storybook, 또는 직접 선택하려면 --stories "button--primary,card--*")는 dev 서버 대신 Storybook을 시작하고, 선택한 스토리와 이유를 기록하며, 결과를 스토리 ID로 이름 짓습니다. 일치하는 스토리가 없으면 종료하고 ID를 제안합니다.
{"changed":2,"added":1,"unchanged":3,...}와 같은 카운트를 출력합니다. 기본값: base = PR의 base 브랜치(없으면 기본 브랜치), viewports = 데스크톱 1440×900 + iPhone 13, 라이트 모드. 테마, 색상 또는 토큰을 변경하는 경우 --schemes light,dark를 추가하세요.
실패한 경우, 오류는 어떤 단계에서 실패했는지와 로그 위치(.ui-diff/server-*.log, install-*.log, capture-*.log)를 알려줍니다. 일반적인 원인은 누락된 환경 변수, 잘못된 dev 명령어(--dev 전달), 또는 작업 트리에 종속성이 설치되지 않은 경우입니다. 원인을 수정하고 다시 실행하세요. 한 쪽을 건너뛰지 마세요.
4. 결과 읽기 및 요약 작성
먼저 .ui-diff/report/measured.md를 읽으세요. Possible problems로 시작한다면 먼저 확인하세요: 잘린 텍스트, 가로 스크롤, 겹침, 화면 밖 컨트롤, 작은 모바일 터치 대상, 그리고 헤드에서 새로 발생한 axe-core 접근성 위반. 이들은 휴리스틱이므로 각 확대 이미지(report/issues/)를 열어 판단하세요. 실제 문제는 "확인 필요" 항목에 넣고, 의도적으로 보이는 것은 제외하거나 완화된 표현을 사용하세요. measured.md의 나머지 부분은 측정된 사실을 담고 있습니다: 요소별로 그룹화된 계산된 스타일 변경, 크기가 조정된 요소, 레이아웃 이동, 텍스트 변경, 새로운 WCAG 대비 오류. 그런 다음 확대 이미지(report/zoom/*__after.png 및 __before.png)와 diff 오버레이를 파일 또는 이미지 뷰어 도구로 열어 컨텍스트에서 어떻게 보이는지 확인하세요. 이미지를 볼 수 없는 경우 measured.md만으로 요약을 작성하고 스크린샷이 검토되지 않았다고 말하세요. results.json의 warnings도 확인하세요: HTTP 오류, 프레임워크 오버레이, 잡히지 않은 예외.
Figma 링크가 제공된 경우(또는 .ui-diff.json의 라우트에 figma가 있는 경우): 헤드를 디자인 프레임과 비교하세요. references/figma.md를 따르세요.
코드를 읽지 않을 디자이너나 PM을 위해 .ui-diff/report/summary.md를 작성하세요:
**변경된 사항**
- **가격 카드** — CTA 버튼이 이제 알약 모양(radius 4 → 999px)이며 패딩이 더 커짐(8×14 → 12×20px); Pro 카드가 강조 표시됨(2px `#2563EB` 테두리, `#EFF6FF` 채우기)과 "가장 인기 있음" 레이블.
- **헤더(모든 페이지)** — 네비게이션 링크가 파란색 `#2563EB`에서 회색 `#9CA3AF`로 변경됨.
**확인 필요**
- ⚠️ 네비게이션 링크의 흰색 배경 대비가 2.5:1로 떨어짐(이전 5.2:1); 본문 텍스트는 4.5:1 필요.
- ⚠️ `/settings`는 변경된 파일이 없지만 변경됨 — 새로운 `Button` 패딩을 적용하며, "저장"/"취소"가 모바일에서 줄바꿈됨.
**확인되지 않음:** `/admin/*`(로그인 필요), 계정 삭제 모달.
지침:
- 측정된 값 사용:
measured.md의 색상, 크기, 간격을 사용하세요. 픽셀로 추정하지 마세요. 이미지에는 보이지만measured.md에 없는 경우(이미지, 캔버스, SVG 콘텐츠) 관찰된 대로 설명하세요. - 큰 픽셀 변경 비율과 "shifted … layout shift" 라인은 일반적으로 콘텐츠가 아래로 밀렸다는 의미이지 모든 것이 변경된 것은 아닙니다. 그렇게 설명하세요.
- "확인 필요" 항목은 의도하지 않은 것으로 보이는 변경 사항을 먼저 넣으세요: 파일 변경 없이 변경된 페이지, 한 뷰포트에서만 깨짐, 오버플로우, 사라진 요소, 페이지 오류. 그 다음 대비 오류와 작은 터치 대상(모바일에서 약 44px 미만)을 넣으세요.
- "의도적으로 변경됨"이 아닌 "변경됨"이라고 말하세요. 무엇이 변경되었는지는 볼 수 있지만, 이유는 알 수 없습니다.
- 비율을 유지하세요. 한 가지 색상 조정은 한 가지 요점으로 충분합니다.
그런 다음 node $SKILL/scripts/viewer.cjs --report .ui-diff/report를 실행하여 로컬 리뷰 페이지(report/index.html: 슬라이더, 나란히 보기, diff 오버레이, 상단 요약)를 갱신하고 사용자에게 열도록 제안하세요(macOS에서는 open, Linux에서는 xdg-open).
5. 게시
게시는 공유 PR에 쓰고 브랜치를 푸시합니다. 사용자에게 요약을 먼저 보여주고 확인을 받으세요. 단, 사용자의 요청에 이미 게시하라고 명시된 경우는 제외합니다. 그런 다음:
PREFIX=$(bash $SKILL/scripts/publish.sh .ui-diff/report <pr> <head-short-sha>)
node $SKILL/scripts/comment.cjs --report .ui-diff/report --base-url "$PREFIX" \
--summary .ui-diff/report/summary.md --out .ui-diff/comment.md
node $SKILL/scripts/post.cjs --pr <pr> --body .ui-diff/comment.md --mode comment # 또는 --mode description
publish.sh는 일회용 클론에서 이미지를ui-diff-assets브랜치로 푸시합니다(단일 커밋, 게시할 때마다 대체됨). 이미지는 GitHub에서 인라인으로 렌더링되며, 비공개 리포지토리에서도 읽기 권한이 있는 모든 사람이 볼 수 있습니다.- 종료 코드 3은 푸시 액세스 권한이 없음을 의미합니다(일반적으로 포크의 PR). 수동 모드로 전환하세요.
- 리포지토리가 공개라고 표시되면 사용자에게 스크린샷이 공개된다고 알리세요. 실제 계정으로 로그인한
storageState를 사용할 때 특히 중요합니다. 게시 전에 동의를 받으세요.
post.cjs는 기존 ui-diff 댓글 또는 설명 섹션을 새 것으로 교체하며, 새 댓글이 쌓이지 않습니다. 설명의 다른 모든 내용은 그대로 유지됩니다.--approval은.ui-diff.json에"requireApproval": true가 있는 경우에만comment.cjs에 추가하세요(리포지토리가 디자인 리뷰 워크플로우를 사용하는 경우): "디자인 승인됨" 상자를 추가합니다.- 수동 모드(assets 브랜치 없음 또는 푸시 액세스 권한 없음):
--base-url없이comment.cjs를 실행한 후open .ui-diff/report를 실행하세요. 사용자가 이미지를 PR 댓글 상자에 드래그 앤 드롭하면 됩니다(GitHub는 해당 업로드를 위한 API가 없음). 어떤 이미지가 어디에 들어가는지 알려주세요. - 아직 PR이 없는 경우:
.ui-diff/comment.md를 보관하고 PR이 열릴 때 설명에 넣겠다고 제안하세요.
6. 마무리
링크, 카운트, "확인 필요" 항목을 보고하세요. dev 명령어, 라우트, 마스크 또는 동적 ID를 직접 알아낸 경우 .ui-diff.json에 저장하는 옵션을 제공하여 다음 실행이 한 단계로 끝나도록 하세요. PR이 병합되거나 닫히면 bash $SKILL/scripts/prune.sh <pr>가 assets 브랜치에서 해당 이미지를 제거합니다(누군가 여전히 해당 댓글이 필요할 수 있으므로 먼저 물어보세요).