Cursor의 AI는 UI 코드를 많이 작성할 수 있습니다. 하지만 Figma 파일을 읽지는 못합니다. 스크린샷을 붙여 넣으면 추측으로 코드를 생성합니다 — 잘못된 간격, 잘못된 색상 값, 존재하지 않는 컴포넌트 이름. 문제는 모델이 아니라 구조화된 컨텍스트의 부재입니다.

figmascope는 이 간극을 메워 줍니다. Figma 파일을 zip 번들로 내보냅니다 — 디자인 토큰, 화면별 레이아웃 트리, 참조 렌더, 컴포넌트 인벤토리, UI 문자열 — 언어 모델이 그럴 듯한 코드가 아닌 정확한 코드를 생성하는 데 필요한 모든 정보를 포함합니다. 메인 앱은 백엔드나 업로드 없이 브라우저에서 완전히 실행됩니다.

이 페이지는 Figma URL에서 Cursor 코드젠까지의 전체 워크플로우를 안내합니다. Cursor 대신 Claude Code를 사용하신다면 Figma to Claude Code를 참고하세요. 에이전트 친화적 핸드오프의 큰 그림은 AI 디자인 핸드오프를 확인하세요.

컨텍스트 번들에 포함되는 항목

figmascope를 Figma 파일에 실행하면 다음을 포함하는 .zip이 생성됩니다:

업로드는 없습니다. 개인 액세스 토큰은 브라우저 메모리에만 저장되며 api.figma.com에만 전송됩니다. zip은 클라이언트 측에서 조립되어 브라우저 다운로드로 전달됩니다.

1단계 — Figma 개인 액세스 토큰 발급

Figma → 계정 설정 → Personal Access Tokens에서 File content: read-only 범위의 토큰을 생성합니다. 이것이 최소 요구 사항입니다.

토큰은 브라우저 세션을 벗어나지 않습니다. figmascope는 api.figma.com에 대한 요청의 X-Figma-Token 헤더로만 토큰을 사용합니다. 전체 위협 모델은 PAT 보안과 figmascope를 참고하세요.

2단계 — 컨텍스트 번들 내보내기

  1. 브라우저에서 figmascope.dev를 엽니다.
  2. Figma 파일 URL을 붙여 넣습니다 (예: https://www.figma.com/file/ABC123/MyDesign).
  3. 개인 액세스 토큰을 붙여 넣습니다.
  4. Export Context Bundle을 클릭합니다.
  5. figmascope-<fileKey>.zip이 다운로드됩니다.

프로젝트에 압축을 풉니다. 저장소 루트의 design/ 폴더가 적합합니다:

unzip figmascope-ABC123.zip -d design/
# → design/CONTEXT.md
# → design/tokens.json
# → design/screens/Home.json
# → design/screens/Home.png
# → design/components/inventory.json
# → design/strings.json
# → design/_meta.json

3단계 — Cursor에서 프로젝트 열기

평소처럼 Cursor에서 프로젝트 폴더를 엽니다. design/ 디렉토리는 이제 워크스페이스의 일부가 되고 Cursor의 인덱서가 포함시킵니다.

모델에 프롬프트하기 전에 design/CONTEXT.md를 직접 한 번 읽어보세요. 어떤 프레임이 내보내졌는지, 토큰 네이밍 체계가 무엇인지, 내보내기 중 발생한 경고(예: auto-layout이 없는 프레임의 layout-mode-none-inferred)가 무엇인지 알 수 있습니다. 이 경고들은 에이전트도 동일하게 마주칩니다.

4단계 — 효과적인 Cursor 프롬프트 작성

Cursor Chat에 붙여 넣을 수 있는 가장 간단한 참고 프롬프트입니다:

Read design/CONTEXT.md first, then implement the Home screen.

Use:
- design/tokens.json for all color, spacing, and typography values
- design/screens/Home.json for the layout tree
- design/screens/Home.png as the visual reference
- design/strings.json for all copy (use the resource keys as i18n identifiers)
- design/components/inventory.json to match component names

Target: React + Tailwind CSS. Map token values to Tailwind config entries rather
than hardcoding hex values. Use the component names from inventory.json as
component file names (PascalCase).

Cursor Composer는 CONTEXT.md의 제약 조건을 따르고, Home.json의 레이아웃 트리를 조회하고, tokens.json에서 간격을 가져와 디자인 시스템을 근사가 아닌 정확하게 반영하는 코드를 생성합니다.

모델은 여러분의 디자인을 알지 못합니다. 제공된 정보만 알 뿐입니다. 구조화된 JSON은 언제나 스크린샷을 능가합니다.

5단계 — 토큰을 프레임워크 설정에 매핑

내보내진 tokens.json은 W3C 유사 중첩 구조를 사용합니다:

{
  "color": {
    "surface": { "$value": "#f6f2ea", "$type": "color" },
    "accent":  { "$value": "#d96a3a", "$type": "color" }
  },
  "spacing": {
    "4":  { "$value": "16px", "$type": "dimension" },
    "8":  { "$value": "32px", "$type": "dimension" }
  },
  "radius": {
    "sm": { "$value": "4px",  "$type": "dimension" },
    "md": { "$value": "8px",  "$type": "dimension" }
  },
  "typography": {
    "body": {
      "fontFamily": { "$value": "Inter",  "$type": "fontFamily" },
      "fontSize":   { "$value": "14px",   "$type": "dimension" },
      "fontWeight": { "$value": 400,       "$type": "number" }
    }
  }
}

Tailwind의 경우, Cursor에 tokens.json에서 직접 tailwind.config.js theme.extend 블록을 생성하도록 요청하세요. 토큰 형식과 빈도 추론에 대한 자세한 내용은 AI 에이전트를 위한 디자인 토큰 내보내기를 참고하세요. 토큰 구조는 충분히 평평하여 단일 Node 스크립트로 순회할 수 있습니다:

// scripts/tokens-to-tailwind.js
const tokens = require('../design/tokens.json');

const colors = Object.fromEntries(
  Object.entries(tokens.color).map(([k, v]) => [k, v.$value])
);
const spacing = Object.fromEntries(
  Object.entries(tokens.spacing).map(([k, v]) => [k, v.$value])
);

module.exports = { colors, spacing };

6단계 — 멀티 화면 프로젝트 처리

Figma 파일의 각 프레임은 screens/<FrameName>.json과 일치하는 .png가 됩니다. 수십 개의 화면이 있는 프로젝트의 경우 점진적으로 작업하세요. Cursor Composer는 세션당 한 화면씩 잘 처리합니다. 화면 JSON과 PNG를 명시적인 @file 참조로 제공하세요:

@design/screens/Settings.json
@design/screens/Settings.png

Implement the Settings screen. Follow the same component structure
as the Home screen already implemented. Use tokens from design/tokens.json.

컴포넌트 인벤토리(design/components/inventory.json)는 화면 간 이름 드리프트를 방지합니다 — 화면 JSON에서 참조된 모든 컴포넌트는 인벤토리에 정규 id와 name을 가집니다. 공유 컴포넌트 라이브러리를 생성한다면 이 이름을 진실의 원천으로 사용하세요.

실제 IR의 모습

화면별 JSON은 재귀적 노드 구조를 사용합니다. 카드 컴포넌트의 간략한 예시:

{
  "kind": "stack",
  "name": "ProductCard",
  "direction": "vertical",
  "gap": { "$ref": "spacing.4" },
  "padding": { "top": 16, "right": 16, "bottom": 16, "left": 16 },
  "background": { "$ref": "color.surface" },
  "radius": { "$ref": "radius.md" },
  "children": [
    {
      "kind": "leaf",
      "name": "ProductImage",
      "type": "image",
      "width": 320,
      "height": 200
    },
    {
      "kind": "leaf",
      "name": "ProductTitle",
      "type": "text",
      "text": { "$ref": "strings.product.card.title" },
      "style": { "$ref": "typography.heading.sm" }
    }
  ]
}

토큰 참조는 tokens.json의 키와 일치하는 $ref 문자열을 사용합니다. 모델은 별도의 조회 단계 없이 이를 해석할 수 있습니다. 전체 노드 스키마는 화면별 IR 설명을 참고하세요.

컨텍스트를 최신 상태로 유지하기

디자인 파일은 변경됩니다. 디자인에 중요한 수정이 있을 때마다 figmascope를 다시 실행하고, 업데이트된 design/ 폴더를 커밋하고, PR 설명에 버전을 기록하는 것이 좋습니다. _meta.json에는 타임스탬프와 Figma 파일의 lastModified 필드가 포함되어 있어 번들이 마지막으로 재생성된 시점과 파일이 마지막으로 수정된 시점을 비교할 수 있습니다.

// _meta.json
{
  "figmascopeVersion": "1.0.0",
  "fileKey": "ABC123",
  "exportedAt": "2026-05-11T09:14:00Z",
  "figmaLastModified": "2026-05-10T18:30:00Z",
  "frameCount": 12,
  "warnings": []
}

warnings가 비어 있지 않다면 에이전트에 컨텍스트를 전달하기 전에 해결하세요. 일반적인 경고: strings-collision(같은 슬러그를 가진 두 노드가 동일한 키로 해석됨)과 layout-mode-none-inferred(명시적 auto-layout이 없는 컨테이너에서 figmascope가 자식 위치로 레이아웃을 추론함).

일반적인 Cursor 워크플로우

차분 기반 업데이트

디자인에 소규모 수정이 있을 때 — 예를 들어 카드 컴포넌트의 간격 값이 spacing.4에서 spacing.6으로 변경된 경우 — 전체 화면을 재생성하지 않고 델타만 적용하도록 Cursor에 요청할 수 있습니다:

The design/tokens.json was updated. spacing.4 is now 24px instead of 16px.
Find all components using spacing.4 and update them. Do not touch anything else.

이것이 가능한 이유는 생성된 컴포넌트가 원시 픽셀 값이 아닌 Tailwind 클래스(gap-spacing-4)로 토큰 이름을 참조하기 때문입니다. 토큰 변경은 전면 재설계가 아닌 찾기-바꾸기 작업입니다.

기존 코드베이스에 새 화면 추가

이미 1~N-1번 화면이 구현된 코드베이스에 N번 화면을 추가할 때는 에이전트를 기존 컴포넌트 라이브러리에 연결하는 것이 핵심입니다:

@design/screens/Checkout.json
@design/screens/Checkout.png

Implement the Checkout screen. Reuse existing components from src/components/
wherever the component name matches design/components/inventory.json.
Only create new component files for components not already implemented.
Use design/tokens.json for all token values.

컴포넌트 인벤토리는 디자인 컴포넌트 이름과 코드베이스 파일 이름 사이의 다리 역할을 합니다. 없으면 에이전트가 import 경로를 만들어내고 중복 컴포넌트를 생성합니다.

디자인 시스템 베이스라인 생성

화면 구현 전에 컨텍스트 번들을 사용하여 베이스라인 디자인 시스템을 생성하세요 — 토큰 설정, 색상 팔레트 컴포넌트, 기본 타이포그래피 스타일. 이렇게 하면 이후 모든 화면 구현이 동일한 기반에 고정됩니다:

Read design/tokens.json and design/CONTEXT.md.

Generate:
1. tailwind.config.ts theme.extend block from all tokens
2. src/styles/tokens.css with CSS custom properties for the same tokens
3. src/components/foundations/ColorPalette.tsx showing all color tokens
4. src/styles/typography.css with the typography token classes

Name all classes and variables using the token key paths
(e.g. --color-accent, text-ink, bg-surface).

이 베이스라인이 구축되면 모든 화면 구현에서 이를 참조할 수 있습니다. 에이전트가 매 세션마다 디자인에서 색상을 재도출하지 않고 이미 생성된 클래스를 사용합니다.

사전에 알아야 할 한계

figmascope의 컨텍스트 번들은 정적 구조를 캡처합니다. 표현할 수 없는 몇 가지 사항:

CONTEXT.md 파일은 제외된 프레임과 이유를 기록하므로 에이전트가 의도적으로 범위 밖인 항목을 구현하려 하지 않습니다.