Figma 브라우저 제어 키트 (MCP 없이)

---
name: figma-browser
description: Figma MCP·REST API 없이, 내 크롬에 로그인된 figma.com 편집기 탭을 Claude in Chrome 으로 조종해 Figma 파일을 읽고 그리고 고친다. Figma 탭의 figma 전역 객체(플러그인 API)를 javascript_tool 로 호출하는 방식. "피그마에 그려줘", "피그마 연결 점검", "환경 점검", "피그마 브라우저로 제어", "Figma MCP 말고", "figma 객체", 화면·표·프레임을 Figma에 만들거나 바꾸는 요청에 사용.
---

# figma-browser — 크롬으로 Figma 직접 제어

이 키트가 말하는 "KIT" 는 이 스킬이 들어 있는 폴더(`.claude/skills/` 의 상위)다. 배경·실측은 `KIT/docs/02_HOW_IT_WORKS.md`, 예제 코드는 `KIT/docs/03_RECIPES.md`, 위험과 한계는 `KIT/docs/04_LIMITS_AND_RISKS.md`.

## 원칙
- **Figma MCP(`mcp__*Figma*`)나 REST API 를 쓰지 않는다.** 사람이 쓰는 것과 같은 figma.com 편집기 탭에서, 편집기가 제공하는 `figma` 전역 객체를 `javascript_tool` 로 호출한다. 크롬을 조종하는 통로(Claude in Chrome 확장)는 별개다.
- 🧑 = 사용자가 해야 함 / 🤖 = 에이전트가 함. **로그인·비밀번호·결제·좌석 변경은 에이전트가 하지 않는다.**
- **사용자가 준 기존 파일은 읽기부터.** 쓰기 시험은 새 초안 파일에서만 한다. 노드 삭제·덮어쓰기 전에는 무엇을 지우는지 말하고 확인받는다.
- 파일 키(figma.com/design/<키>/…)나 계정 정보는 보고서·로그에 남기지 않는다.

## 1. 연결 확인
1. 🤖 크롬 도구 로드(ToolSearch 로 `mcp__claude-in-chrome__*` 한 번에) → `tabs_context_mcp({createIfEmpty:true})`.
   - 미연결: 🧑 확장 설치·같은 계정 로그인·(CLI) `/chrome` → Reconnect. API 키 로그인은 연동 불가.
   - 모든 호출이 타임아웃: 🧑 크롬에 떠 있는 대화상자(나가기 확인·권한·다운로드)를 닫아 달라고 요청.
2. 🤖 새 탭에서 `https://www.figma.com/files` → 스크린샷. 로그인 화면이면 🧑 로그인 요청.
3. 🤖 작업할 파일을 연다. 사용자가 URL 을 줬으면 그 URL, 없으면 새 탭에서 `https://www.figma.com/design/new`(Drafts 에 생성, 10~40초).
   - 파일 목록으로 되돌아오거나 'locked team… view only' 배너가 보이면 팀이 잠긴 것 → 🧑 다른 계정·팀으로 로그인하거나 플랜·파일 정리 요청(에이전트는 파일을 지우지 않는다).
4. 🤖 `typeof figma` 를 5초 간격으로 최대 60초 폴링(`javascript_tool`). 이 사이 스크린샷 1회로 탭을 활성화한다. `'object'` 가 되면 준비 끝.
5. 60초 후에도 `'undefined'` 면 **플러그인 한 번 실행 폴백**(실제로 동작한 방법):
   1) 새 탭에서 `https://www.figma.com/community/search?resource_type=plugins&query=lorem%20ipsum`
   2) 아무 플러그인의 **Open in…** → 대상 파일 선택 → 새 탭에서 파일이 열림
   3) 플러그인 상세가 뜨면 **Run** → 플러그인 창은 Esc 로 닫고 **새로고침** → `typeof figma` 재확인 → 이후 그 탭에서 작업
   - 조직 계정이면 'full access to Figma Design / update your seat' 창이 뜰 수 있다 → **좌석 변경은 비용이 생길 수 있으니 누르지 말고** 🧑 사용자에게 확인.

## 2. 브리지 (파일을 컨텍스트 밖으로 올리기)
긴 JSON·스크립트를 `javascript_tool` 인자로 붙이면 토큰이 들고 한도에 걸린다. 대신:
1. `KIT/scripts/figma-bridge.js` 내용을 그대로 `javascript_tool` 로 실행 → `BRIDGE_READY`.
2. `find("FB data input")` → ref → `file_upload(paths:[KIT/scripts/figma-helpers.js, 올릴 파일들…])`. (`file_upload` 가 경로를 거부하면 Claude 를 KIT 폴더에서 실행하도록 안내.)
3. `await window.FB_LOADING; FB.version` → `0.1.0`. 올린 파일은 `FB_FILES['이름']` 에 텍스트로 들어간다. 두 번째 업로드부터는 **추가**된다.
- Figma 탭에서 `fetch('http://localhost…')` 는 쓰지 않는다(크롬 '로컬 네트워크 접근' 권한창이 떠서 탭이 멈춘다).

## 3. 작업 규칙 (실측으로 알게 된 함정)
| 함정 | 대처 |
|---|---|
| `javascript_tool` 한 번이 약 45초를 넘으면 타임아웃 | 긴 작업은 `FB.job(async (j) => {…})` 로 백그라운드 실행, `FB.status()` 를 5~10초 간격으로 폴링. `await` 로 기다리지 않는다 |
| `javascript_tool` 결과가 약 1,000자에서 잘림 | 결과는 요약(개수·이름 목록)으로 돌려주고, 큰 데이터는 나눠 읽는다 |
| 탭이 안 보이면(`document.visibilityState==='hidden'`) Figma 의 로딩·렌더가 멈춘다 | 작업 중 Figma 탭을 활성 탭으로, 크롬 창을 앞으로. 진행이 20초 넘게 안 움직이면 🧑 에게 창을 앞으로 가져와 달라고 요청 |
| 브라우저 대화상자(`alert/confirm`, "사이트에서 나가시겠습니까?", 다운로드 확인)가 뜨면 모든 탭 제어가 멈춤 | Figma 탭을 닫거나 다른 주소로 이동하지 말고 **새 탭**을 쓴다. 멈추면 🧑 에게 대화상자를 닫아 달라고 요청 |
| `figma.root.name = …` 은 무시됨 | 파일 이름은 UI 로: 좌상단 파일명 더블클릭 → 편집 상태(파란 테두리) 확인 → 입력 → Enter. 편집 상태가 아닐 때 타이핑하면 캔버스 단축키로 빈 노드가 생긴다(생기면 삭제) |
| 폰트 | `Noto Sans KR` 는 로드됨. `Pretendard` 등 로컬 폰트는 로드 실패 |
| 페이지 수 제한(Starter 팀 파일 등) | 쓰기 전 3~4번째 페이지를 만들어 보는 시험으로 판정 → `docs/03_RECIPES.md` "페이지 제한 시험" |
| 이미지 | `figma.createImage(bytes)` 가능 |
| `eval` | Figma 탭에선 허용(CSP 차단 없음). 다른 사이트 탭은 CSP 가 막을 수 있으니 스크립트를 그대로 붙여 쓴다 |
| 변경은 자동 저장됨 | 새로고침 뒤에도 유지된다. 그래서 **되돌리기 어려운 변경은 먼저 말하고 한다** |

## 4. 작업 흐름
1. 🤖 연결(1단계) → 브리지(2단계). 기존 파일이면 먼저 읽기만: 페이지·최상위 노드 목록을 요약해 사용자에게 보여 준다.
2. 🤖 변경 계획을 한두 문장으로 말하고, 영향 범위(어느 페이지·몇 개 노드)를 밝힌다.
3. 🤖 변경 실행(짧으면 `javascript_tool`, 길면 `FB.job`). 예제 코드는 `docs/03_RECIPES.md`.
4. 🤖 확인: `FB.preview(node)` 후 스크린샷 1장, 또는 노드 수·이름 목록으로 결과를 확인. 보고에는 **무엇을 바꿨는지**(페이지·노드 수)와 **확인한 방법**을 적고, 확인하지 못한 것은 못했다고 쓴다.
5. 🤖 끝나면 `FB.closePreview()`. 시험용 노드·페이지는 지운다(내가 만든 것만).

## 하지 않는 것
- 로그인 정보 입력, 좌석·플랜 변경, 파일 삭제·공유 설정 변경.
- 사용자가 지정하지 않은 파일·팀의 내용 열람 또는 수정.
- 쿠키·토큰 등 브라우저 저장 정보 조회.