Design token multi-brand: 6 passi da un solo livello di primitive

Alla fine di questa guida avrai un'unica fonte di token al servizio di più brand. È fatta di quattro parti: un livello di primitive da cui attingono tutti i brand, un contratto semantico che ogni brand rispetta, un piccolo file di decisioni per ciascun brand e componenti che leggono soltanto nomi semantici. Aggiungere un brand diventa un nuovo file e un nuovo target di build. La libreria di componenti resta com'è.

L'architettura dei token multi-brand è un modo di organizzare i design token perché più prodotti condividano una sola libreria di componenti, ognuno con i propri colori, caratteri e forme. Serve ai team che gestiscono prodotti gemelli, piattaforme white-label o un gruppo con più marchi rivolti al pubblico. Chi ne fa a meno se ne accorge dai fork. Infinum ha raccontato il caso di un gruppo di telecomunicazioni con quattro brand, ciascuno con il suo file di asset, il suo file di componenti mobile e quello dei componenti web: dodici file, e ogni modifica condivisa fatta quattro volte.

Sul formato, ormai, non ci sono più dubbi. Il Design Tokens Community Group ha pubblicato la prima specifica stabile, la 2025.10, il 28 ottobre 2025, e tra le novità principali c'è proprio il supporto a temi e multi-brand. I passi che seguono usano il suo formato JSON, così qualsiasi strumento che lo legge (Style Dictionary, Terrazzo, Tokens Studio) può generare il risultato.

Cosa serve prima di cominciare

• Una libreria di componenti che legge già token o custom property CSS, non valori esadecimali scritti a mano. Se non è così, si parte da lì: il component drift è il punto in cui i progetti multi-brand si arenano.
• L'elenco dei brand e, per ciascuno, una persona che può dire sì o no a un colore.
• Uno strumento di build che legge il JSON DTCG e gira una volta per ogni brand e piattaforma.
• Uno strumento di design con le variabili. In Figma il numero di modi per collezione dipende dal piano: fino a 10 con Professional, fino a 20 con Organization, illimitati con Enterprise tramite le extended collection.

Passo 1. Elencare cosa cambia davvero tra i brand

Si mettono i brand uno accanto all'altro in un foglio di calcolo, una riga per decisione: colore principale, tinta dei neutri, carattere dei titoli, carattere del testo, raggio degli angoli, forma dei pulsanti, densità, movimento. Ogni riga si segna come condivisa o specifica del brand.

Le righe specifiche di solito sono meno di quante se ne aspettino i team dei brand. Scale di spaziatura, breakpoint, livelli di z-index e durate tendono a coincidere ovunque, e stanno nel nucleo comune. Colore, famiglie di caratteri e raggi invece tendono a cambiare. L'elenco va scritto prima di dare il nome a un solo token, perché decide quanto sarà grande ogni file di brand. Un file di brand con 300 voci vuol dire che l'analisi è stata saltata.

Conviene anche annotare cosa cambia nella struttura e non nell'aspetto. Un brand che ha bisogno di un'altra navigazione o di un passaggio in più nel checkout ha un problema di componenti. I token non lo risolvono.

Passo 2. Costruire un solo livello di primitive per tutti i brand

Le primitive sono valori grezzi, senza un significato: rampe di colore, famiglie di caratteri, una scala di raggi, una scala di spaziature. Vanno tutte in un unico livello, comprese le rampe di ogni brand, e ognuna prende il nome da ciò che è (color.teal.600), mai da chi la usa (color.acme.primary).

Così due brand con un blu quasi identico condividono una rampa, e un restyling che sposta un brand dal verde acqua al viola cambia un alias, senza rinominare una rampa. I componenti questo livello non lo leggono mai. Se lo leggono, cambiare brand vuol dire mettere mano al codice dei componenti.

Passo 3. Definire il contratto semantico che ogni brand deve rispettare

I token semantici danno il nome a un ruolo: color.action.background, color.text.default, radius.control, font.family.heading. Questo elenco è l'API tra il sistema e i brand. I componenti leggono solo quello, e ogni brand deve fornire un valore per ogni voce.

Il contratto va tenuto piccolo e stabile. Ogni nuovo token semantico è un obbligo in più per tutti i brand, quindi se ne aggiunge uno solo quando quel ruolo esiste in almeno due brand. Dei nomi parliamo in un sistema di naming a 3 livelli.

Passo 4. Scrivere un file per brand, fatto solo di alias

Un file di brand collega i token semantici alle primitive e non contiene valori grezzi. In JSON DTCG una voce si scrive così:

{
  "color": {
    "action": {
      "background": { "$type": "color", "$value": "{color.teal.600}" }
    }
  }
}

Con gli alias ogni brand resta dentro il livello delle primitive, l'unico in cui si controlla il contrasto. Un designer che vuole una tonalità nuova la aggiunge a una rampa, dove la vedono tutti i brand.

Il modulo Resolver della specifica descrive come combinare questi file. Si dichiarano i set (i file del nucleo) e i modificatori (brand, tema), ognuno con i suoi contesti, e un ordine di risoluzione. Il modulo segnala la trappola in cui cade ogni sistema multi-brand: quando un modificatore di brand e uno di tema impostano lo stesso token, il valore lo decide l'ordine dell'array. L'ordine va scelto di proposito. Se il tema si risolve prima del brand, un file di brand può correggere un valore del tema scuro che non lo convince. Qualunque ordine si scelga, va scritto nel readme.

Passo 5. Una build per ogni brand e ogni piattaforma

L'esempio multi-brand e multi-piattaforma di Style Dictionary mostra la forma: token divisi in cartelle per brand, per piattaforma e globali, e uno script di build che passa ogni coppia brand e piattaforma e scrive in build/web/brand-1/ e così via.

Sul web il risultato si distribuisce in due modi:

• Un file per brand. Ogni prodotto carica solo il proprio CSS. È la scelta giusta quando i brand sono app separate.
• Un solo file, diviso per attributo. Le custom property di ogni brand stanno sotto un selettore come [data-brand="b"], e l'app cambia brand cambiando un attributo. È la scelta giusta per i prodotti white-label, dove un solo deploy serve molti clienti.

Prima di aggiungere un modificatore conviene contare le build. Quattro brand, due temi e tre piattaforme fanno già 24 build. Il modulo Resolver la chiama esplosione combinatoria, e ogni asse in più (densità, alto contrasto, movimento ridotto) la moltiplica di nuovo.

Passo 6. Riportarlo in Figma e sorvegliarlo in CI

In Figma le primitive vanno in una collezione e i token semantici in un'altra, con un modo per brand. Con il piano Enterprise le extended collection lo fanno in modo più pulito: ogni brand estende una collezione madre, sovrascrive solo ciò che cambia ed eredita ogni modifica successiva alle variabili che non ha toccato. Una extended collection non può aggiungere variabili o modi propri: è lo stesso contratto del passo 3, imposto dallo strumento.

In CI tre controlli bloccano quasi tutte le regressioni:

1. Ogni token semantico si risolve per ogni brand. Un valore mancante fa fallire la build.
2. Nessun file di componente fa riferimento a una primitiva o a un token con il nome di un brand.
3. Ogni coppia di testo e sfondo rispetta il contrasto minimo di 4,5:1 per il testo corrente, per ogni brand e ogni tema.

Come verificare che funziona

Si aggiunge un brand finto con valori volutamente vistosi: un verde saturo, angoli vivi, un carattere graziato per i titoli. Poi si mostra tutta la galleria dei componenti con quel brand. Ogni componente deve cambiare. Quello che conserva il vecchio aspetto legge una primitiva o un valore scritto a mano, e l'hai trovato prima che lo trovasse un brand vero.

Errori frequenti e come correggerli

• Nomi di brand dentro i componenti. Un pulsante che legge color.acme.primary funziona per un solo brand. Si sostituisce con il token semantico e il valore del brand si sposta nel file del brand.
• Token di componente copiati per ogni brand. Scrivere button.background a parte per ciascun brand moltiplica i file senza dare più controllo. I token di componente vanno collegati a quelli semantici, e un brand ne sovrascrive uno solo quando è davvero diverso.
• Valori esadecimali grezzi in un file di brand. Saltano i controlli di contrasto del livello delle primitive. La tonalità si aggiunge a una rampa, poi si collega con un alias.
• Struttura scambiata per aspetto. Quando un brand ha bisogno di un altro layout o di un altro flusso, nessun token glielo darà. Diventa una variante di componente e resta fuori dai file dei token.

Per andare oltre

I brand raramente differiscono solo nel colore. Anche tipografia, movimento e densità portano identità, e in design token oltre il colore spieghiamo come modellarli. Quando più prodotti usano lo stesso nucleo, il processo di rilascio conta quanto l'architettura: in come governare un design system su 10 progetti descriviamo il versionamento e le regole di revisione che usiamo.