Design system
Come costruire un design system dai token
Un design system nasce dai token: inventario dei valori grezzi, scale con nomi neutri, ruoli semantici, poi i componenti. Il codice viene dopo.
In sintesi
- Parti dai valori grezzi già presenti nel codice: sono il sistema attuale.
- Due livelli bastano: scala con nomi neutri e ruoli semantici.
- Se cambiare un token tocca cinquanta file, era un valore grezzo travestito.
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.
Passo 1: contare i valori grezzi
grep -rhoE '#[0-9a-fA-F]{6}' src --include='*.tsx' | sort | uniq -c | sort -rn | head -20Il 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.
Domande frequenti
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.