Design token: cosa sono e come funzionano nei design system

Design token in sintesi

• Definizione: nome simbolico che sostituisce un valore grezzo di design (colore, spazio, font) per mantenere coerenza tra progettazione e codice.
• Livelli: i token si organizzano in tre strati — globali, semantici e specifici — ciascuno con uno scopo diverso.
• Formato: lo standard aperto promosso dal W3C Design Tokens Community Group definisce una struttura JSON comune.
• Strumenti: Figma, Tokens Studio, Penpot gestiscono i token lato design; Style Dictionary li trasforma in codice nativo.
• Vantaggi: modifica centralizzata, temi multipli (chiaro/scuro) e minore debito tecnico tra design e sviluppo.
• Naming: il nome di un token segue uno schema con elemento, categoria, proprietà e opzione di stile.

Cos’è un design token e a cosa serve

Un design token elimina il valore hardcoded dal codice e dai file grafici, sostituendolo con un’entità con nome che rappresenta una decisione di progettazione. Invece di scrivere direttamente margin: 16px o color: #0066CC, si richiama un token come space-md o color-action-primary: il valore resta definito in un unico punto e viene propagato ovunque serva.

Questo meccanismo nasce come fondamento strutturale di un design system, l’insieme organizzato di componenti, pattern e regole visive che un prodotto digitale adotta su più piattaforme. Senza token, uno stesso colore o una stessa spaziatura finiscono per vivere in tre forme diverse — uno stile Figma, un valore scritto a mano in un componente, un hex perso in un foglio di stile — e ogni rebrand o cambio di tema richiede di correggerle una per una.

Il concetto separa il valore (il dato grezzo) dal significato (lo scopo d’uso): un designer aggiorna il token in uno strumento di progettazione e lo sviluppatore riceve lo stesso riferimento nel codice sorgente, senza passaggi intermedi manuali. Questa separazione è ciò che permette a un’interfaccia di restare coerente quando cresce su web, iOS e Android contemporaneamente.

L’adozione dei token risale alle prime esperienze di design system su larga scala e si è poi diffusa come pratica standard in ogni sistema che debba mantenere uniformità visiva su più superfici, incluse le implementazioni istituzionali come quella pubblicata nel Design System .italia.

I tre livelli dei design token

I token si distribuiscono su tre livelli di astrazione, ciascuno con una funzione precisa nella catena che va dal valore grezzo al componente finale.

Il token globale descrive solo il dato grezzo: non comunica dove o perché venga usato. Il token semantico aggiunge un’intenzione, così che un cambio di brand o il passaggio alla modalità scura richieda di aggiornare solo il valore a cui il token semantico punta, senza toccare i componenti. Il token specifico, infine, permette di far deviare un singolo elemento dal comportamento generale del sistema, mantenendo comunque il collegamento ai livelli superiori.

Se manca un token semantico adatto

Se esiste già un token semantico che descrive lo scopo richiesto, il token specifico del componente deve referenziare quel token semantico, non il valore grezzo. Se invece nessun token semantico riutilizzabile copre quel caso, il token specifico può puntare direttamente al valore primitivo, in attesa che l’esigenza si ripeta abbastanza da giustificare un nuovo livello semantico.

I token globali non vanno mai applicati direttamente a un elemento dell’interfaccia: la loro unica funzione è alimentare i livelli semantico e specifico. Applicarli in modo diretto vanifica il vantaggio principale del sistema, perché ogni cambiamento richiederebbe di rintracciare manualmente ogni punto in cui il valore grezzo è stato usato.

Come si chiamano i design token: naming e tassonomia

Il nome di un token non è un’etichetta arbitraria: segue una struttura ripetibile che permette a chiunque, leggendo solo il nome, di capire a cosa serve quel valore. La sequenza tipica combina quattro tipologie di termine separate da un trattino.

Elemento

Il componente o la parte di interfaccia a cui il token si riferisce, come un pulsante, un’etichetta o un modulo.

Categoria

Il tipo di stile coinvolto: colore, font, spaziatura, dimensione, raggio di curvatura.

Proprietà

L’aspetto specifico legato a quella categoria, ad esempio lo sfondo per la categoria colore.

Opzione

La variante applicata: uno stato come attivo o disabilitato, oppure un valore su una scala dimensionale come xs o lg.

Il numero di termini presenti nel nome cresce con il livello di profondità del token: un token globale ha un nome breve e descrittivo del valore grezzo (ad esempio color-blue-40), mentre un token specifico include sempre il riferimento al componente per facilitarne l’adozione sia in fase di progettazione sia in fase di sviluppo.

Una convenzione diffusa per i colori primitivi usa una scala numerica, non nomi di fantasia: valori da 0 a 100 (o su scale più ampie come 100-1000) esprimono la quantità di luce presente in un colore, dove l’estremo più alto corrisponde al bianco pieno e quello più basso al nero pieno. Questo approccio resta leggibile anche quando la palette supera poche decine di tonalità, a differenza di nomi descrittivi che diventano difficili da memorizzare oltre un numero limitato di colori.

Qualunque sia la logica scelta, va applicata in modo coerente su tutto il sistema: un nome deve comunicare cosa fa il token, non semplicemente cosa contiene, ed è preferibile che resti breve, modulare e facile da interpretare da chiunque lavori sul progetto.

Vantaggi dell’adozione dei design token

Il beneficio principale è la gestione centralizzata: modificare un singolo token aggiorna automaticamente ogni elemento collegato, sia nei file di progettazione sia nel codice in produzione. Questo riduce il tempo necessario per un rebrand o per un intervento di manutenzione su larga scala, perché non è più necessario individuare manualmente ogni occorrenza di un valore.

Un secondo vantaggio riguarda i temi multipli. Passare dalla modalità chiara alla modalità scura, o adattare l’interfaccia a un nuovo brand, significa cambiare solo i valori a cui i token semantici puntano, lasciando invariati i nomi usati nei componenti e nel codice. Lo stesso meccanismo consente di gestire varianti di prodotto o white label senza duplicare la base di codice.

Il terzo beneficio è la riduzione del debito tecnico e di design: quando designer e sviluppatori condividono lo stesso nome per lo stesso valore, le incongruenze tra ciò che è stato progettato e ciò che è stato implementato diminuiscono, e gli handoff tra i due ruoli diventano più rapidi perché chi legge il codice trova un nome con significato invece di un valore grezzo privo di contesto.

Un quarto effetto, meno immediato ma rilevante su team numerosi, è la scalabilità del linguaggio visivo: aggiungere una piattaforma (una nuova app mobile, un nuovo canale) richiede di tradurre gli stessi token nel formato nativo di quella piattaforma, non di ridefinire da zero le decisioni di stile.

Lo standard W3C per il formato dei design token

Per anni ogni strumento ha salvato i token in un formato proprietario, rendendo difficile spostare un set di valori da un software di progettazione a un altro. Il Design Tokens Community Group, gruppo di lavoro del W3C, ha definito uno standard aperto, noto come DTCG, che descrive la struttura di un file JSON comune a più strumenti.

Un file conforme allo standard organizza i token in oggetti con un nome, un valore e, facoltativamente, una descrizione e un tipo (colore, dimensione, font, ombra). Avere un formato condiviso significa poter esportare le variabili create in uno strumento di progettazione e importarle in un software diverso, oppure elaborarle con uno strumento di build senza dover scrivere un convertitore su misura per ogni combinazione di software.

L’effetto pratico dello standard riguarda soprattutto l’interoperabilità: un set di token definito una sola volta può alimentare contemporaneamente fogli di stile CSS, risorse native per iOS e Android e documentazione, mantenendo la stessa fonte di partenza. Chi gestisce un sistema di token su più team trae beneficio diretto dall’adozione di questo formato, perché riduce la necessità di mantenere più copie manuali dello stesso valore in strumenti differenti.

Design token in Figma, Penpot e gli strumenti di sincronizzazione

In Figma i design token si gestiscono tramite il pannello delle variabili, che permette di creare collezioni distinte per i valori primitivi, applicare alias semantici e collegare le variabili ai componenti. Il plugin Tokens Studio estende questa funzione, consentendo di esportare i tre livelli — globale, semantico e specifico — in file JSON separati, pronti per essere versionati in un repository.

Penpot, alternativa open source ai software di progettazione proprietari, supporta anch’esso un sistema di variabili di design pensato per essere esportato in formati standard, così da poter alimentare la stessa pipeline di sviluppo usata con altri strumenti.

Dal lato del codice, Style Dictionary prende in input i file JSON dei token e genera le variabili native per ogni piattaforma di destinazione: fogli di stile CSS e Sass, risorse per iOS, risorse per Android, costanti JavaScript. Questo passaggio automatizzato elimina la trascrizione manuale dei valori e garantisce che il codice resti allineato a ogni aggiornamento dei token, finché la pipeline di build viene eseguita a ogni modifica.

Un’implementazione pubblica di questo flusso è disponibile nel repository ufficiale dei token del Design System .italia, dove i tre livelli sono distribuiti in file global.json, semantic.json e specific.json, accompagnati da un foglio di tassonomia scaricabile che documenta la logica di naming adottata.

Esempi pratici di design token

Un esempio completo mostra come lo stesso valore attraversi i tre livelli. Un valore primitivo come color-blue-500: #0066CC diventa, a livello semantico, color-action-primary: color-blue-500, assegnandogli il ruolo di colore per le azioni principali dell’interfaccia. A livello di componente, lo stesso riferimento alimenta button-primary-background-active: color-action-primary, applicato allo sfondo di un pulsante primario nello stato attivo.

Per la spaziatura, una scala primitiva può definire valori come space-4, space-8 e space-16, corrispondenti a incrementi in pixel; il token semantico space-md punta a uno di questi valori e viene richiamato nei margini e nei padding dei componenti, senza che lo sviluppatore debba ricordare il valore numerico esatto.

Per il tema scuro, lo stesso token semantico cambia il valore primitivo a cui punta: color-action-primary può riferirsi a color-blue-500 in modalità chiara e a color-blue-400 in modalità scura, lasciando invariato il nome usato in ogni componente e nel codice che lo richiama.

Questi esempi mostrano perché la distinzione tra scopo (il token semantico) ed esecuzione (il token di componente) è centrale: il primo comunica l’intenzione progettuale, il secondo la applica a un elemento preciso, e un’interfaccia coerente nasce dal rispetto di questa catena su ogni piattaforma.

Come costruire una gerarchia di design token

Costruire una gerarchia di token richiede un ordine preciso, perché ogni livello dipende da quello precedente.

1. Definire i token primitivi: raccogliere ogni colore, spaziatura, dimensione di font e raggio di curvatura usato nel sistema, assegnando a ciascuno un nome breve basato sul valore grezzo.
2. Creare i token semantici: per ogni primitivo usato più volte con lo stesso scopo, definire un alias che ne comunichi l’intenzione d’uso, come colore di azione primaria o colore di testo secondario.
3. Definire i token specifici: per i componenti che richiedono una personalizzazione puntuale, creare token che referenzino i livelli semantico o, in assenza di un’alternativa riutilizzabile, direttamente il livello primitivo.
4. Esportare la struttura in formato JSON conforme allo standard DTCG, separando i tre livelli in file distinti per facilitarne la manutenzione.
5. Trasformare il JSON in codice nativo con uno strumento di build, generando variabili CSS, Sass o risorse per le piattaforme mobili di destinazione.
6. Collegare lo strumento di progettazione al repository di codice, così che ogni aggiornamento dei token in fase di design si rifletta nella build successiva senza trascrizioni manuali.

Questo percorso resta valido sia che si parta da un progetto nuovo, sia che si stia integrando i token in un sistema esistente: nel secondo caso conviene partire da un inventario dei valori già in uso, individuare le duplicazioni e ricondurle a un unico token primitivo prima di procedere ai livelli superiori.

Errori frequenti nella gestione dei design token

Il primo errore è applicare direttamente un token globale a un elemento dell’interfaccia, saltando il livello semantico: questo vanifica il vantaggio della gestione centralizzata, perché un cambio di brand richiede di rintracciare manualmente ogni occorrenza del valore grezzo.

Il secondo errore riguarda il naming: usare nomi descrittivi di fantasia per i colori primitivi funziona solo con palette molto ridotte; oltre poche decine di valori diventa impossibile ricordare quale nome corrisponda a quale tonalità, ed è preferibile una scala numerica coerente.

Il terzo errore è non definire una convenzione di naming condivisa prima di iniziare: ogni persona del team finisce per adottare una logica diversa, rendendo i token difficili da cercare e da mantenere nel tempo.

Il quarto errore è trattare i token di componente come l’unico livello da usare, ignorando quello semantico: ogni piccola variazione di stile genera un nuovo token specifico invece di riutilizzare un alias esistente, con una crescita incontrollata del numero di token nel sistema.

Infine, mancare di una pipeline automatizzata tra file JSON e codice costringe a trascrivere i valori a mano, introducendo disallineamenti tra ciò che i designer vedono nel loro strumento e ciò che gli sviluppatori implementano in produzione.

Design token e altri significati del termine token

Il termine token è un omonimo usato in ambiti molto diversi dal design. Nella sicurezza informatica indica un dispositivo fisico o software, detto anche token di autenticazione, che genera codici numerici temporanei per confermare un’identità in un’autenticazione a due fattori: è il caso del token bancario usato per autorizzare un bonifico.

In finanza e nelle infrastrutture blockchain, token identifica un asset digitale programmabile, distinto in fungibile (interscambiabile, come una criptovaluta) e non fungibile (NFT, legato a un bene unico). Il valore di questi token dipende dal mercato in cui vengono scambiati e non è un dato tecnico definibile in astratto: va verificato di volta in volta su una piattaforma di scambio.

Nell’elaborazione del linguaggio naturale e nei modelli di intelligenza artificiale, un token è l’unità minima in cui un testo viene suddiviso prima di essere elaborato: può corrispondere a una parola, una parte di parola o un singolo carattere, ed è l’unità su cui si basa il conteggio dei costi di utilizzo di questi modelli.

In ambito educativo e psicologico, la token economy è una tecnica di rinforzo comportamentale che assegna gettoni simbolici a fronte di comportamenti desiderati, scambiabili successivamente con una ricompensa concordata.

Nessuno di questi significati coincide con il design token descritto in questa pagina, che resta un concetto specifico dei sistemi di progettazione e sviluppo di interfacce digitali.

Domande frequenti sui design token

Che cosa si intende per design token?

Un design token è una variabile con nome che rappresenta una decisione di progettazione, come un colore o una spaziatura, al posto di un valore scritto direttamente nel codice o nei file grafici. Il nome resta stabile mentre il valore a cui punta può cambiare in un unico punto.

Quali sono i livelli dei design token?

Sono tre: globale (valore grezzo di riferimento), semantico (assegna uno scopo d’uso al valore) e specifico (applica la decisione a un singolo componente). Ogni livello superiore si costruisce referenziando quello precedente.

Come si assegna un nome a un design token?

Il nome combina elemento, categoria, proprietà e opzione di stile, separati da un trattino, e cresce in lunghezza man mano che il token diventa più specifico. La coerenza della convenzione conta più della logica scelta.

Come si gestiscono i design token in Figma e Penpot?

In Figma si usano il pannello delle variabili e plugin come Tokens Studio per creare ed esportare i token in JSON; Penpot offre un sistema di variabili analogo, pensato per alimentare la stessa pipeline di esportazione verso il codice.

Cos’è lo standard DTCG per i design token?

È il formato JSON aperto definito dal Design Tokens Community Group del W3C, pensato per rendere i token leggibili da strumenti diversi senza bisogno di conversioni manuali tra formati proprietari.

Qual è un esempio di design token?

Un esempio tipico è color-action-primary, un token semantico che punta a un valore primitivo come color-blue-500 e viene richiamato dal token di componente che definisce lo sfondo di un pulsante.

Che differenza c’è tra design token e token di sicurezza o criptovaluta?

Il design token è una variabile di stile usata nei sistemi di progettazione; il token di sicurezza genera codici per l’autenticazione a due fattori; il token in ambito blockchain rappresenta un asset digitale scambiabile. Sono concetti distinti che condividono solo il nome.

Come si inizia a costruire una gerarchia di design token?

Si parte censendo i valori primitivi già in uso, si definiscono i token semantici per gli usi ricorrenti, si creano i token di componente dove serve una personalizzazione puntuale e si esporta tutto in JSON verso una pipeline di build.