Token di colore in CSS e Tailwind
· Lettura di 3 min
Come dare un nome alle variabili di colore e organizzarle per ruolo, collegare tema chiaro e scuro in CSS e usare gli stessi token in un tema Tailwind v4.
I valori esadecimali scritti a mano e sparsi in un foglio di stile sono il motivo principale per cui cambiare colori è doloroso. Un rebranding, l’aggiunta del tema scuro o la correzione di un problema di contrasto diventano un cerca e sostituisci su centinaia di righe. I token di colore, cioè variabili con un nome che descrive a cosa serve un colore, risolvono il problema. Questa guida mostra come strutturarli in CSS puro e usare gli stessi token in Tailwind.
Due livelli: primitivi e ruoli
Un impianto solido separa quali sono i colori da come vengono usati.
I token primitivi sono la palette grezza, con nomi basati su tonalità e livello. Non compaiono mai direttamente negli stili dei componenti.
:root {
--blue-100: #E3E8FF;
--blue-500: #3D5AFE;
--blue-700: #2638C4;
--sand-50: #F7F5F0;
--ink-900: #1D2433;
}I token semantici (di ruolo) descrivono un compito nell’interfaccia e puntano a un primitivo oppure contengono un valore proprio. I componenti usano sempre e solo questi.
:root {
--color-bg: var(--sand-50);
--color-surface: #EFECE4;
--color-border: #DAD6CC;
--color-text: var(--ink-900);
--color-muted: #5C6475;
--color-primary: var(--blue-500);
--color-on-primary: #FFFFFF;
--color-accent: #C2410C;
}.button {
background: var(--color-primary);
color: var(--color-on-primary);
}
.card {
background: var(--color-surface);
border: 1px solid var(--color-border);
color: var(--color-text);
}Adesso il pulsante non sa di essere blu. Se il brand passa al verde, cambi una riga. Se una verifica del contrasto fallisce, regoli un token e tutti i componenti si adeguano.
Dai ai token nomi di ruolo, non di aspetto
Nomi come --light-gray o --brand-blue descrivono com’è un colore oggi. Diventano sbagliati appena il valore cambia, e in tema scuro --light-gray conterrebbe un colore scuro. I nomi di ruolo restano veri:
--color-bg,--color-surface,--color-borderper la struttura.--color-texte--color-mutedper i contenuti.--color-primary,--color-accentper l’enfasi.--color-on-primary,--color-on-accentper il testo sopra i colori pieni.- Ruoli di stato facoltativi:
--color-success,--color-warning,--color-danger.
Tieni l’elenco corto. Una dozzina di token di ruolo basta per la maggior parte dei prodotti; aggiungere un token per ogni componente riporta al problema di partenza.
Il tema scuro diventa una serie di nuovi valori
Con i token di ruolo, il tema scuro non è un secondo foglio di stile. Sono gli stessi nomi con valori diversi. Lo schema qui sotto segue l’impostazione di sistema e permette comunque a un interruttore di forzare l’uno o l’altro tema con un attributo data-theme:
@media (prefers-color-scheme: dark) {
:root:not([data-theme="light"]) {
--color-bg: #14161F;
--color-surface: #1C1F2B;
--color-border: #2C3040;
--color-text: #E6E8EF;
--color-muted: #9AA1B2;
--color-primary: #8C9EFF;
--color-on-primary: #14161F;
--color-accent: #FB923C;
}
}
:root[data-theme="dark"] {
/* gli stessi valori, per chi sceglie il tema scuro a mano */
}Nota che il primario scuro è un blu più chiaro e la sua etichetta è scura. I valori scuri vanno scelti, non calcolati per inversione: laguida al tema scuro spiega perché.
I browser moderni supportano anche la funzione light-dark(), che tiene entrambi i valori su una riga. Segue la proprietàcolor-scheme, quindi per funzionare ha bisogno di quella dichiarazione:
:root {
color-scheme: light dark;
--color-bg: light-dark(#F7F5F0, #14161F);
--color-text: light-dark(#1D2433, #E6E8EF);
}Ricava i colori discreti
Superfici e bordi si possono mescolare a partire da sfondo e testo invece di sceglierli a mano. In CSS lo fa color-mix(), e mescolare in OKLCH dà passaggi uniformi e naturali:
:root {
--color-surface: color-mix(in oklch, var(--color-bg) 94%, var(--color-text));
--color-border: color-mix(in oklch, var(--color-bg) 82%, var(--color-text));
}Dato che fanno riferimento ad altri token, si aggiornano da soli in tema scuro. Se il bordo delimita un campo o un altro controllo, verifica che arrivi a 3:1.
Usare i token in Tailwind CSS v4
Tailwind v4 si configura in CSS. Ogni variabile --color-* dichiarata in @theme diventa una serie completa di utility (bg-*, text-*, border-* e così via). Le utility generate leggono la variabile in fase di esecuzione (bg-primary diventa background-color: var(--color-primary)), quindi basta sovrascrivere la variabile per il tema scuro:
@import "tailwindcss";
/* i valori chiari diventano utility: bg-bg, text-text, bg-primary ... */
@theme {
--color-bg: #F7F5F0;
--color-surface: #EFECE4;
--color-text: #1D2433;
--color-muted: #5C6475;
--color-primary: #3D5AFE;
--color-on-primary: #FFFFFF;
--color-accent: #C2410C;
}
/* i valori scuri sovrascrivono le stesse variabili */
@media (prefers-color-scheme: dark) {
:root {
--color-bg: #14161F;
--color-text: #E6E8EF;
--color-primary: #8C9EFF;
--color-on-primary: #14161F;
/* ... */
}
}<button class="bg-primary text-on-primary">Save</button>
<p class="text-muted">Last edited 2 hours ago</p>Non servono varianti dark: su ogni elemento: i token cambiano già da soli, quindi bg-primary è corretto in entrambi i temi.
Tailwind v3
In v3, associa le stesse variabili nel file di configurazione:
// tailwind.config.js
module.exports = {
theme: {
extend: {
colors: {
bg: 'var(--color-bg)',
surface: 'var(--color-surface)',
text: 'var(--color-text)',
primary: 'var(--color-primary)',
accent: 'var(--color-accent)',
},
},
},
}Scrivere i valori in OKLCH
L’esadecimale va bene per conservare i colori, ma quando li modifichi è più facile ragionare in OKLCH. I suoi tre canali sono luminosità, croma (saturazione) e tonalità, e la luminosità corrisponde da vicino a ciò che vede l’occhio. Per ottenere una versione più scura di un colore del brand da usare per il testo, abbassi L e lasci invariato il resto: oklch(55% 0.2 265)diventa oklch(42% 0.2 265). Tutti i principali browser attuali supportano oklch().
Risparmiati la fatica
Ogni palette su Colorset si esporta esattamente con questa struttura: token di ruolo per tema chiaro e scuro come variabili CSS, un tema Tailwind v4, una config di Tailwind v3, SCSS, JSON o design token, in HEX, RGB, HSL o OKLCH. Scegli uno schema che ti piace, apri Esporta e incolla. Il generatore di sfumature crea una scala primitiva 50–950 da qualsiasi colore, se vuoi costruire tu il livello dei primitivi.