Raccogliere token CSS: dal caos degli stili a un sistema gestibile

Collezionare token CSS non è un capriccio guidato dal design o un’estetica fine a se stessa. È una pratica ingegneristica volta a normalizzare le decisioni visive e ridurre i costi operativi del frontend.

In questo articolo tratteremo:

• cosa significano i token CSS in termini pratici;
• come appaiono effettivamente nei progetti del mondo reale;
• quali problemi espone la raccolta di token;
• e perché questo processo dovrebbe essere automatizzato come parte di un audit.

Cosa significano in pratica i token CSS

Un token di design assegna un nome a una decisione, come un colore o una spaziatura. Raccogliere i valori CSS ripetuti aiuta a trovare candidati, ma la sola ripetizione non li rende token. Puoi inventariare:

• colori (#0d6efd, rgb(13,110,253))
• dimensioni dei caratteri (14px, 1rem)
• altezze di riga
• spaziature (8px, 16px, 24px)
• raggi di arrotondamento
• ombre e valori di z-index

Esempio illustrativo di e-commerce:

.button-primary {
	background: #005bff;
	border-radius: 6px;
}

.checkout-button {
	background-color: #005bff;
	border-radius: 8px;
}

I pulsanti hanno lo stesso colore di sfondo ma raggi di arrotondamento diversi. Prima di unificare i valori, verifica se la differenza è intenzionale.

Problemi tipici rivelati dalla raccolta di token

1. Falsa diversità

Consideriamo un esempio didattico di audit SaaS con questi valori:

• 27 tonalità distinte di blu
• 19 delle quali differiscono di 1–3 unità RGB

Questo è un classico sintomo di:

• copia-incolla manuale da Figma;
• l'assenza di un contratto di progettazione tra i team;
• debito tecnico accumulato.

2. Distanziamento senza sistema

Un esempio di interfaccia di amministrazione:

margin-bottom: 12px;
margin-bottom: 14px;
margin-bottom: 16px;
margin-bottom: 18px;

La domanda non è “quale spaziatura è corretta”. La vera domanda è perché ce ne sono quattro in tutto.

La raccolta dei token ti consente di:

• visualizzare la distribuzione dei valori;
• individuare gruppi simili;
• scegliere una scala adatta, per esempio una griglia da 4 o 8 punti.

3. Deriva tipografica

Un altro esempio didattico è un portale aziendale con:

• 11 dimensioni dei caratteri
• 7 valori di altezza della linea
• 5 pesi di carattere per il corpo del testo

Raggruppare per scopo può far emergere tre ruoli tipografici. Verifica l’uso effettivo prima di unificare gli altri valori.

Come funziona tecnicamente la raccolta di token CSS

A livello meccanico, il processo è semplice:

1. Carica la pagina.
2. Raccogli gli stili accessibili, incorporati ed esterni.
3. Analizza le dichiarazioni.
4. Raggruppa i valori per categoria:

• colori
• dimensioni dei caratteri
• spaziature
• raggi di arrotondamento

5. Calcola la frequenza.

Esempio di output JSON:

{
	"colors": {
		"#005bff": 143,
		"#ffffff": 98,
		"#f5f7fa": 34
	},
	"spacing": {
		"8px": 76,
		"16px": 112,
		"24px": 41
	}
}

Questi conteggi aiutano l’analisi. La frequenza da sola non determina il significato di un valore né la sua priorità.

Perché un approccio manuale non è scalabile

All’inizio i team possono concordare le regole a voce. Quando hai:

• 5 o più sviluppatori;
• branch di funzionalità paralleli;
• più fonti di design;

mantenere gli accordi verbali diventa più difficile.

Senza la raccolta automatizzata dei token:

• è più difficile mantenere un inventario affidabile;
• diventa più difficile confrontare gli effetti del refactoring;
• rischi di non notare regressioni visive.

Scenario illustrativo: redesign senza fermare lo sviluppo

Immagina un sito di marketing di circa 120 pagine. I numeri illustrano una possibile migrazione: non sono un risultato cliente verificato né una previsione.

Prima:

• Oltre 4.000 regole CSS
• 32 colori
• 19 dimensioni dei caratteri

Passi effettuati:

1. Raccogliere i valori nelle pagine principali.
2. Ordinarli per frequenza.
3. Definire un insieme base di token.
4. Migrare gradualmente, senza riscrivere tutto.

Dopo:

• 9 colori base
• 6 token tipografici
• riduzione del CSS del 18%
• meno regressioni visive nei test A/B

Dove entrano in gioco i miglioramenti prestazionali

I token CSS non riguardano solo il design:

• unificare dichiarazioni duplicate può ridurre il CSS;
• condividere i valori facilita la manutenzione;
• semplificare le regole può ridurre i conflitti della cascata;
• gli effetti su gzip/Brotli, copertura e CSS critico vanno misurati.

La sola raccolta dei token non accelera una pagina. Confronta byte trasferiti e tempi di caricamento dopo la modifica del codice.

Perché lo trattiamo come un problema di audit

A milten.io, la raccolta dei token CSS è:

• diagnostica, non un generatore di “bel report”;
• un modo per esporre la struttura dove appare assente;
• un punto di accesso alla standardizzazione, ai sistemi di progettazione e all'architettura frontend scalabile.

Se è difficile formalizzare i candidati, esamina le regole di design e le eccezioni. Questa difficoltà non dimostra da sola l’assenza di un design system.

Sommario

Ridotto alla logica gestionale:

• CSS senza token = una risorsa non gestita
• raccolta di token = inventario
• frequenza = priorità
• automazione = scalabilità

Senza rivedere i valori condivisi, piccoli aggiustamenti agli stili possono aggiungere incoerenze a ogni redesign.

Raccogli i valori usati nel progetto, scegli modifiche motivate e misurane gli effetti.