README Screenshots

Overview

돌아가는 앱을 실제로 띄워서 찍은 화면을 README에 붙인다. 목적은 "이미지가 있다"가 아니라 읽는 사람이 설치 전에 이 프로젝트가 뭔지 알게 하는 것이다.

핵심 원칙 네 가지:

1. 찍기 전에 목록을 합의한다. 어떤 화면을, 몇 장, 어떤 테마로 넣을지 먼저 정한다. 다 찍고 나서 고르면 앱을 두 번 띄우게 된다.
2. 캡처 조건을 고정한다. 뷰포트·devicePixelRatio·테마·스크롤 위치를 매번 같은 값으로 못 박는다. 조건이 흔들리면 다음 갱신 때 이미지 크기가 달라져 README 레이아웃이 깨진다.
3. 화면에 뜬 것도 커밋되는 것이다. 스크린샷은 코드 리뷰를 안 거치고 레포에 들어간다. 실명·이메일·토큰·사내 데이터·절대 홈 경로가 찍혔으면 그대로 공개된다.
4. 추가가 아니라 갱신. 이미 스크린샷이 있으면 같은 파일명으로 덮어쓴다. hero-v2.png를 옆에 붙이면 어느 게 현재 UI인지 아무도 모른다.

When to Use

• README에 프로젝트 화면 스크린샷을 처음 넣을 때
• UI가 바뀌어서 README에 박힌 스크린샷이 낡았을 때
• 데모 링크는 있지만 README만 보고 넘어가는 사람에게 결과물을 보여줘야 할 때

Not for: UI 변경의 before/after를 PR 리뷰용으로 남기는 것(그건 문서가 아니라 증빙이다), 브라우저에서 안 돌아가는 CLI·라이브러리(대신 --help 출력이나 터미널 asciicast를 쓴다), 로그인 뒤 실데이터 화면(4단계 참고 — 시드 계정 없이 찍지 않는다).

절차

1. 넣을 화면을 먼저 정한다

레포를 훑어 라우트 목록(app/, pages/, 라우터 정의)과 테마 토글 여부를 파악한 뒤, AskUserQuestion으로 확인받는다. 넘겨짚고 다 찍지 않는다.

물어볼 것:

항목	기본값
찍을 화면	홈 1장 + 대표 상세/기능 화면 12장. **34장을 넘기지 않는다**
테마	다크 모드가 구현돼 있으면 라이트/다크 쌍, 아니면 1장
뷰포트	데스크톱 1440x900. 모바일은 반응형이 이 프로젝트의 셀링 포인트일 때만 추가
전체 페이지 여부	기본 뷰포트 캡처. fullPage는 세로로 길어져 README에서 읽히지 않으므로 요청이 있을 때만

2. 앱을 띄우고, 준비됐는지 확인하고 나서 찍는다

package.json의 dev 스크립트를 읽어 실행하고(run_in_background), 로그에서 실제 포트를 읽는다. 3000을 가정하지 않는다 — 이미 쓰이고 있으면 조용히 3001로 뜬다.

npm run dev  (background)  →  로그의 "Local: http://localhost:PORT" 확인

new_page로 열고, wait_for로 페이지의 실제 텍스트가 나타날 때까지 기다린다. 로딩 스피너나 빈 화면을 찍는 실패는 여기서만 막을 수 있다. list_console_messages로 치명적 에러가 없는지도 본다 — 에러난 화면을 README에 박으면 안 된다.

앱이 안 뜨면 거기서 멈춘다. 목업을 만들거나, 이전 스크린샷을 재활용하거나, 디자인 파일을 캡처해서 대신 넣지 않는다. 왜 못 띄웠는지 보고한다.

3. 캡처 조건을 고정한다

emulate로 뷰포트와 테마를 한 번에 못 박는다. 창 크기에 의존하는 resize_page보다 재현성이 높다.

emulate  viewport: "1440x900x2"          # 데스크톱, 2x (레티나 선명도)
emulate  viewport: "390x844x3,mobile"    # 모바일 (필요할 때만)
emulate  colorScheme: "dark" | "light"

테마는 colorScheme 하나로 끝나지 않을 수 있다. 앱이 prefers-color-scheme만 보면 이걸로 충분하지만, localStorage나 <html class="dark">로 관리하면 반영되지 않는다. 다음 순서로 시도하고, 캡처 결과를 눈으로 확인해 실제로 테마가 바뀌었는지 검증한다.

1. emulate colorScheme → 스크린샷 확인
2. 안 바뀌면 UI의 테마 토글 버튼을 click
3. 그래도 안 되면 evaluate_script로 앱이 쓰는 저장소를 직접 세팅하고 새로고침

찍기 직전에 스크롤을 맨 위로 올리고, 마우스가 얹혀 hover 상태로 남은 요소가 없는지 확인한다. 애니메이션이 있으면 끝날 때까지 기다린다 — 중간 프레임이 찍히면 흐릿한 이미지가 나온다.

4. 화면에 뜬 내용을 검사한다

캡처한 이미지를 직접 Read해서 눈으로 본다. 아래가 보이면 그 화면은 못 쓴다.

• 실명, 실제 이메일 주소, 전화번호, 프로필 사진
• 토큰·API 키·세션 값이 노출된 화면(디버그 패널, 개발자 도구 열린 상태)
• 사내 시스템 이름, 실제 테이블/버킷/큐 이름, 티켓 ID, 사내 도메인
• 브라우저 주소창이나 터미널이 함께 찍혀 나온 /Users/<이름>/ 경로
• 깨진 이미지 자리표시자, 로딩 스켈레톤, 에러 토스트

로그인이 필요한 화면은 시드 데이터나 데모 계정으로만 찍는다. 본인 실계정으로 찍은 화면은 README에 넣지 않는다.

5. 파일로 저장한다

• 위치: docs/ (없으면 만든다). 레포에 assets/나 .github/ 관례가 이미 있으면 그걸 따른다
• 이름: <화면>-<테마>.png — hero-light.png, hero-dark.png, skill-detail-light.png. kebab-case, 순번(1.png) 금지 — 순서가 바뀌면 이름이 거짓말이 된다
• 형식: PNG. 스크린샷에 사진이 많이 섞였고 500KB를 넘으면 format: "webp", quality: 85로 다시 찍는다
• 용량: 장당 500KB를 넘으면 줄인다. sips -Z 2880 docs/hero-light.png로 긴 변을 제한하는 게 가장 간단하다. 레포에 5MB짜리 PNG를 넣으면 clone 하는 모든 사람이 그 비용을 낸다

6. README에 넣는다

template.md의 골격을 따른다. 형식 규칙:

[![라이트 모드 홈](./docs/hero-light.png)](./docs/hero-light.png)

• 상대경로(./docs/...)를 쓴다. GitHub 웹 에디터가 만드는 /owner/repo/raw/main/... 절대경로는 레포 이름이 바뀌거나 포크되면 깨진다. 상대경로는 브랜치·포크·로컬 뷰어에서 모두 산다
• 이미지를 링크로 감싼다. README 본문에서는 축소돼 보이므로, 클릭하면 원본으로 열리게 한다
• alt text는 화면 이름으로 쓴다. "스크린샷", "이미지 1"은 스크린리더 사용자에게 아무것도 알려주지 않는다
• 위치는 프로젝트 한 줄 소개 바로 다음, 설치 안내 앞. 설치법 아래로 내려가면 "설치할지 말지" 판단하는 시점에 안 보인다
• 라이트/다크 쌍은 나란히 놓는다. 마크다운에서 두 이미지를 같은 줄에 쓰면 옆으로 붙는다

7. 갱신할 때

기존 스크린샷 섹션이 있으면 파일명을 그대로 두고 이미지만 덮어쓴다. README 마크다운은 손댈 필요가 없다. 화면 구성 자체가 바뀌어 파일이 늘거나 줄 때만 마크다운을 고치고, 없어진 화면의 png는 지운다.

검증

커밋 전에 확인한다. 하나라도 못 하면 그 항목을 못 했다고 말한다.

• 저장된 png를 Read해서 실제로 열리는지, 의도한 화면·테마인지 확인했다
• 4단계 항목 중 화면에 찍힌 게 없다
• 장당 500KB 이하다 (du -h docs/*.png)
• README의 이미지 경로가 실제 파일과 일치한다 (grep -o 'docs/[^)]*\.png' README.md | sort -u | xargs ls)
• 백그라운드로 띄운 dev 서버를 종료했다

Common Mistakes

• 화면 목록을 안 정하고 다 찍는다 — 앱을 두 번 띄우게 되고, README는 스크린샷 갤러리가 된다
• 로딩 중인 화면을 찍는다 — wait_for 없이 new_page 직후 캡처한 결과. 스피너가 박힌 README가 나온다
• 테마가 바뀐 걸 확인 안 한다 — emulate colorScheme을 호출했다고 앱이 반응한 건 아니다. 이미지를 봐야 안다
• 앱이 안 떠서 목업이나 옛날 이미지로 대체한다 — README의 스크린샷은 "실제로 이렇게 나온다"는 주장이다. 못 띄웠으면 못 띄웠다고 한다
• 실계정 화면을 찍는다 — 레포는 공개될 수 있고, git 히스토리에서 지우기 어렵다
• 절대경로 raw 링크를 써서 포크에서 깨지게 만든다
• 낡은 스크린샷을 지우지 않고 새 파일을 옆에 추가한다
• 최적화 없이 수 MB짜리 PNG를 커밋한다