Le Figma Variables sono arrivate nel 2023 come risposta tanto attesa della piattaforma ai design token. La funzionalità è potente: raccolte denominate di valori primitivi — colori, numeri, stringhe, booleani — che puoi associare a qualsiasi proprietà di qualsiasi componente. Cambia la variabile, ogni istanza si aggiorna. Aggiungi una raccolta dark mode, ogni binding di variabile si scambia automaticamente.

Per la generazione di codice AI, le Variables non sono solo utili. Sono il meccanismo che converte un file Figma da un mockup pixel-perfect a una specifica che il tuo agente può implementare correttamente. Quando un colore ha un nome — color/brand/primary, non #7F5CFE — l'agente può mapparlo a un token di codice, implementare correttamente la dark mode e produrre output che partecipa al tuo design system reale.

Ecco il problema: la maggior parte dei file Figma in uso attivo oggi non ha Variables configurate. figmascope gestisce entrambi i casi. Questo articolo spiega come.

Cosa sono davvero le Variables

Una Figma Variable è uno scalare denominato associato a una raccolta. Le raccolte organizzano le variabili per modalità — "Light" e "Dark" sono l'esempio canonico. Ogni variabile in una raccolta può avere valori diversi per modalità: color/surface/background è #FFFFFF in Light e #0D0D0D in Dark. Il binding si propaga: ogni riempimento che fa riferimento a color/surface/background si aggiorna quando si cambia modalità.

Le Variables possono essere colori, numeri, stringhe o booleani. In pratica, i più impattanti sono colori e numeri — che copre la maggior parte della superficie dei token in un tipico design system: palette di colori, scala di spaziatura, border radius, dimensioni dei font, valori di elevazione.

Figma espone le Variables tramite la sua REST API come raccolta localVariables. Ogni variabile ha un ID, un nome, un tipo e valori per modalità. Le proprietà dei componenti che fanno riferimento a variabili portano un campo boundVariables con l'ID della variabile. Questi sono dati strutturati che viaggiano in modo pulito attraverso la pipeline di estrazione.

Il percorso ottimale: le Variables sono presenti

Quando un file Figma ha Variables, figmascope le legge dall'API e costruisce un tokens.json seguendo una struttura compatibile con il W3C Design Tokens Community Group. Ogni token ha un $value e un $type. I token colore ottengono valori hex con alpha opzionale. I token di spaziatura ottengono valori numerici con un suggerimento di unità px. Il nome del token segue il percorso della raccolta e del nome della variabile:

{
  "color": {
    "brand": {
      "primary": { "$value": "#7F5CFE", "$type": "color" }
    },
    "surface": {
      "background": { "$value": "#FFFFFF", "$type": "color" }
    }
  },
  "spacing": {
    "4": { "$value": 4, "$type": "number" },
    "8": { "$value": 8, "$type": "number" },
    "16": { "$value": 16, "$type": "number" }
  }
}

Quando viene costruito l'IR per schermata, ogni riempimento che aveva un riferimento boundVariables ottiene il nome del token invece dell'hex risolto. Il nodo porta:

"fills": [{ "type": "SOLID", "tokenRef": "color/brand/primary" }]

Non #7F5CFE. Il nome del token. L'agente lo legge e genera background-color: var(--color-brand-primary) o Color.brandPrimary o qualsiasi sia il pattern di consumo dei token del framework target. Questo è l'output che si desidera: codice connesso al design system, non codice che si romperà nel momento in cui un designer aggiorna un colore.

La denominazione semantica è la differenza tra codice che invecchia bene e codice che diverge. Un valore hex nel codice sorgente è una passività; un riferimento a un token è un contratto. Le Variables sono ciò che rende i file Figma capaci di esprimere contratti, non solo pixel.

La realtà: la maggior parte dei file non ha Variables

Le Variables richiedono il piano Figma Professional o superiore. Richiedono un designer che le abbia configurate — il che significa creare raccolte, nominare variabili e associarle manualmente a ogni proprietà dei componenti. In un file di design system maturo e ben mantenuto questo è fatto. In un file Figma di una startup, nel file di un cliente freelance, o in qualsiasi file che precede la funzionalità Variables, tipicamente non lo è.

figmascope è stato progettato per essere utile anche per quei file. Degrada con grazia: quando le Variables sono assenti, ricade sull'inferenza dei token basata sulla frequenza.

Il fallback: inferito dalla frequenza

L'algoritmo di inferenza funziona così:

  1. Percorre ogni nodo foglia in ogni frame esportato.
  2. Raccoglie tutti i colori di riempimento, i valori di spaziatura e i border radius.
  3. Conta le occorrenze di ogni valore univoco.
  4. I valori che appaiono sopra una soglia di frequenza vengono promossi a token inferiti.
  5. Ogni token ottiene un nome derivato dal valore: color.7f5cfe, spacing.16, radius.8.

Il tokens.json di output ha un aspetto strutturalmente simile al percorso Variables, ma i nomi sono derivati dai valori anziché essere semantici:

{
  "color": {
    "7f5cfe": { "$value": "#7F5CFE", "$type": "color" },
    "f6f2ea": { "$value": "#F6F2EA", "$type": "color" }
  },
  "spacing": {
    "16": { "$value": 16, "$type": "number" },
    "8": { "$value": 8, "$type": "number" }
  }
}

Nell'IR, i nodi che usano questi valori ottengono riferimenti a token: "tokenRef": "color.7f5cfe". Non letterali hardcoded. Riferimenti — solo a token inferiti anziché a token denominati.

L'agente genera ancora codice referenziato ai token. var(--color-7f5cfe) non è leggibile quanto var(--color-brand-primary), ma è comunque un token — puoi fare find-and-replace, puoi rinominarlo, puoi verificarne l'utilizzo. È un handle denominato su un valore, non un numero magico.

Il campo tokensSource

Ogni bundle di figmascope include un _meta.json che documenta cosa è nel bundle e come è stato prodotto. Il campo tokensSource ha tre possibili valori:

Questo è importante perché dice all'agente consumatore (e allo sviluppatore che legge il bundle) esattamente quanto fidarsi dei nomi dei token. Un bundle figma-variables è la fonte di verità per il design system. Un bundle inferred-from-frequency è un utile scaffold strutturale che necessita di una revisione dei nomi da parte del designer prima di essere canonico. Un bundle none è un punto di partenza con valori hardcoded che devono essere tokenizzati in seguito.

I metadati onesti sono sottovalutati. Gli strumenti che inferiscono silenziosamente senza segnalarlo come inferenza creano una falsa confidenza. figmascope espone esplicitamente la catena di inferenza in modo che tu sappia con cosa stai lavorando.

Perché l'inferenza per frequenza è meglio di niente

L'alternativa all'inferenza per frequenza è produrre valori letterali risolti ovunque — #7F5CFE in ogni nodo di riempimento che usa quel colore. Questo produce codice più difficile da refactoring, più difficile da verificare e più difficile da connettere a un design system quando alla fine ne viene aggiunto uno.

L'inferenza per frequenza al minimo estrae l'insieme di valori che il design usa effettivamente. Se #7F5CFE appare 47 volte nel design, questo è un segnale: è un colore primario, non un accento. Il nome del token non lo sa — è solo color.7f5cfe — ma i dati di frequenza raccontano la storia. Un agente a cui vengono forniti i token inferiti può fare ipotesi ragionevoli su quali valori sono primari e quali sono occasionali.

Più praticamente: l'inferenza per frequenza ti dà un tokens.json confrontabile tra versioni. Se esporti lo stesso file due volte dopo che un designer ha cambiato un colore ricorrente, il diff mostra che il valore del token è cambiato. Senza inferenza, dovresti inseguire ogni singola modifica di letterale sparsa in più file IR.

Cosa i designer dovrebbero comunque fare

L'inferenza per frequenza è uno strato di compatibilità, non un sostituto delle Variables. Il percorso corretto è che i designer adottino le Variables per tutti i valori che partecipano a un design system: colori del brand, scala dei neutri, scala di spaziatura, border radius, elevazione, tipografia. Una volta che questi sono in atto, il bundle di figmascope passa da token di qualità scaffold a token di qualità produzione.

Le Variables sblocano anche il theming nel bundle: valori per modalità multipla per token. Un file con modalità Light/Dark produce un tokens.json con valori per modalità che si alimenta direttamente in proprietà CSS custom con override di media query, o oggetti tema specifici per piattaforma. Questo è impossibile da inferire da un singolo snapshot del design — richiede un intento esplicito del designer, espresso attraverso le Variables.

Il percorso di aggiornamento è incrementale. Un team può iniziare oggi con token di qualità inferita, adottare le Variables gradualmente man mano che il design system matura e ottenere bundle migliori automaticamente mentre lo fa. Il campo tokensSource tiene traccia di dove ci si trova in quella progressione.

La pipeline dei token completa

Per renderlo concreto, ecco l'ordine di risoluzione completo che figmascope usa per ogni riempimento nell'IR:

  1. Il nodo ha un riferimento boundVariables.fills? Se sì, risolvi al nome della variabile e al valore della modalità zero. Sorgente token: figma-variables.
  2. Il valore risolto è presente nei token di frequenza inferiti (sopra la soglia)? Se sì, mappa al nome del token inferito. Sorgente token: inferred-from-frequency.
  3. Altrimenti: usa direttamente il valore hex risolto. Nessun riferimento a token. Sorgente token: none.

I passi vengono provati in ordine. La sorgente di qualità più alta vince. Il campo tokensSource in _meta.json riflette il percorso dominante per il bundle nel suo complesso.

Ciò significa che un file parzialmente variabilizzato — dove alcuni componenti hanno binding e altri no — produce un bundle misto. Token denominati dove esistono, token inferiti dove non lo fanno. Questo è il comportamento corretto: usa ogni briciola di informazioni strutturate disponibili, ricadi con grazia dove mancano, e sii onesto su quale percorso ha preso ogni valore.

Esporta il tuo bundle dall'app figmascope per vedere quale tokensSource produce il tuo file. Poi usa il bundle con Claude Code o Cursor per una generazione di codice accurata e referenziata ai token.