후보 캡처 비교 (capture-compare)

시각적인 결정은 말로 설명하면 사용자가 머릿속으로 그려야 하고, 한 방향씩 구현해 보여주면 왕복이 길어진다. 후보 3~4개를 같은 데이터·같은 배치·같은 화면 크기에서 찍어 한 장에 나란히 놓으면 사용자가 한 번에 고를 수 있다. Blog 저장소의 Fragments 개발에서 그래프 배치(8가지 비교)와 관계 화살표 모양을 이렇게 정했다.

gated-tdd 스킬과 함께 쓰면 이 비교는 구현 전 결정 단계이고, 고른 안의 반영은 gated-tdd의 사이클(Red → … → 판정)로 진행한다.

절차

1. 변수 하나만 정한다. 이번 비교에서 바꾸는 것(예: 선·화살표 스타일)을 정하고, 나머지(데이터, 노드 위치, 테마, 창 크기)는 모든 후보에서 똑같이 유지한다. 두 가지가 동시에 바뀌면 사용자가 무엇 때문에 좋아 보이는지 판단할 수 없다.
2. 후보를 3~4개로 만든다. 항상 **"현재"**를 첫 후보로 넣어 기준으로 삼는다. 나머지는 점진적으로 쌓는 편이 비교하기 쉽다(A: 모양만 → B: A + 선 스타일 → C: B + 색). 각 후보에 한 줄 설명을 붙인다.
3. 저장소 코드는 건드리지 않는다. 탐색 단계에서는 실행 중인 페이지에 스타일을 덮어써서 찍는다(page.addStyleTag, 라이브러리 인스턴스 API 등). 스크립트·결과물은 세션 임시(scratchpad) 폴더에 둔다. 사용자가 고른 뒤에 실제 코드를 고친다.
   • Cytoscape 예(Blog의 #fragment-graph): document.getElementById('fragment-graph')._cyreg.cy로 인스턴스를 얻고, cy.style().json()을 원본으로 저장한 뒤 후보마다 cy.style().fromJson([...원본, ...후보규칙]).update()로 교체한다. 레이아웃을 다시 돌리지 않으므로 노드 위치가 모든 후보에서 같다.
4. 상태도 함께 찍는다. 평소 화면뿐 아니라 그 요소가 달라지는 상태(마우스 올림·강조, 어두운 테마, 390px 모바일 등)를 후보마다 같은 순서로 찍는다. 평소엔 괜찮은데 강조 상태에서 깨지는 경우가 많다.
5. 캡처를 방해하는 요소를 치운다. 개발 도구 막대(astro-dev-toolbar{display:none!important}), 쿠키 배너, 로딩 애니메이션을 숨기고, 레이아웃이 끝날 때까지 기다린 뒤 찍는다.
   • 요소 캡처는 그 요소를 화면 위쪽으로 스크롤한다. 상단 고정(position:sticky/fixed) 내비게이션이 있으면 요소를 덮으므로 캡처 중에는 position:static!important로 푼다.
   • 여백을 넣으려고 대상에 음수 margin을 주지 않는다. 요소가 화면 밖(x<0)으로 밀리면 엉뚱한 영역(페이지 맨 위)이 찍힌다. 여백은 padding만으로 준다.
   • 후보 CSS에 쓰는 변수 이름(var(--bg) 등)이 그 사이트에 실제로 있는지 먼저 확인한다. 없는 변수는 조용히 무시되어 글자가 사라지거나 테두리가 빠진 채 찍힌다.
   • 트랜지션이 있는 hover는 settleMs를 트랜지션 시간보다 길게 둔다.
6. 보여주기 전에 직접 본다. Read 도구로 PNG를 열어 확인한다. 특히 다음을 점검한다.
   • 샘플이 후보 차이를 드러내는가? (예: 관계 12개 중 9개가 같은 유형이면 유형별 스타일 비교가 안 된다 → 유형이 고르게 섞인 대상으로 다시 고른다)
   • 비교 대상이 너무 작거나 가려지지 않았는가? (화살촉이 허브 노드 밑에 묻힘 → 크기를 키우거나 확대해서 다시 찍는다)
   • 의도치 않은 요소가 찍히지 않았는가? 문제가 있으면 고쳐서 다시 찍는다. 사용자에게 혼란스러운 첫 판을 보여주지 않는다.
7. 비교 시트를 만들어 연다. 후보별로 [상태1 | 상태2 …]를 한 행에 두고, 제목·설명·측정 조건(데이터, 대상, 화면 크기, 테마)을 적은 한 장짜리 PNG를 만든다. scripts/capture-sheet.mjs가 이 작업을 해 준다. Windows에서는 Start-Process <png>, macOS는 open으로 사용자 화면에 띄운다.
8. 관찰과 추천을 함께 보고한다. 사용자에게 아래를 전달하고 선택을 기다린다.
   • 파일 경로(시트 + 개별 캡처 폴더)
   • 후보 비교표(후보 × 달라지는 속성)
   • 캡처에서 실제로 보인 것: 어떤 후보가 멀리서도 구분되는지, 공통 문제(예: 겹침), 이번 비교와 무관한 기존 문제, 샘플 데이터의 한계
   • 하나의 추천과 이유, 그리고 사용자가 정할 것 사용자가 고르기 전에는 실제 코드를 바꾸지 않는다.
9. 고른 뒤. 선택한 안을 코드에 반영하고, 가능하면 같은 스크립트로 반영 후 화면을 다시 찍어 시트의 후보와 같은지 확인한다. 결정과 이유는 프로젝트의 결정 기록(gated-tdd를 쓰는 저장소는 docs/decision/)에 남긴다.

스크립트 사용법

scripts/capture-sheet.mjs <설정.mjs> <출력폴더>를 실행하면 Playwright로 후보 × 상태를 찍고 sheet.html/sheet.png를 만든다. 프로젝트의 @playwright/test(또는 playwright)를 현재 작업 폴더 기준으로 찾으므로 프로젝트 루트에서 이 스킬 폴더의 스크립트를 절대 경로로 실행한다(node <이 스킬 폴더>/scripts/capture-sheet.mjs …). 프로젝트에 Playwright가 없으면 설치 여부를 사용자에게 먼저 묻는다.

설정 파일은 다음을 export default 한다.

export default {
  title: '관계 유형별 선·화살표 후보 비교',
  url: 'http://127.0.0.1:4403/fragments/?view=graph',
  viewport: { width: 1280, height: 1000 },
  target: '#fragment-graph',              // 찍을 요소 (생략 시 전체 화면)
  hideCss: 'astro-dev-toolbar{display:none!important}',
  async setup(page) { /* 대기, 대상 선택 등. 반환한 문자열은 시트의 측정 조건에 표시 */ },
  variants: [
    { key: 'now', title: '현재', desc: '기준', async apply(page) {} },
    { key: 'A', title: 'A. …', desc: '…', async apply(page) { /* 스타일 덮어쓰기 */ } },
  ],
  states: [
    { key: 'plain', label: '평소', async apply(page) {} },
    { key: 'hover', label: '마우스 올림', async apply(page) { /* 강조 */ } },
  ],
};

apply는 이전 후보의 흔적을 지우고 자기 상태를 적용해야 한다(원본 스타일을 setup에서 저장해 두고 매번 원본 + 후보로 교체하는 식). 설정 예시는 references/example-graph-arrows.mjs를 본다.