Entendiendo la anatomía del fichero theme.json

Descubre en este tutorial la estructura interna del fichero theme.json y aprende cómo puedes personalizarlo.

WordPress 5.8 introdujo el fichero theme.json que es una de las piezas clave sobre las que se fundamentan los temas de bloques o FSE (Full Site Editing).

Lo bueno es que el fichero theme.json se puede usar en temas clásicos así que te invito a que te familiarices con él lo antes posible.

Por eso estoy preparando una serie de tutoriales centrados en que entiendas cómo funciona y sobre todo en cómo puedes modificarlo a tu gusto.

Y es que desde el este fichero puedes personalizar muchos aspectos de un tema de WordPress:

Paleta de colores, gradientes y douotonos
Fuentes/Tipografía (familias, tamaño…)
Anchura del sitio
Espaciado
Estilos de los bloques
Variaciones de estilos globales
Gestión de los template parts o partes de plantillas (temas FSE)
Gestión de los block templates o plantillas de bloques (temas FSE)
Definir propiedades de CSS personalizadas
Y más.

Al ofrecer tantas opciones (y en cada actualización de WordPress se añaden más) puede resultar un poco intimidante. De hecho, si abres el fichero theme.json de algún tema de bloques, por ejemplo, el Twenty Twenty-Two, te vas a encontrar más de 300 líneas.

Por eso, en este tutorial vamos revisar la estructura para que te familiarices con la misma. Así te sentirás más preparado/a para personalizar los ajustes que quieras o incluso añadir nuevos.

Estructura interna del fichero theme.json

Este sería el «esqueleto» de un theme.json:

}
    "version": 2,
    "settings": {},
    "styles": {}
}

Es decir, además de la versión existen dos secciones principales:

version: actualmente la 2 (de WordPress 5.9 en adelante)
settings: donde defines los controles de bloques, paletas de color, tamaño de fuentes…
styles: donde aplicas esos colores, tamaño de fuentes… a la web.

Si vas a utilizar el fichero en un tema clásico con esto tendrás suficiente. Pero si vas a utilizarlo en un tema FSE, hay dos secciones que se han añadido más recientemente y que también te pueden interesar. La estructura quedaría así:

}
    "version": 2,
    "settings": {},
    "styles": {},
    "customTemplates": {},
    "templateParts": {}
}

version: actualmente la 2 (de WordPress 5.9 en adelante)
settings: donde defines los controles de bloques, paletas de color, tamaño de fuentes…
styles: donde aplicas esos colores, tamaño de fuentes… a la web.
customTemplates: donde asignas los block templates que pueden ser modificados desde editor de plantillas (temas FSE).
templateParts: donde asignas los template parts o partes de plantilla, como las cabeceras o footers (temas FSE).

Estas serían las secciones que se encuentran en el primer nivel de la estructura. Pero dentro de estas se encuentran otras sub-secciones.

Como hay muchas (y siguen ampliándose en cada versión de WordPress), voy a destacar las más importantes a la hora de personalizar un tema:

version
settings
- color
  - palette
  - gradients
  - duotone
- layout
- spacing
- typography
  - fontFamily
  - fontSize
  - fontStyle
  - fontWeight
  - letterSpacing
  - lineHeight
  - textDecoration
  - textTransform
styles
- border
- blocks
- color
- dimensions
- filter
- outline
- elements
- shadow
- spacing
- typography
customTemplates
templateParts
patterns

Como puedes observar la semántica que se utiliza facilita bastante entender de qué se encarga cada ajuste.

Y seguro que puedes intuir qué ajustes debes modificar para configurar los elementos mencionados en el primer listado.

Los ajustes y propiedades del fichero theme.json son muchos y repasarlos todos en este tutorial no tiene sentido, ya que vamos a dedicar otros específicos para cada apartado.

Pero sí me parece interesante que veas cómo es un fichero theme.json «vacío» para que veas representados sus ajustes y propiedades:

{
    "version": "2",
    "settings": {
      "appearanceTools": true,
      "border": {
        "color": true,
        "radius": true,
        "style": true,
        "width": true
      },
      "color": {
        "text": true,
        "background": true,
        "link": true,
        "custom": true,
        "customDuotone": true,
        "customGradient": true,
        "defaultGradients": false,
        "defaultPalette": false,
        "duotone": [],
        "gradients": [],
        "palette": [
          {
            "color": "",
            "slug": "",
            "name": ""
          }
        ]
      },
      "custom": {
        "spacing": {
          "small": "",
          "medium": "",
          "large": "",
          "outer": ""
        },
        "typography": {
          "dropCap": false,
          "fontSize": {
            "small": "",
            "medium": "",
            "large": ""
          },
          "lineHeight": {
            "tiny": 1.15,
            "small": 1.2,
            "medium": 1.4,
            "normal": 1.6
          }
        }
      },
      "layout": {
        "contentSize": "",
        "wideSize": ""
      },
      "spacing": {
        "blockGap": null,
        "margin": true,
        "padding": true,
        "units": [
          "px",
          "em",
          "rem",
          "vh",
          "vw"
        ]
      },
      "typography": {
        "customFontSize": true,
        "dropCap": true,
        "fontFamilies": [],
        "fontSizes": [],
        "fontStyle": true,
        "fontWeight": true,
        "letterSpacing": true,
        "lineHeight": true,
        "textDecoration": true,
        "textTransform": true
      }
    },
    "styles": {
      "border": {
        "color": "",
        "radius": "",
        "style": "",
        "width": ""
      },
      "color": {
        "background": "",
        "gradient": "",
        "text": ""
      },
      "filter": {
        "duotone": ""
      },
      "spacing": {
        "blockGap": "",
        "margin": {
          "top": "",
          "right": "",
          "bottom": "",
          "left": ""
        },
        "padding": {
          "top": "",
          "right": "",
          "bottom": "",
          "left": ""
        }
      },
      "typography": {
        "fontFamily": "",
        "fontSize": "",
        "fontStyle": "",
        "fontWeight": "",
        "letterSpacing": "",
        "lineHeight": "",
        "textDecoration": "",
        "textTransform": ""
      },
      "elements": {
        "link": {
          "border": {},
          "color": {},
          "spacing": {},
          "typography": {}
        },
        "h1": {},
        "h2": {},
        "h3": {},
        "h4": {},
        "h5": {},
        "h6": {}
      }
    },
    "customTemplates": [],
    "templateParts": [
        {
          "area": "footer",
          "name": "footer",
          "title": "Footer"
        },
        {
          "area": "header",
          "name": "header",
          "title": "Header"
        }
      ]
  }

En este caso, faltan los valores que se añadirían entre comillas "" y los arrays que se añadirían entre los corchetes [] y las llaves {}.

También puedes ver que hay varios ajustes que pueden como configurarse como true o false.

No te preocupes porque no tienes que aprenderte ni la estructura ni los ajustes de memoria. De hecho, en el siguiente tutorial te explico un truco que te va a facilitar mucho la vida en este aspecto:

Cómo personalizar con facilidad el fichero theme.json usando schema.

Espero que después de este repaso te resulte más sencillo entender el contenido de un fichero theme.json y sobre todo que te sirva de base para aplicar los siguientes tutoriales donde vamos a personalizar diferentes secciones.

Conclusiones

Entender la estructura del fichero theme.json es imprescindible si quieres empezar a sacarle partido, tanto en temas clásicos como en los temas de bloques (FSE).

Ahora que ya lo conoces un poco mejor, en los próximos tutoriales te explicaré como usarlo para personalizar temas de WordPress.

Si tienes alguna duda sobre este tutorial, déjala en los comentarios.

¿Sugerencias para próximos snippets? Envíamelas con el formulario de contacto.

Todo ventajas de ser suscriptor.

Estructura interna del fichero theme.json

Conclusiones

Tutoriales relacionados

Nahuai Badiola