| name | figma-screen-capture |
| description | Extract Figma frames by node-id whitelist → screens/ PNG + manifest.json + 화면정의.md + mockup/index.html gallery. Input: Figma fileKey + node-id whitelist (CSV or mapping table) + output directory. Output: screens/*.png + manifest.json + 02-화면정의.md + mockup/index.html (standalone gallery). Use when: (1) given a whitelist of Figma node-ids and need per-frame screenshots, (2) generating 화면정의서 (screen definition docs) from Figma, (3) building a standalone meeting mockup gallery HTML. SKIP for: full Figma design-token sync (use figma-design-sync), code extraction from Figma, or non-whitelist bulk export. Triggers: "화면정의", "목업 갤러리", "Figma 프레임 추출", "figma-screen-capture".
|
figma-screen-capture
Figma 화이트리스트 프레임 → 화면정의서 + 목업 갤러리 자동화.
역할
Figma 화이트리스트 프레임을 화면정의서(02-화면정의.md)와 독립형 목업 갤러리(mockup/index.html)로 변환하는 추출기. 전수 열거가 아닌 화이트리스트 지정 노드만 처리하며, 코드 추출은 하지 않는다(구조정의만).
컨텍스트
Figma node-id 화이트리스트(CSV 또는 매핑표)와 함께 "화면정의"/"목업 갤러리"/"Figma 프레임 추출" 요청 시 발동. 전체 디자인 토큰 동기화는 figma-design-sync가 담당하므로 이 스킬의 범위 밖.
출력
{out_dir}/manifest.json(SSoT) + {out_dir}/screens/*.png + 02-화면정의.md + mockup/index.html(자립형 갤러리, CDN 0).
제약
- 화이트리스트만 — 전수 열거 X. MCP 호출 ≤60.
- 구조정의만 — 코드 추출 X (개발 단계 React 재구현).
- 미러 주의:
~/.claude/skills/ 직접 편집 차단. SSoT = ~/forge/.claude/skills/. 작성 후 node ~/.claude/scripts/forge-sync.mjs sync 필수.
- node-id MCP 형식:
: → - 변환 (예: 40010405:23928 → 40010405-23928).
핵심 로직 (Claude 실행 순서)
① URL/fileKey + 화이트리스트 수집
② node-id : → - 변환
③ manifest.json 초기화 (figma_capture.py init)
④ 화이트리스트 각 node → get_screenshot → screens/ 저장
⑤ 구조 파악: get_metadata (선택, 호출 예산 여유 시)
⑥ manifest.json 업데이트 (components/interactions/domain_diff 기입)
⑦ 02-화면정의.md 생성 (figma_capture.py gen-md)
⑧ mockup/index.html 생성 (figma_capture.py gen-html)
⑨ rate-limit → fallback-vision.md 참조
스크립트 사용법
python3 ~/.claude/skills/figma-screen-capture/scripts/figma_capture.py init \
--whitelist "40010405:23928,40010405:24045" \
--names "로그인_크리에이터,플랫폼미선택" \
--sections "로그인,로그인" \
--out /abs/path/to/login-signup-approval/ \
--file-key Ke2sPiVdS1yvfLlYBgFXfY \
--page-node "63801:6816"
python3 ~/.claude/skills/figma-screen-capture/scripts/figma_capture.py gen-md \
--manifest /abs/path/.../manifest.json \
--out /abs/path/to/login-signup-approval/ \
--title "로그인·회원가입·승인 화면정의서"
python3 ~/.claude/skills/figma-screen-capture/scripts/figma_capture.py gen-html \
--manifest /abs/path/.../manifest.json \
--template ~/.claude/skills/figma-screen-capture/assets/mockup-template.html \
--out /abs/path/to/login-signup-approval/
MCP 호출 패턴
# get_screenshot (필수)
fileKey: Ke2sPiVdS1yvfLlYBgFXfY
nodeId: <mcp_node_id> # : → - 변환된 형태
maxDimension: 1024 # 기본; 세부 확인 시 2048
# get_metadata (선택 — 구조 파악용, 호출 예산 여유 시)
fileKey: Ke2sPiVdS1yvfLlYBgFXfY
nodeId: <mcp_node_id>
PNG 저장 경로: screens/{name}_{mcp_node_id}.png (curl 다운로드 or base64).
산출물 구조
{out_dir}/
├── manifest.json — 화면명/node-id/구조노트/상태/배지 (단일 소스)
├── 02-화면정의.md — 화면정의서 (manifest 기반 자동 생성)
├── screens/ — PNG 파일
│ └── {name}_{nodeid}.png
└── mockup/
└── index.html — 자립형 갤러리 (CDN 0, 상대경로 ../screens/)
배지·상태 규칙
| 배지 | 의미 |
|---|
| ✅로컬PNG | 로컬에 이미 PNG 존재 |
| ⚠️MCP추출 | MCP get_screenshot으로 추출 |
| ❌ClaudeDesign신규 | Figma 없음 → Claude Design TODO |
data_status (검토중/확정/이슈): manifest.json에서 수동 설정.
Rate-limit 폴백
→ references/fallback-vision.md 참조.
⚠️TODO 처리
Figma에 해당 화면 없는 경우:
- manifest.json
status: "❌ClaudeDesign신규" 기입
- 02-화면정의.md 해당 섹션에
> ⚠️TODO: Claude Design 신규 디자인 필요 명시
- 신규 디자인 생성 X (별도 안건)
참조 파일
scripts/parse_figma_url.py — Figma URL → fileKey + nodeIdscripts/figma_capture.py — manifest/md/html 생성 헬퍼assets/mockup-template.html — 자립형 갤러리 HTML 템플릿references/fallback-vision.md — rate-limit 폴백 흐름
자동 평가 (eval-rubric 통합)
본 스킬 결과 산출 후 자동으로 eval-rubric 호출 → 4축 Rubric 채점 → eval_cases.jsonl 누적.
호출 시점
- 02-화면정의.md 저장 완료 후
- mockup/index.html 브라우저 렌더 확인 후
절차
- 산출물 저장 후:
/eval-rubric --target {화면정의.md 경로}
- verdict + 4축 점수 + rationale 수신
- eval_cases.jsonl append (
~/.claude/scripts/eval-cases-append.py)
- case_id: EC-figma-screen-capture-{N}
자동 비활성
EVAL_RUBRIC_AUTO=off- frontmatter
eval_cases: off
