Cursor Composer può scrivere molto codice UI. Quello che non può fare è leggere il tuo file Figma. Incolla uno screenshot e indovina — spaziatura sbagliata, valori di colore inventati, nomi di componenti che non corrispondono a nulla nel tuo codebase. Il problema non è il modello. È il contesto strutturato mancante.
figmascope risolve questo. Esporta il tuo file Figma come bundle zip: design token, alberi di layout per schermata, render di riferimento 2×, un inventario dei componenti e stringhe UI — tutto ciò di cui l'agente Cursor ha bisogno per generare codice accurato anziché codice dall'aspetto plausibile.
Questa guida copre l'intera pipeline: URL Figma → bundle di contesto → prompt Cursor → output revisionato.
Cosa contiene il bundle
Quando figmascope esporta il tuo file, lo zip contiene:
CONTEXT.md— la specifica che l'agente legge prima. Elenca il framework target, le sorgenti dei token, i vincoli e le lacune note.tokens.json— design token tipizzati: spaziatura, border-radius, colore, tipografia.screens/<name>.json— rappresentazione intermedia per schermata: nodi stack/overlay/absolute/leaf con riempimenti, spaziatura e riferimenti a stringhe.screens/<name>.png— render di riferimento 2× per conferma visiva.components/inventory.json— id, nome e tipo dei componenti.strings.json— stringhe UI con chiavi di risorse in notazione punto._meta.json— manifesto di build: nome del file sorgente, timestamp di esportazione, avvisi.
Il bundle rimane sul tuo dispositivo. Non viene mai ricaricato da nessuna parte.
Passaggio 1: Genera il bundle
Vai su figmascope e incolla l'URL del tuo file Figma nel campo di input. L'esportatore gira nel tuo browser contro la REST API di Figma — la prima volta avrai bisogno di un personal access token (salvato in localStorage, mai inviato ai server di figmascope).
Premi Esporta Contesto Agente. La pagina elabora ogni frame, risolve i token, costruisce l'IR, poi scarica context-bundle.zip sul tuo dispositivo.
Se il tuo file ha molti frame, vengono inclusi solo i frame di primo livello che non sono componenti o thumbnail. Il file _meta.json mostra esattamente quali frame sono stati esportati e gli eventuali avvisi (riempimenti a gradiente, effetti non supportati).
Passaggio 2: Decomprimi nel tuo progetto
Metti il bundle dove Cursor può vederlo — una directory design/ alla radice del tuo repo è il pattern più pulito.
# dalla radice del tuo progetto
unzip ~/Downloads/context-bundle.zip -d ./design/
# verifica la struttura
ls design/
# CONTEXT.md _meta.json components/ screens/ strings.json tokens.jsonAggiungi design/ a .gitignore se non vuoi committare il bundle. Oppure committalo — è deterministico; lo stesso file Figma nello stesso stato produce sempre lo stesso bundle, quindi le diff hanno significato.
Passaggio 3: Aggiungi uno snippet .cursorrules
Cursor legge .cursorrules alla radice del repo e lo antepone a ogni contesto di chat. Qui è dove colleghi l'agente al bundle.
# .cursorrules
Quando si costruiscono schermate UI:
1. Leggi prima ./design/CONTEXT.md. Specifica il framework target e i vincoli.
2. Usa i token da ./design/tokens.json per tutti i valori di spaziatura, colore, raggio e tipografia.
3. Fai riferimento a ./design/screens/<name>.json per la struttura del layout e la gerarchia dei nodi.
4. Usa ./design/screens/<name>.png per la conferma visiva — usalo come controllo di sanità, non come fonte della verità.
5. Usa le chiavi di stringa da ./design/strings.json invece di hardcodare il testo UI.
6. Non inventare valori di token. Se un valore non è in tokens.json, segnalalo.Questo singolo blocco previene le tre fonti di deriva più comuni: colori inventati, stringhe hardcoded e indovinare il layout dallo screenshot.
Passaggio 4: Apri Cursor Composer e implementa una schermata
Apri Composer (Cmd+I su macOS). Aggiungi i file prima del prompt: clicca sull'icona graffetta e aggiungi design/CONTEXT.md, design/tokens.json e design/screens/home.json. Poi fai il prompt:
Implementa la schermata home da ./design/screens/home.json.
Vincoli:
- Il framework target e le convenzioni dei componenti sono in ./design/CONTEXT.md
- Tutti i valori di spaziatura, colore e raggio devono provenire da ./design/tokens.json
- Le stringhe UI devono usare le chiavi da ./design/strings.json
- Il nodo radice è uno stack (verticale). I figli sono dichiarati in ordine nel JSON.
- Non inventare valori non presenti nei file token o IR.Cursor leggerà i file aggiunti, mapperà i nodi IR alle primitive del tuo framework e genererà l'implementazione. L'output è referenziato ai token — se ispezioni il codice generato, ogni valore di spaziatura dovrebbe risalire a una chiave in tokens.json.
Passaggio 5: Rivedi e itera
Apri design/screens/home.png accanto all'output renderizzato. Il PNG è un'esportazione 2× da Figma — mostra esattamente come dovrebbe apparire il design. Le differenze sono significative: puntano a lacune nella mappatura IR o a valori di token non applicati.
Problemi comuni e prompt di follow-up:
Deriva dei token — l'agente ha usato un hex hardcoded invece di un token:
Confronta ogni valore di colore nel componente generato con ./design/tokens.json.
Elenca tutti i colori che non corrispondono a una chiave token. Sostituiscili con il riferimento token corretto.Componente mancante — l'IR fa riferimento a un ID componente che l'agente non ha risolto:
L'IR fa riferimento a componentId "btn-primary-01". Controlla ./design/components/inventory.json
per il suo nome e tipo, poi implementa un placeholder con quel nome e i valori token corretti.Layout sbagliato — la spaziatura o l'allineamento non corrisponde al PNG:
Il gap verticale tra l'header e la lista di card dovrebbe essere spacing.24 da tokens.json (24dp).
Il tuo output usa 16px. Correggilo.Cosa funziona, cosa no
Funziona bene: schermate piatte con layout stack, spaziatura e colore basati su token, testo con riferimenti a stringhe, semplici pattern di card e list. Cursor gestisce questi bene una volta che l'IR è in contesto — smette di indovinare e inizia a mappare.
Funziona meno bene: overlay complessi con posizionamento assoluto (Cursor a volte fraintende le coordinate di offset), riempimenti a gradiente (segnalati come avvisi in _meta.json — Cursor approssimerà), e icone vettoriali (l'IR memorizza solo un ID di riferimento, non i dati del percorso).
Solo screenshot vs. bundle: andare solo con screenshot è più veloce da iniziare ma non deterministico. Ogni sessione ricomincia da zero. Il modello potrebbe azzeccare la spaziatura una volta e sbagliarla al turno successivo. Il bundle è referenziabile in tutta la sessione — Cursor può verificare il proprio output rispetto al file token in qualsiasi momento senza ricaricare nulla.
Suggerimento: controlla gli avvisi di _meta.json prima del prompt
Prima del tuo primo prompt di implementazione, leggi design/_meta.json. L'array warnings elenca tutto ciò che l'esportatore non ha potuto risolvere completamente: riempimenti a gradiente, mappature token mancanti, frame con immagini incorporate. Aggiungi una nota su questi al tuo prompt in modo che l'agente non tenti di implementarli ricadendo silenziosamente su valori hardcoded.
cat design/_meta.json | python3 -m json.tool | grep -A 20 '"warnings"'Se l'output mostra "gradientFill: not fully supported" su un nodo specifico, di' a Cursor di saltare lo sfondo di quel nodo e lasciare invece un commento // TODO: gradiente.
Riepilogo
Il flusso di lavoro è: esporta una volta, referenzia ovunque. Il bundle è una specifica stabile e leggibile dalle macchine che Cursor può consultare su più turni senza rielaborare il design. Ottieni codice accurato ai token, referenziato alle stringhe e corretto nel layout, invece di un'approssimazione da screenshot — e quando qualcosa diverge, puoi rimandare l'agente alla fonte della verità in una riga.
Eseguilo tu stesso su figmascope.dev — incolla il tuo URL Figma, premi Esporta Contesto Agente e decomprimi il bundle nel tuo workspace Cursor in meno di due minuti.