Architettura dei token per più temi e brand

Un tema modifica la modalità colore dello stesso brand, ad esempio le versioni chiara e scura dello stesso prodotto. Un brand rappresenta un'identità visiva diversa: gli stessi componenti del design system vengono visualizzati con colori, tipografia e spaziatura differenti per servire prodotti o clienti diversi. Entrambi usano la stessa architettura dei token, ma a livelli di astrazione diversi.

I token primitivi costituiscono la tavolozza completa dei valori grezzi disponibili nel sistema. Includono ogni tonalità di colore (da color-blue-50 a color-blue-900), ogni unità di spaziatura e ogni dimensione del carattere. I token primitivi non vengono mai usati direttamente nei componenti: sono referenziati esclusivamente dai token semantici. La tavolozza viene definita una volta sola e condivisa tra tutti i temi e i brand.

I token semantici esprimono l'intento: color-background-page, color-text-primary, color-action-primary. Ogni token semantico fa riferimento al valore di un token primitivo appropriato per il tema corrente. I componenti vengono costruiti usando esclusivamente token semantici. È a questo livello che avviene la gestione dei temi.

Nel tema chiaro: color-background-page fa riferimento a color-white, color-text-primary fa riferimento a color-gray-900 e color-action-primary fa riferimento a color-blue-500. Queste mappature sono definite in un file di token specifico del tema, che sovrascrive il livello semantico nel contesto chiaro.

Nel tema scuro: color-background-page fa riferimento a color-gray-950, color-text-primary fa riferimento a color-gray-50 e color-action-primary fa riferimento a color-blue-400 (leggermente più chiaro per garantire il contrasto sugli sfondi scuri). Cambiano solo le mappature semantiche: la tavolozza primitiva e tutti i componenti rimangono invariati.

Il Brand A usa il blu come colore primario (color-action-primary: {color-blue-500}). Il Brand B usa il verde (color-action-primary: {color-green-500}). Il componente pulsante legge var(--color-action-primary) e non sa quale brand sia attivo. Gli override del brand modificano solo le mappature dei token semantici, mai il codice dei componenti.

Le proprietà personalizzate CSS rendono semplice cambiare tema a runtime. Memorizzare il tema corrente in un attributo data: document.documentElement.setAttribute('data-theme', 'dark'). Le regole CSS sovrascrivono i token semantici sotto [data-theme="dark"]. Il browser risolve immediatamente tutti i riferimenti var() nei nuovi valori, senza bisogno di eseguire nuovamente il rendering con JavaScript.

Per brand diversi distribuiti separatamente, usare la gestione dei temi in fase di build: generare file CSS di token distinti per ogni brand con Style Dictionary e caricare il CSS del brand corretto all'avvio dell'applicazione. Questo approccio è appropriato quando il brand viene determinato al momento della distribuzione (domini, sottodomini o istanze white-label diversi), non durante l'interazione dell'utente.

Un sistema multi-brand e multi-tema richiede una matrice a due dimensioni: Brand A chiaro, Brand A scuro, Brand B chiaro, Brand B scuro. Le proprietà personalizzate CSS gestiscono questa situazione in modo elegante con selettori annidati: [data-brand="a"][data-theme="dark"] sovrascrive i token semantici per quella specifica combinazione. Quattro combinazioni richiedono quattro blocchi CSS, non quattro codebase.

Con l'evoluzione del design system, i token vengono aggiunti, rinominati o rimossi. Gestire i token sotto controllo versione nello stesso repository del codice. Quando si depreca un token, mantenere il vecchio nome come alias che punta al nuovo nome per un ciclo di rilascio, aggiungere un commento di deprecazione e aggiornare il codice che lo utilizza. Coordinare le modifiche ai token tra design e sviluppo tramite un changelog strutturato.

La governance definisce chi può aggiungere o modificare i token e quale processo di revisione è richiesto. I token primitivi richiedono l'approvazione del team di design. I token semantici richiedono la revisione sia del design sia dell'ingegneria. I token dei componenti possono essere gestiti dal responsabile del componente. In assenza di questa governance, emergono token duplicati e la garanzia della "single source of truth" viene meno.

Perché i componenti dovrebbero fare riferimento ai token semantici anziché ai token primitivi?

I temi cambiano le modalità cromatiche all'interno di un brand; i brand sono identità visive diverse. I token primitivi costituiscono la palette grezza, mentre i token semantici esprimono il significato e consentono la tematizzazione. I componenti usano solo token semantici. La modalità scura e gli override del brand modificano solo le mappature dei token semantici: i componenti restano invariati. La tematizzazione a runtime usa proprietà personalizzate CSS con selettori [data-theme]; il branding a build time genera un CSS separato per ogni brand. La governance e il versioning dei token mantengono il sistema coerente mentre si evolve.