“Puoi cambiare il blu primario con un blu leggermente più scuro?” In una codebase legacy, questa richiesta costa € 5.000. Perché? Perché “#3b82f6” è codificato in 400 file CSS, 20 file JS e 5 modelli HTML. In una codebase moderna, questa richiesta costa € 0. Aggiorni il Design Token in Figma e si propaga automaticamente a iOS, Android e Web.

Perché Maison Code ne parla

In Maison Code Paris, agiamo come la coscienza architettonica dei nostri clienti. Spesso ereditiamo stack “moderni” costruiti senza una comprensione fondamentale della scala.

Discutiamo di questo argomento perché rappresenta un punto di svolta critico nella maturità ingegneristica. Implementarlo correttamente differenzia un MVP fragile da una piattaforma resiliente di livello aziendale.

Cosa sono i token di design?

I Design Token sono gli “atomi” del visual design. Sono coppie chiave-valore indipendenti dalla piattaforma.

Legacy: colore: #000000;
Token: color: var(--color-foreground);

La gerarchia dei token

Non appiattiamo semplicemente tutto. Utilizziamo una gerarchia a 3 livelli per garantire il significato semantico.

1. Token primitivi (globali)

Valori grezzi. Non devono mai essere utilizzati direttamente nell’interfaccia utente.

blu-500: #3b82f6
grigio-900: #111827
spacer-4: 16px

2. Token semantici (alias): orientati allo scopo.

colore-primario: {blu-500}
color-surface: {gray-900} (fondamentale per la modalità oscura)
spacing-card-padding: {spacer-4}

3. Token componenti (specifici)

Sostituzioni guidate dal contesto.

button-bg-primary: {color-primary}
card-bg: {color-surface}
input-border-error: {color-destructiva}

Il flusso di lavoro: da Figma a codice

Trattiamo Figma come la “fonte della verità” per la progettazione, proprio come trattiamo Git come la fonte della verità per il codice. Utilizziamo la funzione Variabili in Figma combinata con il plugin “Tokens Studio”.

Passaggio 1: esportazione dei token

Esportiamo tokens.json. Questo file è l’unica fonte di verità.

{
  "globale": {
    "colori": {
       "blu": { "500": { "valore": "#3b82f6" } }
    }
  },
  "semantico": {
    "primario": { "valore": "{colors.blue.500}" },
    "on-primary": { "value": "{colors.white}" }
  }
}

Passaggio 2: trasformazioni (dizionario degli stili)

JSON è inutile per iOS (Swift) o Android (XML). Utilizziamo il Dizionario di stile (di Amazon) per trasformare il JSON in artefatti specifici della piattaforma. La pipeline di compilazione (npm run build:tokens) è simile alla seguente:

“sirena”. grafico LR Figma[Variabili Figma] —>|Plugin| JSON[token.json] JSON —>|CI/CD| SD[Dizionario di stile]

SD -->|Trasforma| CSS[Variabili CSS]
SD -->|Trasforma| TS[Configurazione vento in coda]
SD -->|Trasforma| Swift[Color.swift]
SD -->|Trasforma| XML[colori.xml]


### Passaggio 3: consumo in Tailwind
Per la nostra vetrina headless (creata con [Atomic Design](/it/blog/tech-atomic-design-it)), mappiamo questi token a **Tailwind CSS**.
In `tailwind.config.js` non codifichiamo i valori. Leggiamo gli artefatti della build.

```javascript
// tailwind.config.js
const token = require('./build/tokens.js');

modulo.esporta = {
  tema: {
    colori: {
      primario: 'var(--color-primary)', // Mappa su CSS var
      sfondo: 'var(--colore-sfondo)',
    },
    estendere: {
      borderRadius: tokens.radius,
      fontFamily: tokens.tipografia,
      spaziatura: tokens.spacing
    }
  }
}

Ciò significa che non scriviamo mai class="bg-[#3b82f6]". Scriviamo class="bg-primary". Se il marchio viene rebrandizzato in Rosso, cambiamo il token “primario” -> “rosso-500” in Figma. L’intero sito si aggiorna immediatamente dopo la distribuzione.

Architettura in modalità oscura

La modalità oscura non riguarda l‘“inversione dei colori”. Si tratta di scambio di token. Definiamo una mappa “chiara” e una mappa “scura”. Condividono gli stessi nomi semantici (--color- background), ma puntano a primitive diverse.

Implementazione CSS

:radice {
  /* Predefinito (Leggero) */
  --colore-sfondo: var(--bianco);
  --colore-testo: var(--nero);
  --color-border: var(--gray-200);
}

[tema-dati="scuro"] {
  /* Sostituisci */
  --colore-sfondo: var(--nero);
  --colore-testo: var(--bianco);
  --color-border: var(--gray-800);
}

Poiché Tailwind utilizza il nome semantico, la classe bg- background funziona in entrambe le modalità. È bianco in modalità luce e nero in modalità scura. Non sono necessarie classi aggiuntive (dark:bg-black) nei componenti React. Ciò riduce significativamente la dimensione del pacchetto.

Sistemi Multimarca (Tematizzazione)

Per le agenzie che gestiscono più negozi (ad esempio, GAP, Old Navy, Banana Republic), i sistemi di token consentono di riutilizzare la stessa base di codice React. Basta caricare un file tokens.css diverso.

Gap: primario = Blu, raggio = 4px.
Vecchia Marina: primaria = Marina, raggio = 8px. Il codice del componente <Button /> rimane identico: <button className="bg-primary round-radius">. Questa è la “etichettatura bianca” su larga scala.

Gettoni tipografici

I token di design non sono solo colori.

Dimensione: testo-xl -> 1.25rem
Peso: font-bold -> 700
Altezza della linea: leading-tight -> 1.25
Spaziatura lettere: tracking-wide -> 0.025em

Codifichiamo “Typescales” (Terza maggiore, Quarta perfetta) nei token per garantire l’armonia matematica. Se imposti manualmente font-size: 17px, rompi il ritmo. I token rafforzano il sistema.

9. Visualizzazione dei token: il componente aggiuntivo Storybook

I token sono astratti. Gli sviluppatori devono vederli. Costruiamo un componente aggiuntivo Storybook personalizzato che mostra tutti i token in tempo reale.

Tavolozza dei colori: griglie di campioni di colore con i nomi dei token.
Scala tipografica: testo reso in ciascuna dimensione del carattere.
Ombre: riquadri che mostrano i livelli di elevazione. Questa serve come “documentazione vivente”. Se uno sviluppatore ha bisogno di un colore, non apre Figma. Aprono Storybook, cercano “Primaria” e copiano il nome della classe.

10. Il contesto “Fornitore di temi”.

In React, come si cambiano i temi in modo efficiente? Non passare oggetti di scena. Utilizza variabili CSS + contesto. “tsx const ThemeContext = createContext({ tema: ‘luce’, attiva/disattiva: () => {} });

funzione di esportazione ThemeProvider({ figli }) { const [tema, setTheme] = useState(‘light’);

useEffect(() => { document.documentElement.dataset.theme = tema; }, [tema]);

return <ThemeContext.Provider value={{ theme, setTheme }}>{children}</ThemeContext.Provider>; }

Questo aggiorna l'attributo `data-theme` sul tag `<html>`.
Le variabili CSS vengono ricalcolate istantaneamente.
Il React Tree **non** viene ri-renderizzato (ad eccezione del pulsante Attiva/disattiva stesso).
Questo è fondamentale per le prestazioni.

## 11. Manutenzione e governance
"Da un grande potere derivano grandi responsabilità."
Se un Junior Designer cerca di cambiare il blu "primario", potrebbe violare la conformità all'accessibilità nell'app.
Implementiamo **CI Checks** (Style Dictionary Linting) per i token.

### Controlli automatizzati
1. **Controllo del contrasto**: assicurati che il testo "su primario" abbia un contrasto di 4,5:1 rispetto allo sfondo "primario". In caso contrario, la compilazione fallisce.
2. **Convenzione di denominazione**: rifiuta "blue-final-v2". Applicare "blu-500".
3. **Token orfani**: avvisa se un token definito non viene mai utilizzato nella logica dell'interfaccia utente.

## 12. Aliasing dei token per l'accessibilità

L'accessibilità non è solo contrasto cromatico. È la preferenza dell'utente.
Alcuni utenti necessitano della "Modalità contrasto elevato".
Alcuni utenti necessitano del "Movimento ridotto".
Mappiamo i token a queste query multimediali.
`durata-movimento: { var(--motion-fast) }`
`@media (preferisce-movimento ridotto) { --motion-fast: 0ms; }`
La tokenizzazione del movimento ci consente di rispettare il desiderio dell'utente di disattivare le animazioni a livello globale, senza riscrivere i componenti CSS.

## 13. Token mobile e Web

iOS utilizza i punti. Web utilizza Rem. Android utilizza DP.
Un’esportazione ingenua fallisce.
Utilizziamo le **trasformazioni del dizionario di stile** per gestire i calcoli.
`spacing.4` (16px) -> iOS `16pt` -> Android `16dp`.
Gestiamo anche le **Convenzioni di denominazione**:
* Web: `kebab-case` (`--color-primary`)
* iOS: `camelCase` (`colorPrimary`)
* Android: `snake_case` (`color_primary`)
Ciò garantisce che gli sviluppatori si sentano a casa sulla loro piattaforma.

## 14. Conclusione
I Design Token sono le "API" tra Design e Ingegneria.
Disaccoppiano il *valore* (codice esadecimale) dall'*intento* (colore primario).
Per una Maison, dove le linee guida del marchio sono sacre, i Design Token sono l'unico modo per garantire la fedeltà al 100% su ogni touchpoint digitale.
Smetti di scrivere CSS. Inizia a scrivere Systems.



<hr style="margin: 1rem 0" />

**[Assumi i nostri architetti](/contact)**.