# How to build a design system from tokens

A design system starts from tokens: inventory the raw values, name the scales, add semantic roles, then build components. Code comes last.

> Page: https://ui.eneawork.it/blog/come-creare-un-design-system-dai-token
> Markdown: https://ui.eneawork.it/blog/come-creare-un-design-system-dai-token.md

*2026-11-01*

Un design system si costruisce partendo dai token: prima si inventariano i valori grezzi, poi si nominano le decisioni, infine si generano i componenti. Il codice viene dopo, non prima.

Il catalogo EneUI conta 111.985 componenti, 1.556 blocchi e 12.808 icone da 1.472 librerie, letti da /api/stats il 1 novembre 2026. Il conteggio viene da una query all'endpoint e misura i record pubblicati: è il materiale da cui un sistema può partire, non un sistema già pronto.

## Passo 1: contare i valori grezzi

grep -rhoE '#[0-9a-fA-F]{6}' src --include='*.tsx' | sort | uniq -c | sort -rn | head -20

Il comando elenca i colori esadecimali scritti a mano nei componenti e quante volte compaiono. I primi venti valori sono il tuo sistema attuale, anche se nessuno lo ha mai chiamato così.

## Passo 2: nominare le scale

Raggruppa i valori in scale: colore, spazio, raggio, tipografia, ombra. Ogni gradino prende un nome neutro (--gray-100, --space-4) e un valore. Non mescolare ancora semantica e scala.

## Passo 3: aggiungere lo strato semantico

Sopra la scala metti i ruoli: --primary, --muted, --border. I componenti usano solo i ruoli, così un tema scuro cambia i ruoli e non i file. shadcn/ui, progetto MIT, usa questo schema in globals.css, come mostra il record dropdown menu.

## Passo 4: generare il CSS

Scrivi i token una volta in un file JSON e genera il CSS con uno script. Il file JSON è la fonte, il CSS è l'artefatto; se modifichi il CSS a mano, il prossimo build cancella la modifica.

## Passo 5: costruire un componente alla volta

Parti dai componenti più usati: pulsante, campo, dialog, tabella. Ogni componente consuma token, non valori. Nel catalogo EneUI trovi 111.985 componenti e 12.808 icone come riferimento, più 1.556 blocchi già composti.

## Passo 6: documentare la regola, non il file

Per ogni token scrivi quando usarlo e quando no. La documentazione utile è la frase che impedisce l'errore, non la tabella che ripete il valore.

## La limitazione

I token non correggono un componente sbagliato. Se il pulsante ha un contrasto insufficiente, il token semantico propaga lo stesso errore in ogni tema; serve una misura di contrasto, non un'altra variabile.

## Dove continuare

Il tema completo è in come tematizzare shadcn, la misura del contrasto in palette e contrasto misurato. Il confronto tra UI kit e design system è in UI kit, component library o design system.

## FAQ

### Da dove inizio se il progetto ha già componenti?

Dall'inventario: conta i colori e gli spazi scritti a mano e raggruppali in scale. Il sistema nasce dai valori che usi già.

### Token e variabili CSS sono la stessa cosa?

No. Il token è la decisione con un nome; la variabile CSS è uno dei modi per distribuirla. Dallo stesso token puoi generare CSS, tipi TypeScript o JSON.

### Devo usare un formato standard come W3C design tokens?

Non è obbligatorio. Il formato JSON del W3C aiuta quando più strumenti leggono gli stessi token; per un solo progetto un file JSON tuo basta.

### Quanti livelli di token servono?

Due bastano: scala e semantica. Un terzo livello per componente si giustifica solo quando un componente ha bisogno di un valore che nessun altro usa.

### Come aggiorno un token già usato?

Cambi il valore nella fonte, rigeneri il CSS e leggi il diff. Se il cambio tocca cinquanta file, il token era un valore grezzo travestito.