theme.json en WordPress: guía práctica para diseñadores

WordPress permite centralizar muchas de las decisiones de diseño de un tema —colores, tipografía, espaciado, anchuras de contenido y estilos de bloques— en un archivo theme.json.

Para quienes diseñan temas de bloques, theme.json funciona como puente entre el sistema de diseño y su implementación en WordPress. En lugar de repartir ajustes entre CSS, PHP y distintas opciones de configuración, muchas de las reglas visuales pueden expresarse en un formato estructurado que WordPress entiende directamente.

Esto no significa que theme.json sustituya por completo al CSS ni que contenga toda la arquitectura de un tema. Su función es proporcionar un sistema común para definir ajustes y estilos que puedan compartir el editor, los bloques, los patrones y las plantillas.

Resumen clave

• theme.json es un archivo de configuración que centraliza muchos de los ajustes y estilos de un tema de WordPress.
• Se introdujo en WordPress 5.8 y puede utilizarse tanto en temas de bloques como, con ciertas limitaciones, en temas clásicos.
• Permite definir paletas de colores, familias y tamaños tipográficos, espaciados, anchuras de contenido y estilos globales o específicos para determinados bloques.
• También permite controlar qué herramientas de diseño están disponibles para los editores de contenido.
• Los presets definidos en theme.json funcionan como tokens de diseño reutilizables en distintas partes del tema.
• WordPress 7.1 amplía estas posibilidades con estados de estilo adaptables para móvil y tableta.
• Las variaciones de estilos permiten ofrecer distintas combinaciones visuales sin necesidad de crear temas independientes.
• theme.json puede reducir considerablemente la necesidad de CSS personalizado, pero no pretende sustituirlo en todos los casos.

¿Qué es exactamente theme.json?

theme.json apareció en WordPress 5.8 como una forma estandarizada de definir ajustes y estilos relacionados con el editor de bloques.

Normalmente se encuentra en la raíz del directorio del tema:

wp-content/themes/nombre-del-tema/theme.json

Es un archivo de texto en formato JSON. WordPress interpreta su contenido para configurar herramientas del editor, generar presets y aplicar reglas de estilo.

Desde el punto de vista del diseñador, puede entenderse como una de las capas de implementación de un sistema de diseño. Permite convertir decisiones como «estos son nuestros colores», «esta es nuestra escala tipográfica» o «estas son las anchuras de contenido permitidas» en reglas que WordPress puede aplicar y ofrecer en su interfaz.

No contiene por sí solo toda la estructura del sitio. Las plantillas, las partes de plantilla y los patrones son recursos independientes que trabajan junto con los ajustes y estilos establecidos en theme.json.

La versión actual del esquema es la versión 3, introducida con WordPress 6.6.

¿Por qué es útil para un diseñador?

Antes de theme.json, muchas decisiones visuales de un tema se distribuían entre style.css, funciones PHP, opciones del Personalizador y otros archivos.

theme.json permite trasladar muchas de esas decisiones a una configuración común.

Mantener la coherencia

Una paleta, una escala tipográfica y un sistema de espaciado predefinidos ofrecen a los editores opciones aprobadas en lugar de obligarlos a recordar códigos de color, tamaños de fuente o valores de margen.

Esto ayuda a reducir la deriva del diseño: la aparición progresiva de colores ligeramente distintos, tamaños tipográficos arbitrarios y espaciados inconsistentes a medida que se crean nuevas páginas.

Facilitar la colaboración

El diseñador puede definir los tokens y reglas del sistema visual y el desarrollador trasladarlos a theme.json.

En lugar de una especificación que diga simplemente «azul corporativo», el tema puede contener un preset denominado brand-primary. Ese mismo nombre puede utilizarse en patrones, bloques y CSS personalizado.

Diseño e implementación comparten así un vocabulario reconocible.

Controlar sin bloquear innecesariamente

Un sistema de diseño no tiene por qué impedir que los editores tomen decisiones.

theme.json permite determinar dónde conviene ofrecer flexibilidad y dónde es preferible restringirla. Un sitio corporativo puede limitar los colores a una paleta aprobada y, al mismo tiempo, ofrecer varios tamaños de fuente o valores de espaciado.

Simplificar cambios posteriores

Cuando los elementos utilizan presets en lugar de valores introducidos manualmente, muchos cambios pueden realizarse de forma centralizada.

Si cambia el color corporativo principal, por ejemplo, puede modificarse el valor del preset correspondiente sin tener que buscar ese código hexadecimal por todo el tema.

Estructura básica de theme.json

Entre las propiedades principales que puede contener theme.json se encuentran:

• $schema: identifica el esquema JSON y facilita la validación y el autocompletado.
• version: indica la versión del formato theme.json.
• settings: define presets y herramientas disponibles en el editor.
• styles: establece estilos globales y específicos.
• customTemplates: proporciona metadatos para plantillas personalizadas.
• templateParts: proporciona metadatos para partes de plantilla.
• patterns: puede registrar patrones del directorio de patrones de WordPress.org.

No es necesario utilizar todas estas propiedades.

Un archivo inicial puede ser tan sencillo como:

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

A partir de ahí pueden añadirse únicamente las configuraciones que requiera el proyecto.

El esquema $schema: una ayuda durante el desarrollo

La propiedad $schema resulta especialmente útil cuando se edita theme.json con un editor compatible, como Visual Studio Code.

Por ejemplo:

"$schema": "https://schemas.wp.org/trunk/theme.json"

El esquema permite al editor reconocer qué propiedades admite theme.json, qué valores espera y en qué lugar deben aparecer. Esto facilita el autocompletado, la documentación contextual y la detección de errores.

Un equipo que desarrolle deliberadamente para una versión concreta de WordPress también puede utilizar el esquema correspondiente a esa versión.

Para un diseñador que conoce los tokens y reglas del sistema visual pero tiene menos experiencia con JSON, estas ayudas reducen considerablemente la dificultad de trabajar directamente con el archivo.

settings: definir las reglas del sistema de diseño

La sección settings determina buena parte de las opciones que WordPress pone a disposición de los usuarios.

Permite responder a preguntas como:

• ¿Qué colores pueden utilizarse?
• ¿Qué tamaños de fuente estarán disponibles?
• ¿Se permitirán colores o tamaños personalizados?
• ¿Qué controles de espaciado podrán utilizar los editores?
• ¿Cuál será la anchura normal y la anchura amplia del contenido?

Las áreas principales incluyen color, typography, spacing y layout.

También existe appearanceTools, que permite habilitar conjuntamente una serie de herramientas adicionales de diseño en los bloques que las admiten.

En proyectos donde sea importante mantener un sistema visual muy controlado, puede ser preferible activar únicamente las herramientas necesarias en lugar de ofrecer todas las opciones posibles.

Crear una paleta de colores

El color es uno de los ejemplos más claros de cómo trasladar un sistema de diseño a WordPress.

Una paleta puede definirse en settings.color.palette:

{
  "settings": {
    "color": {
      "palette": [
        {
          "slug": "brand-primary",
          "name": "Color principal",
          "color": "#1A3D7C"
        },
        {
          "slug": "brand-accent",
          "name": "Color de acento",
          "color": "#FF6B35"
        },
        {
          "slug": "neutral-light",
          "name": "Neutro claro",
          "color": "#F5F5F5"
        }
      ],
      "custom": false
    }
  }
}

Cada color tiene un slug, un nombre visible para el usuario y un valor.

WordPress genera a partir de estos presets variables CSS como:

--wp--preset--color--brand-primary

que pueden reutilizarse en otras partes del tema.

Con "custom": false, se puede impedir la elección libre de colores y limitar las opciones a los presets establecidos por el tema.

La paleta no debería limitarse a copiar los colores de un manual de marca. Conviene pensar en su función: colores de texto, fondos, acentos, enlaces y elementos interactivos, además de comprobar que las combinaciones previstas proporcionan suficiente contraste.

Definir la tipografía

La tipografía se reparte principalmente entre dos áreas.

settings.typography define las opciones disponibles para el usuario, mientras que styles.typography puede establecer los valores aplicados por defecto.

Por ejemplo:

{
  "settings": {
    "typography": {
      "fontFamilies": [
        {
          "slug": "sans-ui",
          "name": "Sans UI",
          "fontFamily": "'Inter', sans-serif"
        },
        {
          "slug": "serif-display",
          "name": "Serif Display",
          "fontFamily": "'Playfair Display', serif"
        }
      ]
    }
  }
}

También puede establecerse una escala de tamaños:

{
  "fontSizes": [
    {
      "slug": "small",
      "size": "0.875rem",
      "name": "Pequeño"
    },
    {
      "slug": "medium",
      "size": "1rem",
      "name": "Medio"
    },
    {
      "slug": "large",
      "size": "1.5rem",
      "name": "Grande"
    },
    {
      "slug": "xl",
      "size": "2.25rem",
      "name": "Extra grande"
    }
  ]
}

Los bloques compatibles muestran estos presets en sus controles tipográficos.

También puede desactivarse la introducción de tamaños arbitrarios cuando se quiera mantener una escala estricta.

WordPress admite además tipografía fluida, que permite que determinados tamaños evolucionen entre valores mínimos y máximos según la anchura disponible. Esto puede reducir la necesidad de establecer saltos bruscos entre tamaños para distintos dispositivos.

El interlineado debe considerarse junto con el tamaño de fuente para mantener una lectura cómoda en diferentes pantallas.

Espaciado y anchuras de contenido

El espaciado es otra fuente frecuente de pequeñas inconsistencias.

En lugar de permitir valores arbitrarios para márgenes y rellenos, theme.json puede definir una escala de espaciado que los bloques compatibles utilicen como presets.

Las dimensiones generales del contenido pueden definirse mediante layout:

{
  "settings": {
    "layout": {
      "contentSize": "720px",
      "wideSize": "1200px"
    }
  }
}

contentSize establece la anchura normal del contenido y wideSize, la utilizada por los elementos con alineación amplia.

Esto permite trasladar directamente al tema decisiones que normalmente ya existen en el sistema de diseño.

Estilos adaptables en WordPress 7.1

WordPress 7.1 amplía las posibilidades de diseño adaptable dentro del propio sistema de estilos.

Los estilos pueden utilizar estados @mobile y @tablet para establecer variaciones destinadas a esos tamaños de pantalla. El estilo normal actúa como base, por lo que no es necesario un estado @desktop independiente.

Por defecto, WordPress utiliza 480 px para móvil y 782 px para tableta. Los temas pueden configurar estos puntos de ruptura mediante settings.viewport.

Esto permite representar dentro del sistema de estilos de WordPress muchos ajustes que anteriormente requerían media queries personalizadas.

No significa que el CSS adaptable deje de ser necesario. Los diseños complejos pueden seguir requiriendo reglas específicas. La ventaja es que las necesidades habituales pueden integrarse mejor en el mismo sistema que utiliza el resto del diseño.

La tipografía fluida, los presets de espaciado y los estados adaptables pueden complementarse: los valores fluidos sirven para cambios progresivos y los estados para modificaciones que deben producirse en puntos concretos.

styles: estilos globales y específicos

Mientras que settings establece las opciones disponibles, styles permite definir cómo debe presentarse el contenido por defecto.

Por ejemplo:

{
  "styles": {
    "color": {
      "background": "var(--wp--preset--color--neutral-light)",
      "text": "var(--wp--preset--color--brand-primary)"
    },
    "typography": {
      "fontFamily": "var(--wp--preset--font-family--sans-ui)",
      "lineHeight": "1.6"
    }
  }
}

También pueden definirse reglas para elementos concretos mediante styles.elements, como encabezados, enlaces o botones.

Los bloques individuales pueden recibir estilos propios a través de styles.blocks.

Por ejemplo, un bloque de cita puede utilizar un tratamiento tipográfico particular y un bloque de navegación puede tener reglas específicas de espaciado, mientras ambos siguen utilizando los mismos presets globales.

Este sistema permite relacionar tokens, estilos globales, elementos HTML y bloques específicos sin repetir innecesariamente las mismas decisiones.

No elimina la necesidad de CSS. Selectores complejos, animaciones, interacciones especiales o determinados componentes pueden seguir requiriendo hojas de estilos.

Controlar las opciones del editor

Una de las aplicaciones más interesantes de theme.json es limitar las posibilidades de personalización cuando el proyecto lo requiere.

Por ejemplo:

"custom": false

puede impedir que el usuario introduzca colores arbitrarios.

Del mismo modo, customFontSize puede controlar la disponibilidad de tamaños de fuente personalizados y defaultPalette puede utilizarse para decidir si se ofrece la paleta predeterminada de WordPress.

Estas restricciones no tienen por qué convertir el editor en una herramienta rígida.

El objetivo es decidir conscientemente qué opciones necesita quien crea contenido. Un equipo editorial puede necesitar cierta flexibilidad, mientras que en un sitio corporativo puede ser preferible ofrecer una selección mucho más reducida.

Bien configurado, el editor deja de ser un lienzo completamente abierto y pasa a reflejar las reglas del sistema de diseño.

Estilos específicos para bloques

Tanto settings como styles pueden incluir configuraciones destinadas a bloques concretos.

Por ejemplo:

{
  "styles": {
    "blocks": {
      "core/heading": {
        "typography": {
          "fontFamily": "var(--wp--preset--font-family--serif-display)",
          "fontWeight": "700"
        }
      },
      "core/button": {
        "border": {
          "radius": "4px"
        },
        "color": {
          "background": "var(--wp--preset--color--brand-accent)",
          "text": "#ffffff"
        }
      }
    }
  }
}

Esto permite que determinados bloques tengan un tratamiento propio sin abandonar los tokens compartidos por el resto del tema.

No debe confundirse esta posibilidad con la carga condicional de hojas de estilo. WordPress dispone de mecanismos específicos para asociar hojas CSS a bloques y cargarlas cuando corresponde. Son herramientas complementarias.

Variaciones de estilos

Un tema no tiene por qué ofrecer una única combinación visual.

Las variaciones de estilos son archivos JSON adicionales que normalmente se guardan en la carpeta /styles del tema. Pueden modificar parte de la configuración visual establecida por theme.json.

Por ejemplo, un tema podría ofrecer:

• una variante clara con fondo blanco y texto oscuro;
• una variante oscura con fondo oscuro y texto claro;
• una alternativa basada principalmente en otra tipografía;
• una combinación de colores específica para una sección o marca.

No es necesario duplicar todo el archivo principal. Una variación puede modificar únicamente aquello que cambia.

Esto permite ofrecer alternativas deliberadas dentro del sistema de diseño sin mantener varios temas independientes.

Para el diseñador, la ventaja es importante: las variaciones forman parte del sistema y pueden probarse y mantenerse como tales, en lugar de convertirse en una colección de modificaciones manuales realizadas página por página.

Relación con plantillas y partes de plantilla

theme.json trabaja junto con los elementos estructurales del tema, pero no los sustituye.

templateParts puede proporcionar metadatos para elementos reutilizables como la cabecera o el pie:

{
  "templateParts": [
    {
      "name": "header",
      "title": "Cabecera",
      "area": "header"
    },
    {
      "name": "footer",
      "title": "Pie",
      "area": "footer"
    }
  ]
}

customTemplates puede describir plantillas alternativas, por ejemplo una plantilla especial para páginas de destino.

La distinción resulta útil:

• theme.json define ajustes, estilos y determinados metadatos.
• Las plantillas establecen la estructura general con la que se muestra un tipo de contenido.
• Las partes de plantilla representan elementos estructurales reutilizables, como cabeceras y pies.

Relación entre theme.json y los patrones

Los patrones son composiciones reutilizables de bloques: una cabecera de página, una sección de testimonios, una llamada a la acción o una presentación de artículos relacionados.

Funcionan especialmente bien cuando utilizan los presets definidos en theme.json.

Si un patrón utiliza brand-primary en lugar de un código de color introducido directamente, un cambio posterior del preset puede reflejarse en los elementos que lo utilizan.

Conviene distinguir dos mecanismos.

La propiedad patterns de theme.json puede registrar patrones del directorio de patrones de WordPress.org mediante sus slugs.

Los patrones incluidos directamente con el tema se guardan normalmente como archivos en la carpeta /patterns, desde donde WordPress puede registrarlos automáticamente.

Esto permite pensar en el sistema por capas:

reglas y tokens globales → bloques → patrones → plantillas

Cada nivel resuelve un tipo distinto de reutilización.

De Figma a theme.json

No existe un único flujo de trabajo entre una herramienta de diseño y WordPress.

Un equipo puede definir colores, tipografías, espaciados y otros tokens en Figma y trasladarlos manualmente a theme.json.

Otros equipos utilizan scripts o herramientas específicas para transformar o sincronizar parte de esos datos.

La automatización no es el objetivo en sí misma. Lo importante es mantener una correspondencia clara entre el sistema de diseño y su implementación.

Por ejemplo:

Utilizar nombres coherentes evita preguntas como «¿cuál de estos cinco azules es el corporativo?» y facilita la comunicación entre diseño y desarrollo.

Buenas prácticas

Antes de empezar a añadir propiedades a theme.json, conviene definir las reglas que se quieren implementar.

La paleta, la escala tipográfica, el espaciado y las anchuras deberían responder a un sistema, no ser una acumulación de valores elegidos durante el desarrollo.

Utiliza nombres que expresen una función. brand-accent, text-primary o surface-light comunican más que blue-1 o grey-3.

Comprueba siempre el resultado tanto en el editor como en el frontal del sitio. theme.json ayuda a mantener la coherencia entre ambos, pero plugins, bloques de terceros y CSS adicional pueden introducir diferencias.

Prueba también contenido real: titulares largos, imágenes con proporciones diferentes, formularios, páginas antiguas y distintos tamaños de pantalla.

La accesibilidad debe formar parte del sistema desde el principio. Comprueba el contraste de las combinaciones previstas, la legibilidad de la tipografía y el comportamiento del contenido cuando aumenta el tamaño del texto.

Finalmente, utiliza control de versiones. Una modificación de un preset global puede afectar a muchas partes del sitio y, si varios sitios utilizan el mismo tema, a todos ellos.

theme.json y CSS personalizado

theme.json no elimina el CSS. Permite trasladar a un sistema estructurado muchas decisiones que antes se expresaban únicamente mediante reglas CSS.

El CSS sigue siendo apropiado para animaciones, selectores complejos, interacciones particulares, compatibilidad con determinados plugins y cualquier diseño que theme.json no pueda expresar adecuadamente.

WordPress también permite utilizar hojas de estilo específicas para bloques cuando esa solución resulta más apropiada.

Las variables generadas a partir de los presets de theme.json pueden utilizarse dentro del CSS personalizado:

.mi-elemento {
  color: var(--wp--preset--color--brand-accent);
}

Así, el CSS adicional sigue vinculado al sistema de diseño. Si cambia el valor de brand-accent, no es necesario modificar manualmente todas las reglas que utilizan esa variable.

El criterio no debería ser reducir el CSS hasta alcanzar una cantidad determinada de líneas. La cuestión es utilizar theme.json cuando representa bien una decisión y recurrir a CSS cuando CSS es la herramienta adecuada.

¿Qué papel tiene style.css?

style.css y theme.json cumplen funciones diferentes.

En un tema de bloques, style.css sigue formando parte de la estructura del tema y contiene la cabecera con sus metadatos. También puede contener estilos CSS globales cuando sean necesarios.

theme.json, por su parte, proporciona la configuración estructurada de ajustes y estilos del sistema de bloques.

No es necesario elegir entre uno y otro. Un tema puede utilizar theme.json, style.css y hojas de estilo específicas para bloques, asignando a cada mecanismo el trabajo para el que resulta más apropiado.

Probar los cambios antes de publicarlos

Un cambio en theme.json puede afectar a numerosas páginas y bloques.

Por eso conviene trabajar en un entorno de desarrollo o staging y utilizar control de versiones.

Antes de desplegar cambios, comprueba especialmente:

• encabezados de diferentes longitudes;
• páginas con contenido antiguo;
• imágenes con distintas proporciones;
• formularios y elementos interactivos;
• bloques proporcionados por plugins;
• móvil y tableta;
• combinaciones de color y contraste;
• patrones que dependan de los presets del tema.

La validación mediante $schema ayuda además a detectar propiedades o valores incorrectos durante la edición.

Preguntas frecuentes sobre theme.json

¿Puedo utilizar theme.json en un tema clásico basado en PHP?

Sí. Un tema clásico puede incorporar theme.json para aprovechar parte del sistema de ajustes y estilos del editor de bloques.

Esto no lo convierte automáticamente en un tema de bloques ni activa la edición completa del sitio. Sus plantillas pueden seguir estando controladas por archivos PHP como index.php, header.php o footer.php.

Esta posibilidad permite introducir progresivamente un sistema de presets y estilos estructurados sin reconstruir el tema desde cero.

¿Qué ocurre si cometo un error en theme.json?

Un JSON mal formado o una configuración incorrecta puede impedir que determinadas reglas se interpreten como se esperaba.

Por eso resulta recomendable utilizar el esquema oficial, un editor que valide JSON, control de versiones y un entorno de pruebas.

Estas herramientas permiten detectar muchos errores antes de que los cambios lleguen al sitio en producción.

¿Cómo afecta theme.json a los editores de contenido?

Depende de cómo se configure.

Un sitio puede ofrecer una paleta cerrada, una escala tipográfica determinada y valores de espaciado predefinidos. Otro puede permitir más libertad.

La ventaja es que esa flexibilidad se decide como parte del sistema de diseño.

En proyectos donde se reduzcan considerablemente las opciones disponibles, conviene explicar los cambios al equipo editorial para que las nuevas limitaciones se entiendan como parte del funcionamiento del tema y no como un problema del editor.

¿Puedo migrar un tema antiguo a theme.json sin rehacerlo?

Sí. La adopción puede hacerse gradualmente.

Un primer paso consiste en identificar los valores que ya utiliza el tema —colores, tipografías, tamaños y espaciados— y convertir las decisiones repetidas en presets.

Después pueden trasladarse progresivamente otras reglas cuando theme.json proporcione una solución adecuada, manteniendo en CSS aquello que todavía lo requiera.

No es necesario transformar todo el tema de una sola vez.

¿theme.json mejora el rendimiento?

No debería utilizarse principalmente como una técnica de optimización.

Una configuración estructurada puede simplificar la arquitectura de estilos y evitar ciertas duplicaciones, pero utilizar theme.json no convierte automáticamente un tema en uno más rápido.

El rendimiento depende también de imágenes, fuentes, scripts, plugins, bloques, hojas de estilo y otros recursos.

WordPress dispone además de mecanismos específicos para cargar estilos asociados a determinados bloques. Esas posibilidades deben distinguirse de las funciones propias de theme.json.

¿Cómo contribuye theme.json a la accesibilidad?

theme.json puede ayudar a establecer decisiones visuales más coherentes: paletas con combinaciones de contraste adecuadas, escalas tipográficas legibles, espaciados consistentes y opciones editoriales controladas.

También puede reducir el riesgo de que un editor introduzca accidentalmente determinados colores o tamaños que se aparten del sistema previsto.

Sin embargo, theme.json no garantiza por sí mismo la accesibilidad de un sitio. La estructura del contenido, la navegación mediante teclado, los formularios, los textos alternativos, el HTML generado y muchos otros aspectos también deben diseñarse y probarse adecuadamente.

Del sistema de diseño a WordPress

La mejor forma de entender theme.json no es como un sustituto de CSS ni como un archivo técnico cuyas propiedades haya que memorizar.

Es una forma de convertir decisiones recurrentes de diseño en reglas que WordPress puede entender y reutilizar.

Una paleta se convierte en presets de color. Una escala tipográfica, en familias y tamaños disponibles en el editor. Los espaciados pasan a ser valores reutilizables. Las anchuras forman parte de la configuración del layout. Las alternativas visuales pueden convertirse en variaciones de estilos y muchas decisiones adaptables pueden integrarse en el mismo sistema.

Bloques, patrones y plantillas pueden construirse después sobre esas reglas compartidas.

Utilizado de esta manera, theme.json se convierte en un punto de encuentro entre diseño, desarrollo y edición de contenido: el diseñador define el lenguaje visual, el desarrollador implementa las reglas necesarias y quien mantiene el contenido trabaja con opciones que ya reflejan las decisiones fundamentales del diseño.

WordPress como CMS