Cómo crear un tema de bloques de WordPress personalizado con theme.json: Guía paso a paso

Resumen

Construir un tema de bloques de WordPress personalizado con Full Site Editing (FSE) puede ser abrumador, pero theme.json simplifica el proceso. Esta guía te guía a través de la configuración de un tema de bloques mínimo, la definición de estilos globales como colores y tipografía en theme.json, y la creación de plantillas personalizadas usando marcado de bloques. Aprenderás a añadir patrones de bloques y variaciones de estilo, permitiendo un sitio totalmente diseñable sin archivos PHP de plantilla. Cubriremos errores comunes, como mezclar características de temas clásicos y de bloques, y mostraremos cómo probar tu tema. Al final, tendrás un tema de bloques moderno y extensible listo para producción. Este enfoque aprovecha las capacidades más recientes de WordPress para un desarrollo más rápido y visual.

Introducción

Full Site Editing (FSE) ha revolucionado el desarrollo de temas de WordPress, permitiéndote diseñar visualmente cada parte de tu sitio. Pero muchos desarrolladores aún dependen de temas clásicos o tienen dificultades para crear temas de bloques desde cero. La clave para desbloquear el poder de FSE es theme.json—un archivo de configuración que controla estilos globales, configuraciones y plantillas. Este artículo proporciona una guía práctica, paso a paso, para construir un tema de bloques personalizado usando theme.json. Aprenderás a configurar la estructura de carpetas, definir paletas de colores y ajustes de tipografía, crear plantillas personalizadas con marcado de bloques y añadir variaciones de estilo. Al final, tendrás un tema de bloques listo para producción, fácil de mantener y extender. Sumérgete y desmitifica el desarrollo de FSE.

Para una visión más amplia de cómo FSE está dando forma al futuro del diseño de WordPress, consulta Gutenberg FSE: El futuro del diseño de WordPress en 2026.

1. Configuración de un tema de bloques mínimo

Un tema de bloques requiere un mínimo de dos archivos: style.css e index.html. Vamos a crearlos.

Estructura de carpetas

Crea una carpeta llamada my-block-theme en tu directorio wp-content/themes/. Dentro, coloca:

• style.css
• index.html
• (opcional) theme.json

style.css

Aunque los temas de bloques dependen menos de CSS, style.css sigue siendo necesario para la identificación del tema:

/*
Theme Name: My Block Theme
Theme URI: https://example.com
Author: Your Name
Description: A custom block theme built with theme.json.
Version: 1.0
Requires at least: 5.9
Tested up to: 6.5
Requires PHP: 7.4
License: GPL v2 or later
Text Domain: my-block-theme
*/

La línea Requires at least: 5.9 asegura que el tema funcione con la función FSE.

index.html

Esta es tu plantilla de respaldo. Debe comenzar con marcado de bloques. Crea un diseño simple:

<!-- wp:template-part {"slug":"header","tagName":"header"} /-->

<!-- wp:group {"layout":{"type":"constrained"}} -->
<div class="wp-block-group">
    <!-- wp:post-title /-->
    <!-- wp:post-content /-->
</div>
<!-- /wp:group -->

<!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->

Esto usa sintaxis de bloques para incluir partes de plantilla de encabezado y pie de página, y muestra el título y contenido de la entrada.

Advertencia: Los temas de bloques no deben contener archivos PHP de plantilla como header.php o footer.php. Mezclar plantillas clásicas y de bloques romperá FSE.

Activar el tema

Sube la carpeta mediante FTP o instalación zip, y actívala. Deberías ver un sitio en blanco con tu estructura mínima. A continuación, lo estilizaremos con theme.json.

2. Dominar theme.json: Estilos y configuraciones globales

theme.json centraliza todos los controles de diseño. Se encuentra en la raíz de tu carpeta del tema. Vamos a crear uno con configuraciones de color y tipografía.

Estructura básica

{
    "version": 2,
    "settings": {
        "color": {
            "palette": [
                {
                    "slug": "primary",
                    "color": "#007cba",
                    "name": "Primary"
                },
                {
                    "slug": "secondary",
                    "color": "#005a87",
                    "name": "Secondary"
                },
                {
                    "slug": "background",
                    "color": "#ffffff",
                    "name": "Background"
                }
            ],
            "gradients": []
        },
        "typography": {
            "fontFamilies": [
                {
                    "fontFamily": "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif",
                    "slug": "system",
                    "name": "System"
                },
                {
                    "fontFamily": "'Georgia', serif",
                    "slug": "serif",
                    "name": "Serif"
                }
            ],
            "fontSizes": [
                {
                    "slug": "small",
                    "size": "14px",
                    "name": "Small"
                },
                {
                    "slug": "medium",
                    "size": "18px",
                    "name": "Medium"
                },
                {
                    "slug": "large",
                    "size": "24px",
                    "name": "Large"
                }
            ]
        },
        "spacing": {
            "padding": true,
            "margin": true,
            "units": ["px", "em", "rem"]
        }
    },
    "styles": {
        "color": {
            "background": "var(--wp--preset--color--background)",
            "text": "var(--wp--preset--color--primary)"
        },
        "typography": {
            "fontFamily": "var(--wp--preset--font-family--system)",
            "fontSize": "var(--wp--preset--font-size--medium)"
        }
    }
}

Esto define una paleta de colores, familias de fuentes, tamaños de fuente y estilos globales. Las funciones var() hacen referencia a propiedades personalizadas CSS generadas automáticamente por WordPress. Los usuarios pueden luego cambiarlas en el Editor del sitio.

Consejo: Usa propiedades personalizadas CSS para consistencia. Evita codificar valores en archivos CSS; deja que theme.json sea la única fuente de verdad.

3. Creación de plantillas personalizadas

Las plantillas de bloques son archivos HTML con marcado de bloques. Siguen una jerarquía similar a los archivos de plantilla clásicos. Por ejemplo, crea single.html para entradas individuales:

<!-- wp:template-part {"slug":"header","tagName":"header"} /-->

<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<main class="wp-block-group">
    <!-- wp:post-title {"level":1} /-->
    <!-- wp:post-featured-image /-->
    <!-- wp:post-content /-->
    <!-- wp:post-navigation-link {"type":"previous"} /-->
    <!-- wp:post-navigation-link {"type":"next"} /-->
</main>
<!-- /wp:group -->

<!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->

Del mismo modo, crea page.html, archive.html, etc. También puedes crear plantillas personalizadas añadiendo un bloque wp:post-template dentro de un bucle de consulta.

Para personalización avanzada, considera construir bloques personalizados. Aprende cómo en Más allá de los bloques básicos: Creación de bloques de Gutenberg personalizados para funcionalidad mejorada de WordPress.

Partes de plantilla

Crea una carpeta parts/ para partes reutilizables. Por ejemplo, header.html:

<!-- wp:group {"tagName":"header","layout":{"type":"flex","flexWrap":"nowrap"}} -->
<header class="wp-block-group">
    <!-- wp:site-logo /-->
    <!-- wp:navigation {"themeLocation":"primary"} /-->
</header>
<!-- /wp:group -->

Y footer.html:

<!-- wp:paragraph {"align":"center"} -->
<p class="has-text-align-center">&copy; 2025 My Site</p>
<!-- /wp:paragraph -->

4. Añadir patrones de bloques y variaciones de estilo

Los patrones de bloques son diseños predefinidos. Defínelos en una carpeta patterns/. Crea patterns/hero.php:

<?php
/**
 * Title: Hero
 * Slug: my-block-theme/hero
 * Categories: hero
 */
?>
<!-- wp:cover {"overlayColor":"primary","minHeight":50,"align":"full"} -->
<div class="wp-block-cover alignfull" style="min-height:50vh">
    <span aria-hidden="true" class="wp-block-cover__background has-primary-background-color"></span>
    <div class="wp-block-cover__inner-container">
        <!-- wp:heading {"textAlign":"center","level":1,"style":{"color":{"text":"#ffffff"}}} -->
        <h1 class="has-text-align-center has-text-color" style="color:#ffffff">Welcome</h1>
        <!-- /wp:heading -->
        <!-- wp:paragraph {"align":"center","textColor":"white"} -->
        <p class="has-text-align-center has-white-color">This is a custom hero section</p>
        <!-- /wp:paragraph -->
    </div>
</div>
<!-- /wp:cover -->

Las variaciones de estilo permiten a los usuarios cambiar completamente el aspecto. Crea styles/default.json y styles/dark.json que sobrescriban la configuración del tema.

5. Advertencias y mejores prácticas

• Rendimiento: theme.json se almacena en caché. Limpia la caché después de los cambios. Usa el hook wp_register_theme_json si es necesario.
• Compatibilidad hacia atrás: Los temas de bloques solo funcionan desde WordPress 5.9. Si tu sitio debe admitir versiones anteriores, considera un enfoque híbrido pero evita mezclar archivos de plantilla.
• Temas hijo: Los temas de bloques se pueden usar como temas padre para temas hijo clásicos, pero no al revés. Usa template en style.css para declarar un tema de bloques padre.
• Internacionalización: Usa la función __() dentro de partes de plantilla PHP para cadenas traducibles. En el marcado de bloques, especifica el dominio de texto mediante el atributo textDomain.

Para más sobre mejores prácticas de desarrollo de plugins, consulta Construcción de plugins de WordPress robustos: Una guía práctica de mejores prácticas.

Conclusión

Construir un tema de bloques personalizado con theme.json te permite crear un sitio totalmente diseñable sin tocar PHP. Siguiendo esta guía, has configurado un tema mínimo, definido estilos globales, creado plantillas personalizadas y añadido patrones. Recuerda probar a fondo, especialmente para casos extremos como páginas de archivo o tipos de entrada personalizados. A medida que WordPress evoluciona, los temas de bloques se convertirán en el estándar. Comienza a aprovechar FSE hoy para optimizar tu flujo de trabajo y ofrecer a los clientes una flexibilidad sin igual.

Si quieres acelerar aún más la creación de temas, considera usar una herramienta que genere un sitio completo a partir de una descripción. Por ejemplo, puedes describir tu diseño deseado y obtener un tema de bloques listo para usar en minutos.

¿Listo para poner en marcha tu tema de bloques? Con una descripción en texto plano, puedes generar una página de aterrizaje o un sitio web completamente funcional, sin necesidad de código.