Ogni esportazione di figmascope inizia con un .zip contenente sette artefatti. CONTEXT.md è quello che viene letto per primo — per design. Non è un README. Non è documentazione generata. È un contratto in stile compilatore tra il design e l'agente che lo trasformerà in codice.

Questo articolo illustra cosa contiene, perché è strutturato in quel modo e cosa va storto quando lo si salta.

Come appare un contratto rispetto alla documentazione

La documentazione descrive ciò che esiste. Un contratto specifica ciò che deve essere vero. Questa distinzione è importante quando il tuo lettore è un LLM che inventerà allegramente valori di spaziatura, appiattirà gerarchie di layout o hardcoderà colori hex nel momento in cui non ha un'opzione migliore.

CONTEXT.md si apre con una dichiarazione di target:

# CONTEXT.md — target Jetpack Compose

Questo file è la specifica autorevole per generare codice UI da questo bundle.
Leggilo prima di leggere qualsiasi altro file.

Il "target Jetpack Compose" non è decorativo. L'agente lo usa per scegliere i primitivi composable, gestire le unità dp vs sp, sapere che Modifier.padding() è l'astrazione giusta per la spaziatura e capire che Box con Alignment è il modo per gestire i layout overlay. Un target React/Tailwind genera un CONTEXT.md diverso con primitivi diversi nei vincoli.

L'istruzione "leggi questo per primo" è anch'essa intenzionale. Gli agenti elaborano il contesto da sinistra a destra. Se una regola token appare dopo che l'agente ha già iniziato a ragionare su un componente, il vincolo arriva troppo tardi. Mettere il contratto in primo piano significa che le regole sono attive dal primo token di generazione.

La sezione dei vincoli rigidi

La parte più portante di CONTEXT.md è il blocco dei vincoli:

## Vincoli rigidi (da rispettare)

- Non hardcodare mai valori dp se esiste un token entro ±2dp
- Non appiattire mai la gerarchia di layout — preserva ogni nodo stack/overlay/absolute
- Usa i valori stringRef da strings.json, mai testo letterale inline
- Tratta i campi mancanti come assenti, non come zero
- Non inventare nomi di componenti non presenti in components/inventory.json

Ogni vincolo esiste perché abbiamo visto gli agenti violarlo. La regola del token ±2dp è l'esempio più chiaro. Senza di essa, un agente che incontra un gap: 14 su un nodo stack scriverà Arrangement.spacedBy(14.dp). Con la regola, sa di controllare se spacing.16 o spacing.12 è entro 2dp e usare il token invece. Questo è un output diverso — uno che rimane coerente quando il valore del token cambia, uno che non lo fa.

La regola della gerarchia esiste perché Compose è un albero di layout. Quando un agente appiattisce uno stack annidato in un elenco piatto di elementi posizionati, distrugge il comportamento responsive implicito nella struttura originale. L'IR preserva ogni livello di annidamento per una ragione — vedi IR per Schermata — Stack, Overlay, Absolute, Leaf per come quell'annidamento codifica l'intento di layout.

Il vincolo non è "usa i token se ti va". È "non hardcodare mai se esiste un token". Questa è una proibizione, non un suggerimento. Gli LLM rispondono diversamente alle proibizioni rispetto ai suggerimenti.

La regola stringRef è importante per l'i18n. Se un agente inline "Speed Test" invece di referenziare la chiave risorsa, hai creato un buco di localizzazione. Il vincolo indirizza l'agente esplicitamente a strings.json.

Come l'agente legge CONTEXT.md sequenzialmente

Le finestre di contesto degli LLM elaborano i token da sinistra a destra. La struttura di CONTEXT.md sfrutta questo. L'ordine è:

  1. Dichiarazione di target (imposta l'intero frame di generazione)
  2. Vincoli rigidi (proibizioni che si applicano ad ogni decisione)
  3. Mappa del bundle (quali file esistono e cosa contiene ciascuno)
  4. Regole di utilizzo dei token (come risolvere spaziatura, colore, raggio, tipografia)
  5. Note di ambito (gap onesti — cosa questo bundle copre e non copre)

La sezione della mappa del bundle dice all'agente quali file leggere e in quale ordine:

## Contenuti del bundle

- tokens.json — design token (spaziatura, raggio, colore, tipografia)
- screens/*.json — IR per schermata in formato stack/overlay/absolute/leaf
- components/inventory.json — elenco di identità dei componenti
- strings.json — chiavi risorsa i18n
- _meta.json — metadati di generazione e avvisi

Senza questa mappa, un agente potrebbe non sapere che components/inventory.json esiste, o potrebbe trattare _meta.json come la specifica principale. L'enumerazione esplicita guida l'ordine di lettura.

Note di ambito — cosa la v0.4 onestamente non copre

La sezione delle note di ambito è dove figmascope documenta le proprie limitazioni. Questo è deliberato e non negoziabile. Un agente che non sa che una specifica è incompleta riempirà con fiducia i gap con invenzione. Questo è peggio che sapere che il gap esiste.

## Note di ambito (v0.4)

- I riempimenti gradiente non sono supportati. I nodi con riempimenti gradiente emettono un avviso
  in _meta.json sotto warnings. Tratta come approssimazione con colore solido o TODO.
- I token tipografici richiedono che le Figma Variables siano popolate. Se tokensSource
  è "inferred-from-frequency" o "none", la copertura tipografica potrebbe essere parziale.
- Questo bundle copre solo la struttura UI. Navigazione, gestione dello stato,
  e chiamate di rete sono fuori ambito.
- Le istanze di componenti sono identificate da componentId. Le props complete della sorgente del componente
  non sono incluse — l'inventario dà identità, non implementazione.

L'avviso sul gradiente è particolarmente importante. Figma supporta riempimenti gradiente complessi che non hanno un equivalente diretto in Compose senza disegno personalizzato. Anziché eliminare silenziosamente i gradienti o generare codice rotto, figmascope emette un avviso background-gradient-not-supported:<name> in _meta.json e lo annota qui così l'agente sa di trattare i nodi interessati come un gap noto anziché un bug nel proprio output.

La nota sulla tipografia si collega al campo tokensSource in _meta.json. Quando un file Figma non ha Variables, figmascope inferisce i token per frequenza — i valori comuni diventano token, quelli rari no. La nota di ambito dice all'agente che questa inferenza è imperfetta e di non assumere una copertura tipografica completa. Vedi tokens.json Spiegato per come funziona il fallback di inferenza.

Esempi WRONG / RIGHT

Rendiamo questo concreto. Dato un nodo stack con gap: 16 e un file token contenente spacing.16: 16:

Senza vincoli CONTEXT.md (SBAGLIATO):

Column(
    modifier = Modifier.padding(horizontal = 24.dp),
    verticalArrangement = Arrangement.spacedBy(16.dp)
) {

Con vincoli CONTEXT.md (GIUSTO):

Column(
    modifier = Modifier.padding(horizontal = Spacing.spacing24),
    verticalArrangement = Arrangement.spacedBy(Spacing.spacing16)
) {

L'output GIUSTO è con riferimento ai token. Quando il design system cambia spacing.16 da 16dp a 14dp, il codice rimane corretto senza una ricerca-e-sostituzione nella codebase.

Un altro esempio — gestione delle stringhe. Dato un nodo leaf con text: "Speed Test" e stringRef: "speed.test":

SBAGLIATO:

Text(text = "Speed Test")

GIUSTO:

Text(text = stringResource(R.string.speed_test))

Il vincolo indirizza a strings.json, la chiave è speed.test e l'agente sa come mappare la notazione a punti agli ID risorsa Android. Questo è possibile solo se l'agente ha letto il vincolo prima di generare il componente.

Perché non fare il prompt all'agente tu stesso?

Puoi scrivere queste istruzioni manualmente nel tuo prompt. figmascope le esternalizza in un file perché:

L'obiettivo non è fare prompt engineering intorno alle impostazioni predefinite dell'agente. È spedire una specifica che rende irrilevanti le impostazioni predefinite.

Struttura rispetto alle alternative

Figma Dev Mode produce misurazioni, variabili e snippet di codice. Non produce una specifica. L'agente che usa l'output di Dev Mode deve inferire le regole dagli esempi — il che significa che inferirà regole sbagliate per i casi limite.

Locofy e strumenti simili generano codice direttamente. Non hanno un equivalente CONTEXT.md perché non si aspettano che un agente legga una specifica — si aspettano di essere l'agente. Questo funziona quando la generazione di codice dello strumento corrisponde esattamente al tuo stack. Non funziona quando hai convenzioni di denominazione specifiche per il progetto, una libreria di componenti personalizzata o un design system con token che lo strumento non conosce.

CONTEXT.md è un brief di design leggibile dalla macchina. È la cosa che esisteva come pagina Confluence o documento Notion in ogni consegna design pre-LLM, solo strutturata per un pubblico che segue effettivamente le regole.

Cosa fare con esso

Quando apri un'esportazione di figmascope in Cursor o Claude Code:

  1. Aggiungi @CONTEXT.md al tuo contesto prima di qualsiasi prompt sul design.
  2. Fai riferimento al JSON della schermata su cui stai lavorando: @screens/home.json.
  3. Se stai toccando i token, aggiungi @tokens.json.
  4. Se stai lavorando con le stringhe, aggiungi @strings.json.

I vincoli di CONTEXT.md si applicano all'intera sessione una volta caricati. Non lo riaggiungere per ogni prompt — lo aggiungi una volta all'inizio e lasci che inquadri ogni generazione successiva.

Gli altri artefatti nel bundle sono trattati nel resto di questa serie. Inizia con tokens.json Spiegato per come il sistema di token gestisce i file con e senza Figma Variables, oppure IR per Schermata per come i layout Figma si mappano ai nodi stack/overlay/absolute/leaf. Pronto a provarlo? Incolla il tuo URL Figma su figmascope.dev ed esporta il tuo primo bundle.