Configurar theme.json en WordPress: colores y tipografía
¿Qué es el archivo theme.json?
El archivo theme.json es un archivo de configuración de los temas de WordPress que permite definir los ajustes y estilos disponibles en el editor de bloques, así como establecer la apariencia general de un sitio web. En esta guía aprenderás a configurar theme.json en WordPress paso a paso.
Gracias a este archivo, podemos configurar aspectos como la paleta de colores, la tipografía, el espaciado, la anchura del contenido y los estilos de los distintos bloques de WordPress, entre otras opciones.
Antes de la aparición de theme.json, muchas de estas personalizaciones requerían escribir código CSS o utilizar diferentes mecanismos de configuración. Con este archivo, WordPress ofrece una forma centralizada de definir buena parte de estas opciones y controlar cómo se presentan en el editor y en la web.
El fichero theme.json adquirió especial importancia con los temas de bloques y la edición completa del sitio (Full Site Editing o FSE), ya que permite configurar numerosos aspectos del tema desde un único lugar. No obstante, también puede utilizarse en temas clásicos compatibles.
Es importante distinguir entre los ajustes y los estilos. Los ajustes determinan qué opciones están disponibles para el usuario en el editor, mientras que los estilos permiten establecer los valores y la apariencia predeterminados del sitio.
A lo largo de esta guía veremos cómo se estructura theme.json, qué propiedades podemos utilizar y cómo crear un archivo de configuración adaptado a las necesidades de nuestro tema. Además, aprenderás a configurar theme.json en WordPress paso a paso.
¿Dónde se encuentra y para qué sirve?
El archivo theme.json se encuentra en la carpeta principal del tema de WordPress, junto a otros archivos como style.css y las carpetas que contienen las plantillas y las partes de plantilla.
En un tema de bloques, la estructura básica podría ser la siguiente:
mi-tema/
├── style.css
├── theme.json
├── functions.php
├── templates/
│ └── index.html
└── parts/
├── header.html
└── footer.htmlUna precisión técnica: aunque el ejemplo muestra la estructura de un tema de bloques, theme.json también puede utilizarse en temas clásicos compatibles. El archivo functions.php que aparece en el árbol no es obligatorio para que un tema de bloques básico funcione.
En este ejemplo, theme.json está situado directamente dentro de la carpeta mi-tema/. No debemos confundirlo con los archivos de las plantillas, que se encuentran dentro de templates/, ni con las partes de plantilla, que se guardan en parts/.
¿Para qué sirve theme.json?
La principal función de este archivo es centralizar la configuración del tema y definir los ajustes y estilos que WordPress debe utilizar. Entre otras cosas, nos permite:
- Definir una paleta de colores: establecer los colores que queremos utilizar en el sitio y que estarán disponibles en el editor.
- Configurar la tipografía: definir las fuentes, los tamaños de letra y otros aspectos relacionados con el texto.
- Controlar el espaciado: establecer opciones para los márgenes, el relleno y la separación entre bloques.
- Definir la anchura del contenido: establecer el ancho de contenido normal y el ancho amplio que utilizarán los bloques compatibles.
- Aplicar estilos globales: definir valores predeterminados para elementos como el texto, los enlaces y los encabezados.
- Personalizar los bloques: establecer ajustes y estilos específicos para determinados bloques de WordPress.
Además, podemos controlar qué opciones de personalización estarán disponibles en el editor. Podemos limitar la paleta de colores para que los usuarios trabajen con los colores definidos por el tema.
¿Es obligatorio incluir theme.json?
No todos los temas de WordPress necesitan incorporar este archivo. Sin embargo, resulta especialmente útil cuando queremos controlar de forma centralizada la configuración y los estilos de un tema, sobre todo si trabajamos con temas de bloques.
En las siguientes secciones veremos cómo crear este archivo desde cero y cómo utilizar sus propiedades para configurar nuestro tema.
Estructura básica de theme.json
El archivo theme.json utiliza el formato JSON, un formato de texto que permite organizar información mediante propiedades y valores.
Su estructura se basa en un conjunto de propiedades que WordPress interpreta para configurar los ajustes, los estilos y otros aspectos del tema.
Vamos a empezar con una estructura básica que nos servirá para comprender cómo se organiza el archivo antes de añadir configuraciones más avanzadas.
Para poner en práctica los conceptos que veremos a lo largo de esta guía, vamos a crear un proyecto llamado theme-json-lab en una instalación limpia de WordPress 7.1.3.
De esta forma, podremos experimentar con las distintas propiedades de theme.json, comprobar cómo afectan a la configuración del editor de bloques y observar los resultados en nuestra web, sin modificar ningún sitio en producción.
Crearemos un tema desde cero e iremos incorporando las configuraciones paso a paso. Así podremos entender para qué sirve cada propiedad y cómo utilizarla en nuestros propios temas de WordPress.
La propiedad $schema
La propiedad $schema indica la dirección del esquema JSON que utilizaremos como referencia para validar la estructura del archivo. Esta dirección permite que editores de código como Visual Studio Code puedan reconocer las propiedades admitidas, ofrecer sugerencias mientras escribimos y señalar determinados errores de estructura.
La propiedad version
La propiedad version indica qué versión del formato de configuración de theme.json estamos utilizando.
El valor 3 corresponde a la versión 3 del esquema, disponible desde WordPress 6.6. Es la versión que utilizaremos en esta guía, trabajando con WordPress 7.1.3.
Las propiedades settings y styles
Estas dos propiedades son fundamentales para configurar nuestro tema.
- settings permite definir qué opciones estarán disponibles en el editor, como los controles de color, las opciones tipográficas o las herramientas de espaciado.
- styles permite establecer los estilos predeterminados del sitio, de determinados elementos HTML y de los bloques de WordPress.
Por ejemplo, mediante settings podemos definir una paleta de colores para que aparezca en el editor. Con styles, podemos establecer cuál será el color de fondo predeterminado de la web.
Más adelante veremos ambas propiedades en profundidad y añadiremos ejemplos prácticos para comprender cómo funcionan.
Cómo configurar theme.json paso a paso
Configurar la paleta de colores
Una de las primeras cosas que podemos configurar en theme.json es la paleta de colores del tema. De esta manera, podemos definir los colores que estarán disponibles en el editor de bloques y utilizarlos de forma coherente en los distintos elementos de nuestra web
Para ello, utilizaremos la propiedad palette, que se encuentra dentro de settings.color.
Cada color que añadamos tendrá tres propiedades:
- name: el nombre que se mostrará para identificar el color en el editor.
- slug: un identificador único que WordPress utilizará para generar nombres de clases y variables CSS.
- color: el valor del color, que podemos expresar mediante un código hexadecimal, como #cc454e.
{
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 3,
"settings": {
"color": {
"palette": [
{
"name": "Fondo",
"slug": "background",
"color": "#000000"
},
{
"name": "Texto",
"slug": "foreground",
"color": "#ffffff"
},
{
"name": "Principal",
"slug": "primary",
"color": "#cc454e"
}
]
}
},
"styles": {}
}
En este ejemplo hemos definido tres colores para nuestro tema:
- Fondo: negro (#000000), que podemos utilizar como color de fondo.
- Texto: blanco (#ffffff), pensado para el texto que se muestre sobre el fondo negro.
- Principal: rojo (#cc454e), que podemos utilizar para destacar botones, títulos y otros elementos de la web.
Los nombres y valores son ejemplos de configuración. Definir un color en la paleta no significa que WordPress lo aplique automáticamente a toda la web; lo que hacemos es registrarlo para que pueda utilizarse en los elementos compatibles.
¿Cómo aparecen estos colores en WordPress?
Como podemos observar, WordPress muestra nuestros tres colores personalizados en un grupo identificado como ‘TEMA’, mientras que los colores que incluye por defecto aparecen en otro grupo denominado ‘POR DEFECTO’.
De esta forma, podemos seleccionar los colores que hemos definido en theme.json directamente desde los ajustes de color de los bloques, sin necesidad de introducir manualmente sus códigos hexadecimales.
¿Cómo ocultar la paleta predeterminada de WordPress?
Añadimos la propiedad defaultPalette: false dentro de settings.color en theme.json.
Al añadir la propiedad defaultPalette: false dentro de settings.color, desactivamos la paleta de colores predeterminada de WordPress.
Como podemos observar en la captura, el grupo ‘POR DEFECTO’ ha desaparecido y únicamente se muestran los tres colores que hemos definido en nuestro tema.
Desactivar los colores personalizados
Para evitar que los usuarios puedan elegir colores personalizados distintos de los que hemos definido en nuestra paleta, añadiremos la propiedad custom: false dentro de settings.color.
A tener en cuenta: La propiedad custom: false desactiva la posibilidad de elegir colores personalizados, pero no afecta a los degradados ni a los filtros duotono. Estas opciones se controlan mediante propiedades independientes: customGradient y customDuotone.
Configurar la tipografía
Mediante la propiedad settings.typography de theme.json, podemos configurar las opciones tipográficas disponibles en el editor de bloques de WordPress. Entre otras cosas, podemos controlar las familias tipográficas, los tamaños de fuente y las opciones de apariencia que los usuarios pueden seleccionar al editar el contenido.
Además, mediante la propiedad styles.typography, podemos establecer los estilos tipográficos predeterminados de la web, como la familia y el tamaño de fuente que se aplicarán al texto.
A continuación, veremos cómo configurar estas opciones paso a paso.
Configurar los tamaños de fuente
Mediante la propiedad settings.typography.fontSizes, podemos definir una lista de tamaños de fuente preestablecidos que estarán disponibles en el editor de bloques de WordPress.
{
"name": "Principal",
"slug": "primary",
"color": "#cc454e"
}
]
},
"typography": {
"defaultFontSizes": false,
"fontSizes": [
{
"name": "Pequeño",
"slug": "small",
"size": "14px"
},
{
"name": "Normal",
"slug": "normal",
"size": "18px"
},
{
"name": "Grande",
"slug": "large",
"size": "32px"
}
]
}
},
"styles": {}
}
Una vez guardados los cambios en theme.json, WordPress mostrará en los ajustes de tipografía del editor los tres tamaños que hemos definido: Pequeño, Normal y Grande, representados por las letras S, M y L, respectivamente.
La configuración de cada tamaño incluye tres propiedades:
- name: establece el nombre descriptivo del tamaño. En nuestro ejemplo, hemos utilizado ‘Pequeño’, ‘Normal’ y ‘Grande’. Estos nombres se muestran como información al pasar el ratón por encima de cada opción del selector.
- slug: define el identificador del tamaño, que WordPress utiliza para generar las clases CSS correspondientes. En nuestro caso, hemos utilizado small, normal y large.
- size: establece el tamaño de la fuente que se aplicará al seleccionar cada opción. Hemos definido 14px para el tamaño pequeño, 18px para el normal y 32px para el grande.
Además, hemos añadido la propiedad defaultFontSizes: false dentro de settings.typography. Con ella desactivamos los tamaños de fuente predeterminados de WordPress, de modo que en el selector solo aparecen los tres tamaños que hemos definido en nuestro tema.
De esta forma, podemos controlar qué tamaños de fuente están disponibles en el editor y adaptar las opciones tipográficas a las necesidades de nuestro tema.
Configurar la familia tipográfica
En el archivo theme.json añade la propiedad fontFamilies dentro de settings.typography, al mismo nivel que fontSizes.
Definimos dos opciones:
- Arial: una familia tipográfica sin remates (sans-serif).
- Georgia: una familia tipográfica con remates (serif).
La propiedad fontFamily incluye una lista de fuentes alternativas que el navegador puede utilizar si la primera no está disponible.
Comprobar el resultado en WordPress
Guarda los cambios en theme.json.
Abre una página o entrada en el editor de bloques.
Selecciona un bloque de párrafo.
Abre los ajustes de Tipografía y busca la opción Fuente.
"slug": "large",
"size": "32px"
}
],
fontFamilies": [
}
"name": "Arial",
"slug": "arial",
"fontFamily": "Arial, Helvetica, sans-serif"
},
{
"name": "Georgia",
"slug": "georgia",
"fontFamily": "Georgia, 'Times New Roman', serif"
}
]
Como podemos observar, WordPress muestra las dos familias tipográficas que hemos definido en theme.json: Arial y Georgia. Podemos seleccionarlas desde los ajustes de tipografía de un bloque para cambiar la apariencia del texto de ese bloque.
Cada familia se define mediante tres propiedades:
- name: establece el nombre que se muestra en el editor.
- slug: define el identificador de la familia tipográfica.
- fontFamily: indica la familia tipográfica que utilizará el navegador. Podemos incluir varias fuentes separadas por comas para que, si la primera no está disponible, se utilice una alternativa.
En nuestro ejemplo, Arial utiliza Helvetica como alternativa y termina con sans-serif, mientras que Georgia incluye Times New Roman y termina con serit.
De esta forma, podemos ofrecer distintas familias tipográficas en el editor sin necesidad de que el usuario escriba manualmente sus nombres.
Incorporar una fuente propia al tema
Para utilizar una fuente propia, necesitamos dos cosas:
- El archivo de la fuente, por ejemplo, en formato .ttf.
- La configuración en theme.json para registrar la familia tipográfica y permitir que WordPress la utilice.
En este ejemplo alojaremos el archivo dentro de nuestro tema, en una carpeta llamada fonts. De esta forma, la fuente formará parte del tema y no dependerá de un servicio externo.
theme-json-lab/
├── parts/
├── templates/
├── fonts/
│ └── mi-fuente.ttf
├── style.css
└── theme.json
Utilizaremos la fuente Fraunces, que descargaremos en formato .ttf para incorporarla a nuestro tema.
Incorporar el archivo al tema
Puedes acceder aquí para descargar la fuente: Fraunces en Google Fonts
Para registrar la fuente que hemos incorporado a la carpeta fonts, añadiremos su definición dentro de la propiedad fontFamilies, justo debajo y al mismo nivel a las familias Arial y Georgia que configuramos anteriormente.
Una vez en la dirección arriba indicada, nos descargamos el siguiente fichero y lo renombramos como fraunces-variable.ttf y lo incluimos dentro de la carpeta fonts.
theme-json-lab/
├── fonts/
│ └── fraunces-variable.ttf
├── parts/
├── templates/
├── style.css
└── theme.json
Añadir la fuente a theme.json
Para registrar la fuente que hemos incorporado a la carpeta fonts, añadiremos su definición dentro de la propiedad fontFamilies, justo debajo y al mismo nivel a las familias Arial y Georgia que configuramos anteriormente.
fontFamilies": [
}
"name": "Arial",
"slug": "arial",
"fontFamily": "Arial, Helvetica, sans-serif"
},
{
"name": "Georgia",
"slug": "georgia",
"fontFamily": "Georgia, 'Times New Roman', serif"
},
{
"name": "Fraunces",
"slug": "fraunces",
"fontFamily": "Fraunces",
"fontFace": [
{
"fontFamily": "Fraunces",
"fontStyle": "normal",
"fontWeight": "100 900",
"src": ["file:./fonts/fraunces-variable.ttf"]
}
]
}
]
Comprobar el resultado
Selecciona un párrafo y accede a Tipografía → Fuente. Selecciona Fraunces y comprueba que se aplica correctamente al texto.
Para comprobar que la fuente se está aplicando correctamente, abriremos en el navegador cualquier entrada de nuestra web y verificaremos que el texto se muestra con la tipografía Fraunces que hemos incorporado al tema.
Puedes ampliar conocimientos visitando:
Introducción a theme.json
Configuración de la tipografía
Ajustes y estilos globales