alima-max/prototype-to-figma-skill

작동하는 Claude Code 프로토타입을 구조화된 Figma 디자인 파일로 변환하는 Claude skill — 각 인터랙션 흐름을 개별 프레임으로 분해하고, 사용자의 디자인 시스템 (Design System) 컴포넌트를 사용하며, Figma 내에서 인터랙션 상세 내용을 네이티브하게 주석(Annotation)으로 달아줍니다.

Claude Code에서 프로토타입을 구축할 때, 교차 기능 파트너(PM, 디자이너, 엔지니어)로부터 비동기 피드백을 받는 것은 어렵습니다. 그들은 스스로 라이브 프로토타입을 쉽게 살펴볼 수 없기 때문입니다. 이 skill은 프로토타입을 리뷰어가 아무것도 실행하지 않고도 탐색하고, 댓글을 달고, 이해할 수 있는 Figma 파일로 번역함으로써 그 간극을 메워줍니다.

인터랙션 상태당 하나의 프레임— 사용자 흐름(User Flow)의 모든 의미 있는 단계가 각각의 프레임을 가집니다. 디자인 시스템 (Design System) 컴포넌트— Figma 파일의 연결된 라이브러리에서 실제 DS 컴포넌트를 사용합니다. DS 매칭이 없는 요소는 프리미티브(Primitives)로 구축되며 "No DS match" 배지가 표시됩니다. 네이티브 Figma 주석 (Annotations)— 트리거, 전환(Transitions), 조건(Conditions), 에지 케이스(Edge Cases)를 설명하는 필터링 가능한 카테고리(Interaction, Navigation, Validation, Error Handling 등)를 포함한 Dev Mode 주석. 플로우 화살표 (Flow arrows)— 사용자가 상태를 거쳐가는 경로를 보여주는 시각적 커넥터. 개요 프레임 (Overview frame)— 리뷰어를 위한 범례(Legend)와 미결 질문(Open questions)이 포함된 목차. Code Connect 매핑 (Code Connect mappings)— 선택적으로 Figma 컴포넌트를 코드베이스로 다시 연결합니다.

Figma MCP 도구 (Figma MCP tools)— 이 skill은 use_figma, search_design_system, get_design_context, get_metadata, get_screenshot, get_code_connect_map, get_context_for_code_connect, get_code_connect_suggestions, send_code_connect_mappings, add_code_connect_map, whoami, 그리고 create_new_file을 사용합니다.

작동하는 프로토타입— Claude Code에서 구축되었으며, 일반적으로 팀의 실제 컴포넌트 라이브러리를 사용합니다. 대상 Figma 파일— 선택 사항입니다. 파일을 제공하지 않으면 skill이 자동으로 새 파일을 생성합니다.

• Releases 페이지에서 최신 zip 파일을 다운로드합니다 (또는 이 리포지토리를 클론한 후 루트 폴더를 zip으로 압축합니다)
• **Settings → Customize → Skills → "+" → "+ Create skill"**으로 이동하여 zip 파일을 업로드합니다
• skill 공유 기능을 통해 조직(org)과 공유합니다

git clone https://github.com/alima-max/prototype-to-figma-skill.git ~/.claude/skills/prototype-to-figma

SKILL.md와 figma-patterns.md를 클라이언트의 skills 또는 context 디렉토리에 추가합니다. 정확한 위치는 클라이언트의 문서를 참조하십시오.

/v1/skills 엔드포인트를 통해 업로드합니다. 자세한 내용은 Skills API 문서를 참조하십시오.

설치가 완료되면, Figma URL 없이도 Claude에게 자연스럽게 요청하면 됩니다:

"이 프로토타입을 Figma에 넣어서 팀이 검토할 수 있게 해줘"
"비동기 피드백을 위해 이 프로토타입을 Figma 프레임으로 분해해줘"
"디자인 검토를 위해 내 프로토타입으로부터 Figma 스펙을 생성해줘"
"디자인 팀이 이 프로토타입을 검토할 수 있게 만들어줘"

만약 특정 기존 Figma 파일에 결과물을 넣고 싶다면, URL을 포함하세요:

"이것을 Figma에 넣어줘: figma.com/design/abc123/..."

그렇지 않으면, Claude가 자동으로 새 Figma 파일을 생성하고 완료되면 링크를 공유합니다.

대상 파일 해결 (Resolves the target file)— 제공된 파일 URL을 사용하거나, whoami + create_new_file을 통해 자동으로 새 Figma 파일을 생성합니다.

프로토타입 분석 (Analyzes the prototype)— 소스 코드를 읽어 컴포넌트 목록을 작성하고, 상호작용 흐름(interaction flows)을 매핑하며, 모든 UI 상태를 식별합니다.

디자인 시스템 매핑 (Maps to the design system)— 대상 Figma 파일에 연결된 라이브러리에서 일치하는 DS(Design System) 컴포넌트를 검색합니다. 일치하지 않는 요소는 기본 요소(primitives)로 구축되며 "No DS match" 배지가 표시됩니다.

페이지 구조 계획 (Plans the page structure)— 흐름에 따라 프레임을 구성하며, 성공/오류 상태에 대한 분기 경로를 포함합니다.

Figma에서 구축 (Builds in Figma)— 프레임을 생성하고 DS 컴포넌트 인스턴스를 가져와 구성합니다. createComponent()를 호출하지 않습니다.

또는 요소를 건너뜁니다상호작용 주석 달기 (Annotates interactions)— 필터링 가능한 카테고리와 범례(legend)를 포함한 네이티브 Figma 주석을 추가합니다검증 및 제시 (Verifies and presents)— 결과물을 스크린샷으로 찍고, 선택적으로 Code Connect 매핑을 생성하며, 요약 정보와 함께 파일 URL을 공유합니다

새 버전이 출시되면 설치 항목을 수동으로 업데이트해야 합니다. 재인증은 필요하지 않으며, 단순히 파일을 교체하는 과정입니다.

• Releases 페이지에서 최신 zip 파일을 다운로드합니다.
• Settings → Customize → Skills로 이동하여 "Prototype → Figma"를 찾아 새 zip 파일을 다시 업로드합니다.

cd ~/.claude/skills/prototype-to-figma
git pull

SKILL.md와 figma-patterns.md를 이 리포지토리(repo)의 최신 버전으로 교체하세요.

변경 사항을 확인하려면 커밋 히스토리(commit history)나 릴리스(releases)를 확인하십시오.

이 스킬은 모든 Figma MCP 클라이언트에서 작동하지만, 출력 결과는 클라이언트가 지원하는 도구에 따라 달라집니다:

클라이언트 (Client)	Figma 내 구축 (Builds in Figma)	Code Connect
Claude Code, Claude Desktop, Cursor, VS Code, Copilot CLI, Augment Code, Factory, Firebender, Codex	✅	✅
...

각 티어(tier)가 생성하는 결과에 대한 자세한 내용은 SKILL.md를 참조하세요.

이 스킬은 프로토타입 제작 시 실제 공유 컴포넌트 라이브러리를 사용하는 팀을 위해 설계되었습니다. 설정이 다른 경우, 포크(fork)하여 다음과 같은 부분을 조정할 수 있습니다:

컴포넌트 매칭 로직 (Component matching logic)— 코드와 Figma가 매우 다른 명명 규칙(naming conventions)을 사용하는 경우
프레임 크기 (Frame sizes)— 기본값은 1440×900 (데스크톱) 또는 390×844 (모바일)입니다
프리미티브 폴백 패턴 (Primitive fallback patterns)— figma-patterns.md에는 Button, Input, Card, Banner를 위한 헬퍼(helpers)가 포함되어 있습니다. 다른 컴포넌트 유형에 대해서는 직접 추가할 수 있습니다
플로우 세분성 (Flow granularity)— 이 스킬은 기본적으로 마이크로 인터랙션(micro-interactions)을 하나의 주석이 달린 프레임으로 그룹화합니다. 플로우당 프레임 수를 더 늘리거나 줄이고 싶을 수 있습니다

MIT