use_figma. Figma Plugin API 스킬
use_figma 도구를 사용하여 Plugin API를 통해 Figma 파일에서 JavaScript를 실행하세요. 모든 상세 참조 문서는 references/ 디렉토리에 있습니다.
use_figma 호출 시 항상 skillNames: "figma-use"를 전달하세요. 이는 스킬 사용을 추적하기 위한 로깅 매개변수입니다. 실행에는 영향을 미치지 않습니다.
Figma MCP 도구가 지연 도구로 표시되면 select: 문법을 사용하여 단일 ToolSearch 호출로 모든 스키마를 일괄 로드하세요. 예: ToolSearch query="select:use_figma,get_screenshot,get_metadata,create_new_file". 한 번의 왕복으로 여섯 번을 이깁니다.
작업이 코드에서 Figma의 전체 페이지, 화면 또는 여러 섹션 레이아웃을 구축하거나 업데이트하는 것과 관련된 경우, figma-generate-design도 로드하세요. 이는 search_design_system을 통해 디자인 시스템 컴포넌트를 발견하고, 가져오고, 점진적으로 화면을 조립하는 워크플로우를 제공합니다. 두 스킬이 함께 작동합니다: 이 스킬은 API 규칙을, 해당 스킬은 화면 구축 워크플로우를 담당합니다.
작업이 Figma에서 컴포넌트(단일 컴포넌트라도)를 생성하거나 구축하는 것과 관련된 경우, figma-generate-library도 로드하세요. 이는 컴포넌트 생성 워크플로우, 변수 기초, 변형 세트, 디자인 토큰 바인딩을 제공합니다. use_figma 단독으로는 다루지 않는 내용입니다.
시작하기 전에 plugin-api-standalone.index.md를 로드하여 무엇이 가능한지 이해하세요. Plugin API 코드를 작성하라는 요청을 받으면 이 컨텍스트를 사용하여 plugin-api-standalone.d.ts에서 관련 타입, 메서드 및 속성을 grep하세요. 이것이 API 표면에 대한 결정적인 진실 공급원입니다. 매우 큰 타이핑 파일이므로 한 번에 모두 로드하지 말고 필요에 따라 관련 섹션을 grep하세요.
중요: 디자인 시스템을 다룰 때는 먼저 working-with-design-systems/wwds.md를 시작하여 Figma에서 디자인 시스템 작업에 대한 주요 개념, 프로세스 및 지침을 이해하세요. 그런 다음 필요에 따라 컴포넌트, 변수, 텍스트 스타일 및 효과 스타일에 대한 더 구체적인 참조를 로드하세요.
1. 중요 규칙
- 데이터를 다시 보내려면
return을 사용하세요. 반환 값은 자동으로 JSON 직렬화됩니다(객체, 배열, 문자열, 숫자).figma.closePlugin()을 호출하거나 코드를 async IIFE로 감싸지 마세요. 이는 자동으로 처리됩니다. - 최상위
await및return을 사용하여 일반 JavaScript를 작성하세요. 코드는 자동으로 async 컨텍스트로 감싸집니다.(async () => { ... })()로 감싸지 마세요. figma.notify()는 "구현되지 않음"을 던집니다: 절대 사용하지 마세요. 3a.use_figma에서는getPluginData()/setPluginData()가 지원되지 않습니다: 사용하지 마세요. 대신getSharedPluginData()/setSharedPluginData()를 사용하세요(이들은 지원됩니다). 또는 노드 ID를 반환하고 후속 호출에 전달하여 추적하세요.console.log()는 반환되지 않습니다. 출력에는return을 사용하세요.- 작은 단계로 점진적으로 작업하세요. 큰 작업을 여러
use_figma호출로 나누세요. 각 단계 후에 검증하세요. 이는 버그를 피하기 위한 가장 중요한 단일 사례입니다. - 색상은 0-1 범위(0-255가 아님)입니다:
{r: 1, g: 0, b: 0}= 빨간색. - 채우기/획은 읽기 전용 배열입니다: 복제, 수정, 재할당하세요.
- 모든 텍스트 편집은 정식 레시피를 따릅니다: 글꼴 로드 →
await→ 변경 → 영향을 받은 노드 ID 반환. 로드를 건너뛰면Cannot write to node with unloaded font "<family> <style>"오류가 발생합니다. 이 규칙은characters보다 더 많은 것을 다룹니다: 로드되지 않은 글꼴이 있는 노드에 대한 모든 작업(appendChild,insertChild,setBoundVariable,setExplicitVariableModeForCollection,setValueForMode, 텍스트를 건드리는findAll콜백)에 적용됩니다. 기존 텍스트를 변경할 때는 하드코딩된 기본값이 아닌getStyledTextSegments(['fontName'])을 통해 노드의 현재 글꼴을 로드하세요. Inter는 대부분의 환경에서 미리 로드되므로 다른 패밀리에서 이 버그가 더 자주 발생합니다. 레시피는 모든 글꼴에 대해 동일합니다. 스타일 문자열이 확인되지 않은 경우 먼저await figma.listAvailableFontsAsync()를 사용하세요. 정식 텍스트 편집 레시피를 참조하세요. - 페이지는 점진적으로 로드됩니다:
await figma.setCurrentPageAsync(page)를 사용하여 페이지를 전환하고 콘텐츠를 로드하세요. 동기 설정자figma.currentPage = page는 작동하지 않으며 오류를 던집니다(아래 페이지 규칙 참조). setBoundVariableForPaint는 새로운 페인트를 반환하므로 반드시 캡처하여 재할당해야 합니다.createVariable은 컬렉션 객체 또는 ID 문자열을 허용합니다(객체 선호).layoutSizingHorizontal/Vertical은 구조적 컨텍스트에 의해 값이 제한되며,FIXED는 항상 작동하지만HUG와FILL은 그렇지 않습니다.'HUG'는 자동 레이아웃 프레임 자체 또는 자동 레이아웃 프레임의 TEXT 자식에서만 유효합니다.'FILL'은 자동 레이아웃 프레임의 자식으로, 절대 위치에 있지 않고, 변경할 수 없는 프레임 내부에 있지 않으며, 캔버스 그리드 자식이 아닌 경우에만 유효합니다. 실제 결과: 먼저 자동 레이아웃 부모에 추가한 다음HUG/FILL을 설정하세요. 새로 생성되었거나 부모가 없는 노드는 아직 이 규칙을 충족할 수 없습니다. 속성 자체는 모든SceneNode에 존재합니다. 오류는 "속성 없음"이 아니라 값 거부입니다. Gotchas를 참조하세요. 12a. 관련 자식을 보유하는 컨테이너에는 자동 레이아웃을 사용하세요. 자식이 구조적 관계(스택, 나란히, 정렬, 간격, 허깅)를 가질 때는 절대x/y좌표를 사용하는figma.createFrame()이 아닌figma.createAutoLayout()으로 감싸세요. 절대 좌표는 캔버스에서 컨테이너가 어디에 위치하는지를 결정하고, 자동 레이아웃은 그 안에서 자식이 어떻게 서로 관계를 맺는지를 결정합니다. 컨테이너를 건너뛰면 텍스트 리플로우, 콘텐츠 변경 또는 겹침으로부터 보호되지 않습니다.- 새로운 최상위 노드를 (0,0)에서 멀리 배치하세요. 페이지에 직접 추가된 노드는 기본적으로 (0,0)에 위치합니다.
figma.currentPage.children을 스캔하여 명확한 위치(예: 가장 오른쪽 노드의 오른쪽)를 찾으세요. 이는 페이지 수준 노드에만 적용됩니다. 다른 프레임이나 자동 레이아웃 컨테이너 내부에 중첩된 노드는 부모에 의해 배치됩니다. Gotchas를 참조하세요. use_figma오류 발생 시 즉시 중지하세요. 바로 재시도하지 마세요. 실패한 스크립트는 원자적입니다: 스크립트가 오류를 발생시키면 전혀 실행되지 않으며 파일에 변경 사항이 없습니다. 오류 메시지를 주의 깊게 읽고, 스크립트를 수정한 후 재시도하세요. 오류 복구를 참조하세요.- 생성/변경된 모든 노드 ID를 반드시
return하세요. 스크립트가 캔버스에 새 노드를 생성하거나 기존 노드를 변경할 때마다 영향을 받는 모든 노드 ID를 수집하여 구조화된 객체(예:return { createdNodeIds: [...], mutatedNodeIds: [...] })로 반환하세요. 이는 후속 호출에서 해당 노드를 참조, 검증 또는 정리하는 데 필수적입니다. - 변수 생성 시 항상
variable.scopes를 명시적으로 설정하세요. 기본값ALL_SCOPES는 모든 속성 선택기를 오염시키며 거의 원하는 결과가 아닙니다. 배경에는["FRAME_FILL", "SHAPE_FILL"], 텍스트 색상에는["TEXT_FILL"], 간격에는["GAP"]등과 같은 특정 범위를 사용하세요. 전체 목록은 variable-patterns.md를 참조하세요. - 모든 Promise를
await하세요. Promise를 await하지 않은 채로 두지 마세요. await되지 않은 async 호출(예:await없는figma.loadFontAsync(...)또는await없는figma.setCurrentPageAsync(page))은 fire-and-forget 방식으로 실행되어 무음 실패 또는 경쟁 조건을 유발합니다. 스크립트가 async 작업이 완료되기 전에 반환되어 데이터 누락 또는 변경 사항이 절반만 적용될 수 있습니다.
각 규칙에 대한 자세한 잘못된/올바른 예는 Gotchas 및 일반적인 실수를 참조하세요.
2. 페이지 규칙 (중요)
페이지 컨텍스트는 use_figma 호출 사이에 재설정됩니다: figma.currentPage는 매번 첫 번째 페이지에서 시작합니다.
페이지 전환
await figma.setCurrentPageAsync(page)를 사용하여 페이지를 전환하고 해당 콘텐츠를 로드하세요. 동기 설정자 figma.currentPage = page는 작동하지 않습니다: use_figma에서 "Setting figma.currentPage is not supported" 오류를 던집니다. 항상 async 메서드를 사용하세요.
// 특정 페이지로 전환(해당 콘텐츠 로드)
const targetPage = figma.root.children.find((p) => p.name === "My Page");
await figma.setCurrentPageAsync(targetPage);
// targetPage.children이 이제 채워집니다
use_figma 호출당 setCurrentPageAsync를 최대 한 번만 호출하고, 다중 페이지 작업을 병렬로 분산하세요
하나의 스크립트는 페이지를 최대 한 번만 전환해야 합니다. figma.root.children을 반복하고 루프 내에서 페이지를 전환하지 마세요.
작업이 여러 페이지에 걸쳐 있는 경우 해당 작업을 N개의 use_figma 호출(대상 페이지당 하나)로 분할하고 병렬로 전송하세요: N개의 use_figma 도구 사용 블록을 포함하는 단일 어시스턴트 메시지입니다. 실행 환경은 이를 동시에 실행합니다. 각 스크립트는 currentPage를 정확히 한 번 설정합니다.
명시적 지침: 분산할 때는 반드시 N개의 도구 호출을 하나의 메시지로 발행해야 합니다. 여러 턴에 걸쳐 보내지 마세요. 하나를 보내기 전에 다른 하나를 await하지 마세요. 순차적인 페이지별 호출은 이 규칙이 대체하는 루프 내 패턴보다 느리며 분할의 모든 이점을 낭비합니다.
// 피하세요, 하나의 스크립트에서 페이지를 N번 전환하며 파일을 매번 다시 로드합니다
for (const page of figma.root.children) {
await figma.setCurrentPageAsync(page);
// ... 이 페이지를 건드립니다 ...
}
// 선호하세요, 읽기 전용 검색 호출로 페이지 ID를 얻은 후, 다음 메시지에서
// N개의 병렬 use_figma 도구 호출(페이지당 하나)을 발행하고 각각 currentPage를 한 번 설정합니다.
다중 페이지 작업(읽기 및 쓰기 모두)에 대해 기본적으로 병렬 분산을 사용하세요. 전체 근거는 gotchas.md → Set current page once per use_figma call를 참조하세요.
스크립트 실행 간
figma.currentPage는 각 use_figma 호출 시작 시 첫 번째 페이지로 재설정됩니다. 워크플로우가 여러 호출에 걸쳐 있고 기본이 아닌 페이지를 대상으로 하는 경우 각 호출 시작 시 await figma.setCurrentPageAsync(page)를 호출하세요.
파일 상태에 대해 점진적으로 구축하거나 다른 스크립트를 작성하기 전에 정보를 검색하기 위해 use_figma를 여러 번 호출할 수 있습니다. 예를 들어, 기존 노드에 대한 메타데이터를 얻는 스크립트를 작성하고 return한 다음, 해당 데이터를 사용하여 후속 스크립트에서 해당 노드를 수정할 수 있습니다.
3. return이 출력 채널입니다
에이전트는 오직 return한 값만 볼 수 있습니다. 그 외의 모든 것은 보이지 않습니다.
- ID 반환(중요): 캔버스 노드를 생성하거나 변경하는 모든 스크립트는 반드시 영향을 받는 모든 노드 ID를 반환해야 합니다. 예:
return { createdNodeIds: [...], mutatedNodeIds: [...] }. 이는 하드 요구사항이며 선택 사항이 아닙니다. - 진행 보고:
return { createdNodeIds: [...], count: 5, errors: [] } - 오류 정보: 던져진 오류는 자동으로 캡처되어 반환됩니다. 그냥 전파하도록 두거나
throw를 명시적으로 사용하세요. console.log()출력은 절대 에이전트에 반환되지 않습니다.- 후속 호출에서 생성된 객체를 참조할 수 있도록 항상 실행 가능한 데이터(ID, 개수, 상태)를 반환하세요.
4. 편집기 모드
use_figma는 디자인 모드(editorType "figma", 기본값)에서 작동합니다. FigJam("figjam") 및 Slides("slides")는 사용 가능한 노드 유형 집합이 다릅니다. 대부분의 디자인 노드는 FigJam에서 차단되고 FigJam 전용 노드는 Slides에서 차단됩니다.
URL에서 편집기를 확인하세요: 디자인 = figma.com/design/..., FigJam = figma.com/board/..., Slides = figma.com/slides/.... API를 사용할 수 있다고 가정하기 전에 확인하세요.
디자인 모드에서 사용 가능: Rectangle, Frame, Component, Text, Ellipse, Star, Line, Vector, Polygon, BooleanOperation, Slice, Page, Section, TextPath.
디자인 모드에서 차단됨: Sticky, Connector, ShapeWithText, CodeBlock, Slide, SlideRow, SlideGrid, InteractiveSlideElement, Webpage.
Slides 모드에서 사용 가능: Rectangle, Frame, Component, Text, Ellipse, Star, Line, Vector, Polygon, BooleanOperation, Slice, Section, TextPath, Slide, SlideRow, SlideGrid, InteractiveSlideElement.
Slides 모드에서 차단됨: Sticky, Connector, ShapeWithText, CodeBlock, Webpage, Page.
디자인 전용 API(노드 유형뿐만 아니라): figma.createPage()는 디자인 파일(figma.com/design/...)에서만 사용 가능합니다. FigJam(figma.com/board/...) 및 Slides(figma.com/slides/...) 모두에서 TypeError: figma.createPage no such property 'createPage' on the figma global object 오류를 던집니다. FigJam 또는 Slides 워크플로우에서 figma.createPage()를 사용하지 마세요.
Slides 참고: 아직 Slides 파일 전용 읽기 도구는 없습니다. 검사를 위해
use_figma를 읽기 전용 스크립트와 함께 사용하고(섹션 6 "먼저 검사" 패턴 참조), 시각적 컨텍스트를 위해get_screenshot/await node.screenshot()을 사용하세요. Slides 전용 API 지침은 figma-use-slides 스킬을 로드하세요.
5. 효율적인 API. 장황한 대안보다 이것들을 선호하세요
이러한 API는 상용구를 줄이고, 순서 오류를 제거하며, 토큰 출력을 압축합니다. 장황한 대안보다 항상 이것들을 선호하세요.
node.query(selector): CSS와 유사한 노드 검색
CSS와 유사한 선택기를 사용하여 하위 트리 내에서 노드를 찾습니다. 장황한 findAll + 필터 루프를 대체합니다.
// 이전, 장황한 순회
const texts = frame.findAll(n => n.type === 'TEXT' && n.name === 'Title')
// 이후, query를 사용한 한 줄
const texts = frame.query('TEXT[name=Title]')
선택기 구문:
- 유형:
FRAME,TEXT,RECTANGLE,ELLIPSE,COMPONENT,INSTANCE,SECTION(대소문자 구분 안 함) - 속성 정확히 일치:
[name=Card],[visible=true],[opacity=0.5] - 속성 부분 문자열:
[name*=art](포함),[name^=Header](시작),[name$=Nav](끝) - 점 경로 순회:
[fills.0.type=SOLID],[fills.*.type=SOLID](와일드카드 인덱스) - 인스턴스 일치:
[mainComponent=nodeId],[mainComponent.name=Button] - 결합자:
FRAME > TEXT(직접 자식),FRAME TEXT(모든 하위),A + B(인접 형제),A ~ B(일반 형제) - 의사 클래스:
:first-child,:last-child,:nth-child(2),:not(TYPE),:is(FRAME, RECTANGLE),:where(TEXT, ELLIPSE) - 노드 ID:
#nodeId또는 bare GUID - 쉼표:
TEXT, RECTANGLE
query는 읽기 전용입니다. 노드를 변형하지 않습니다. 하위 트리가 변경되는 즉시 결과가 무효화됩니다. 자세한 내용은 쿼리 단원을 참조하세요.
figma.createNode(type): 문자열 기반 노드 생성
지원되는 유형: 'FRAME', 'TEXT', 'RECTANGLE', 'ELLIPSE', 'STAR', 'LINE', 'VECTOR', 'POLYGON', 'SECTION'. 문자열 기반이지만 figma.createRectangle()과 동일한 Node 객체를 반환합니다.
const rect = figma.createNode('RECTANGLE');
// figma.createRectangle()과 동일
node.getCSSAsync(): 디자인 토큰 추출
선택한 행의 CSS 변수를 추출합니다. 디자인 토큰 내보내기와 유사합니다.
node.locked 및 가시성
node.locked, node.visible 등 속성을 직접 사용하세요. 설정자도 지원합니다.
6. 오류 복구 및 자체 수정
오류를 추측하거나 미리 수정하지 마세요. 다음과 같이 진행하세요:
use_figma스크립트 작성- 오류가 발생하면 오류 메시지를 주의 깊게 읽으세요.
- 논리 오류인지 API 오류인지 확인하세요.
- 원래 요청을 다시 보내지 않고 오류 메시지에 따라 스크립트를 수정하여 오류를 해결하세요.
- 수정된 스크립트를 다시 제출하세요.
먼저 검사 패턴 (권장)
변경하기 전에 먼저 읽는 것이 좋습니다. 특히 다루는 파일이 처음이거나 예상치 못한 오류가 발생한 경우 더욱 그렇습니다. 스크립트에서 오타가 난 이름이나 존재하지 않는 노드를 수정하려고 시도하면 오류가 발생합니다.
// 먼저 검사: 구조 이해
const pageInfo = figma.root.children.map(p => ({
name: p.name, id: p.id, childCount: p.children.length
}));
return { pages: pageInfo };
7. 일반적인 패턴
노드 생성 및 포지셔닝
// 프레임 생성
const frame = figma.createNode('FRAME');
frame.name = "My Frame";
frame.resize(200, 100);
// 기존 콘텐츠를 기준으로 포지셔닝
const parent = figma.currentPage;
if (parent.children.length > 0) {
const rightmost = Math.max(...parent.children.map(n => n.x + n.width));
frame.x = rightmost + 100;
frame.y = 0;
}
parent.appendChild(frame);
return { createdNodeIds: [frame.id] };
텍스트 편집
await figma.loadFontAsync({ family: "Inter", style: "Regular" });
const text = figma.createNode('TEXT');
text.characters = "Hello World";
text.fontName = { family: "Inter", style: "Regular" };
text.fontSize = 16;
text.fills = [{ type: 'SOLID', color: { r: 0, g: 0, b: 0 } }];
figma.currentPage.appendChild(text);
return { createdNodeIds: [text.id] };
변수 작업
// 컬렉션 확인
const collections = figma.variables.getLocalVariableCollections();
if (collections.length === 0) {
// 새 컬렉션 생성
const collection = figma.variables.createVariableCollection("Design Tokens");
collection.modes = [{ modeId: "STANDARD", name: "Standard" }];
// 변수 생성
const variable = figma.variables.createVariable("primary", collection, "COLOR");
variable.scopes = ["FRAME_FILL", "SHAPE_FILL"];
variable.setValueForMode(collection.modes[0].modeId, { r: 0.2, g: 0.4, b: 1 });
return { collectionId: collection.id, variableId: variable.id };
}
자세한 지침은
references/디렉토리의 참조 문서를 참조하세요.