Design token: un’unica fonte di verità per colore e tipografia

I design token sono valori con nome per ogni decisione di design che un brand ripete: colori, caratteri, dimensioni del testo, spaziature, raggi degli angoli, ombre e tempi di animazione. Invece di scrivere #5b21b6 in un foglio di stile, in un file Figma e in un’app iOS, definisci color.brand.700 una volta, in un file, e da lì generi il formato di ogni piattaforma. Cambia il token e ogni prodotto si aggiorna insieme. Quell’unica fonte di verità è il punto di tutto.

Che aspetto ha un design token

Un token ha un nome, un valore e un tipo. Il formato pubblicato dal W3C Design Tokens Community Group li scrive come JSON, con proprietà che iniziano con il simbolo del dollaro così non possono entrare in conflitto con i nomi dei gruppi.

{
  "color": {
    "violet": {
      "100": { "$type": "color", "$value": "#ede9fe" },
      "500": { "$type": "color", "$value": "#8b5cf6" },
      "700": { "$type": "color", "$value": "#6d28d9" },
      "900": { "$type": "color", "$value": "#4c1d95" }
    },
    "ink": { "$type": "color", "$value": "#14121f" },
    "paper": { "$type": "color", "$value": "#faf8ff" }
  },
  "font": {
    "heading": { "$type": "fontFamily", "$value": ["Fraunces", "Georgia", "serif"] },
    "body": { "$type": "fontFamily", "$value": ["Inter", "system-ui", "sans-serif"] }
  },
  "radius": {
    "control": { "$type": "dimension", "$value": { "value": 10, "unit": "px" } }
  },
  "duration": {
    "quick": { "$type": "duration", "$value": { "value": 160, "unit": "ms" } }
  }
}

Token primitivi, semantici e di componente

Un elenco piatto di colori è una palette, non un sistema. La struttura che regge negli anni ha tre livelli, ciascuno che rimanda a quello sotto. I componenti non toccano mai i valori grezzi; chiedono uno scopo.

{
  "color": {
    "action": {
      "primary": { "$type": "color", "$value": "{color.violet.700}" },
      "primary-hover": { "$type": "color", "$value": "{color.violet.900}" }
    },
    "text": {
      "default": { "$type": "color", "$value": "{color.ink}" },
      "on-action": { "$type": "color", "$value": "{color.paper}" }
    },
    "surface": {
      "page": { "$type": "color", "$value": "{color.paper}" },
      "tint": { "$type": "color", "$value": "{color.violet.100}" }
    }
  }
}

Molti team si fermano a due livelli, primitivo e semantico, e aggiungono token di componente solo dove un componente differisce davvero. Così il file resta abbastanza piccolo da essere compreso.

Nominare i design token perché durino

I nomi sopravvivono ai valori. Un token chiamato color.purple si rompe il giorno in cui il brand diventa verde acqua; uno chiamato color.action.primary sopravvive. Nomina i token semantici per ruolo e tieni i nomi primitivi descrittivi del valore.

Scegli uno schema, come categoria, poi ruolo, poi variante, poi stato, e scrivilo nella tua guida di stile del brand. La coerenza nei nomi conta più dello schema che scegli.

Dal file dei token al CSS e alle app

Il file dei token non viene distribuito così com’è. Un passaggio di build lo trasforma in ciò che serve a ogni piattaforma. Style Dictionary è lo strumento open source più diffuso per questo, e altri leggono lo stesso formato. Per il web, l’output sono di solito proprietà personalizzate CSS.

:root {
  --color-violet-100: #ede9fe;
  --color-violet-700: #6d28d9;
  --color-violet-900: #4c1d95;
  --color-ink: #14121f;
  --color-paper: #faf8ff;

  --color-action-primary: var(--color-violet-700);
  --color-text-default: var(--color-ink);
  --color-surface-page: var(--color-paper);

  --font-heading: Fraunces, Georgia, serif;
  --radius-control: 10px;
  --duration-quick: 160ms;
}

.button {
  background: var(--color-action-primary);
  color: var(--color-paper);
  border-radius: var(--radius-control);
  transition: background var(--duration-quick) ease;
}

Se usi Tailwind v4, il blocco @theme è già un livello di token: ogni variabile --color-* diventa utility. Colori Tailwind mostra come collegarvi una rampa di token. Lo stesso file può produrre anche costanti Swift e risorse Android, ed è qui che i token si ripagano nei team multipiattaforma.

Dark mode e brand multipli

Poiché i componenti leggono solo token semantici, un tema è solo un diverso insieme di valori per quel livello. La dark mode ridefinisce color.text.default e color.surface.page; un secondo brand ridefinisce color.action.primary. Nei componenti non cambia nulla.

@media (prefers-color-scheme: dark) {
  :root {
    --color-text-default: #e9e5f5;
    --color-surface-page: #0b0a14;
    --color-action-primary: var(--color-violet-500);
  }
}

[data-brand="harbour"] {
  --color-action-primary: #0f766e;
}

Introdurre i design token

1. 1

   Verifica ciò che esiste

   Raccogli ogni colore, dimensione del testo e valore di spaziatura in uso. Aspettati duplicati che differiscono per una cifra esadecimale.

2. 2

   Definisci i primitivi

   Riducili a scale chiare. Costruire rampe di colore in OKLCH mantiene uniformi i passi; vedi OKLCH spiegato.

3. 3

   Aggiungi il livello semantico

   Nomina i ruoli: testo, superficie, bordo, azione, feedback. Fai puntare ciascuno a un primitivo.

4. 4

   Automatizza la build

   Genera CSS e risorse delle app dal file durante la build, mai a mano.

5. 5

   Proteggilo

   Controlla con il linter i valori esadecimali grezzi nei componenti, così il nuovo codice usa i token fin dal primo giorno.

I token mantengono coerente il prodotto, ma i brand divergono anche nelle grafiche fatte fuori da esso: post, slide, banner. Un kit del brand di Gradiently contiene le stesse decisioni, le tue palette di colori, i font per titoli e testo, i logo e la voce, così i design fatti nello Studio coincidono. E poiché Gradiently funziona dentro ChatGPT, Claude e altri assistenti che supportano server MCP remoti, un assistente con una chiave API limitata può creare design coerenti con il brand dallo stesso spazio di lavoro. Coerenza del brand tratta l’abitudine più ampia.