Come Configurare theme.json in WordPress: Tutorial Completo per Principianti

By Alberta Trentino

Se stai sviluppando un tema a blocchi per WordPress, il file theme.json è il cuore pulsante della tua configurazione. In questa guida pratica vedremo come strutturarlo da zero, con esempi reali di codice commentato per colori, tipografia e spaziature. L’obiettivo è arrivare alla fine dell’articolo con un file theme.json funzionante e pronto da usare nel tuo progetto WordPress.

Cos’è theme.json e perché è fondamentale in WordPress

Il file theme.json è un file di configurazione introdotto a partire da WordPress 5.8 che permette di definire impostazioni globali e stili per il block editor (Gutenberg) e per il Full Site Editing. In pratica, sostituisce molte delle vecchie funzioni PHP come add_theme_support() e centralizza la gestione di colori, font, spaziature e layout in un unico file JSON.

I principali vantaggi di utilizzare theme.json sono:

  • Coerenza visiva: stili uniformi tra editor e front-end
  • Performance: WordPress genera CSS ottimizzato automaticamente
  • Manutenibilità: tutto in un solo file, facile da aggiornare
  • Compatibilità futura: è lo standard ufficiale per i temi a blocchi
  • Controllo granulare: puoi limitare o abilitare funzionalità per singolo blocco
wordpress code editor

Dove posizionare il file theme.json

Il file theme.json deve trovarsi nella cartella principale del tuo tema, allo stesso livello di style.css e functions.php. Il percorso tipico è:

/wp-content/themes/nome-tuo-tema/theme.json

Struttura base di theme.json

Ogni file theme.json parte da una struttura minima con quattro sezioni principali. Ecco lo scheletro di partenza commentato:

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

Analizziamo le chiavi principali:

  • $schema: abilita l’autocompletamento nei migliori editor (VS Code, PhpStorm)
  • version: la versione attuale è 3, supportata da WordPress 6.6 in avanti
  • settings: definisce le opzioni disponibili nell’editor
  • styles: applica gli stili effettivi al sito
  • customTemplates e templateParts: dichiarano template personalizzati e parti riutilizzabili

Configurare la palette dei colori

La gestione dei colori è probabilmente la parte più usata di theme.json. Puoi definire una palette personalizzata, gradienti e duotoni. Ecco un esempio pratico:

{
  "settings": {
    "color": {
      "palette": [
        {
          "slug": "primary",
          "color": "#0066FF",
          "name": "Primario"
        },
        {
          "slug": "secondary",
          "color": "#FF3366",
          "name": "Secondario"
        },
        {
          "slug": "dark",
          "color": "#1A1A1A",
          "name": "Scuro"
        },
        {
          "slug": "light",
          "color": "#FAFAFA",
          "name": "Chiaro"
        }
      ],
      "custom": false,
      "customGradient": false,
      "defaultPalette": false
    }
  }
}

Cosa fa questa configurazione:

  1. Definisce 4 colori brand riutilizzabili nell’editor
  2. Disabilita il color picker custom (custom: false) per forzare l’uso della palette
  3. Rimuove la palette di default di WordPress (defaultPalette: false)

Ogni colore diventa automaticamente una variabile CSS utilizzabile come var(--wp--preset--color--primary).

Applicare i colori in styles

Una volta definita la palette, possiamo applicarla nella sezione styles:

{
  "styles": {
    "color": {
      "background": "var(--wp--preset--color--light)",
      "text": "var(--wp--preset--color--dark)"
    },
    "elements": {
      "link": {
        "color": {
          "text": "var(--wp--preset--color--primary)"
        }
      }
    }
  }
}
wordpress code editor

Configurare la tipografia in theme.json

La tipografia è un’altra area chiave. Possiamo definire font family, dimensioni preset, line-height e altro. Vediamo un esempio completo:

{
  "settings": {
    "typography": {
      "fluid": true,
      "fontFamilies": [
        {
          "slug": "sans",
          "name": "Inter",
          "fontFamily": "Inter, sans-serif",
          "fontFace": [
            {
              "fontFamily": "Inter",
              "fontWeight": "400",
              "fontStyle": "normal",
              "src": ["file:./assets/fonts/Inter-Regular.woff2"]
            },
            {
              "fontFamily": "Inter",
              "fontWeight": "700",
              "fontStyle": "normal",
              "src": ["file:./assets/fonts/Inter-Bold.woff2"]
            }
          ]
        }
      ],
      "fontSizes": [
        {
          "slug": "small",
          "size": "0.875rem",
          "name": "Piccolo"
        },
        {
          "slug": "medium",
          "size": "1rem",
          "name": "Medio"
        },
        {
          "slug": "large",
          "size": "clamp(1.5rem, 3vw, 2rem)",
          "name": "Grande",
          "fluid": {
            "min": "1.5rem",
            "max": "2rem"
          }
        }
      ]
    }
  }
}

Le opzioni interessanti qui sono:

  • fluid: true: abilita la tipografia fluida responsive in tutto il tema
  • fontFace: registra automaticamente i web font locali senza bisogno di CSS aggiuntivo
  • fontSizes con fluid: definisce dimensioni che si adattano alla viewport

Gestire spaziature e layout

Le spaziature (padding, margin, gap) sono gestibili tramite preset uniformi. Questo garantisce un sistema di design coerente:

{
  "settings": {
    "spacing": {
      "padding": true,
      "margin": true,
      "blockGap": true,
      "units": ["px", "rem", "em", "%"],
      "spacingSizes": [
        {
          "slug": "30",
          "size": "1rem",
          "name": "Piccolo"
        },
        {
          "slug": "50",
          "size": "2rem",
          "name": "Medio"
        },
        {
          "slug": "70",
          "size": "4rem",
          "name": "Grande"
        }
      ]
    },
    "layout": {
      "contentSize": "720px",
      "wideSize": "1200px"
    }
  }
}

Con contentSize e wideSize definisci la larghezza massima dei contenuti standard e wide, fondamentale per il layout dei blocchi.

Tabella riassuntiva delle sezioni principali

Sezione Scopo Dove agisce
settings.color Definisce palette, gradienti, duotoni Editor + Front-end
settings.typography Font family, dimensioni, line-height Editor + Front-end
settings.spacing Padding, margin, gap, unità Editor + Front-end
settings.layout Larghezza contenuti Front-end
styles Applica gli stili effettivi Front-end
styles.blocks Stili per singoli blocchi Front-end
wordpress code editor

Esempio completo di theme.json funzionante

Mettiamo insieme tutto quello che abbiamo visto per ottenere un file theme.json pronto all’uso:

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "settings": {
    "appearanceTools": true,
    "color": {
      "palette": [
        { "slug": "primary", "color": "#0066FF", "name": "Primario" },
        { "slug": "dark", "color": "#1A1A1A", "name": "Scuro" },
        { "slug": "light", "color": "#FAFAFA", "name": "Chiaro" }
      ],
      "defaultPalette": false
    },
    "typography": {
      "fluid": true,
      "fontSizes": [
        { "slug": "small", "size": "0.875rem", "name": "Piccolo" },
        { "slug": "medium", "size": "1rem", "name": "Medio" },
        { "slug": "large", "size": "1.5rem", "name": "Grande" }
      ]
    },
    "spacing": {
      "spacingSizes": [
        { "slug": "30", "size": "1rem", "name": "S" },
        { "slug": "50", "size": "2rem", "name": "M" },
        { "slug": "70", "size": "4rem", "name": "L" }
      ]
    },
    "layout": {
      "contentSize": "720px",
      "wideSize": "1200px"
    }
  },
  "styles": {
    "color": {
      "background": "var(--wp--preset--color--light)",
      "text": "var(--wp--preset--color--dark)"
    },
    "typography": {
      "fontSize": "var(--wp--preset--font-size--medium)",
      "lineHeight": "1.6"
    },
    "elements": {
      "link": {
        "color": { "text": "var(--wp--preset--color--primary)" }
      },
      "h1": {
        "typography": {
          "fontSize": "var(--wp--preset--font-size--large)",
          "fontWeight": "700"
        }
      }
    }
  }
}

Best practice da seguire

  1. Usa sempre lo schema: ti evita errori di sintassi grazie all’autocompletamento
  2. Nomi slug coerenti: usa convenzioni chiare (primary, secondary, dark, light)
  3. Disabilita il superfluo: se non vuoi che gli utenti personalizzino qualcosa, imposta custom: false
  4. Testa l’editor: ogni modifica si riflette immediatamente nel block editor
  5. Versiona il file: theme.json va sempre nel tuo repository Git
  6. Sfrutta appearanceTools: con true abiliti molte opzioni in un colpo solo

Errori comuni da evitare

  • JSON non valido: una virgola in più rompe tutto, usa sempre un linter
  • Confondere settings e styles: settings definisce cosa è disponibile, styles applica
  • Slug con caratteri speciali: usa solo lettere minuscole, numeri e trattini
  • Dimenticare la versione: senza version: 3 WordPress potrebbe non interpretare correttamente il file

FAQ su theme.json in WordPress

theme.json è obbligatorio per un tema WordPress?

No, non è strettamente obbligatorio, ma è praticamente indispensabile per qualsiasi tema a blocchi moderno. Senza di esso non puoi sfruttare appieno il Full Site Editing.

Posso usare theme.json in un tema classico (non a blocchi)?

Sì, anche i temi classici possono includere theme.json per beneficiare della gestione centralizzata di colori e tipografia nell’editor a blocchi.

Come faccio a sovrascrivere theme.json in un child theme?

Basta creare un file theme.json nella cartella del child theme. WordPress effettuerà il merge con quello del parent, dando priorità al child.

Quale versione di theme.json devo usare nel 2026?

La versione attuale è la 3, supportata da WordPress 6.6 e successivi. È quella consigliata per tutti i nuovi progetti.

Posso aggiungere CSS personalizzato direttamente in theme.json?

Sì, attraverso la proprietà css all’interno di styles o dentro singoli blocchi puoi inserire CSS custom che verrà incluso nell’output finale.

Conclusione

Configurare correttamente theme.json in WordPress significa creare temi più solidi, performanti e facili da mantenere nel tempo. Partendo dalla struttura base e aggiungendo progressivamente colori, tipografia e spaziature, puoi costruire un sistema di design completo in un unico file. Se hai bisogno di supporto nello sviluppo del tuo tema WordPress personalizzato, il team di Mumble Studio è a tua disposizione per aiutarti a portare il tuo progetto al livello successivo.

Leave a Comment