Convenzioni per la denominazione dei token

Nomi incoerenti per i token rendono impossibile prevedere la funzione di un token senza leggerne il valore. Una convenzione di denominazione chiara e prevedibile è fondamentale per un sistema di token scalabile.

Uno schema comune è: [category]-[property]-[variant]. Esempi: color-text-primary, color-text-secondary, spacing-inset-sm. Ogni segmento restringe progressivamente il significato.

Eviti nomi della palette come blue-500 nei componenti. Utilizzi nomi semantici: color-action-default, color-feedback-error. I nomi semantici rimangono validi anche quando cambiano i colori del brand, senza richiedere aggiornamenti ai componenti.

Aggiunga lo stato alla fine: color-button-bg-default, color-button-bg-hover, color-button-bg-disabled. Suffissi di stato coerenti rendono gli insiemi di token prevedibili e completi.

Utilizzi in modo coerente le taglie delle magliette (xs, sm, md, lg, xl) oppure le scale numeriche (100, 200...900). Le scale numeriche consentono di inserire valori intermedi, mentre le taglie delle magliette sono più leggibili per gli insiemi di piccole dimensioni.

Per i sistemi multi-brand o multiprodotto, anteponga ai token uno spazio dei nomi: brand-a-color-primary rispetto a brand-b-color-primary. Gli spazi dei nomi impediscono le collisioni quando si uniscono insiemi di token.

Il kebab-case viene convertito direttamente in custom property CSS: color-text-primary diventa --color-text-primary. I token in camel-case richiedono una trasformazione, mentre quelli in kebab-case no.

I nomi efficaci sono autoesplicativi: spacing-stack-md (spaziatura verticale tra elementi impilati, media) comunica l'intento senza bisogno di un commento. Nomi poco significativi come s3 richiedono documentazione esterna per essere compresi.

Una volta che i token sono in uso, rinominarli costituisce una modifica incompatibile. Utilizzi alias di deprecazione: mantenga il vecchio nome, facendolo però puntare al nuovo token. Conceda ai consumer un periodo per la migrazione prima di rimuovere i token deprecati.

Verifichi i nomi dei token con regole personalizzate in Style Dictionary o tramite uno script CI. Rifiuti i token che non rispettano lo schema di denominazione. L'applicazione automatizzata delle regole previene la deriva dei nomi con la crescita del sistema.

Pubblici una guida alla denominazione con esempi di nomi corretti e scorretti. Organizzi un breve workshop affinché i team di design e sviluppo concordino le convenzioni prima che il sistema cresca. La coerenza richiede una comprensione condivisa, non solo documentazione.

Perché i token dei componenti dovrebbero usare nomi semantici anziché nomi della tavolozza come "blue-500"?

Una convenzione coerente per i nomi dei token, basata su schemi categoria-proprietà-variante, nomi semantici, suffissi per lo stato e prefissi di namespace, rende i sistemi di token prevedibili, autoesplicativi e resistenti ai cambiamenti del brand senza modificare il codice dei componenti.