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-border per la struttura.
  • --color-text e --color-muted per i contenuti.
  • --color-primary, --color-accent per l’enfasi.
  • --color-on-primary, --color-on-accent per 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.