Cursor의 Composer는 많은 UI 코드를 작성할 수 있습니다. 하지만 Figma 파일을 읽을 수는 없습니다. 스크린샷을 붙여넣으면 추측합니다 — 잘못된 간격, 발명된 색상 값, 코드베이스의 어떤 것과도 일치하지 않는 만들어진 컴포넌트 이름. 문제는 모델이 아닙니다. 구조화된 컨텍스트가 없는 것입니다.

figmascope가 이를 해결합니다. Figma 파일을 zip 번들로 내보냅니다: 디자인 토큰, 화면별 레이아웃 트리, 2배 참조 렌더, 컴포넌트 인벤토리, UI 문자열 — Cursor의 에이전트가 그럴듯해 보이는 코드가 아닌 정확한 코드를 생성하는 데 필요한 모든 것.

이 가이드는 전체 파이프라인을 다룹니다: Figma URL → 컨텍스트 번들 → Cursor 프롬프트 → 검토된 출력.

번들에 포함된 것

figmascope가 파일을 내보내면 zip에는 다음이 포함됩니다:

번들은 사용자 컴퓨터에 유지됩니다. 어디에도 다시 업로드되지 않습니다.

1단계: 번들 생성

figmascope로 이동하여 입력 필드에 Figma 파일 URL을 붙여넣습니다. 내보내기는 Figma REST API에 대해 브라우저에서 실행됩니다 — 처음에는 개인 액세스 토큰이 필요합니다(localStorage에 저장되며 figmascope 서버로 전송되지 않음).

에이전트 컨텍스트 내보내기를 클릭하세요. 페이지에서 각 프레임을 처리하고, 토큰을 해결하고, IR을 구성한 다음 context-bundle.zip을 다운로드합니다.

파일에 많은 프레임이 있는 경우, 컴포넌트나 썸네일이 아닌 최상위 프레임만 포함됩니다. _meta.json은 정확히 어떤 프레임이 내보내졌는지와 경고(그라데이션 채우기, 지원되지 않는 효과)를 보여줍니다.

2단계: 프로젝트에 압축 해제

Cursor가 볼 수 있는 위치에 번들을 배치하세요 — 레포지토리 루트의 design/ 디렉토리가 가장 깔끔한 패턴입니다.

# 프로젝트 루트에서
unzip ~/Downloads/context-bundle.zip -d ./design/

# 구조 확인
ls design/
# CONTEXT.md  _meta.json  components/  screens/  strings.json  tokens.json

번들을 커밋하고 싶지 않다면 design/을 .gitignore에 추가하세요. 또는 커밋하세요 — 결정론적입니다. 동일한 상태의 동일한 Figma 파일은 항상 동일한 번들을 생성하므로 diff가 의미있습니다.

3단계: .cursorrules 스니펫 추가

Cursor는 레포지토리 루트의 .cursorrules를 읽고 모든 채팅 컨텍스트 앞에 추가합니다. 여기서 에이전트를 번들에 연결합니다.

# .cursorrules

When building UI screens:
1. Read ./design/CONTEXT.md first. It specifies the target framework and constraints.
2. Use tokens from ./design/tokens.json for all spacing, color, radius, and typography values.
3. Reference ./design/screens/<name>.json for layout structure and node hierarchy.
4. Match ./design/screens/<name>.png for visual confirmation — use it as a sanity check, not the source of truth.
5. Use string keys from ./design/strings.json rather than hardcoding UI copy.
6. Do not invent token values. If a value isn't in tokens.json, flag it.

이 단일 블록은 세 가지 가장 일반적인 드리프트 원인을 방지합니다: 발명된 색상, 하드코딩된 문자열, 스크린샷으로부터의 레이아웃 추측.

4단계: Cursor Composer를 열고 화면 구현

Composer를 엽니다(macOS에서 Cmd+I). 프롬프트 전에 파일을 고정하세요: 클립 아이콘을 클릭하고 design/CONTEXT.md, design/tokens.json, design/screens/home.json을 추가합니다. 그런 다음 프롬프트하세요:

Implement the home screen from ./design/screens/home.json.

Constraints:
- Target framework and component conventions are in ./design/CONTEXT.md
- All spacing, color, and radius values must come from ./design/tokens.json
- UI strings must use keys from ./design/strings.json
- The root node is a stack (vertical). Children are declared in order in the JSON.
- Do not invent any values not present in the token or IR files.

Cursor는 고정된 파일을 읽고, IR 노드를 프레임워크의 기본 요소에 매핑하고, 구현을 생성합니다. 출력은 토큰 참조됩니다 — 생성된 코드를 검사하면 모든 간격 값이 tokens.json의 키로 추적되어야 합니다.

5단계: 검토 및 반복

렌더링된 출력 옆에 design/screens/home.png를 엽니다. PNG는 Figma의 2배 내보내기입니다 — 디자인이 어떻게 보여야 하는지 정확히 보여줍니다. 차이점은 의미있습니다: IR 매핑 공백 또는 적용되지 않은 토큰 값을 가리킵니다.

일반적인 문제와 후속 프롬프트:

토큰 드리프트 — 에이전트가 토큰 대신 하드코딩된 hex를 사용했습니다:

Compare every color value in the generated component against ./design/tokens.json.
List any colors that don't match a token key. Replace them with the correct token reference.

누락된 컴포넌트 — IR이 에이전트가 해결하지 못한 컴포넌트 ID를 참조합니다:

The IR references componentId "btn-primary-01". Check ./design/components/inventory.json
for its name and type, then implement a placeholder with that name and the correct token values.

레이아웃 불일치 — 간격이나 정렬이 PNG와 일치하지 않습니다:

The vertical gap between the header and the card list should be spacing.24 from tokens.json (24dp).
Your output uses 16px. Fix it.

작동하는 것, 작동하지 않는 것

잘 작동합니다: 스택 레이아웃의 평탄한 화면, 토큰 기반 간격 및 색상, 문자열 참조가 있는 텍스트, 간단한 카드 및 목록 패턴. IR이 컨텍스트에 있으면 Cursor가 이를 잘 처리합니다 — 추측을 멈추고 매핑을 시작합니다.

잘 작동하지 않습니다: 복잡한 절대 위치 오버레이(Cursor가 때때로 오프셋 좌표를 잘못 읽음), 그라데이션 채우기(_meta.json에 경고로 표시됨 — Cursor가 근사치를 계산함), 벡터 아이콘(IR은 경로 데이터가 아닌 참조 ID만 저장함).

스크린샷 전용 vs. 번들: 스크린샷 전용은 시작이 빠르지만 비결정론적입니다. 모든 세션이 새로 시작합니다. 모델이 한 번은 간격을 맞추고 다음 턴에 놓칠 수 있습니다. 번들은 전체 세션에 걸쳐 참조 가능합니다 — Cursor는 어느 시점에서도 재업로드 없이 토큰 파일에 대해 자신의 출력을 확인할 수 있습니다.

팁: 프롬프트 전에 _meta.json 경고 확인

첫 번째 구현 프롬프트 전에 design/_meta.json을 읽으세요. warnings 배열에는 내보내기가 완전히 해결하지 못한 항목이 나열됩니다: 그라데이션 채우기, 누락된 토큰 매핑, 내장 이미지가 있는 프레임. 에이전트가 하드코딩된 값으로 조용히 폴백하지 않도록 프롬프트에 이에 대한 메모를 추가하세요.

cat design/_meta.json | python3 -m json.tool | grep -A 20 '"warnings"'

출력에 특정 노드의 "gradientFill: not fully supported"가 표시되면, Cursor에게 해당 노드의 배경을 건너뛰고 대신 // TODO: gradient 주석을 남기도록 지시하세요.

요약

워크플로는 다음과 같습니다: 한 번 내보내고, 어디서나 참조하세요. 번들은 디자인을 재처리하지 않고도 Cursor가 여러 턴에 걸쳐 참조할 수 있는 안정적인 기계 판독 가능 명세입니다. 스크린샷 근사치 대신 토큰 정확, 문자열 참조, 레이아웃 올바른 코드를 얻습니다 — 무언가 벗어나면 한 줄로 에이전트를 진실의 원천으로 돌릴 수 있습니다.

figmascope.dev에서 직접 실행해 보세요 — Figma URL을 붙여넣고, 에이전트 컨텍스트 내보내기를 클릭하고, 2분 이내에 번들을 Cursor 워크스페이스에 압축 해제하세요.