Design Systems · · 12 min di lettura
Token semantici: l'unico modo sensato di fare design system nel 2026
Gli alias non bastano. Serve una gerarchia semantica che sopravviva al dark mode, al theming e al multi-brand. Ecco come costruirla dai principi fondamentali — non dagli strumenti.
Ho visto i design system morire per molte ragioni. Mancanza di governance. Ricambio del team. Adozione parziale da parte degli ingegneri. Ma negli ultimi due anni ho identificato un pattern ricorrente in quelli che crollano più velocemente: hanno token piatti, nessuna semantica, costruiti per sembrare organizzati senza esserlo davvero.
Un file con 200 variabili CSS chiamate --color-blue-500, --color-blue-600 e così via non è un design system. È una palette con un altro nome. E quando arriva la richiesta di supportare il dark mode, un secondo brand o un tema di accessibilità per ipovedenti, quel file diventa un problema serio.
La gerarchia a tre livelli che funziona
Il modello che uso in tutti i miei progetti enterprise ha tre livelli distinti, con responsabilità separate e regole di dipendenza chiare.
Livello 1 — Primitivi. Sono valori grezzi: colori esatti, dimensioni, font, durate. Non portano nessun significato semantico. Sono il vocabolario grezzo del sistema. I token primitivi non vengono mai usati direttamente nei componenti — esistono solo per essere referenziati dal livello successivo.
Livello 2 — Token semantici. Qui avviene la magia. I token semantici mappano i primitivi ai significati dell’interfaccia. Non descrivono un colore — descrivono una funzione: --color-background-default, --color-text-primary, --color-border-subtle. In dark mode, il valore di --color-background-default cambia, ma ogni componente che usa quel token si aggiorna automaticamente — senza toccare un singolo file di componente.
Livello 3 — Token di componente. Specifici per un singolo componente o pattern. --button-primary-background punta a --color-action-primary, che a sua volta punta al primitivo corretto per il tema attivo. Questo livello è opzionale per sistemi piccoli, ma diventa indispensabile con il multi-brand.
Il problema degli alias privi di semantica
Molti team implementano qualcosa che sembra un sistema a tre livelli ma è in realtà un solo livello di profondità. Un alias come --brand-primary: var(--color-blue-600) non è un token semantico — è un alias. Non descrive una funzione nell’interfaccia; dà solo a un colore specifico un nome più corto.
Se devo spiegare cosa fa un token, il nome è sbagliato.
La differenza emerge nel momento in cui si prova a costruire un tema alternativo. Se un pulsante usa --brand-primary come sfondo, cosa succede quando il secondo brand usa il rosso come colore primario? Il token semantico corretto è --color-action-primary-background: descrive la funzione, il ruolo, e può essere mappato su qualsiasi primitivo in qualsiasi tema senza rompere nulla.
Una struttura di naming pratica
La convenzione di naming che uso segue questo pattern: categoria — proprietà — variante — stato. Non ogni segmento è sempre necessario, ma l’ordine è sempre lo stesso.
--color-background-default— categoria: colore, proprietà: sfondo, variante: default--color-text-on-primary— testo posizionato sopra un elemento con sfondo primario--color-border-focus— bordo nello stato di focus (per l’accessibilità WCAG)--size-spacing-md— spaziatura a scala media--duration-interaction-fast— durata per interazioni rapide
Il principio guida è che il nome di un token semantico deve essere leggibile da un designer e da uno sviluppatore allo stesso modo, senza nessun contesto aggiuntivo.
Dark mode senza sovrascrivere tutto
Il beneficio pratico di una gerarchia semantica emerge più chiaramente con il dark mode. Invece di sovrascrivere ogni singola variabile CSS con centinaia di eccezioni, si ridefinisce solo il mapping tra token semantici e primitivi.
I componenti non cambiano — referenziano sempre lo stesso token semantico. Il tema scuro è semplicemente un layer di sostituzione al livello 2, non una riscrittura del CSS dei componenti. Con questo approccio, su un sistema con 60 componenti, il CSS del tema scuro occupa meno di 80 righe.
Multi-brand in produzione
Nel progetto Exein ho dovuto gestire tre brand con identità visive molto diverse sullo stesso sistema di componenti. La soluzione è stata costruire i token semantici in modo brand-neutral — descrivono funzioni, non identità — e creare un file di tema separato per ciascun brand.
Un token semantico ben progettato non sa a quale brand appartiene. Sa solo cosa deve fare nell’interfaccia.
Il risultato pratico: aggiungere un quarto brand ha richiesto meno di mezza giornata. Creare un file di primitivi, mapparlo sui token semantici esistenti, verificare i rapporti di contrasto WCAG. Zero modifiche ai componenti.
Il tooling nel 2026
Token Studio per Figma rimane il riferimento per il ponte design-sviluppo. Style Dictionary di Amazon è lo strumento più flessibile per distribuire i token come CSS, JSON, Swift e Kotlin. Ma la scelta del tooling viene dopo la scelta dell’architettura. Un sistema mal progettato non diventa buono cambiando software.