Il prompt con screenshot ha un tetto. Incolli il design, il modello produce un'approssimazione plausibile, la correggi, al turno successivo torna a derivare. Nulla è ancorato. Il modello non ha una fonte di verità contro cui controllarsi tra i turni.

Il bundle di contesto di figmascope cambia il contratto. Invece di un riferimento pixel che il modello deve interpretare ogni volta, ottieni un insieme strutturato e referenziabile di file — design token, IR del layout, inventario componenti, stringhe UI — che rimangono nella sessione e rimangono coerenti. Claude Code può leggerli, implementare da loro e controllare il proprio output rispetto a loro su richiesta.

Questa guida copre l'intera pipeline dall'esportazione del bundle all'implementazione verificata con i token.

Cosa rende questo deterministico

Tre cose rendono il bundle referenziabile anziché interpretabile:

  1. I token sono tipizzati e con chiave. tokens.json mappa nomi semantici (spacing.16, color.7f5cfe) a valori esatti. Il modello può controllare il proprio output rispetto al file senza rielaborare il design.
  2. L'IR è un albero, non pixel. screens/home.json descrive il layout in termini di nodi stack/overlay/absolute/leaf — la stessa astrazione usata dal target di implementazione (Compose, React, ecc.). Non c'è un passaggio di interpretazione visiva.
  3. Il bundle è stabile tra i turni. Una volta nel repository, ogni prompt nella sessione può fare riferimento agli stessi file. La deriva dei token è rilevabile: chiedi al modello di confrontare il suo output con tokens.json e può farlo meccanicamente.

Passo 1: Genera il bundle

Apri figmascope.dev nel browser. Incolla l'URL del tuo file Figma. L'esportatore gira lato client usando la Figma REST API — il tuo personal access token di Figma è memorizzato in localStorage e non viene mai inviato ai server di figmascope.

Clicca su Export Agent Context. La pagina esporta i frame di primo livello, risolve i design token, costruisce l'IR e scarica context-bundle.zip.

Passo 2: Decomprimi nel progetto

# dalla radice del tuo progetto
unzip ~/Downloads/context-bundle.zip -d ./design/

# conferma cosa hai
find design/ -type f | sort
# design/CONTEXT.md
# design/_meta.json
# design/components/inventory.json
# design/screens/home.json
# design/screens/home.png
# design/screens/settings.json
# design/screens/settings.png
# design/strings.json
# design/tokens.json

Il nome della directory non importa — design/ è solo una convenzione. Quello che conta è che Claude Code possa leggere i file dalla directory di lavoro.

Passo 3: Avvia Claude Code nel repository

cd my-app
claude

Claude Code si avvia nella radice del repository con accesso completo ai file. Può leggere, scrivere e fare riferimento a qualsiasi file nell'albero durante l'intera sessione — questa è la capacità chiave che fa funzionare il pattern del bundle.

Passo 4: Orienta l'agente

Inizia con un prompt di lettura prima di qualsiasi implementazione. Questo carica la specifica nel contesto della sessione e ti permette di verificare che l'esportazione sembri corretta prima di scrivere qualsiasi codice.

Leggi ./design/CONTEXT.md e dimmi:
1. Per quale framework target è questo bundle?
2. Quali file token referenzia?
3. Ci sono avvisi che dovrei conoscere prima di implementare?

Claude riporterà il target (Jetpack Compose per default), la sorgente dei token e qualsiasi avviso dall'intestazione di CONTEXT.md — riempimenti gradiente, mappature token mancanti, effetti non supportati. Li intercetti ora, non dopo aver generato 200 righe di codice.

Segui con un rapido controllo dei token:

Elenca i primi 10 token colore da ./design/tokens.json.
Poi elenca i token di spaziatura.

Questo conferma che il file token è stato analizzato correttamente e ti dà un modello mentale della palette prima dell'implementazione.

Passo 5: Implementa una schermata

Ora il prompt di implementazione. Sii esplicito su quali file sono autorevoli per quali decisioni:

Implementa ./design/screens/home.json come schermata Jetpack Compose.

Regole:
- I vincoli di CONTEXT.md si applicano. Leggilo se non lo hai già fatto.
- Tutti i valori di spaziatura, colore e raggio devono provenire da ./design/tokens.json.
  Mappa le chiavi token ai primitivi Compose appropriati (es. spacing.16 → 16.dp).
- Le stringhe UI devono usare le chiavi da ./design/strings.json via stringResource().
  Usa il campo "fallback" come valore letterale di fallback se non è ancora disponibile un resource ID.
- I tipi di nodi IR si mappano come segue:
    stack (axis:vertical)   → Column
    stack (axis:horizontal) → Row
    overlay                 → Box
    absolute                → Box con Modifier.offset
    leaf (text)             → Text con TextStyle
    leaf (rectangle)        → Box con Modifier.background
- Non inventare alcun valore non presente nei file token o IR.
  Se qualcosa manca, lascia un commento TODO con la chiave token che ti aspettavi.

Claude Code leggerà l'IR, percorrerà l'albero dei nodi, mapperà ogni nodo al suo primitivo Compose e recupererà i valori token per chiave. L'output è tracciabile: ogni valore .dp dovrebbe corrispondere a un token di spaziatura, ogni Color(0xFF...) dovrebbe corrispondere a un token colore.

Passo 6: Rileva e correggi la deriva dei token

Dopo il primo passaggio di implementazione, esegui un controllo della deriva prima di revisionare visivamente. Questo è il vantaggio chiave del bundle rispetto al prompt con screenshot — puoi chiedere al modello di verificare il proprio output meccanicamente.

Confronta ogni valore colore nel HomeScreen.kt generato con ./design/tokens.json.
Elenca qualsiasi valore hex nell'output che non corrisponde a una chiave token colore.
Per ciascuno, identifica il token corretto e sostituisci il valore hardcodato.

Fai lo stesso per la spaziatura:

Confronta ogni valore .dp in HomeScreen.kt con i token di spaziatura in ./design/tokens.json.
Segnala qualsiasi valore che non corrisponde a un token di spaziatura. Sostituisci con il riferimento token corretto.

Questo ciclo — implementa, controlla la deriva, correggi — converge rapidamente. Al secondo o terzo passaggio, l'output è completamente con riferimento ai token.

Suggerimento: includi gli avvisi di _meta.json nel primo prompt

design/_meta.json contiene un array warnings. Queste sono cose che l'esportatore non è riuscito a risolvere completamente: riempimenti gradiente, immagini incorporate, effetti senza un equivalente token. Leggili prima di implementare:

cat design/_meta.json

Se l'output include qualcosa come:

{
  "warnings": [
    "node 'hero-background': gradientFill not fully supported — background fill omitted",
    "node 'avatar': imageFill — reference only, no pixel data"
  ]
}

Aggiungili esplicitamente al tuo prompt di implementazione: "Salta il riempimento hero background e lascia un // TODO: gradiente. Per il nodo avatar, usa un AsyncImage segnaposto con sfondo grigio."

Questo impedisce a Claude di approssimare silenziosamente — farà quello che gli hai detto invece di indovinare.

Perché questo batte il prompt con screenshot

Sicuro tra sessioni. Il file token e l'IR non cambiano tra i turni. Puoi chiedere "hai usato la spaziatura giusta per il padding della card?" al turno 12 e ottenere una risposta accurata, perché la fonte di verità è ancora su disco.

Amichevole per diff. Quando riesporti dopo un cambiamento del design, il nuovo bundle produce un diff rispetto al precedente. Puoi chiedere a Claude di rivedere il diff e aggiornare solo i componenti interessati — nessuna reimplementazione completa richiesta.

Nessun re-upload. Il bundle vive nel tuo repository. Non reincolla screenshot per ogni nuova schermata. Ogni nuova schermata è solo design/screens/<name>.json — un altro file da referenziare nel prossimo prompt.

Onesto sui gap. CONTEXT.md e _meta.json elencano esplicitamente cosa il bundle non copre. Il prompt con screenshot non ha equivalente — il modello indovina attraverso i gap.

L'app figmascope principale gestisce l'esportazione nel tuo browser — incolla il tuo URL Figma, esporta il bundle e sei pronto ad eseguire Claude Code rispetto a una specifica deterministica.