figma-analyzer-agent

Figma 디자인 분석 전문가입니다. 요구사항 추출과 UI 구조 분석에 사용합니다.

항목	내용
실행 명령	`/cc-flutter:figma:analyze`
별칭	`/figma:design`, `/design:analyze`
모델	`sonnet`
MCP 서버	`figma`
연계 스킬	`figma-to-coui`

디자이너가 그린 피그마 화면을 읽어서, 무엇을 만들어야 하는지 정리하고 실제 기능 개발로 이어주는 전문 에이전트입니다.

한마디로#

디자이너가 그린 피그마 화면을 보고 "이걸 앱으로 만들려면 무엇이 필요한지"를 대신 정리해 주는 분석가입니다. 설계 도면을 보고 필요한 자재와 작업 목록을 뽑아주는 현장 반장과 비슷해요.

누가·언제 쓰나요#

피그마 디자인은 나왔는데, 이걸 실제 화면(앱)으로 옮기는 작업을 시작하려는 경우
디자인을 보고 "어떤 데이터가 필요하고, 어떤 화면 요소가 있는지" 요구사항을 정리하고 싶을 때

👉 Figma 공식 플러그인의 Figma MCP 에 로그인돼 있어야 합니다. 켜져 있는지가 아니라 실제로 읽히는지(whoami)로 확인하고, 읽히지 않으면 분석을 시작하지 않습니다 — 화면 사진에서 짐작하지 않습니다.

무엇을 해주나요#

분석이 끝나면 .claude/docs/{기능이름}/ 폴더 아래에 다음 결과물이 만들어집니다.

figma_analysis.md — 피그마 화면을 분석한 결과
requirements.md — "무엇을 만들어야 하는지" 정리한 요구사항 문서
screenshots/ — 분석에 사용한 화면 캡처 이미지

여기에 더해, 분석 결과를 바탕으로 실제 기능 개발(/cc-flutter:feature:create)과 ZenHub 작업 이슈(Epic/Story) 생성까지 이어줄 수 있습니다.

어떻게 쓰나요#

# 피그마에서 직접 선택한 화면을 분석 (기본)
/cc-flutter:figma:analyze --use-selection

# 특정 노드(화면 요소) ID를 지정해서 분석
/cc-flutter:figma:analyze --node-ids "1:23,4:56"

# 이름으로 화면 요소를 검색해서 분석
/cc-flutter:figma:analyze --search-query "로그인 카드"

# 분석 후 곧바로 기능 개발까지 자동으로 이어가기
/cc-flutter:figma:analyze --use-selection --auto-create

--page-name: 특정 피그마 페이지를 지정하고 싶을 때 덧붙입니다.
기능 이름은 직접 적어줄 수도 있고, 비워두면 자동으로 추론합니다.

안에서 무슨 일이 벌어지나요#

크게 다섯 단계를 차례로 진행합니다.

화면 가져오기 — 피그마에서 선택한 화면과 요소를 읽고, 스크린샷을 찍습니다.
화면 뜯어보기 — 어떤 구성 요소(카드, 입력칸 등)가 있는지 식별하고, 글자·색상·간격 같은 디자인 정보를 추출합니다.
요구사항 정리 — 디자인을 보고 필요한 데이터 항목과 화면 위젯, 그리고 동작(추가·조회·수정·삭제)을 정의합니다.
기능 생성 — 요구사항 문서를 만들고, 실제 기능 개발(/cc-flutter:feature:create)을 호출합니다.
작업 이슈 생성 — ZenHub에 Epic/Story를 만들고 피그마 링크를 첨부합니다.

⚙️ 상세 옵션·실행 명세 (개발자 / AI 에이전트용)

Role#

Figma frame analysis -> UI requirements extraction -> Clean Architecture Feature creation automation

Activation Conditions#

/cc-flutter:figma:analyze Activated when command is invoked
The official Figma MCP reads the file: whoami returns an account and get_metadata returns the target node. A server merely named figma is not enough. Unreadable → stop and report; never analyze from a screenshot.
This agent declares no tools: allow-list on purpose — an explicit list does not pass MCP tools through to a subagent, and the agent could not call Figma at all.

Parameters#

Parameter	Required	Description
`figma_url`	✅	Figma file URL (`/design/<fileKey>/…`, optionally with `node-id`) — every Figma MCP call needs the file key
`--node-ids`	Option1	Figma Node ID List (Comma separated)
`--search-query`	Option2	Node Name search query
`--use-selection`	Option3	Use Figma Selected Nodes (default)
`--page-name`	❌	Figma Page name
`feature_name`	❌	Feature name (can be Auto-inferred)
`--auto-create`	❌	Auto feature:create after Analysis

Execution Flow#

Phase 1: 피그마 노드 수집 (공식 Figma MCP)
  - whoami → create_session (figma_url 의 file key)
  - get_metadata — 노드 구조 · id. --use-selection 은 응답 앞의
    "Currently selected nodes" 블록, --search-query 는 이 XML 의 이름에서
  - get_design_context (figma:figma-design-to-code 먼저 로드) — 참조 코드 + 스크린샷
  - get_screenshot → screenshots/
  - 하나라도 실패하면 중단 · 보고 (스크린샷에서 짐작하지 않음)
    ↓
Phase 2: UI 분석
  - 컴포넌트 식별 (FRAME/TEXT/COMPONENT/INSTANCE)
  - CoUI 매핑 — 파일에 Code Connect 가 있으면 get_code_connect_map 이 우선,
    없으면 figma-to-coui 「Figma → CoUI 번역 명세」(라이브러리 인스턴스는 그 릴리스의 components.json)
  - 제품 컴포넌트 — 디자이너의 비교 시트가 있으면 그 판정(F8, cc-blueprint 의 compare-sheet.figma.js 로 읽기) ·
    다른 이름의 흔한 모양은 F9 이름 찾기 표
  - 프레임 모드 — 화면 프레임에 고정한 브랜드 · 서페이스 스타일 · 밀도(resolvedVariableModes) → CoUIApp 인자
  - 텍스트 — get_design_context 의 텍스트 노드
  - 변수(토큰) — get_variable_defs
    ↓
Phase 3: 요구사항 정의
  - Figma → Entity 필드 매핑
  - UI → Flutter 위젯 변환
  - CRUD 메서드 식별
    ↓
Phase 4: Feature 생성
  - Requirements document 생성
  - /cc-flutter:feature:create 호출
    ↓
Phase 5: ZenHub Story 생성
  - Epic/Story 생성
  - Figma 링크 첨부

figma MCP Key Features (official Figma MCP)#

Function	MCP Tool
읽을 수 있는가	`whoami`
작업 세션 (이후 호출에 `sessionId`)	`create_session`
노드 구조 · id · 현재 선택	`get_metadata`
디자인 컨텍스트 (참조 코드 + 스크린샷)	`get_design_context`
변수 (색 · 간격 · 타이포 토큰)	`get_variable_defs`
렌더 이미지	`get_screenshot`
라이브러리 컴포넌트 · 변수 찾기	`search_design_system`
컴포넌트 ↔ 코드 매핑 (Code Connect)	`get_code_connect_map`

Parameter conventions belong to the tool schemas and the Figma plugin's figma-design-to-code skill. get_design_context returns React/HTML reference code — translate it into CoUI through figma-to-coui, never paste it.

Component Mapping#

Widgets are not picked from node names — dropdown → DropdownButton is right only when a name happens to match, and it reaches for Material. Every node maps by its source, and each source has a fixed counterpart. The rules are figma-to-coui → "Figma → CoUI 번역 명세" (F0–F9).

Figma node	Maps to
Library instance (main component in the CoUI library)	Set name = class, member name axes (`Variant=… , Size=… , State=…`) = constructor args — from that release's `components.json` (F0 · F3)
Instance overrides (colour · padding · radius rebound, effect style)	That instance's `withStyle(...)` or token-name getter (F3)
Product-drawn frame (auto-layout)	Vertical `Column` · horizontal `Row` · wrapping `Wrap`, spacing from the bound variable's token (`Gap.spaceN()`, F2). A frame with a shadow is a surface — a surface component (F4)
Text	The text style's role chain, `Text('…').<role>` (F1)
Product component outside the library (`Field` · `StatusPill` · `OptionCard` …)	The designer's verdict on the comparison sheet — read it with `cc-blueprint` `references/recipes/compare-sheet.figma.js`, act on it by F8. No verdict → ask the designer and record a low-confidence interim path (`coui-library-consumption` §4); never write a verdict yourself
A common shape under the product's own name (segmented · keycap · initials circle · sidebar · command palette · editor tab · dashed tile …)	The F9 lookup table — it marks APIs that need a newer CoUI release
Image fill	Data images stay data-driven; fixed assets follow `figma-design-to-code`'s asset rules
Variable modes pinned on screen frames	App arguments, not screen code — `CoUIApp(surfaceStyle: …, density: …)` and the theme module's `CoreBrand` (F5)

figma_analysis.md records, per instance, the set · member name and the constructor it became; per product component, the sheet's verdict and CoUI counterpart (or verdict: none — asked the designer); and lists separately the nodes with off-ladder values (F6), those matching a known difference (F7), and the APIs a newer CoUI release has to bring (F8 · F9).

Output Files#

.claude/docs/{feature_name}/
├── figma_analysis.md       # Figma analysis result
├── requirements.md         # Requirements document
└── screenshots/            # Captured screenshots

Checklist#

Phase 1: Node Collection

Figma read — whoami and the target node's get_metadata answered (not a name in a server list)
Design context retrieved (get_design_context)
Screenshot saved (get_screenshot)

Phase 2: UI Analysis

Component identification complete
CoUI mapping complete — library instances from components.json, product components from the comparison sheet's verdict (F8), other names through F9, frame modes → CoUIApp arguments
No verdict written by the agent — components the sheet doesn't cover are listed as verdict: none with the request to the designer
Off-ladder values (F6) and known differences (F7) listed — not patched
Text/field extraction complete

Phase 3: Requirements

Entity field definition complete
Flutter widget conversion complete
API method identification complete