Token primitivi e semantici

I token di design sono valori con nome che memorizzano le decisioni visive di un design system: colori, spaziature, dimensioni dei caratteri e altro. Invece di inserire direttamente #3b82f6 in tutto il CSS, gli assegnate un nome e fate riferimento a quel nome ovunque. In questo modo create una singola fonte di verità, facile da aggiornare globalmente. La configurazione di Tailwind è una sede naturale per i token di design, perché genera classi utility a partire da quei valori con nome.

I token primitivi sono valori grezzi e descrittivi a cui non è associato alcun significato semantico. Descrivono che cosa è un valore, non dove viene utilizzato. Tra gli esempi ci sono color.blue.500, spacing.4 o fontSize.lg. La palette di colori predefinita di Tailwind è composta interamente da primitivi: blue-500, red-300 e così via. I primitivi vengono usati per costruire il livello semantico superiore.

I token semantici descrivono lo scopo di un valore, non il suo aspetto grezzo. Invece di blue-500, definireste color.primary. Invece di red-500, definireste color.danger. I token semantici rendono il codebase guidato dall'intento: uno sviluppatore che legge text-primary capisce immediatamente che si tratta del colore principale del brand, indipendentemente da quale sia effettivamente quel colore. Questa astrazione consente di applicare facilmente temi diversi e rinnovare il brand.

Un sistema di token robusto utilizza due livelli: i primitivi alla base e i token semantici al livello superiore. Il livello dei primitivi memorizza ogni valore grezzo che potrebbe essere utilizzato nel design. Il livello semantico associa questi primitivi a nomi legati al loro scopo. Quando cambia il colore del brand, è sufficiente aggiornare una volta il primitivo e ogni token semantico che vi fa riferimento eredita automaticamente la modifica. Questa separazione delle responsabilità è fondamentale per creare sistemi di design scalabili.

Dopo aver registrato i token semantici nella configurazione di Tailwind, questi diventano disponibili come classi di utilità in tutte le utility che accettano un colore. È possibile utilizzare bg-primary, text-primary, border-primary e ring-primary: tutte fanno riferimento allo stesso valore semantico. In questo modo, modificando il colore primario nella configurazione, ogni elemento dell'interfaccia che utilizza queste utility semantiche viene aggiornato immediatamente.

Una buona denominazione dei token segue uno schema coerente che comunica il ruolo e la scala. Una convenzione comune utilizza category.role.modifier; ad esempio color.action.default, color.action.hover e color.action.disabled. Eviti nomi troppo specifici come submit-button-blue: non appena vorrà riutilizzare il token altrove, questi nomi diventeranno limitanti. Scelga nomi che descrivano intento e scala, non l'implementazione visiva.

Il modo più pulito per mantenere l'architettura a due livelli consiste nel definire i primitivi come costanti JavaScript in un file separato e importarli nella configurazione di Tailwind. In questo modo i primitivi rimangono leggibili e riutilizzabili, mentre la configurazione contiene solo le associazioni semantiche. Quando un designer modifica la palette del brand, è sufficiente aggiornare il file dei primitivi: l'associazione semantica rimane invariata.

I token non si limitano ai colori. È possibile definire anche token semantici per la spaziatura e la tipografia. Invece di p-4, un token semantico per la spaziatura chiamato card-padding comunica a cosa serve quello spazio. In Tailwind, questi token vengono aggiunti in theme.extend.spacing e theme.extend.fontSize. In questo modo si garantisce la coerenza dell'interfaccia: ogni card dell'app utilizza la stessa spaziatura p-card, che deve essere modificata una sola volta.

È altrettanto importante definire token per gli stati interattivi. Un pulsante primario richiede token per l'aspetto predefinito, al passaggio del mouse, attivo e disabilitato. Senza token semantici, ogni sviluppatore potrebbe scegliere tonalità leggermente diverse per lo stato hover, creando un'incoerenza visiva. Con token semantici come action-hover e action-disabled, ogni pulsante del sistema reagisce allo stesso modo all'interazione dell'utente.

I token semantici esprimono il loro massimo potenziale se combinati con la modalità scura. Un token primitivo come blue-500 ha un valore fisso, mentre un token semantico come primary può essere associato a primitivi diversi nella modalità chiara e in quella scura. Utilizzare le variabili CSS come collegamento consente di cambiare modalità a runtime senza rigenerare il CSS. Questa tecnica viene approfondita nel modulo sui temi, ma comprendere che i token semantici la rendono possibile è un'importante intuizione architetturale.

Man mano che un sistema di design cresce, le verifiche dei token diventano essenziali. Una verifica controlla se ogni token è effettivamente utilizzato, se alcuni token si sono discostati dallo scopo documentato e se sono emersi nuovi pattern che richiedono un nuovo token. Strumenti come grep o gestori dedicati dei design token possono analizzare la codebase alla ricerca dei token inutilizzati. Rimuoverli mantiene snella la configurazione e riduce il carico cognitivo per i nuovi sviluppatori che entrano nel team.

In questa lezione ha imparato che i token primitivi sono valori grezzi denominati, come color.blue.500, i token semantici associano questi primitivi a nomi basati sull'intento, come color.primary, e l'architettura a due livelli separa ciò che un valore rappresenta dal contesto in cui viene utilizzato. Ora vedremo come le variabili CSS collegano i token di Tailwind al cambio di tema a runtime.