Creare color token scalabili per i design system

Il primo design system che ho costruito è stato pubblicato con esattamente un errore che ha perseguitato tutto ciò che è venuto dopo: usavamo blue-500 direttamente nel codice dei componenti. I pulsanti erano blue-500. I link erano blue-500. Il focus ring era blue-500. Sembrava pulito e DRY. Poi il marketing ha fatto un rebranding dal blu al verde acqua, e abbiamo passato due sprint a rincorrere ogni riferimento esadecimale letterale in quaranta repository — perdendone comunque qualcuno, perché alcuni erano stati scritti a mano come #3B82F6 anziché come la variabile. Tutto quell'episodio avrebbe potuto essere una modifica di una riga. Il motivo per cui non lo è stato è l'intera ragione per cui esistono i color token dei design system.

Un color token è semplicemente un riferimento con un nome a un valore di colore. Ma il valore dei token non sta nella denominazione — sta nei livelli di denominazione, e nell'essere disciplinati su quale livello un componente è autorizzato a toccare. Azzecca la stratificazione e un rebranding, un lancio della dark mode o una correzione di contrasto diventano una modifica piccola e contenuta. Sbagliala e ti ritrovi con la pulizia su quaranta repository.

Tre livelli: primitivo, semantico, componente

Il modello mentale che ha retto in ogni sistema su cui ho lavorato è una gerarchia a tre livelli. Ogni livello fa riferimento a quello sottostante, e ai componenti è sempre e solo consentito consumare il livello superiore.

• I token primitivi (chiamati anche di base o globali) sono la tua palette grezza. blue-500: #3B82F6, gray-900: #111827, red-600: #DC2626. Descrivono cos'è il colore e nulla riguardo a dove viene usato. Un primitivo non dovrebbe mai comparire direttamente nel CSS di un pulsante.
• I token semantici descrivono l'intento — il lavoro che il colore svolge. color-text-primary, color-bg-surface, color-border-default, color-action-primary, color-feedback-error. Un token semantico punta a un primitivo: color-action-primary → blue-600.
• I token di componente sono opzionali e descrivono una parte specifica di un componente specifico. button-primary-bg, card-border-color, input-focus-ring. Puntano a token semantici, non a primitivi.

Ecco la regola che fa funzionare l'intera cosa, e quella che la maggior parte dei team salta: i componenti fanno riferimento a token semantici o di componente, mai a primitivi. Nel momento in cui un pulsante scavalca il livello semantico per afferrare direttamente blue-500, hai reintrodotto il problema dei quaranta repository un componente alla volta.

Perché preoccuparsi del livello semantico intermedio? Perché è la cucitura in cui avviene il theming. Quando passi alla dark mode, non ridipingi ogni componente — ripunti qualche decina di token semantici a primitivi diversi. I componenti non sanno che è cambiato qualcosa. Quell'indirezione è la singola decisione a più alta leva dell'intero sistema.

Costruisci la scala prima di nominare qualsiasi cosa

Prima delle semantiche, ti servono primitivi a cui valga la pena puntare — e questo significa una scala numerica, convenzionalmente da 50 a 950. La convenzione resa popolare da Tailwind (50, 100, 200 … 900, 950) è di fatto diventata il default di settore, e vale la pena adottarla solo perché i nuovi sviluppatori si sentano a casa. 50 è la tinta più chiara, 500 è all'incirca la tinta di marca pura, 950 è quasi nero.

L'errore che fanno i principianti è generare una scala schiarendo e scurendo ingenuamente in sRGB — aggiungendo bianco per le tinte chiare, nero per quelle scure. Ottieni mezzitoni fangosi e gradini che non sembrano uniformemente distanziati, perché la luminosità percepita non è lineare in RGB. Un 400 finisce per apparire quasi identico a un 500, mentre da 700 a 800 c'è un dirupo. La soluzione è distanziare i gradini in un modello percettivo. Gli strumenti che lavorano in HSL ti portano gran parte della strada; quelli che usano OKLCH (ora ben supportato in CSS) ti portano il resto, perché OKLCH mantiene la luminosità percepita coerente al variare della tinta. Se vuoi valutare a occhio tinte e sfumature armoniose in fretta mentre prototipi una scala, il generatore di palette di colori è un modo veloce per vedere le relazioni tra le tinte prima di fissarle nei token.

Qualche regola guadagnata sul campo per le scale:

• Àncora la tua scala al contrasto, non all'estetica. Decidi presto quale gradino è il tuo colore "testo su bianco" e verifica che raggiunga i rapporti di cui hai bisogno. Nella maggior parte delle rampe neutre, è a 600 o 700 che superi 4.5:1 sul bianco. Saperlo ti permette di scrivere regole semantiche come "il testo del corpo usa gray-700" con sicurezza.
• Mantieni lo stesso numero di gradini su ogni tinta. Se il blu ha un 950 e il verde si ferma a 900, le tue mappature semantiche diventano irregolari e la dark mode diventa un incubo di casi speciali.
• Non sovra-generare. Undici gradini per tinta sono più che sufficienti. Ho visto team pubblicare scale a venti gradini dove metà dei gradini sono visivamente indistinguibili e nessuno usa mai 425.

Denominazione: descrivi il lavoro, non l'aspetto

Il singolo principio di denominazione più importante è questo: i token semantici e di componente dovrebbero nominare lo scopo, mai l'aspetto. Un token chiamato color-text-red si rompe il giorno in cui il testo di errore diventa arancione — il nome ora mente. Un token chiamato color-feedback-error sopravvive a quel cambiamento intatto, perché "error" resta vero indipendentemente da quale rosso (o arancione) si risolva.

Una struttura di denominazione che scala si legge dalla categoria generale al modificatore specifico, perché si ordina e si controlla in modo pulito:

• category-property-variant-state
• color-bg-surface, color-bg-surface-raised, color-bg-surface-sunken
• color-action-primary, color-action-primary-hover, color-action-danger
• color-text-primary, color-text-secondary, color-text-disabled, color-text-on-action

Quest'ultimo — color-text-on-action — è un token che la gente dimentica e di cui poi si pente. Quando il tuo colore d'azione è un blu saturo, il testo su quel blu deve essere bianco o quasi bianco, e quell'abbinamento non ha nulla a che fare con color-text-primary. Rendilo un token esplicito o vedrai gli sviluppatori scrivere a mano #FFFFFF sui pulsanti per poi aprire bug di accessibilità quando qualcuno introduce un'azione "warning" giallo chiaro.

Per i primitivi, nominare l'aspetto è corretto e atteso — blue-500 dovrebbe descrivere cos'è, perché è proprio quello il senso del livello primitivo. La regola "descrivi l'intento" si applica al di sopra di esso.

Implementazione con le CSS custom properties

Le CSS custom properties sono la casa naturale dei token perché si propagano nella cascata e possono essere sovrascritte dal contesto — che è esattamente come funziona il theming. Lo schema prevede due livelli di variabili: i primitivi definiti una volta sola alla radice, le semantiche definite alla radice e ridefinite sotto un selettore di tema.

Definisci i primitivi globalmente — --blue-600: #2563EB, --gray-900: #111827, e così via. Poi mappa le semantiche su di essi: --color-action-primary: var(--blue-600) e --color-text-primary: var(--gray-900). I componenti leggono sempre e solo le variabili semantiche: color: var(--color-text-primary). Non nominano mai un primitivo e non nominano mai un codice esadecimale.

In Tailwind v4 questo si mappa in modo pulito sulla nuova direttiva @theme, che sia dichiara i token sia genera utility da essi, esponendo ogni token come variabile CSS a runtime. Definisci --color-text-primary: var(--color-gray-900) dentro @theme, usi text-primary nel markup e sovrascrivi la variabile sotto un selettore .dark nel tuo base layer. La documentazione ufficiale sulle theme variables di Tailwind copre i meccanismi, e la stessa disciplina a due livelli si applica indipendentemente dal framework.

La dark mode è un problema di rimappatura dei token, non un problema di colore

Il motivo per cui il livello semantico si guadagna il suo posto è che la dark mode diventa quasi banale una volta che esiste. Non tocchi un singolo componente. Sovrascrivi i token semantici all'interno di uno scope .dark (o [data-theme="dark"]) così che si risolvano in primitivi diversi.

In light mode, --color-bg-surface: var(--white) e --color-text-primary: var(--gray-900). In dark mode, sotto il selettore .dark, --color-bg-surface: var(--gray-900) e --color-text-primary: var(--gray-100). Ogni componente che legge color-bg-surface si capovolge automaticamente, perché è la cascata a fare il lavoro.

Due cose che fregano la gente qui:

• Non limitarti a invertire la scala. Testo bianco puro su nero puro (#000 su #FFF invertito) è aspro e causa alonatura — quel bagliore sbavato attorno al testo sugli schermi OLED. Le superfici scure dovrebbero essere un grigio scuro come da #121212 a #1A1A1A, e il tuo testo più chiaro un bianco sporco morbido anziché #FFFFFF. È per questo che la tua scala ha bisogno di un vero 950 e 50 anziché nero e bianco letterali agli estremi.
• Desatura gli accenti per gli sfondi scuri. Un blue-600 che appare sicuro sul bianco può vibrare in modo fastidioso su una superficie quasi nera. I temi scuri di solito puntano il loro token d'azione a un gradino più chiaro e leggermente meno saturo — blue-400 invece di blue-600. Poiché si tratta di rimappare un solo token, puoi regolarlo globalmente in pochi secondi.

Le insidie che si rompono davvero su larga scala

Dopo abbastanza rebranding e lanci di temi, le modalità di fallimento fanno rima:

• Far trapelare i primitivi nei componenti. Il peccato originale. Fai un lint per questo — una regola che vieta i nomi dei token primitivi e gli esadecimali grezzi nei file dei componenti vale la pena di essere scritta il primo giorno.
• Token semantici che nascondono di soppiatto un valore. color-blue-action è un primitivo travestito da semantico. Se il nome contiene una tinta, non è davvero semantico, e si romperà al rebranding.
• Saltare il livello semantico "per andare veloci". I componenti legati direttamente ai primitivi sembrano andare bene fino al tuo primo tema. Poi ti ritrovi a fare refactoring sotto la pressione delle scadenze — il momento più costoso per farlo.
• Contrasto testato solo in light mode. Un abbinamento che passa 4.5:1 sul bianco può fallire su una superficie scura, e viceversa. Ogni coppia semantica testo-su-sfondo va verificata in ogni tema. Le soglie WCAG sono 4.5:1 per il testo normale e 3:1 per il testo grande e i componenti di interfaccia, secondo la guida W3C sul contrasto WCAG — e il tuo sistema di token è dove dovresti integrare quelle garanzie, non dove dovresti scoprire le violazioni.
• Troppi token. Un sistema con quattrocento token semantici è inutilizzabile quanto uno con quattro. Se due token si risolvono sempre nello stesso valore e lo faranno sempre, sono un token solo. Aggiungi specificità solo quando compare una divergenza reale.

Il riassunto onesto è che i token non prendono le decisioni di colore al posto tuo — rendono le decisioni di colore economiche da cambiare. La struttura è ciò che ti compra la possibilità di fare un rebranding di venerdì, pubblicare la dark mode in uno sprint e correggere un bug di contrasto in una riga invece che in quaranta repository. Spendi i tuoi sforzi sul livello semantico e sulla denominazione, mantieni i componenti onesti su quale livello toccano, e il sistema assorbirà cambiamenti che non puoi nemmeno ancora prevedere.