디자인 시스템으로 화면/뷰 빌드 및 업데이트
이 스킬은 게시된 디자인 시스템(컴포넌트, 변수, 스타일)을 재사용하여 Figma에서 화면, 뷰, 여러 섹션으로 구성된 UI 컨테이너를 생성하거나 업데이트하는 데 사용됩니다. 하드코딩된 값으로 기본 도형을 그리는 대신, 게시된 디자인 시스템을 활용하세요. 여기에는 전체 페이지, 모달, 다이얼로그, 드로어, 사이드바, 패널 및 여러 섹션으로 구성된 모든 뷰가 포함됩니다. 핵심 인사이트: Figma 파일에는 코드베이스의 UI 컴포넌트 및 토큰에 해당하는 컴포넌트, 색상/간격 변수, 텍스트/효과 스타일이 포함된 게시된 디자인 시스템이 있을 가능성이 높습니다. 16진수 색상으로 상자를 그리는 대신 이를 찾아서 사용하세요.
필수: use_figma 호출 전에 반드시 figma-use도 로드해야 합니다. 해당 스킬에는 작성하는 모든 스크립트에 적용되는 중요한 규칙(색상 범위, 글꼴 로딩 등)이 포함되어 있습니다.
이 스킬의 일부로 use_figma를 호출할 때는 항상 skillNames: "figma-generate-design"을 전달하세요. 이는 로깅 파라미터이며 실행에는 영향을 미치지 않습니다.
스킬 경계
- 이 스킬은 구성된 Figma 뷰(신규 또는 업데이트), 전체 페이지 화면, 모달, 다이얼로그, 드로어, 사이드바, 패널 또는 여러 섹션 컨테이너를 디자인 시스템 컴포넌트 인스턴스로 빌드할 때 사용하세요.
- 사용자가 새로운 재사용 가능한 컴포넌트나 변형을 만들려면 figma-use를 직접 사용하세요.
- 사용자가 Code Connect 매핑을 작성하려면 figma-code-connect로 전환하세요.
전제 조건
- Figma MCP 서버가 연결되어 있어야 합니다.
- 대상 Figma 파일에 게시된 디자인 시스템(컴포넌트)이 있거나 팀 라이브러리에 접근 가능해야 합니다.
- 사용자는 다음 중 하나를 제공해야 합니다:
- 작업할 Figma 파일 URL / 파일 키
- 대상 파일에 대한 컨텍스트(에이전트가 페이지를 발견할 수 있음)
- 빌드/업데이트할 화면/뷰의 소스 코드 또는 설명
generate_figma_design을 이용한 병렬 워크플로우 (웹 앱 전용)
브라우저에서 렌더링 가능한 웹 앱에서 화면을 빌드할 때는 두 가지 접근 방식을 병렬로 실행하는 것이 가장 좋은 결과를 냅니다:
- 병렬로:
- 이 스킬의 워크플로우(use_figma + 디자인 시스템 컴포넌트)를 사용하여 화면 빌드 시작
generate_figma_design을 실행하여 실행 중인 웹 앱의 픽셀 완벽한 스크린샷 캡처
- 두 작업이 모두 완료되면:
generate_figma_design캡처의 픽셀 완벽한 레이아웃과 일치하도록 use_figma 출력을 업데이트합니다. 캡처는 목표로 할 정확한 간격, 크기, 시각적 처리를 제공하며, use_figma 출력은 디자인 시스템에 연결된 적절한 컴포넌트 인스턴스를 갖습니다. 캡처에 이미지가 포함된 경우 캡처의 이미지 채우기에서imageHash값을 복사하여 use_figma 출력으로 전송하세요(자세한 내용은 5단계 참조). - 보기에 좋은 것이 확인되면:
generate_figma_design출력을 삭제합니다. 시각적 참조용으로만 사용되었습니다.
이렇게 하면 두 가지 장점을 모두 얻을 수 있습니다: generate_figma_design은 픽셀 완벽한 레이아웃 정확성을 제공하고, use_figma는 연결 및 업데이트 가능한 적절한 디자인 시스템 컴포넌트 인스턴스를 제공합니다.
소스에 이미지가 포함된 경우 이 병렬 워크플로우는 필수입니다. use_figma 플러그인 API는 외부 이미지 URL을 가져올 수 없습니다. 파일에 이미 있는 노드에서 imageHash 값을 복사하여 이미지 채우기를 설정할 수만 있습니다. generate_figma_design은 보이는 모든 이미지를 Figma로 래스터화하여 필요한 해시를 제공합니다. 이미지가 있을 때 캡처를 건너뛰면 이미지 프레임이 비어 있게 됩니다.
iOS, Android 등 웹이 아닌 앱 또는 기존 화면 업데이트의 경우 아래 표준 워크플로우를 사용하세요.
필수 워크플로우
다음 단계를 순서대로 따르세요. 단계를 건너뛰지 마십시오.
하드 게이트, 금지된 지름길:
- 금지됨: 2a-i 단계 완료 및 2a-ii 단계 시도 또는 해당 없음(예: "빈 파일, 기존 화면 없음")으로 기록되기 전에
search_design_system으로 컴포넌트 키 검색.- 금지됨: 아래 체크리스트의 모든 2단계 행이 채워질 때까지 캔버스를 변경하는
use_figma호출(3단계 이상).
1단계: 결과물 이해
Figma를 다루기 전에 무엇을 빌드할지 이해하세요:
- 코드로 빌드하는 경우 관련 소스 파일을 읽어 구조, 섹션 및 사용된 컴포넌트를 파악하세요.
- 뷰의 주요 섹션을 식별하세요(예: 페이지의 경우 헤더, 히어로, 콘텐츠 패널, 푸터; 모달의 경우 제목 표시줄, 양식 섹션, 작업 표시줄; 사이드바의 경우 탐색, 콘텐츠 영역, 푸터 작업).
- 각 섹션에 대해 관련된 UI 컴포넌트(버튼, 입력, 카드, 탐색 필, 아코디언 등)를 나열하세요.
- 뷰에 이미지가 포함되어 있는지 확인하세요(예:
<img>,<Image>, 배경 이미지, 제품 사진, 아바타, URL에서 로드되는 아이콘). 포함되어 있고 이것이 웹 앱인 경우 병렬generate_figma_design캡처 워크플로우를 실행해야 하며, 컴포넌트를 발견하는 동안 캡처가 실행되도록 2단계와 동시에 즉시 시작하세요. 위의 "generate_figma_design을 이용한 병렬 워크플로우"를 참조하세요.
2단계: 컴포넌트 키, 변수 및 스타일 수집
디자인 시스템에서 세 가지가 필요합니다: 컴포넌트(버튼, 카드 등), 변수(색상, 간격, 반경), 스타일(텍스트 스타일, 그림자와 같은 효과 스타일). 디자인 시스템 토큰이 존재하는 경우 16진수 색상이나 픽셀 값을 하드코딩하지 마세요.
2a: 컴포넌트 발견
2a-i. 필수: 필요한 컴포넌트에 대한 Code Connect 확인. 1단계에서 만든 컴포넌트 목록에서 시작하여 각 컴포넌트에 코드베이스에 Code Connect 파일이 있는지 확인하세요. Code Connect 파일은 컴포넌트 소스 옆에 있으며 플랫폼별로 이름이 지정됩니다:
- TypeScript/JS:
*.figma.ts,*.figma.js - React (파서 기반):
*.figma.tsx - Kotlin/Compose:
@FigmaConnect를 포함하는.kt파일 - Swift:
FigmaConnect를 포함하는.swift파일
필요한 각 컴포넌트(예: Button, Card, Input)에 대해 Code Connect 파일을 검색하고, 컴포넌트 이름으로 glob 또는 grep을 수행하세요(예: **/Button.figma.tsx, **/Card.figma.ts). 실제로 필요한 컴포넌트와 일치하는 파일만 읽으세요.
일치하는 각 Code Connect 파일에서 Figma 컴포넌트 URL을 추출하세요. URL에서 fileKey와 nodeId를 파싱하세요(하이픈을 콜론으로 변환: 123-456 → 123:456). 그런 다음 use_figma를 통해 컴포넌트 키를 확인하세요:
예시: Code Connect 파일에 // url=https://figma.com/design/ABC123/File?node-id=609-35535가 포함되어 있습니다. fileKey = ABC123, nodeId = 609:35535를 파싱하세요. 라이브러리 파일(fileKey ABC123, 대상 파일이 아님)에 대해 use_figma를 실행하여 키를 확인하세요:
const node = await figma.getNodeByIdAsync("609:35535");
const set = node?.parent?.type === "COMPONENT_SET" ? node.parent : node;
return { componentKey: set.key };
단일 호출에서 여러 조회를 일괄 처리하세요. 반환된 키를 4단계에서 importComponentSetByKeyAsync()와 함께 사용하세요.
확인된 컴포넌트를 표시하세요. 모든 컴포넌트가 확인되면 2a-ii 및 2a-iii를 건너뛰세요. 필요한 컴포넌트 중 Code Connect 파일이 없는 것이 있으면 2a-ii로 진행하세요.
2a-ii. 확인되지 않은 컴포넌트가 남아 있으면 필수: 기존 화면 검사. 대상 파일에 동일한 디자인 시스템을 사용하는 화면이 이미 포함되어 있는지 확인하세요. 기존 프레임의 인스턴스를 탐색하는 단일 use_figma 호출은 정확하고 권위 있는 컴포넌트 맵을 제공합니다:
// 읽기 전용 발견, 수백 배 빠른 findAllWithCriteria를 위해
// 인스턴스 내부의 보이지 않는 콘텐츠(숨겨진 변형 등)를 건너뜁니다.
figma.skipInvisibleInstanceChildren = true;
const frame = figma.currentPage.findOne(n => n.name === "Existing Screen");
const uniqueSets = new Map();
frame.findAllWithCriteria({ types: ["INSTANCE"] }).forEach(inst => {
const mc = inst.mainComponent;
const cs = mc?.parent?.type === "COMPONENT_SET" ? mc.parent : null;
const key = cs ? cs.key : mc?.key;
const name = cs ? cs.name : mc?.name;
if (key && !uniqueSets.has(key)) {
uniqueSets.set(key, { name, key, isSet: !!cs, sampleVariant: mc.name });
}
});
return [...uniqueSets.values()];
결과를 확인되지 않은 컴포넌트와 대조하세요. 새로 확인된 것을 표시하세요. 모든 컴포넌트가 확인되면 2a-iii를 건너뛰세요.
2a-iii. 최후의 수단: search_design_system. 2a-i 및 2a-ii를 모두 완료한 후에도 컴포넌트가 확인되지 않은 경우에만 사용하세요.
검색 전에 get_libraries를 호출하여 파일에 사용 가능한 라이브러리를 발견하세요. 이는 두 가지 목록을 반환합니다: 파일에 이미 추가된 라이브러리와 추가할 수 있는 라이브러리(커뮤니티 UI 키트 및 조직 라이브러리). 각 항목에는 search_design_system에 includeLibraryKeys 파라미터로 전달할 수 있는 libraryKey가 포함되어 있어 검색 범위를 모든 라이브러리 대신 특정 라이브러리로 좁힐 수 있습니다.
// 1단계: 사용 가능한 라이브러리 발견
get_libraries({ fileKey })
// 반환: {
// libraries_added_to_file: [...],
// libraries_available_to_add: [...],
// libraries_available_to_add_next_offset: number | null
// }
// 2단계: libraryKey를 사용하여 특정 라이브러리 내 검색
search_design_system({ query: "button", fileKey, includeLibraryKeys: ["lk-abc123..."] })
libraries_available_to_add의 조직 라이브러리는 페이지네이션됩니다(페이지당 20개). libraries_available_to_add_next_offset이 null이 아닌 경우 더 많은 조직 라이브러리를 사용할 수 있으므로 offset을 해당 값으로 설정하여 get_libraries를 다시 호출하고 다음 페이지를 가져오세요. 커뮤니티 UI 키트는 첫 페이지에만 나타납니다. 사용자가 특정 라이브러리를 언급했지만 현재 페이지에 보이지 않으면 포기하기 전에 더 페이지를 넘기세요.
이는 파일에 많은 라이브러리가 있고 모든 라이브러리에서 일치하는 결과를 얻는 대신 특정 라이브러리(예: "iOS 26" 또는 "Material 3") 내에서만 검색하려는 경우 특히 유용합니다.
광범위하게 검색하세요: 여러 용어와 동의어를 시도하세요(예: "button", "input", "nav", "card", "accordion", "header", "footer", "tag", "avatar", "toggle", "icon" 등). 컴포넌트에 집중하려면 includeComponents: true를 사용하세요.
컴포넌트 속성을 맵에 포함하세요. 각 컴포넌트가 텍스트 재정의에 대해 노출하는 TEXT 속성을 알아야 합니다. 임시 인스턴스를 만들고 componentProperties(및 중첩된 인스턴스의 속성)를 읽은 다음 임시 인스턴스를 제거하세요.
속성 정보가 포함된 컴포넌트 맵 예시:
컴포넌트 맵:
- Button → key: "abc123", type: COMPONENT_SET
Properties: { "Label#2:0": TEXT, "Has Icon#4:64": BOOLEAN }
- PricingCard → key: "ghi789", type: COMPONENT_SET
Properties: { "Device": VARIANT, "Variant": VARIANT }
중첩된 "Text Heading" 속성: { "Text#2104:5": TEXT }
중첩된 "Button" 속성: { "Label#2:0": TEXT }
2b: 변수 발견(색상, 간격, 반경)
먼저 기존 화면 검사(컴포넌트와 동일). 또는 includeVariables: true와 함께 search_design_system을 사용하세요.
경고: 두 가지 다른 변수 발견 방법을 혼동하지 마십시오.
use_figma와figma.variables.getLocalVariableCollectionsAsync(): 현재 파일에 정의된 로컬 변수만 반환합니다. 이것이 비어 있으면 변수가 없다는 의미가 아닙니다. 원격/게시된 라이브러리 변수는 이 API에 표시되지 않습니다.includeVariables: true와search_design_system: 모든 연결된 라이브러리(원격 및 게시된 라이브러리 포함)를 검색합니다. 이는 디자인 시스템 변수를 발견하기 위한 올바른 도구입니다.
getLocalVariableCollectionsAsync()가 비어 있다는 것만으로 "변수가 없다"고 결론내리지 마십시오. 변수를 직접 만들기로 결정하기 전에 항상includeVariables: true와 함께search_design_system을 실행하여 라이브러리 변수가 있는지 확인하세요.
쿼리 전략: search_design_system은 변수 이름(예: "Gray/gray-9", "core/gray/100", "space/400")과 일치하며, 카테고리와는 일치하지 않습니다. 하나의 복합 쿼리보다는 여러 개의 짧고 간단한 쿼리를 병렬로 실행하세요:
- 기본 색상: "gray", "red", "blue", "green", "white", "brand"
- 의미적 색상: "background", "foreground", "border", "surface", "text"
- 간격/크기: "space", "radius", "gap", "padding"
초기 검색이 비어 있으면 더 짧은 조각이나 다른 명명 규칙을 시도하세요. 라이브러리는 매우 다양합니다("grey" vs "gray", "spacing" vs "space", "color/bg" vs "background").
가장 권위 있는 결과를 위해 기존 화면의 바인딩된 변수를 검사하세요:
// 읽기 전용 발견, 속도를 위해 인스턴스 내부 보이지 않는 콘텐츠 건너뜁니다.
figma.skipInvisibleInstanceChildren = true;
const frame = figma.currentPage.findOne(n => n.name === "Existing Screen");
// boundVariables는 모든 씬 노드에 존재할 수 있으며, 모든 씬 유형을 열거하여
// findAllWithCriteria에 전달하는 것은 findAll(() => true)와 거의 동일하며
// 스크립트 출력이 훨씬 더 복잡해집니다.
const uniqueIds = new Set(
frame.findAll(() => true).flatMap(n =>
Object.values(n.boundVariables ?? {})
.flatMap(b => Array.isArray(b) ? b : [b])
.map(b => b?.id)
.filter(Boolean)
)
);
const variables = await Promise.all(
[...uniqueIds].map(id => figma.variables.getVariableByIdAsync(id))
);
return variables
.filter(Boolean)
.map(v => ({ name: v.name, id: v.id, key: v.key, type: v.resolvedType, remote: v.remote }));
라이브러리 변수(remote = true)의 경우 figma.variables.importVariableByKeyAsync(key)로 키별로 가져오세요. 로컬 변수의 경우 figma.variables.getVariableByIdAsync(id)를 직접 사용하세요.
바인딩 패턴은 variable-patterns.md를 참조하세요.
2c: 스타일 발견(텍스트 스타일, 효과 스타일)
includeStyles: true와 "heading", "body", "shadow", "elevation"과 같은 용어로 search_design_system을 사용하여 스타일을 검색하세요. 또는 기존 화면에서 사용하는 것을 검사하세요:
// 읽기 전용 발견, 속도를 위해 인스턴스 내부 보이지 않는 콘텐츠 건너뜁니다.
figma.skipInvisibleInstanceChildren = true;
const frame = figma.currentPage.findOne(n => n.name === "Existing Screen");
const styles = { text: new Map(), effect: new Map() };
for (const node of frame.findAll(() => true)) {
// textStyleId는 TEXT 및 TEXT_PATH에 있고, effectStyleId는 대부분의 씬
// 셰이프/컨테이너 유형에 있습니다. `in` 가드를 사용하여
// 완전한 유형 목록 없이 둘 다 처리하세요.
if ('textStyleId' in node && node.textStyleId) {
const textStyle = await figma.getStyleByIdAsync(node.textStyleId);
if (textStyle && !styles.text.has(textStyle.key)) {
styles.text.set(textStyle.key, {
name: textStyle.name,
key: textStyle.key,
remote: textStyle.remote
});
}
}
if ('effectStyleId' in node && node.effectStyleId) {
const effectStyle = await figma.getStyleByIdAsync(node.effectStyleId);
if (effectStyle && !styles.effect.has(effectStyle.key)) {
styles.effect.set(effectStyle.key, {
name: effectStyle.name,
key: effectStyle.key,
remote: effectStyle.remote
});
}
}
}
return {
textStyles: [...styles.text.values()],
effectStyles: [...styles.effect.values()]
};
3단계: 대상 페이지 준비
빈 프레임(Figma에서 '섹션'이라고 함)으로 시작하세요. 기존 화면을 업데이트하는 경우 대상 프레임을 찾거나 재사용할 대상을 식별하세요.
4단계: 디자인 시스템 요소 가져오기
가져오기 전에 마스터 컴포넌트가 이미 로컬에 있는지 확인하세요. 대부분의 경우 importComponentSetByKeyAsync가 필요합니다. 필요한 컴포넌트가 이미 로컬에 있는 경우 건너뛰고 직접 인스턴스화할 수 있습니다.
const componentKeys = ["abc123", "def456", "ghi789"];
await Promise.all(
componentKeys.map(key => figma.importComponentSetByKeyAsync(key))
);
변수 및 스타일도 유사하게 가져옵니다.
5단계: 섹션별로 뷰 어셈블
한 번에 모든 것을 빌드하려고 하지 마세요. 각 섹션을 개별적으로 빌드, 정렬 및 스타일링하세요. 각 섹션에 대해:
- 프레임 생성 - 섹션에 대한 상위 컨테이너 설정
- 컴포넌트 인스턴스화 - 올바른 변형 선택, 텍스트 재정의 적용, 가시성 전환 설정
- 변수로 스타일링 - 채우기, 획, 간격, 모서리 반경에 변수 적용.
setBoundVariable사용:
const variable = await figma.variables.importVariableByKeyAsync("varKey");
frame.setBoundVariable("fills", variable);
setBoundVariable이 예상치 못한 오류(빨간색과 유사한 오류)를 발생시키는 경우 변수를 직접 적용하세요:
const variable = await figma.variables.importVariableByKeyAsync("varKey");
const collectionId = variable.variableCollectionId;
const modeId = (await figma.variables.getVariableCollectionByIdAsync(collectionId)).defaultModeId;
frame.fills = [{ type: "SOLID", color: { r: 0, g: 0, b: 0 }, boundVariables: { color: { id: variable.id, type: "VARIABLE_ALIAS" } } }];
- 참고:
setBoundVariable은 대부분의 경우 선호되는 API이지만 예상치 못한 오류(예: 빨간색 유사 오류)가 발생할 수 있습니다. 이 경우 위의 대체 접근 방식을 사용하여 수동으로 채우기를 설정하고boundVariables에서 변수 ID를 참조하세요.
- 텍스트 스타일 적용 - 선택한 텍스트 노드에 텍스트 스타일 적용
- 이미지 처리 - 이미지 채우기가 필요한 경우
generate_figma_design캡처에서 imageHash를 가져와 복사하세요:
// generate_figma_design 캡처 노드에서 imageHash 추출
const captureNode = /* generate_figma_design로 생성되거나 식별된 노드 */;
const imageHash = captureNode.fills[0].imageHash;
// 동일한 이미지 해시를 사용하여 대상 노드에 이미지 채우기 설정
targetNode.fills = [{ type: "IMAGE", imageHash, scaleMode: "FILL" }];
- 인스턴스 및 프레임 정렬 - AutoLayout, 간격, 패딩 조정
6단계: 검토 및 반복
각 섹션을 추가한 후 빌드를 검토하세요. 누락된 섹션을 식별하고 발견되지 않은 디자인 시스템 요소를 캡처하기 위해 search_design_system을 다시 실행하세요. 섹션을 수정, 추가 또는 제거하세요.
체크리스트
다음 값이 모두 채워지면 3단계 진행이 허용됩니다:
- 각 필수 컴포넌트의 키가 수집됨 (2a-i, 2a-ii, 또는 2a-iii에서)
- 각 필수 변수의 키가 수집됨 (2b에서)
- 각 필수 스타일의 키가 수집됨 (2c에서)
- 필수 이미지에 대해
generate_figma_design이 시작됨 (웹 앱의 경우, 1단계에서 확인)
오류 처리
- 컴포넌트 키 가져오기 실패: 대상 라이브러리에서 키를 다시 확인하세요. Code Connect URL은 파일 키가 아니라 라이브러리 키를 가리킬 수 있습니다. 다른 라이브러리를 시도하세요.
- 스타일을 찾을 수 없음: 정확히 일치하는 항목을 찾을 수 없으면 사용 가능한 가장 가까운 스타일을 사용하세요. 생성하지 마세요.
- 변수를 찾을 수 없음: 유사하게 사용 가능한 변수 중 가장 가까운 일치 항목을 사용하세요. 대상 라이브러리에서 이름을 확인하세요.
- 스크립트 오류: Figma MCP stdout에서 오류를 확인하세요. 일반적인 문제: 변수 이름에 예약 문자, 존재하지 않는 노드에 대한 참조, 수정 전 읽기 잠금 획득 실패.
예시 워크플로우
"이 버튼이 포함된 가격 페이지를 Figma에 만들어 줘"
- 코드를 읽고 페이지가 PricingCard, Button, Tag 컴포넌트로 구성되어 있음을 식별합니다.
- PricingCard에 대한 Code Connect 파일을 확인하고 (
**/PricingCard.figma.ts를 grep) 해당 라이브러리 파일에서 컴포넌트 키ghi789를 찾습니다. - Button에 대한 Code Connect 파일을 확인하고 (
**/Button.figma.ts를 grep) 컴포넌트 키abc123을 찾습니다. - Tag에는 Code Connect 파일이 없습니다. 기존 화면을 검사합니다. 없으므로
search_design_system({ query: "tag", .., })을 사용하고 키def456을 찾습니다. - 변수 발견:
search_design_system({ includeVariables: true, query: "space" })를 실행하고space/4,space/6을 찾습니다. - 변수 발견:
search_design_system({ includeVariables: true, query: "gray" })를 실행하고core/gray/100을 찾습니다. - 스타일 발견:
search_design_system({ includeStyles: true, query: "shadow" })를 실행하고shadow/sm을 찾습니다. use_figma를 사용하여 PricingCard, Button, Tag를 가져오고 변수와 스타일을 적용합니다.- 페이지를 섹션별로 어셈블하고 AutoLayout을 적용하여 배치합니다.