Su un tema sviluppato prima dell’introduzione di theme.json, cambiare il colore primario del brand su richiesta del cliente significava cercare la stessa variabile CSS ripetuta in otto file diversi, e nella metà dei casi qualcuno la dimenticava in un componente secondario. Theme.json è il file di configurazione, in formato JSON, con cui un tema WordPress a blocchi dichiara i propri design token, colori, font, dimensioni, spaziature, generando automaticamente le CSS custom properties che ogni blocco nativo e ogni blocco custom possono consumare, senza duplicare gli stessi valori in decine di fogli di stile separati.
Il file vive nella root del tema e si divide in due macro sezioni: settings, che definisce cosa un utente può personalizzare nell’editor (palette colori disponibili, dimensioni font selezionabili, se abilitare i bordi custom), e styles, che applica valori di default a blocchi ed elementi HTML. WordPress legge questo file e genera automaticamente variabili CSS con il prefisso –wp–preset– per i valori dei preset e –wp–custom– per valori arbitrari definiti sotto la chiave custom.
Un esempio concreto di come funziona
{
"version": 2,
"settings": {
"color": {
"palette": [
{ "slug": "primary", "color": "#1A2B3C", "name": "Primary" },
{ "slug": "accent", "color": "#E8A530", "name": "Accent" }
]
},
"typography": {
"fontSizes": [
{ "slug": "small", "size": "0.875rem", "name": "Small" },
{ "slug": "large", "size": "1.5rem", "name": "Large" }
]
}
},
"custom": {
"spacing": {
"section-gap": "4rem"
}
}
}
Da questa configurazione, WordPress genera automaticamente var(–wp–preset–color–primary), var(–wp–preset–font-size–large) e var(–wp–custom–spacing–section-gap), utilizzabili in qualsiasi CSS del tema o di un blocco custom. Cambiare il colore primario del brand significa modificare un solo valore in un solo file: ogni blocco che referenzia quella variabile si aggiorna automaticamente, in tutte le pagine del sito, senza toccare un singolo file CSS aggiuntivo.
Cosa vede il cliente nell’editor grazie a questa configurazione
La sezione settings di theme.json non serve solo a WordPress internamente: determina anche cosa il cliente vede e può scegliere nel pannello Stili dell’editor, raggiungibile dall’icona a forma di mezzaluna nella schermata Aspetto > Editor. Se la palette dichiarata contiene cinque colori, il cliente vede esattamente quei cinque colori come opzioni per lo sfondo di un blocco o il colore di un testo, non l’intera ruota cromatica. Disabilitare esplicitamente alcune funzionalità, come i gradienti personalizzati o le dimensioni font arbitrarie, tramite le chiavi custom: false dentro settings, riduce ulteriormente lo spazio di scelta a quello che il design system del progetto prevede davvero.
"settings": {
"color": {
"custom": false,
"customGradient": false
},
"typography": {
"customFontSize": false
}
}
Questa configurazione è particolarmente utile su progetti dove il cliente finale, non l’agenzia, gestisce i contenuti in autonomia dopo la consegna: meno opzioni libere significano meno probabilità che qualcuno, senza cattive intenzioni, scelga un colore o una dimensione font che rompe la coerenza visiva costruita durante lo sviluppo.
Perché elimina un’intera categoria di bug
Prima di theme.json, la coerenza visiva di un sito dipendeva dalla disciplina dello sviluppatore nel riusare le stesse variabili CSS ovunque. Con più persone che lavorano sullo stesso progetto, o con progetti ereditati da altri sviluppatori, questa disciplina si rompe quasi sempre: qualcuno scrive un valore hex diretto invece di richiamare la variabile, e quel colore smette di aggiornarsi quando il brand cambia palette.
Problema: modifica del colore primario del brand richiesta dal cliente, ma alcuni componenti del sito restano con il vecchio colore
Causa: quei componenti avevano il valore colore scritto direttamente in hex invece di richiamare la variabile CSS generata da theme.json
Soluzione Blurr: audit dei CSS custom del progetto per sostituire ogni valore hardcoded con la variabile corrispondente, e regola di sviluppo interna che vieta valori colore diretti nei blocchi custom, solo variabili da theme.json
L’altro beneficio, meno visibile ma altrettanto concreto, riguarda l’editor stesso. Con theme.json configurato correttamente, l’editor a blocchi mostra al cliente solo le opzioni di colore e font effettivamente previste dal design system del sito, invece del color picker completo che permette di scegliere qualsiasi tonalità RGB. Riduce drasticamente il rischio che un cliente, editando autonomamente una pagina, scelga un colore fuori dal brand senza nemmeno accorgersene.
Come lo usiamo per mantenere coerenza tra progetti diversi
Sui progetti che sviluppiamo per le agenzie partner, theme.json non è solo uno strumento tecnico, è diventato il punto di partenza di ogni nuovo tema. Prima ancora di scrivere un blocco custom, definiamo la palette colori, la scala tipografica e gli spazi in theme.json, così che ogni componente sviluppato dopo erediti automaticamente i valori corretti invece di doverli reimpostare uno per uno.
Un progetto per un’agenzia di Padova ci aveva chiesto di intervenire su un tema esistente dove la scala tipografica non era mai stata standardizzata: sei dimensioni di font diverse per titoli che avrebbero dovuto essere identici, causate da modifiche accumulate nel tempo da sviluppatori diversi. Migrando la configurazione tipografica dentro theme.json e sostituendo ogni valore hardcoded con le variabili generate, la manutenzione futura sulla tipografia è passata da una ricerca manuale in decine di file a una singola modifica centralizzata.
Un dettaglio tecnico che vale la pena conoscere riguarda i temi child: se il child theme include un proprio theme.json, WordPress unisce le due configurazioni invece di sostituire completamente quella del parent, dando priorità ai valori dichiarati nel child. È un comportamento utile per progetti che partono da uno starter theme condiviso tra più clienti, dove il child theme personalizza solo la palette colori specifica del brand del cliente, ereditando dal parent tutta la struttura di spaziature e tipografia già validata su decine di progetti precedenti.
Va detto con chiarezza che theme.json non risolve tutto da solo: richiede disciplina nello scriverlo bene fin dall’inizio e nel resistere alla tentazione di scrivere un valore diretto quando si ha fretta. Ma il framework che offre, una volta rispettato, elimina alla radice il problema della coerenza visiva che affligge molti siti WordPress sviluppati in modo incrementale nel tempo.
Per capire come questa configurazione si integra con lo sviluppo di componenti custom, leggi il nostro approfondimento su come funzionano gli ACF Blocks. Theme.json è anche la base su cui poggia il Full Site Editing: senza una configurazione solida di design token, un tema a blocchi produce un’esperienza di editing incoerente per il cliente. Se gestisci un tema con problemi di coerenza visiva accumulati nel tempo e vuoi valutare una migrazione a theme.json, su blurr.it/contatti/possiamo fare un audit del progetto.
Domande frequenti
No, funziona anche con i temi classici basati su template PHP, a partire da WordPress 5.8, anche se il beneficio è massimo sui temi a blocchi dove ogni componente dell’editor legge direttamente da questa configurazione.
Non necessariamente da zero: si può introdurre gradualmente, migrando prima i valori più critici (colori brand, scala tipografica) e lasciando il resto del CSS esistente fino a una revisione più ampia del tema.
No. Theme.json genera le variabili e gli stili di base per i blocchi, ma un tema continua ad avere fogli di stile propri per layout, animazioni e componenti che vanno oltre quello che il sistema di design tokens copre nativamente.
Il componente smette di essere collegato al design system: se il brand cambia colore, quel componente specifico non si aggiorna automaticamente e va corretto manualmente, lo stesso problema che theme.json è nato per risolvere.









