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

[Canonical HTML page](https://gradiently.design/it/guide/design-tokens)

Un colore di brand che vive in quaranta file finirà per divergere. Un token vive in un solo posto e ogni piattaforma lo legge da lì. Ecco come strutturare i design token, nominarli perché durino e portarli nel codice e negli strumenti di design.

## The short version

- I design token sono valori con nome e indipendenti dalla piattaforma per le decisioni di design, come colori, famiglie di font, dimensioni, spaziature, raggi, ombre e tempi di movimento.
- La maggior parte dei sistemi di token usa tre livelli: i token primitivi contengono i valori grezzi, i token semantici descrivono uno scopo e i token di componente applicano gli scopi a parti specifiche.
- Il formato del W3C Design Tokens Community Group salva i token come JSON con le proprietà $value e $type e richiama altri token con le parentesi graffe.
- Strumenti come Style Dictionary trasformano un solo file di token in proprietà personalizzate CSS, JavaScript e risorse iOS e Android.
- Dark mode e brand multipli diventano una questione di scambiare i valori dietro i token semantici, mentre i componenti restano invariati.

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](https://www.w3.org/community/design-tokens/) li scrive come JSON, con proprietà che iniziano con il simbolo del dollaro così non possono entrare in conflitto con i nomi dei gruppi.

```json
{
  "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 nel formato del community group. I gruppi si annidano liberamente; il percorso, come color.violet.700, diventa il nome del token.

- color.violet.100: #ede9fe
- color.violet.500: #8b5cf6
- color.violet.700: #6d28d9
- color.violet.900: #4c1d95
- color.ink: #14121f
- color.paper: #faf8ff

I token di colore qui sopra come campioni. Sono ingredienti grezzi: nulla dice ancora quale sia un pulsante o un titolo.

## 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.

| Livello | Nome di esempio | Valore | Cambia quando |
| --- | --- | --- | --- |
| Primitivo | `color.violet.700` | `#6d28d9` | La palette viene ridisegnata |
| Semantico | `color.action.primary` | `{color.violet.700}` | Un ruolo passa a un altro colore |
| Semantico | `color.text.default` | `{color.ink}` | Dark mode, un nuovo brand |
| Componente | `button.primary.background` | `{color.action.primary}` | Un componente ha bisogno di un’eccezione |

I riferimenti tra parentesi graffe sono alias. Cambia color.violet.700 e ogni token che lo richiama lo segue.

```json
{
  "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}" }
    }
  }
}
```

I token semantici descrivono a cosa serve un colore. È il livello in cui dovrebbero parlare designer e ingegneri.

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.

### Nomi che invecchiano male

- `color.purple` usato per i pulsanti
- `text.dark`, che è chiaro in dark mode
- `spacing.16` usato come regola di layout
- `blue2`, `blueNew`, `blueFinal`
- `hero.gradient.lisa` che porta il nome di una persona

### Nomi che durano

- `color.action.primary`
- `color.text.default`
- `space.section` che rimanda a `{space.16}`
- Una scala numerata come `blue.100` fino a `blue.900`
- `gradient.hero` con i suoi stop come token

Scegli uno schema, come categoria, poi ruolo, poi variante, poi stato, e scrivilo nella tua [guida di stile del brand](https://gradiently.design/it/guide/brand-style-guide). 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.

```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;
}
```

Output generato. Gli alias diventano riferimenti var(), così il livello semantico sopravvive nel browser. Vedi [variabili CSS per i temi](https://gradiently.design/it/guide/css-custom-properties-theming).

Se usi Tailwind v4, il blocco `@theme` è già un livello di token: ogni variabile `--color-*` diventa utility. [Colori Tailwind](https://gradiently.design/it/guide/tailwind-colors) 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.

```css
@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;
}
```

Due sovrascritture, nessuna modifica ai componenti. Anche i gradienti meritano valori scuri propri; [gradienti in dark mode](https://gradiently.design/it/guide/dark-mode-gradients) spiega come regolarli.

> **Token negli strumenti di design** Le variabili di Figma supportano collezioni e modalità, che corrispondono bene ai token primitivi e semantici e ai temi chiaro e scuro. Tieni il file dei token come fonte e sincronizza verso lo strumento di design, non il contrario, o i due saranno in disaccordo entro un mese.

## Introdurre i design token

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. **Definisci i primitivi** Riducili a scale chiare. Costruire rampe di colore in OKLCH mantiene uniformi i passi; vedi [OKLCH spiegato](https://gradiently.design/it/guide/oklch-explained).
3. **Aggiungi il livello semantico** Nomina i ruoli: testo, superficie, bordo, azione, feedback. Fai puntare ciascuno a un primitivo.
4. **Automatizza la build** Genera CSS e risorse delle app dal file durante la build, mai a mano.
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](https://gradiently.design/it/guide/brand-consistency) tratta l’abitudine più ampia.

## FAQ

### Cosa sono i design token?

Valori con nome per decisioni di design come colori, font, spaziature, raggi e movimento, salvati in un unico file neutro rispetto alla piattaforma e trasformati in CSS, codice delle app e variabili degli strumenti di design.

### Che differenza c’è tra token primitivi e semantici?

I token primitivi contengono valori grezzi, come `color.violet.700`. I token semantici descrivono uno scopo, come `color.action.primary`, e puntano a un primitivo.

### I design token sono la stessa cosa delle variabili CSS?

No. I token sono la fonte, salvati in un formato neutro come JSON; le proprietà personalizzate CSS sono un output generato da essi, insieme agli output per altre piattaforme.

### Esiste un formato standard per i design token?

Il W3C Design Tokens Community Group pubblica un formato JSON che usa $value, $type e alias tra parentesi graffe, leggibile da strumenti come Style Dictionary.

### Come gestiscono la dark mode i design token?

I componenti leggono token semantici, e un tema scuro fornisce valori diversi per quei token, quindi i componenti non richiedono modifiche.