motion-review

모션 리뷰

모션 페이지는 모니터에서 동작할 때 완성된 것이 아닙니다. 고정된 평가표에서 좋은 점수를 받고, 데스크톱과 모바일에서 모든 차단 검사를 통과하며, 코드를 신뢰하는 대신 결과물을 직접 확인했을 때 완성됩니다.

이 스킬은 세 가지를 제공합니다:

1. 보고-수정 루프: 스크린샷 촬영, 점수 평가, 최악의 문제 수정, 다시 스크린샷 촬영.
2. 10개 항목 평가표(1~10점, 5/8/10점 기준 설명 포함): references/rubric.md.
3. 차단 QA 체크리스트와 이를 측정하는 두 개의 독립 실행 스크립트: references/qa-checklist.md, scripts/section-shots.mjs, scripts/qa-lite.mjs.

기준

• 평가표 평균 8점 이상, 모든 항목 7점 미만 없음.
• 모든 차단 검사 통과 (1440x900 및 390x844 해상도).
• 각 섹션을 두 해상도 모두에서 직접 확인해야 함. 스크린샷 없는 리뷰는 추측에 불과합니다.

페이지가 기준에 미치지 못하면 히어로가 아무리 멋져도 출시할 준비가 되지 않았습니다.

요구 사항

• Node 18 이상.
• 리뷰할 프로젝트에 Playwright 설치: npm i -D playwright 후 npx playwright install chromium. 또는 playwright-core와 함께 설치된 Chrome을 사용하고 --chrome "<chrome 경로>"를 전달할 수 있습니다. 스크립트는 Windows, macOS, Linux의 일반적인 위치에서 Chrome이나 Edge를 자동으로 찾습니다.
• 선택 사항: 연속 사진(contact sheet)을 위해 npm i -D sharp. 없어도 개별 PNG는 생성됩니다.
• 프로젝트 폴더에서 스크립트를 실행하세요. 스크립트는 먼저 실행 폴더에서 Playwright와 sharp를 찾고, 그 다음 스크립트 옆에서 찾습니다. 따라서 프로젝트에 한 번만 설치하면 됩니다. 아래 스크립트 경로는 이 스킬 폴더 기준 상대 경로입니다. Claude Code는 스킬 로드 시 이 폴더를 표시합니다. 수동 복사 후에는 예를 들어 ~/.claude/skills/motion-review/이므로 전체 호출은 node ~/.claude/skills/motion-review/scripts/qa-lite.mjs ./site입니다.

?shot=N 규칙

스크립트는 index.html?shot=N을 열고 페이지가 N번째 섹션으로 이동할 것으로 예상합니다. 페이지에 다음을 한 번 추가하세요 (몇 줄만 추가하면 모든 리뷰를 반복 가능하게 만듭니다):

// QA 훅: ?shot=N은 페이지 로드 후 N번째 섹션을 뷰포트 중앙으로 스크롤합니다.
const shot = new URLSearchParams(location.search).get("shot");
if (shot !== null) addEventListener("load", () => {
  const marked = document.querySelectorAll("[data-shot]");
  const s = (marked.length ? marked : document.querySelectorAll("section"))[+shot];
  if (s) scrollTo(0, s.getBoundingClientRect().top + scrollY + s.offsetHeight / 2 - innerHeight / 2);
});

필름이나 한 번 재생되는 인트로의 경우, ?shot이 존재할 때 타임라인을 정착된 상태로 점프시켜 스크린샷이 1프레임이 아닌 완성된 프레임을 보여주도록 하세요. 시간 기반 필름의 경우 애널리틱스 스킬의 공정 캡처 방법을 참조하세요: ../motion-analytics/references/reference-grading.md.

보고-수정 루프

페이지가 기준을 충족할 때까지 이 루프를 실행하세요. 각 패스에서는 작은 문제 여러 개를 동시에 고치지 말고, 가장 해로운 문제 하나를 먼저 수정해야 합니다.

1. 촬영

node scripts/section-shots.mjs ./my-site 6 ./qa/shots

이 명령은 ./my-site를 로컬 포트에 서빙하고, 데스크톱 및 모바일 크기에서 index.html?shot=0부터 ?shot=5까지 열어 d0.png ... d5.png, p0.png ... p5.png를 생성하며, sharp가 설치된 경우 desk-sheet.png와 phone-sheet.png도 생성합니다. 발견된 모든 페이지 오류와 콘솔 오류를 출력합니다.

2. 확인

먼저 두 개의 연속 사진을 연 다음 개별 프레임을 확인하세요. 섹션별로 다음을 질문하세요:

• 페이지의 핵심 아이디어가 이 프레임에 보이는가, 아니면 일반적인 섹션인가?
• 모바일 프레임이 고유한 구성을 가지고 있는가, 아니면 데스크톱을 그대로 축소한 것인가?
• 이미지의 복잡한 부분 위에 텍스트가 놓여 있지 않은가?
• 잘리거나, 겹치거나, 비어 있거나, 아직 로딩 중인 부분이 있는가?
• 모든 섹션이 같은 브랜드처럼 보이는가?

점수를 매기기 전에 본 내용을 평범한 말로 적으세요. "모바일 히어로 제목이 주제의 얼굴을 가리고 있다"는 유용합니다. "좋아 보인다"는 유용하지 않습니다.

3. 검사

node scripts/qa-lite.mjs ./my-site

차단 검사별로 PASS 또는 FAIL을 측정된 숫자와 함께 출력합니다. FAIL이 하나라도 있으면 출시를 차단합니다. 각 검사의 의미, 측정 방법, 일반적인 수정 방법은 references/qa-checklist.md를 참조하세요.

일부 검사는 사람이 직접 확인해야 합니다: 일시 정지 제어가 모든 움직이는 요소를 멈추는지, 빠른 플링 후 역방향 스크롤이 깔끔하게 재생되는지, 소리가 켜졌을 때 페이지가 적절한 느낌인지 등. 체크리스트에 이러한 항목은 수동(manual)으로 표시되어 있습니다. 직접 확인하세요.

4. 점수 평가

스크린샷과 페이지 사용 경험을 바탕으로 10개 평가표 항목 모두에 점수를 매기세요. references/rubric.md의 기준을 사용하세요. 코드가 의도한 것이 아니라 화면에 보이는 것을 기준으로 점수를 매기세요. 점수당 한 문장의 근거를 작성하세요.

5. 최악의 문제 수정

가장 낮은 점수 또는 첫 번째 FAIL을 선택하세요. 증상이 아닌 원인을 수정하세요: 모바일에서 텍스트를 읽을 수 없다면 이미지를 줄이는 것이 아니라 글자 크기와 반투명 오버레이를 수정하세요. 변경은 작고 국소적으로 유지하세요.

6. 반복

다시 촬영하고, 다시 확인하고, 수정한 항목을 다시 평가하세요. 기준에 도달하면 중단하세요. 새 페이지의 경우 일반적으로 3~5회 패스가 필요합니다.

리뷰 보고서 형식

리뷰를 보고할 때는 결과를 시간 경과에 따라 비교할 수 있도록 다음 형식을 사용하세요:

Page: <이름>   Pass: <회차>   Date: <yyyy-mm-dd>
Rubric: idea 8, craft 7, motion 9, ... average 8.1, lowest 7 (craft)
Blocking: 12개 중 11개 PASS. FAIL: tap targets (모바일에서 44px 미만 3개: .nav a, #prev, #next)
Seen: 데스크톱 6, 모바일 6 프레임
Worst problem: <한 문장>
Fix applied: <한 문장>
Next: <한 문장>

경험 법칙

• 점수 평가 시 모바일 우선. 대부분의 방문자는 모바일로 옵니다. 데스크톱에서 9점, 모바일에서 6점인 페이지는 6점입니다.
• 멈출 수 없는 모션은 버그입니다. 5초 이상 움직이는 요소는 가시적인 일시 정지 제어가 필요하며, 모션 감소 설정 시 완전하고 정리된 페이지가 제공되어야 합니다.
• 스크롤은 양방향으로 작동해야 합니다. 위로 스크롤하면 아래로 스크롤한 결과가 어떤 속도에서든 깔끔하게 취소되어야 합니다.
• 조용한 오류 금지. 콘솔 오류 하나는 FAIL입니다. 페이지가 정상으로 보여도 마찬가지입니다. 이는 일반적으로 대체 경로가 손상되었음을 의미합니다.
• 정착된 프레임과 움직이는 프레임 모두 평가하세요. 스크린샷은 구성을 보여주고, 페이지를 직접 사용해야 타이밍을 알 수 있습니다. 둘 다 수행하세요.

관련 자료

• 프레임 시간, 품질 등급 및 페이지 무게 측정: ../motion-analytics/SKILL.md.
• 페이지 제작: ../motioncraft-builder/SKILL.md.