timelabs 0.1.0 → 0.1.1

package/skills/web-design/claude-code/analyze/analyze-benchmark.md

@@ -0,0 +1,302 @@
+# 멀티사이트 벤치마킹
+
+> 트리거: `/wd benchmark <URL1> [URL2] [URL3]`
+> 원본: skills/benchmarking/SKILL.md
+> Dependencies: analyze/analyze-benchmark-rules.md
+
+## 역할
+
+사용자가 제공한 URL(1~5개)에 Playwright로 접속하여 스크린샷 캡처, CSS 값 추출, DOM 구조 분석을 수행한 뒤, 비교 분석 보고서와 디자인 토큰 초안을 생성합니다.
+
+---
+
+## 입력
+
+| 파라미터 | 필수 | 설명 |
+|---------|------|------|
+| URL | O | 벤치마킹 대상 URL (1~5개, 공백 구분) |
+| `--focus` | X | 분석 관점 (쉼표 구분): layout, color, typography, spacing, component, style, responsive |
+| `--viewport` | X | 캡처 뷰포트: desktop(1440×900), mobile(390×844), tablet(768×1024) |
+| `--mobile` | X | `--viewport mobile` 단축 |
+| `--output` | X | 출력 디렉토리 (기본: `docs/benchmarking/`) |
+
+## 출력
+
+```
+{output_dir}/
+├── screenshots/
+│   ├── {site}-desktop-full.png
+│   ├── {site}-mobile-full.png
+│   └── {site}-section-*.png
+├── data/
+│   ├── {site}-analysis.json        # 사이트별 분석 데이터
+│   └── ...
+├── report.md                        # 비교 분석 보고서
+└── recommended-tokens.json          # 추천 디자인 토큰 초안
+```
+
+---
+
+## 워크플로우
+
+### 0단계: 공유 컨텍스트 읽기
+
+```
+1. Read 도구로 .claude/project-context.json 읽기
+2. 파일이 없으면 → context = {} (빈 객체), 정상 진행
+3. 읽기 항목:
+   - design.style → 보고서에 현재 스타일 참조
+   - design.token_format → 추천 토큰 형식 결정
+```
+
+### 1단계: 인자 파싱
+
+```
+$ARGUMENTS 분석:
+
+URL 패턴 (https?://...) → urls[] 배열에 수집
+--focus {값} → focus[] 배열 (미지정 시 7가지 전체)
+--viewport {값} → viewports[] 배열 (기본: [desktop, mobile])
+--mobile → viewports = [mobile]
+--output {경로} → output_dir (기본: docs/benchmarking/)
+
+URL이 0개 → AskUserQuestion:
+  "벤치마킹할 사이트 URL을 입력해주세요 (최대 5개, 쉼표 구분)"
+```
+
+### 2단계: 환경 준비
+
+```bash
+# Playwright 설치 확인
+npm list playwright 2>/dev/null || npm install --save-dev playwright
+npx playwright install chromium
+```
+
+```
+설치 실패 시:
+  → "Playwright 설치가 불가능한 환경입니다."
+  → URL만 {output_dir}/urls.txt에 기록
+  → "수동 분석을 위해 URL을 기록했습니다. 각 사이트를 브라우저에서 직접 확인해주세요."
+  → 종료
+```
+
+### 3단계: 데이터 수집 (URL별 반복)
+
+> 참조: `analyze/analyze-benchmark-rules.md` § 3 (CSS 추출 항목)
+
+각 URL에 대해 순차 실행합니다.
+
+#### 3-1. 브라우저 접속 + 방해 요소 처리
+
+```javascript
+// Playwright 접속
+const browser = await chromium.launch();
+const page = await browser.newContext({ viewport }).newPage();
+await page.goto(url, { waitUntil: 'networkidle' });
+
+// 방해 요소 자동 제거
+// [class*="cookie"], [class*="consent"], [class*="popup"],
+// [class*="modal"], [class*="overlay"], [class*="banner"]
+// → 닫기/수락 버튼 클릭
+
+// 레이지 로딩 대응: 전체 스크롤 (300px 단위, 100ms 간격)
+// → 상단 복귀 → 1초 대기
+```
+
+#### 3-2. 스크린샷 캡처
+
+| 캡처 대상 | 파일명 | 조건 |
+|----------|--------|------|
+| 전체 페이지 (데스크톱) | `{site}-desktop-full.png` | desktop in viewports |
+| 전체 페이지 (모바일) | `{site}-mobile-full.png` | mobile in viewports |
+| 전체 페이지 (태블릿) | `{site}-tablet-full.png` | tablet in viewports |
+| 섹션별 | `{site}-section-{name}.png` | header, nav, main, footer, hero, cta |
+
+#### 3-3. CSS 값 추출
+
+`document.querySelectorAll('*')`의 computed style에서 추출:
+
+| 추출 대상 | 필터 조건 |
+|----------|----------|
+| colors (color, backgroundColor, borderColor) | Set 중복 제거 |
+| fontFamilies, fontSizes, fontWeights, lineHeights | Set 중복 제거 |
+| paddings, margins | `0px 0px 0px 0px` 제외 |
+| borderRadii | `0px` 제외 |
+| boxShadows | `none` 제외 |
+| maxWidths, gaps | `none`/`normal` 제외 |
+| transitions | 기본값 제외 |
+
+#### 3-4. CSS 변수 추출
+
+외부 스타일시트의 `:root` / `html`에서 `--` 접두사 Custom Properties 추출.
+CORS 불가 시 건너뜀.
+
+#### 3-5. DOM 구조 분석
+
+- 시맨틱 구조 트리 (depth 5까지)
+- 반복 컴포넌트 패턴 (동일 클래스 3회 이상, 상위 20개)
+- 그리드/레이아웃 (`display: grid` 요소)
+- 접근성 (img alt 누락, ARIA 요소 수, 헤딩 구조)
+
+### 4단계: 데이터 정제
+
+> 참조: `analyze/analyze-benchmark-rules.md` § 4 (데이터 정제 규칙)
+
+1. **색상**: rgb→hex 변환, 투명/검정 필터, 빈도순 정렬, 역할 추정
+2. **타이포**: px 숫자 정렬, 타입 스케일 비율 계산
+3. **간격**: px 정렬, 기본 단위(4px/8px) 추정
+4. **CSS 변수**: 사이트 자체 토큰 체계 매핑
+
+### 5단계: AI 분석
+
+> 참조: `analyze/analyze-benchmark-rules.md` § 2 (스타일 판별 기준)
+
+1. **스크린샷 시각 분석**: 레이아웃 구조, 시각적 무게, 브랜드 톤
+2. **수치 데이터 분석**: 토큰 체계, 스타일 판별
+3. **멀티 사이트 비교** (2개 이상): 공통 패턴, 차별 요소, 추천 값
+
+focus 파라미터 지정 시 해당 관점만 집중 분석합니다.
+
+### 6단계: 보고서 생성
+
+> 참조: `analyze/analyze-benchmark-rules.md` § 8 (보고서 구조)
+
+#### 6-1. 사이트별 분석 JSON
+
+`{output_dir}/data/{site}-analysis.json` 저장:
+
+```json
+{
+  "url": "https://example.com",
+  "capturedAt": "ISO 8601",
+  "screenshots": { "desktop": "...", "mobile": "...", "sections": [] },
+  "designTokens": {
+    "colors": { "primary": [], "neutral": [], "background": [] },
+    "typography": { "families": [], "scale": [], "weights": [] },
+    "spacing": { "baseUnit": "8px", "values": [] },
+    "borderRadius": [],
+    "shadows": [],
+    "maxWidth": "1200px"
+  },
+  "structure": { "semanticTree": "...", "componentPatterns": "...", "gridSystem": "..." },
+  "styleAnalysis": { "detectedStyles": [], "rationale": "..." }
+}
+```
+
+#### 6-2. 비교 보고서
+
+`{output_dir}/report.md` 생성:
+
+```markdown
+# 벤치마킹 비교 보고서
+
+## 분석 대상
+- 사이트 A: [URL] - [한줄 설명]
+
+## 비교 매트릭스
+(analyze/analyze-benchmark-rules.md § 5 템플릿 적용)
+
+## 공통 패턴
+## 차별화 요소
+## 추천 디자인 토큰 (CSS Custom Properties)
+## 추천 디자인 스타일 조합 (analyze/analyze-benchmark-rules.md § 6 참조)
+## 참고 스크린샷
+```
+
+#### 6-3. 추천 토큰 초안
+
+`{output_dir}/recommended-tokens.json` 생성:
+
+```json
+{
+  "source": "benchmarking",
+  "basedOn": ["site-a.com", "site-b.com"],
+  "tokens": {
+    "colors": { "primary": "#...", "neutral": "#..." },
+    "typography": { "baseSize": "16px", "scaleRatio": 1.25, "family": "..." },
+    "spacing": { "baseUnit": "8px" },
+    "borderRadius": { "default": "8px" },
+    "shadows": ["0 1px 3px rgba(0,0,0,0.1)"]
+  }
+}
+```
+
+### 7단계: context 업데이트
+
+```json
+{
+  "last_updated": "{ISO8601}",
+  "updated_by": "/web-design",
+
+  "benchmarking": {
+    "last_run": "{ISO8601}",
+    "urls": ["{분석된 URL 목록}"],
+    "detected_styles": ["{감지된 스타일}"],
+    "report_path": "{output_dir}/report.md"
+  }
+}
+```
+
+### 8단계: 결과 보고 + 다음 단계 안내
+
+```
+벤치마킹 분석 완료:
+- 분석 대상: {N}개 사이트
+- 감지된 스타일: {detectedStyles}
+- 보고서: {output_dir}/report.md
+- 추천 토큰: {output_dir}/recommended-tokens.json
+```
+
+AskUserQuestion:
+```
+다음으로 어떻게 진행할까요?
+
+① 추천 토큰으로 /wd generate 시작 (추천)
+② 보고서만 확인
+③ 추가 URL 분석
+```
+
+---
+
+## 멱등성
+
+```
+if exists("{output_dir}/report.md"):
+  AskUserQuestion:
+    "이전 벤치마킹 결과가 존재합니다.
+     [1] 기존 결과 사용
+     [2] 다시 분석 (덮어쓰기)"
+  → [1] 즉시 8단계로
+  → [2] 기존 결과 삭제 후 2단계부터
+```
+
+---
+
+## 에러 처리
+
+| 상황 | 대응 |
+|------|------|
+| Playwright 설치 불가 | URL만 기록, 수동 분석 가이드 안내 후 종료 |
+| 사이트 접속 불가 (404, 500) | 에러 기록 후 해당 URL 건너뛰기 |
+| 로그인 필요 | 공개 페이지만 분석 가능 안내 |
+| SPA | `waitUntil: 'networkidle'` + 추가 대기 |
+| CORS 외부 CSS | computed style 기반 대체 |
+| 무한 스크롤 | 최대 10회 스크롤 제한 |
+| 캡차/봇 차단 | 자동 분석 불가 안내 |
+
+---
+
+## 주의사항
+
+- **저작권**: 벤치마킹은 참고를 위한 것이며, 디자인을 그대로 복제하면 저작권 문제가 될 수 있음을 안내
+- **성능**: 사이트당 30초~1분 소요 (5개 시 약 5분)
+- **동적 콘텐츠**: A/B 테스트, 지역별 차이 등은 캡처 시점에 따라 달라질 수 있음
+- **네트워크 필수**: 외부 사이트 접속 필요
+
+---
+
+## web-design 연동
+
+collect-style.md에서 벤치마킹 결과 자동 참조:
+- recommended-tokens.json → Q3-1 스타일 추천 기본값
+- report.md → 감지된 스타일 코드 매핑