Convenzioni di naming dei design token: un sistema a 3 livelli

Alla fine di questa guida avrai uno schema di naming in cui uno sviluppatore riesce a nominare un nuovo token in modo corretto al primo colpo, senza chiedere a nessuno. Lo schema usa tre livelli, primitivo, semantico e di componente, e il nome stesso ti dice a quale livello appartiene un token.

Una convenzione di naming dei design token è l'insieme di regole che decide come si chiama ogni token e in che ordine vanno le parti del nome. Se la imposti bene, il sistema scala. Un designer aggiunge un colore, uno sviluppatore sa dove collocarlo e il passaggio alla dark mode cambia poche righe. Se la imposti male, ti ritrovi con blue2, blueDark e brandBlueNew che puntano a tre tonalità che sei mesi dopo nessuno sa più distinguere.

Cosa ti serve prima di iniziare

Tre cose, e la seconda è quella che genera più discussioni, quindi chiudila per prima.

• Un elenco dei valori grezzi già presenti nel prodotto: colori, step di spaziatura, dimensioni dei font, raggi, ombre e durate. Stai dando un nome a ciò che esiste, non inventando una palette.
• Un accordo su un solo delimitatore e un solo ordine delle parole. Mischiare color-bg-primary e colorBgPrimary nello stesso sistema rompe i tool e la ricerca. Scegline uno e fallo rispettare.
• Un formato di file in cui scrivere. Da ottobre 2025 il W3C Design Tokens Format Module ha una prima versione stabile, quindi il JSON con $value e $type è un default sicuro che Style Dictionary, Tokens Studio e le variabili di Figma leggono tutti.

Passo 1: dividi ogni token in uno di tre livelli

I sistemi maturi, tra cui Carbon di IBM, organizzano i token in tre livelli collegati da una catena di riferimenti: primitivo verso semantico verso componente. Ogni livello risponde a una domanda diversa.

• Primitivo (detto anche globale o base): il valore grezzo senza contesto. blue-500 dice che un blu esiste e a quanto equivale. Non dice dove usarlo.
• Semantico (detto anche alias): l'intento. color-text-default punta a un primitivo e dice a cosa serve quel valore.
• Di componente: legato a un solo componente. button-background-hover punta a un semantico ed esiste perché un componente possa divergere per conto suo.

I primitivi sono le opzioni. I semantici sono le scelte. Il prodotto consuma i token semantici e di componente; i primitivi restano dietro le quinte come valori di riferimento.

Passo 2: nomina i primitivi per quello che sono

I primitivi descrivono l'aspetto, perché l'aspetto è tutto ciò che portano. Usa una categoria, una tinta o proprietà e una scala numerica: color-blue-500, dimension-space-4, font-size-300. La scala numerica conta. Step di 100 (da 100 a 900) lasciano spazio per inserire un valore in seguito senza rinominare i vicini. Evita aggettivi come blueMedium o spaceBig: finiscono lo spazio nel momento in cui aggiungi una tonalità tra due di essi.

Passo 3: nomina i token semantici per intento, mai per aspetto

Questa è la regola singola che risparmia più problemi. Nomina un token semantico per quello che fa, non per come appare. Usa color-feedback-success, non color-green. Quando un brand rende il successo in ambra, o la dark mode ribalta una superficie, il nome d'intento regge e cambia solo il suo riferimento. Un nome d'aspetto come color-green-button diventa una bugia il giorno in cui il valore smette di essere verde.

La tassonomia dei token di Nathan Curtis dà i livelli a cui un nome semantico può attingere: namespace, categoria, concetto, proprietà, variante, stato e scala. Raramente li usi tutti. Una forma comune e leggibile è categoria, concetto, proprietà e poi stato: color-action-primary-hover. Letta da sinistra a destra dice: un colore, per le azioni, quella primaria, nel suo stato hover.

Passo 4: aggiungi token di componente solo quando un componente se lo guadagna

Un token di componente esiste per dare a un singolo componente un gancio che un designer può ripuntare senza toccare il livello semantico condiviso. card-border-default permette al team della card di cambiare i bordi della card da solo. È utile il giorno in cui un componente ha davvero bisogno di divergere. È rumore ogni altro giorno. Parti dal livello semantico. Promuovi un valore a token di componente quando, e solo quando, compare una divergenza reale. La maggior parte dei componenti non ne ha mai bisogno.

Passo 5: fissa un delimitatore e un ordine, poi scrivilo nel linter

Ordina i livelli dal generale allo specifico: namespace, categoria, concetto, proprietà, variante, stato, scala. Togli i livelli che un token non usa. L'esempio dello stesso Curtis, esds-color-neutral-42, impacchetta in quell'ordine un namespace (esds), una categoria (color), una variante (neutral) e una scala (42).

Il delimitatore dipende dall'output. Usa i punti nel sorgente JSON (color.text.default), perché è così che i gruppi si annidano nel formato W3C. Usa i trattini nelle custom property CSS che il build produce (--ds-color-text-default). Scegli un singolo prefisso di namespace per il livello CSS (qui --ds-) così i tuoi token non entrano mai in collisione con un foglio di stile di terze parti. Un tool come Style Dictionary trasforma un solo sorgente in ogni output, quindi il nome lo scrivi una volta sola.

Passo 6: trasforma la convenzione in una grammatica di una pagina

Un elenco di token diventa obsoleto la settimana dopo che l'hai pubblicato. Una grammatica di una pagina no. Scrivi ogni livello, le parole ammesse a quel livello (si dice bg o background, text o fg) e l'ordine in cui compaiono. Con la grammatica in mano, uno sviluppatore nomina un token che non ha mai visto e arriva allo stesso nome che avrebbe scelto un manutentore. È tutto qui il senso di una convenzione.

Come capisci se la convenzione funziona?

Due test. Primo: dai a un nuovo sviluppatore un valore grezzo senza token e chiedigli di nominarlo. Se produce il nome che avresti scritto tu, senza chiedere, la convenzione regge. Se sbaglia, la grammatica ha un buco. Secondo: esegui un cambio di tema. Un rebrand o una dark mode dovrebbero toccare il livello semantico e nient'altro. Se costringe a modifiche su decine di token di componente, il tuo livello semantico è troppo sottile e i componenti puntano direttamente ai primitivi.

Errori comuni e come correggerli

• Parole d'aspetto nel livello semantico. color-green-success vanifica lo scopo. Rinomina in color-feedback-success e ripunta il riferimento.
• Codificare il valore nel nome. color-text-16px mescola un colore con una dimensione. La dimensione è un token a sé; tieni separati i due assi.
• Proliferazione di sinonimi. bg, background e surface usati per lo stesso concetto costringono tutti a indovinare. Scegli una parola per concetto e vieta le altre nel linter.
• Annidamento fuori controllo. color-button-primary-default-hover-large ha troppi livelli per essere letto. Limita i nomi a circa quattro livelli significativi; se te ne servono di più, dentro si nasconde un token di componente.
• Token di componente di default. Creare button-*, card-* e modal-* per ogni proprietà prima che una di esse diverga raddoppia la superficie senza alcun vantaggio. Aspetta la divergenza.

Per approfondire

Il naming è un livello di una struttura più ampia. Leggi design token, variabili CSS e Tailwind a confronto per capire dove stanno i token nello stack, la struttura di un design system per l'ordine in cui costruire le categorie e la deriva dei componenti per cosa succede quando una convenzione esiste sulla carta ma nessuno la fa rispettare.