Design Token Spiegati, con un Convertitore dal Vivo da JSON a CSS
Design Token Spiegati
Design Token Spiegati con Esempi (JSON, CSS, Tailwind) | We.Inc
Cosa sono i design token, come li scrive il formato JSON del community group W3C e un convertitore dal vivo che trasforma il JSON dei token in variabili CSS e in un blocco @theme di Tailwind v4.
I design token sono decisioni di design con un nome, come color.primary o space.md, salvate come dati così che ogni piattaforma legga gli stessi valori. Il formato del Design Tokens Community Group li scrive in JSON con $value e $type, e permette a un token di puntare a un altro con le parentesi graffe. Gli strumenti trasformano poi quel JSON in variabili CSS, temi Tailwind o codice per app.
I livelli di token usati dalla maggior parte dei team
Livello
Nome di esempio
Contiene
Base (primitivo)
Un valore grezzo: un colore, una dimensione o un font
Semantico (alias)
Un ruolo che punta a un token base
Componente
Un ruolo limitato a un solo componente
La maggior parte delle spiegazioni si ferma alla definizione. Incolla o modifica qui sotto il JSON dei token nel formato del community group e vedi, mentre scrivi, le custom property CSS e il tema Tailwind v4 che produce, con gli alias risolti in riferimenti var().
Modifica il JSON a sinistra. I gruppi possono impostare $type una sola volta per tutti i token che contengono.
Fai riferimento a un altro token racchiudendo il suo percorso con i punti tra parentesi graffe, per esempio {color.blue-500}.
Leggi la scheda CSS per le variabili su :root, o la scheda Tailwind per un blocco @theme.
Copia l'output nel tuo foglio di stile. Prima correggi eventuali messaggi di errore mostrati sotto l'editor.
Dai ai token semantici il nome della loro funzione (text, surface, danger) invece del loro aspetto (red, dark), così un rebranding cambia solo il livello base.
Tieni i token base fuori dai componenti. I componenti dovrebbero leggere i nomi semantici, così la dark mode e i temi possono sostituire i valori sottostanti.
Conserva i token in un unico file sotto controllo di versione e genera da lì l'output per ogni piattaforma.
Usa l'estensione consigliata .tokens o .tokens.json, così gli strumenti riconoscono i file.
Domande frequenti
Cos'è un design token?
Un design token è un nome abbinato a un valore di design, per esempio color.text che contiene un colore quasi nero. Il codice e i file di design usano il nome, quindi cambiare il valore in un solo punto aggiorna ogni pulsante, pagina e app che vi fa riferimento.
Esiste un formato standard per i design token?
Sì. Il Design Tokens Community Group del W3C ha pubblicato il Format Module 2025.10 come report finale del community group il 28 ottobre 2025 e lo descrive come stabile. È un report di community group, non una W3C Recommendation.
Che differenza c'è tra design token e variabili CSS?
I token sono i dati di origine, indipendenti da qualsiasi piattaforma. Le custom property CSS sono uno degli output. Lo stesso file di token può generare anche costanti Swift, Android o JavaScript, cosa che le sole variabili CSS non possono darti.
Come funzionano i design token con Tailwind CSS?
In Tailwind v4 dichiari le variabili del tema dentro @theme, come --color-primary. Tailwind crea da queste utility come bg-primary e le emette anche come normali variabili CSS su :root, così token e utility restano sincronizzati.
Come si scrivono i colori nel formato dei token?
Nel formato 2025.10 il valore di un colore è un oggetto con un colorSpace, come srgb, e un array di componenti da 0 a 1, con alpha facoltativo. Il convertitore qui accetta anche semplici stringhe, così puoi incollare file di token più vecchi.
Perché i team adottano i token
Senza token, il blu del brand vive come un codice esadecimale incollato in centinaia di punti tra CSS, app mobile e file di design. Cambiarlo significa un cerca e sostituisci che ne dimentica sempre uno.
Con i token, quel blu ha un solo nome e una sola casa. Designer e sviluppatori parlano di color.primary, e un passaggio di build scrive il valore nel formato proprio di ogni piattaforma.
Leggere il formato JSON
Qualsiasi oggetto con un $value è un token; qualsiasi altro oggetto è un gruppo. Le proprietà che iniziano con il simbolo del dollaro sono riservate dal formato: $value, $type, $description, $deprecated e $extensions.
La specifica definisce tipi semplici come color, dimension, fontFamily, fontWeight, duration, cubicBezier e number, più tipi compositi come shadow, border, transition, typography, strokeStyle e gradient. Dimensioni e durate sono oggetti con un valore numerico e un'unità.
Dai token a un tema funzionante
Un sito piccolo può tenere i token direttamente in CSS come custom property. Quando distribuisci su più di una piattaforma, o progetti in uno strumento che esporta token, genera invece il CSS dal JSON così da avere un'unica fonte.
La dark mode diventa un secondo insieme di valori semantici. I colori base restano gli stessi, e il livello semantico cambia il token base a cui punta ogni ruolo dentro una media query per lo schema scuro o un attributo data.
Token semantici con un tema scuro
Cambia i valori semantici, mantieni quelli base
La card legge solo --surface e --text. Il blocco scuro riassegna quei due nomi e la card si adegua senza alcuna modifica alle proprie regole.
Un token composito
Token di ombra nel formato del community group
I token compositi raggruppano più valori. Qui il colore è a sua volta un alias, e gli offset usano oggetti dimension.
Nessun token trovato. Un token è un oggetto con una proprietà $value.
Non è ancora JSON valido: {message}
Convertitore da JSON dei token a CSS
Modifica il file dei token e le variabili CSS e il tema Tailwind si aggiornano mentre scrivi. Il file iniziale viene convertito in: