Design Tokens: cosa sono e come usarli nel design system

Immagina di dover cambiare il colore principale di un prodotto digitale: un blu usato in centinaia di pulsanti, link, icone, bordi e sfondi. Senza un sistema, significa aprire decine di file, cercare ogni valore esadecimale a mano e sperare di non dimenticarne nemmeno uno. Con i design tokens, basta cambiare un valore in un punto solo e l'aggiornamento si propaga ovunque, dal design al codice.

I design tokens sono una delle competenze che separano chi "fa schermate carine" da chi costruisce prodotti scalabili. Sono il linguaggio condiviso che permette a designer e sviluppatori di parlare delle stesse decisioni visive senza fraintendimenti, e sono il motore invisibile dietro ogni design system serio.

In questa guida ti spiego cosa sono i design tokens, perché esistono, come si organizzano in livelli (primitivi, semantici e di componente) e come gestirli concretamente in Figma con le variabili. È un argomento tecnico, ma lo affronteremo passo dopo passo: alla fine avrai un modello mentale chiaro, anche se stai ancora imparando.

Cosa imparerai leggendo:

• Cosa sono i design tokens e quale problema risolvono
• La differenza tra token primitivi, semantici e di componente
• Esempi pratici per colore, spaziatura e tipografia
• Come i token collegano il lavoro di design a quello di sviluppo
• Come creare e gestire i token in Figma con le variabili
• Come definire una naming convention che non diventi un caos

Cosa sono i design tokens

Un design token è la più piccola unità di una decisione di design, salvata in un formato riutilizzabile e indipendente dalla piattaforma. In pratica è una coppia nome → valore: invece di scrivere "questo pulsante è #2563EB", dai un nome a quel valore — per esempio color-primary — e lo usi ovunque ti serva quel blu.

Il punto chiave è la separazione tra il nome e il valore. Il nome esprime l'intento ("colore primario", "spaziatura piccola", "testo grande"); il valore è il dettaglio tecnico ("#2563EB", "8px", "24px"). Questa distinzione, apparentemente banale, è ciò che rende i token così potenti: puoi cambiare il valore senza toccare il nome, e tutto ciò che usa quel nome si aggiorna in automatico.

I token possono descrivere praticamente qualsiasi proprietà visiva: colori, dimensioni dei testi, spaziature, raggi degli angoli, ombre, durate delle animazioni. Sono il vocabolario di base di un design system, e il loro scopo è garantire coerenza (lo stesso valore usato ovunque allo stesso modo) e manutenibilità (un cambiamento in un punto solo).

Perché esistono: il problema che risolvono

Per capire il valore dei token, pensa a come funziona un prodotto senza di essi. Ogni schermata viene disegnata con valori "scritti a mano": un grigio leggermente diverso qui, una spaziatura di 14px là, un altro grigio quasi-ma-non-proprio-uguale nella schermata accanto. Moltiplica tutto questo per decine di schermate, due o tre designer e un team di sviluppo che reinterpreta a modo suo: il risultato è un prodotto incoerente e impossibile da mantenere.

I design tokens risolvono tre problemi concreti:

1. Coerenza — esiste una sola "fonte di verità" per ogni valore. Se il grigio dei testi secondari è text-secondary, è sempre quello, in ogni schermata e in ogni piattaforma.
2. Scalabilità — aggiungere una nuova schermata o un nuovo componente significa riusare token esistenti, non inventare valori nuovi ogni volta.
3. Velocità di aggiornamento — un rebrand, il passaggio a una nuova palette o l'introduzione di una dark mode diventano operazioni controllate, non maratone di copia-incolla.

C'è poi un quarto vantaggio, forse il più importante: i token sono agnostici rispetto alla piattaforma. Lo stesso token color-primary può essere esportato in CSS, in codice iOS, in codice Android. Una sola decisione di design, tante destinazioni. È questo che li rende il ponte naturale tra design e sviluppo.

I tre livelli: primitivi, semantici e di componente

L'errore più comune di chi inizia è creare un unico, enorme elenco di token. Funziona finché il prodotto è piccolo, poi diventa ingestibile. La soluzione adottata dai design system maturi è organizzare i token in livelli (tier), dove ogni livello fa riferimento a quello sotto.

Token primitivi (o globali)

I token primitivi sono i valori grezzi, la "tavolozza" completa a disposizione del prodotto. Non hanno significato d'uso: descrivono solo il valore.

blue-500   = #2563EB
blue-600   = #1D4ED8
gray-100   = #F3F4F6
gray-900   = #111827
space-2    = 8px
space-4    = 16px

Un token primitivo come blue-500 non dice dove va usato quel blu: dice solo che esiste e quanto vale. È il livello più stabile e cambia raramente.

Token semantici (o di alias)

I token semantici danno un significato ai primitivi. Non descrivono cosa è il valore, ma a cosa serve. Sono alias che puntano a un primitivo:

color-action-primary   → blue-500
color-text-default      → gray-900
color-text-muted        → gray-500
spacing-inline-sm       → space-2

Questo è il livello che usi nel 90% dei casi quando progetti. Il vantaggio è enorme: se domani il colore primario diventa verde, ti basta far puntare color-action-primary a green-500 invece che a blue-500. Tutto ciò che usa il token semantico cambia, mentre la tavolozza dei primitivi resta intatta. È anche il livello che abilita i temi: una dark mode è semplicemente lo stesso set di token semantici che puntano a primitivi diversi.

Token di componente

I token di componente sono il livello più specifico: descrivono le proprietà di un singolo componente e di solito fanno riferimento a un token semantico.

button-primary-background  → color-action-primary
button-primary-text         → color-text-on-action
input-border-focus          → color-action-primary

Non sempre servono: introducili solo quando un componente ha bisogno di un controllo fine e indipendente. Su prodotti piccoli puoi tranquillamente fermarti ai primi due livelli e aggiungere i token di componente più avanti.

La regola d'oro è la direzione del riferimento: componente → semantico → primitivo. Un componente non dovrebbe mai puntare direttamente a un primitivo, perché perderesti il significato e la flessibilità che i livelli ti regalano.

Esempi pratici: colore, spaziatura, tipografia

Vediamo come i tre tipi più comuni di token prendono forma nella pratica.

Colore. Parti da una scala di primitivi (per esempio gray-50 fino a gray-900, più le tinte del brand). Poi crei i semantici che esprimono l'uso: color-background-page, color-surface-card, color-text-default, color-border-subtle, color-action-primary. Quando disegni una card, non scegli "il grigio chiaro": applichi color-surface-card. Il nome ti dice già cosa stai facendo.

Spaziatura. Definisci una scala basata su un'unità di base, tipicamente 4px o 8px: space-1 (4px), space-2 (8px), space-3 (12px), space-4 (16px), e così via. Poi i semantici descrivono il contesto: spacing-stack-md per lo spazio verticale tra elementi impilati, spacing-inset-lg per il padding interno di un contenitore. Una scala di spaziatura coerente è ciò che dà ritmo a un'interfaccia, e i token la rendono impossibile da "sbagliare a occhio".

Tipografia. Qui i token spesso si raggruppano in stili compositi. I primitivi sono font-size-sm (14px), font-size-md (16px), font-weight-regular (400), line-height-normal (1.5). I semantici li combinano in ruoli: text-body, text-heading-1, text-caption. Applicando text-heading-1 a un titolo, applichi in un colpo solo dimensione, peso e interlinea già decisi e coerenti.

Se questi concetti ti ricordano qualcosa, è perché il pensiero per token si sposa naturalmente con l'atomic design: i token sono, in un certo senso, gli "atomi" delle decisioni visive, ancora più piccoli dei componenti.

Il ponte tra design e sviluppo

Qui sta il vero superpotere dei design tokens. Tradizionalmente il passaggio dal design al codice è un punto di attrito: il designer consegna un file, lo sviluppatore "traduce" i valori a occhio o copiandoli a mano, e inevitabilmente qualcosa si perde per strada.

Con i token, design e codice condividono la stessa fonte di verità. I token vengono salvati in un formato strutturato — di solito JSON — e poi trasformati nel codice specifico di ogni piattaforma tramite strumenti di "build" (il più noto è Style Dictionary). Lo stesso file di partenza diventa variabili CSS per il web, costanti per iOS, risorse per Android.

{
  "color": {
    "action": {
      "primary": { "value": "#2563EB" }
    }
  }
}

Da questo JSON, un build tool genera automaticamente --color-action-primary: #2563EB; per il CSS e gli equivalenti per le altre piattaforme. Quando il designer cambia il valore, il codice si rigenera: niente più valori che divergono nel tempo. Questo è esattamente l'approccio che sistemi maturi come Material Design 3 hanno reso uno standard di settore, con token semantici pensati fin dall'inizio per supportare temi e personalizzazione.

Il risultato pratico: designer e sviluppatori smettono di discutere su "quale grigio è giusto" e iniziano a parlare la stessa lingua, fatta di nomi condivisi.

Come gestire i design tokens in Figma con le variabili

Per anni in Figma i token venivano simulati con gli "stili" (di colore, di testo), utili ma limitati. Oggi lo strumento giusto sono le variabili di Figma, che riproducono fedelmente la logica dei token, inclusi i riferimenti tra livelli e i temi.

Ecco come impostarle, passo dopo passo:

1. Crea le collezioni. Una buona struttura prevede una collezione per i primitivi (la tua tavolozza completa) e una per i semantici. Tenerle separate riflette i livelli di cui abbiamo parlato.
2. Definisci i primitivi. Inserisci tutti i valori grezzi: i colori della scala, i numeri della spaziatura, le dimensioni dei font. Sono variabili "foglia", che contengono valori reali.
3. Crea i semantici come alias. Questa è la parte cruciale: una variabile semantica come color/action/primary non deve contenere un valore esadecimale, ma puntare alla variabile primitiva blue/500. In Figma lo fai assegnando come valore un'altra variabile. È la stessa logica del riferimento semantico → primitivo.
4. Usa le modalità (modes) per i temi. Le modalità ti permettono di avere, nella stessa collezione semantica, una colonna "Light" e una "Dark": il token color/surface/page punta a gray/50 in Light e a gray/900 in Dark. Cambiando modalità, l'intero file si adatta.
5. Applica solo i semantici nei design. Quando colori un rettangolo o un testo, scegli sempre il token semantico, mai il primitivo diretto. Così mantieni intatta la catena di riferimenti.

Lavorare così trasforma Figma da semplice strumento di disegno a vera fonte dei token, allineata con il codice. È una competenza molto richiesta, e la approfondiamo nella pratica nel nostro tutorial completo su Figma, dove le variabili sono uno dei pilastri.

Naming convention: la regola che tiene tutto in piedi

Un sistema di token vale quanto la sua naming convention. Nomi incoerenti o ambigui vanificano tutti i vantaggi: se nessuno capisce quale token usare, ognuno ne inventa uno nuovo e si torna al caos.

La convenzione più diffusa segue una struttura gerarchica, dal generale allo specifico:

[categoria]-[proprietà]-[variante]-[stato]

color-text-primary
color-text-primary-hover
spacing-inset-sm
color-border-error

Alcuni principi pratici da adottare:

• Descrivi l'intento, non l'aspetto. Usa color-action-primary, non color-blue. Se domani il primario diventa verde, il nome color-blue diventerebbe una bugia.
• Vai dal generale allo specifico. Categoria prima, dettaglio dopo: color-text-muted è più leggibile e ordinabile di muted-text-color.
• Sii coerente nei livelli. I primitivi possono usare scale numeriche (gray-100, gray-200); i semantici usano nomi d'uso (text-default, surface-card).
• Evita abbreviazioni opache. spacing-sm è chiaro; sp-s no.

Una convenzione solida è ciò che permette a un designer nuovo nel team di capire al volo quale token serve, e a uno sviluppatore di prevederne il nome senza dover chiedere. È un investimento che ripaga a ogni schermata.

In sintesi

I design tokens sono coppie nome → valore che catturano le decisioni di design in un formato riutilizzabile e indipendente dalla piattaforma. Si organizzano in tre livelli — primitivi (i valori grezzi), semantici (l'intento d'uso) e di componente (le proprietà specifiche) — collegati da una catena di riferimenti che va dal componente al semantico al primitivo.

Il loro valore è triplice: garantiscono coerenza, abilitano la scalabilità e velocizzano gli aggiornamenti, dai rebrand alla dark mode. Soprattutto, sono il ponte tra design e sviluppo: una sola fonte di verità, esportabile in CSS, iOS e Android, che fa parlare designer e programmatori la stessa lingua. In Figma si gestiscono con le variabili, sfruttando alias e modalità per riprodurre fedelmente i livelli e i temi.

Capire i design tokens significa fare un salto: dal disegnare schermate al progettare sistemi. È esattamente il tipo di competenza strutturale che insegniamo nel nostro percorso di Visual Design, dove imparerai a costruire design system coerenti e pronti per lo sviluppo, non solo file belli da vedere.

Domande frequenti

Qual è la differenza tra design tokens e stili in Figma? Gli stili di Figma raggruppano proprietà visive (un colore, uno stile di testo), ma non permettono di creare riferimenti tra valori né temi multipli. Le variabili di Figma, invece, riproducono la vera logica dei token: una variabile semantica può puntare a una primitiva, e le modalità gestiscono dark mode e brand diversi. Per lavorare a token, oggi si usano le variabili.

Servono sempre tutti e tre i livelli di token? No. I livelli primitivo e semantico sono il cuore del sistema e quasi sempre necessari. I token di componente vanno introdotti solo quando un componente richiede un controllo indipendente e fine: su prodotti piccoli puoi tranquillamente farne a meno all'inizio e aggiungerli quando il sistema cresce.

I design tokens servono solo a chi sviluppa, o anche al designer? Servono soprattutto al designer. Sono il modo in cui prendi decisioni visive coerenti e le rendi riutilizzabili, ben prima che arrivino allo sviluppo. Pensare a token migliora la qualità del lavoro di design in sé; il fatto che poi diventino codice in modo automatico è un vantaggio aggiuntivo, non il loro unico scopo.