Che cos'è theme.json in WordPress?

È un unico file di configurazione JSON nella radice di un tema a blocchi che controlla due cose: quali opzioni di design l'editor a blocchi mette a disposizione degli utenti e quali sono gli stili di default. WordPress lo legge, ne genera proprietà CSS personalizzate e un foglio di stile, e lo unisce ai default del core e agli eventuali Stili globali salvati dall'utente.

Qual è la differenza tra settings e styles in theme.json?

settings definisce cosa è disponibile e genera variabili CSS più i controlli dell'editor, ma da solo non applica niente. styles applica i valori veri usando quelle variabili. Aggiungere un colore alla palette non cambia nessun elemento finché non lo richiami anche sotto styles oppure finché un utente non lo sceglie nell'editor.

Perché le mie modifiche a theme.json non si vedono sul front end?

Quasi sempre perché gli Stili globali salvati nel database hanno la precedenza su theme.json. Nel momento in cui qualcuno tocca il pannello Stili nell'Editor del sito, quel record salvato vince per ogni proprietà che contiene. Apri Stili, usa il pannello delle revisioni per tornare ai default del tema, poi ricarica. Il secondo sospettato è la cache dei dati di theme.json già elaborati.

Serve ancora un file style.css se uso theme.json?

Sì. WordPress richiede style.css per il commento di intestazione del tema, quello che fornisce nome, versione e altri metadati: senza, il tema non viene nemmeno riconosciuto. Per il resto puoi lasciarlo vuoto e mettere le tue scelte di design in theme.json, oppure tenerci un po' di CSS per le cose che theme.json non sa esprimere.

Che numero di versione devo usare in theme.json?

Usa la versione più alta che la release minima di WordPress che supporti sa interpretare. La chiave version dice a WordPress quale forma di schema analizzare, e le release più vecchie ignorano le chiavi che non riconoscono. Se hai installazioni datate tra i tuoi target, resta sulla versione che loro supportano invece di dare per scontato che le chiavi nuove degradino con eleganza.

theme.json sostituisce completamente il CSS?

No. Copre bene preset, default dei blocchi, stili degli elementi, larghezze di layout e spaziature, ma non ha alcun concetto di media query scritte da te, selettori complessi, animazioni o stati pseudo-classe oltre ai pochi che supporta. La maggior parte dei temi a blocchi in produzione distribuisce theme.json più un foglio di stile ridotto per il resto.

theme.json di WordPress spiegato: settings, styles e la cascade

theme.json è un unico file di configurazione nella radice di un tema a blocchi che svolge due lavori distinti: settings decide cosa l’editor a blocchi offre agli utenti, styles decide come appare davvero il sito per impostazione predefinita. WordPress lo analizza, lo unisce ai propri default e a tutto ciò che è stato salvato nell’Editor del sito, e restituisce il risultato come proprietà CSS personalizzate più un foglio di stile inline su ogni pagina.

Confondere questi due lavori è il motivo per cui la maggior parte delle modifiche a theme.json sembra non produrre nulla. Dichiarare un colore sotto settings non applica quel colore da nessuna parte. Crea soltanto una variabile e un campione nella barra laterale dell’editor.

Le chiavi di primo livello

Un file minimo si presenta così:

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "settings": {},
  "styles": {},
  "templateParts": [],
  "customTemplates": []
}

Chiave	A cosa serve
`$schema`	Solo autocompletamento e validazione nell’editor di codice. WordPress la ignora.
`version`	Dice a WordPress quale forma di schema analizzare. Non è la versione del tuo tema.
`settings`	Genera le variabili CSS e stabilisce cosa l’editor mette a disposizione.
`styles`	Applica davvero lo stile di default.
`templateParts`	Dichiara le parti in `parts/` e a quale area appartengono.
`customTemplates`	Registra i template di pagina in `templates/` per l’editor dei contenuti.

version manda in confusione perché sembra il numero di versione del tema. Non lo è. Seleziona una modalità di parsing, e le release più vecchie di WordPress ignorano in silenzio le chiavi di una forma di schema che non conoscono. Se supporti installazioni datate, punta alla versione che quelle installazioni capiscono invece di sperare che le chiavi nuove degradino con eleganza. La versione 3 è quella attuale mentre scriviamo; la 2 è ancora molto diffusa e viene ancora interpretata.

$schema punta a un URL di schema ospitato da WordPress. Fissarlo su trunk ti dà i suggerimenti più aggiornati nell’editor di codice; un URL legato a una versione specifica è più prudente se stai deliberatamente restando su uno schema più vecchio.

settings: cosa offre l’editor

Tutto ciò che sta sotto settings produce una proprietà CSS personalizzata e, nella maggior parte dei casi, un controllo nell’editor. Niente sotto settings applica stile.

{
  "settings": {
    "color": {
      "palette": [
        { "slug": "brand", "color": "#1f4ed8", "name": "Brand" },
        { "slug": "ink", "color": "#111827", "name": "Ink" }
      ],
      "custom": false
    },
    "typography": {
      "fontSizes": [
        { "slug": "small", "size": "0.875rem", "name": "Small" },
        { "slug": "large", "size": "1.5rem", "name": "Large" }
      ]
    },
    "layout": {
      "contentSize": "680px",
      "wideSize": "1200px"
    }
  }
}

Da qui nascono variabili il cui nome deriva dal percorso del preset e dallo slug:

--wp--preset--color--brand
--wp--preset--color--ink
--wp--preset--font-size--small
--wp--preset--font-size--large

Genera anche classi di utilità come .has-brand-color e .has-brand-background-color: è così che l’editor applica a un blocco il campione scelto.

La riga "custom": false è l’altra metà di settings: disattivare opzioni. Impostala e il selettore di colore libero sparisce, lasciando agli utenti la tua palette e nient’altro. Lo stesso schema vale ovunque — settings.typography.customFontSize, settings.spacing.customSpacingSize, settings.border, e così via. Sotto settings non c’è niente di decorativo: ogni chiave aggiunge una variabile, aggiunge un controllo, oppure toglie un controllo.

settings.custom è un contenitore libero per le tue variabili:

{
  "settings": {
    "custom": {
      "lineHeight": { "body": 1.6 },
      "shadow": { "card": "0 1px 3px rgba(0,0,0,0.12)" }
    }
  }
}

Diventano --wp--custom--line-height--body e --wp--custom--shadow--card. Attenzione alla trasformazione: le chiavi in camelCase vengono spezzate in kebab-case e l’annidamento è unito da doppi trattini. Sbagliare il nome di una variabile è un motivo ricorrente per cui un valore torna in silenzio al fallback.

Puoi limitare le impostazioni al singolo blocco: è così che permetti il selettore di colore sui pulsanti ma non sui paragrafi.

{
  "settings": {
    "blocks": {
      "core/paragraph": {
        "color": { "custom": false, "customGradient": false }
      }
    }
  }
}

styles: cosa viene renderizzato davvero

styles è dove i valori vengono applicati. Rispecchia la struttura dell’editor: un livello radice, poi elements, poi blocks.

{
  "styles": {
    "color": {
      "background": "var(--wp--preset--color--base)",
      "text": "var(--wp--preset--color--ink)"
    },
    "typography": {
      "lineHeight": "var(--wp--custom--line-height--body)"
    },
    "elements": {
      "link": {
        "color": { "text": "var(--wp--preset--color--brand)" },
        ":hover": { "typography": { "textDecoration": "none" } }
      }
    },
    "blocks": {
      "core/quote": {
        "typography": { "fontStyle": "italic" },
        "spacing": { "padding": { "left": "var(--wp--preset--spacing--40)" } }
      }
    }
  }
}

Gli styles di primo livello finiscono sul body. elements copre le primitive HTML che non sono blocchi — link, pulsante, titoli, didascalia. blocks colpisce un tipo di blocco specifico chiamandolo per nome.

Il limite, detto onestamente: styles non può esprimere tutto ciò che il CSS esprime. Non c’è modo di scrivere media query tue, niente selettori complessi, niente animazioni, e solo un piccolo insieme di stati pseudo-classe supportati. La tipografia fluida e il dimensionamento basato sul layout coprono buona parte di ciò per cui si usavano i breakpoint, ma non tutto. Quasi tutti i temi a blocchi distribuiti portano con sé theme.json più un foglio di stile contenuto, ed è un esito normale, non un fallimento.

La trappola settings contro styles

La domanda di supporto più frequente in assoluto è una variante di “ho aggiunto il colore del mio brand e non è cambiato niente”.

Esatto. Aggiungerlo a settings.color.palette ha creato --wp--preset--color--brand e un campione. Non ha applicato nulla. Per renderlo il colore predefinito dei link devi scriverlo anche sotto styles:

{
  "settings": {
    "color": {
      "palette": [{ "slug": "brand", "color": "#1f4ed8", "name": "Brand" }]
    }
  },
  "styles": {
    "elements": {
      "link": { "color": { "text": "var(--wp--preset--color--brand)" } }
    }
  }
}

Leggila così: settings è la scatola di colori che consegni all’utente, styles è la mano di vernice che dai prima che arrivi.

La cascade, dal livello più basso al più alto

È la parte che spiega un sito che sembra “ignorare” il file del tema. WordPress unisce diversi livelli prima di emettere il CSS:

Default del core di WordPress — il core distribuisce un proprio theme.json con palette, dimensioni dei caratteri e scala delle spaziature di base.
theme.json del tema parent
theme.json del tema child — unito sopra al parent chiave per chiave, non sostituendo l’intero file.
Stili globali salvati nel database — ciò che scrive il pannello Stili dell’Editor del sito.
Stili per singolo blocco — attributi memorizzati nel contenuto del post, resi come stili inline o classi.

Il livello 4 è quello che rompe i siti. Nell’istante in cui qualcuno apre il pannello Stili e salva, WordPress memorizza un record di Stili globali e quel record vince sul tuo file per ogni proprietà che contiene. Modificare theme.json dopo non cambia nulla di visibile per quelle proprietà: il sito resta identico dopo un deploy mentre il file su disco è palesemente diverso.

La soluzione è cancellare il record salvato, non rilanciare a colpi di !important. Apri l’Editor del sito, vai su Stili, apri il pannello delle revisioni e riporta tutto ai default del tema. Prima conferma con il cliente o con il proprietario del sito: il ripristino butta via le sue personalizzazioni, ed è un costo reale, non un’operazione gratuita.

Il secondo sospettato è la cache. WordPress tiene in cache i dati di theme.json già elaborati invece di rileggere il file a ogni richiesta: è esattamente ciò che vuoi in produzione ed esattamente ciò che non vuoi mentre sviluppi. Attivare WP_DEBUG, o l’impostazione di modalità sviluppo del tema nelle release più recenti, fa sì che WordPress rilegga il file ogni volta. Se le tue modifiche compaiono solo dopo un deploy o uno svuotamento della cache, è questo che stai osservando.

templateParts e customTemplates

Sono entrambi array che descrivono file già presenti nel tuo tema.

{
  "templateParts": [
    { "name": "header", "title": "Header", "area": "header" },
    { "name": "footer", "title": "Footer", "area": "footer" }
  ],
  "customTemplates": [
    { "name": "page-wide", "title": "Wide Page", "postTypes": ["page"] }
  ]
}

name corrisponde al nome del file senza estensione — parts/header.html, templates/page-wide.html. Il valore di area conta: decide se la parte viene racchiusa in un elemento landmark di intestazione o di piè di pagina e come l’editor la categorizza. Se lo ometti, la parte resta senza categoria.

customTemplates è ciò che fa comparire un template nel menu a tendina dell’editor dei contenuti. Senza quella voce il file esiste ma nessuno può selezionarlo.

Un ordine rapido di diagnosi

Quando un tema a blocchi non applica gli stili che il file dichiara, passa da qui prima di toccare qualsiasi cosa:

Visualizza il sorgente e cerca il blocco di stili globali generato. Se la tua variabile non c’è, il problema è in settings o in uno slug scritto male.
Se la variabile c’è ma non è usata da nessuno, manca una voce in styles.
Se ci sono entrambe ma qualcosa le sovrascrive, cerca un record di Stili globali salvato.
Solo a quel punto guarda il tuo foglio di stile, i plugin, o un page builder che inietta CSS più avanti nella cascade.