Figma to Cursor — Esporta il Contesto Design per Cursor AI

L'AI di Cursor può scrivere molto codice UI. Quello che non può fare è leggere il tuo file Figma. Incolli uno screenshot e indovina — spaziatura sbagliata, valori di colore errati, nomi di componenti inventati. Il problema non è il modello. È il contesto strutturato mancante.

figmascope colma quel gap. Esporta un file Figma come bundle zip — design token, alberi di layout per schermata, render di riferimento, inventario componenti, stringhe UI — tutto ciò che un modello linguistico necessita per generare codice accurato anziché codice dall'aspetto plausibile. L'app principale gira interamente nel browser senza backend né upload.

Questa pagina illustra l'intero flusso di lavoro dall'URL Figma alla generazione di codice con Cursor. Se usi Claude Code invece di Cursor, vedi Figma to Claude Code per il flusso specifico per Claude. Per uno sguardo più ampio su cosa rende una consegna adatta agli agenti, vedi AI Design Handoff.

Cosa contiene il bundle di contesto

Quando esegui figmascope su un file Figma, ottieni un .zip contenente:

CONTEXT.md — un documento di specifica scritto perché l'agente lo legga per primo. Elenca vincoli, note di ambito, annotazioni di versione ed esempi derivati dal file stesso.
tokens.json — design token tipizzati (colore, spaziatura, raggio, tipografia) in una struttura annidata simile a W3C. Ricavati da Figma Variables quando presenti; altrimenti inferiti dalla frequenza d'uso.
screens/*.json — rappresentazione intermedia per schermata. Ogni nodo è tipizzato (stack, overlay, absolute o leaf), preservato spazialmente e con riferimenti incrociati ai token.
screens/*.png — render di riferimento a 2× per la verità visiva.
components/inventory.json — { id, name, type } per ogni componente nel file.
strings.json — tutte le stringhe UI consolidate, con chiavi risorsa in notazione a punti (onboarding.welcome.title).
_meta.json — manifesto di build: timestamp, fileKey, frameCount, eventuali avvisi.

Nulla viene caricato. Il tuo Personal Access Token risiede solo nella memoria del browser ed è inviato esclusivamente a api.figma.com. Lo zip è assemblato lato client e consegnato al download del browser.

Passo 1 — Ottieni un Personal Access Token di Figma

Vai su Figma → Impostazioni Account → Personal Access Tokens e crea un token con ambito File content: read-only. È il minimo richiesto.

Il token non lascia mai la sessione del browser; figmascope lo invia nell'header X-Figma-Token nelle richieste a api.figma.com e in nessun altro luogo. Vedi Sicurezza PAT e figmascope per il modello completo di minacce.

Passo 2 — Esporta il bundle di contesto

Apri figmascope.dev nel browser.
Incolla l'URL del file Figma (es. https://www.figma.com/file/ABC123/MyDesign).
Incolla il tuo Personal Access Token.
Clicca su Export Context Bundle.
Un file figmascope-<fileKey>.zip viene scaricato sul tuo computer.

Decomprimi nella tua cartella di progetto. Una posizione sensata è una cartella design/ nella radice del repository:

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

Passo 3 — Apri il progetto in Cursor

Apri la cartella del progetto in Cursor normalmente. La directory design/ fa ora parte del workspace e l'indicizzatore di Cursor la includerà.

Prima di fare il prompt al modello, leggi design/CONTEXT.md una volta tu stesso. Ti dice quali frame sono stati esportati, qual è lo schema di naming dei token e elenca eventuali avvisi emessi durante l'esportazione (es. layout-mode-none-inferred per frame in cui Figma non riportava auto-layout). Questi avvisi sono gli stessi che incontrerà il tuo agente.

Passo 4 — Scrivi un prompt efficace per Cursor

Il punto di partenza più semplice è un prompt di riferimento che puoi incollare in Cursor Chat:

Leggi prima design/CONTEXT.md, poi implementa la schermata Home.

Usa:
- design/tokens.json per tutti i valori di colore, spaziatura e tipografia
- design/screens/Home.json per l'albero di layout
- design/screens/Home.png come riferimento visivo
- design/strings.json per tutti i testi (usa le chiavi risorsa come identificatori i18n)
- design/components/inventory.json per abbinare i nomi dei componenti

Target: React + Tailwind CSS. Mappa i valori token nelle voci di tailwind config invece
di hardcodare valori hex. Usa i nomi dei componenti da inventory.json come
nomi di file componente (PascalCase).

Il Composer di Cursor seguirà i vincoli di CONTEXT.md, cercherà l'albero di layout in Home.json, recupererà la spaziatura da tokens.json e produrrà codice che corrisponde al tuo design system anziché approssimarlo.

Il modello non conosce il tuo design. Conosce ciò che gli dai. JSON strutturato batte uno screenshot ogni volta.

Passo 5 — Mappa i token nella configurazione del framework

Il tokens.json esportato usa una forma annidata simile a 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" }
    }
  }
}

Per Tailwind, chiedi a Cursor di generare un blocco theme.extend in tailwind.config.js direttamente da tokens.json. Vedi Design Token Export per Agenti AI per un approfondimento sul formato dei token e l'inferenza per frequenza. La struttura dei token è abbastanza piatta da poter essere attraversata con un singolo script Node se vuoi automatizzare:

// 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 };

Passo 6 — Gestisci progetti multi-schermata

Ogni frame nel file Figma diventa un screens/<FrameName>.json e un .png corrispondente. Per un progetto con una dozzina di schermate, lavorale incrementalmente. Cursor Composer gestisce bene una schermata per sessione; fornisci il JSON e il PNG della schermata come riferimenti @file espliciti:

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

Implementa la schermata Settings. Segui la stessa struttura di componenti
della schermata Home già implementata. Usa i token da design/tokens.json.

L'inventario componenti (design/components/inventory.json) ti aiuta a evitare la deriva dei nomi tra le schermate — ogni componente referenziato in un JSON schermata ha un id e un name canonici nell'inventario. Se stai generando una libreria di componenti condivisi, usa quei nomi come fonte di verità.

Come appare l'IR nella pratica

Il JSON per schermata usa una struttura di nodi ricorsiva. Un esempio semplificato per un componente card:

{
  "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" }
    }
  ]
}

I riferimenti ai token usano stringhe $ref che corrispondono alle chiavi in tokens.json. Il modello può risolverli senza un passaggio di ricerca separato. Vedi IR per schermata spiegato per lo schema completo dei nodi.

Mantenere il contesto aggiornato

I file di design cambiano. Una buona abitudine: riesegui figmascope ogni volta che il design ha una revisione significativa, effettua il commit della cartella design/ aggiornata e annota la versione nella descrizione della PR. Il file _meta.json include un timestamp e il campo lastModified del file Figma, così puoi calcolare il diff tra l'ultima rigenerazione del bundle e l'ultimo aggiornamento del file.

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

Se warnings non è vuoto, risolvili prima di passare il contesto all'agente. Avvisi comuni: strings-collision (due nodi con lo stesso slug risolti alla stessa chiave) e layout-mode-none-inferred (un container senza auto-layout esplicito, dove figmascope ha inferito il layout dalle posizioni dei figli).

Flussi di lavoro comuni in Cursor

Aggiornamenti basati su diff

Quando il design ha una revisione minore — diciamo, un valore di spaziatura cambiato da spacing.4 a spacing.6 sul componente card — puoi chiedere a Cursor di applicare solo il delta anziché rigenerare l'intera schermata:

Il file design/tokens.json è stato aggiornato. spacing.4 ora è 24px invece di 16px.
Trova tutti i componenti che usano spacing.4 e aggiornali. Non toccare nient'altro.

Questo funziona perché i componenti generati fanno riferimento ai nomi dei token come classi Tailwind (gap-spacing-4) anziché valori pixel grezzi. Un cambiamento di token è un find-and-replace, non una riprogettazione.

Aggiungere una nuova schermata a una codebase esistente

Quando aggiungi la schermata N a una codebase che ha già le schermate da 1 a N-1 implementate, l'aggiunta chiave al prompt è ancorare l'agente alla libreria di componenti esistente:

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

Implementa la schermata Checkout. Riutilizza i componenti esistenti da src/components/
dove il nome del componente corrisponde a design/components/inventory.json.
Crea nuovi file componente solo per componenti non ancora implementati.
Usa design/tokens.json per tutti i valori token.

L'inventario componenti è il ponte tra il nome del componente nel design e il nome del file nella codebase. Senza di esso, l'agente inventerà percorsi di import e creerà componenti duplicati.

Generare una base di design system

Prima di implementare qualsiasi schermata, usa il bundle di contesto per generare una base di design system: la configurazione dei token, un componente tavolozza colori e gli stili tipografici base. Questo ancora tutte le successive implementazioni di schermate alla stessa fondazione:

Leggi design/tokens.json e design/CONTEXT.md.

Genera:
1. Blocco theme.extend di tailwind.config.ts da tutti i token
2. src/styles/tokens.css con proprietà CSS personalizzate per gli stessi token
3. src/components/foundations/ColorPalette.tsx che mostra tutti i token colore
4. src/styles/typography.css con le classi token tipografiche

Nomina tutte le classi e variabili usando i percorsi delle chiavi token
(es. --color-accent, text-ink, bg-surface).

Una volta che questa base esiste, ogni implementazione di schermata può farvi riferimento. L'agente non ri-derivi i colori dal design ad ogni sessione — userà le classi già generate.

Limitazioni da conoscere in anticipo

Il bundle di contesto di figmascope cattura la struttura statica. Alcune cose che non può rappresentare:

Stati hover e focus — i componenti interattivi e le connessioni di prototipazione di Figma non sono inclusi. Dovrai descriverli nel prompt o implementarli per convenzione.
Breakpoint responsivi — l'IR cattura un viewport (le dimensioni del frame). I layout multi-breakpoint richiedono frame separati o indicazioni manuali nel prompt.
Animazioni complesse — Smart Animate di Figma e le impostazioni di transizione non sono incluse. Gli stati di ingresso/uscita statici sono visibili come frame separati se il designer li ha creati.
Nodi non-frame — figmascope elabora i frame Figma (schermate di design di primo livello). Slice, gruppi figli diretti di pagine e sezioni Figma vengono filtrati.

Il file CONTEXT.md annota quali frame sono stati esclusi e perché, così l'agente non tenta di implementare qualcosa che era intenzionalmente fuori ambito.