Extendiendo theme.json a Tipos de Publicación Personalizados y la Salida de Plugins: Una Guía Práctica

Resumen

Muchos desarrolladores de WordPress crean tipos de publicación personalizados o plugins que generan contenido (por ejemplo, testimonios, portafolios). Sin embargo, theme.json—la configuración central para estilos globales—a menudo ignora estos elementos personalizados por defecto, lo que lleva a un diseño desarticulado. Este artículo te guía a través del registro de tipos de publicación personalizados para heredar los estilos de theme.json, anular configuraciones para bloques específicos y conectar la salida de plugins con los tokens de diseño principales. Obtendrás instrucciones paso a paso, ejemplos del mundo real como estilizar un CPT 'Miembro del Equipo', y advertencias sobre rendimiento y conflictos de terceros. Al final, podrás asegurarte de que cualquier contenido personalizado coincida con el sistema de diseño definido por el editor de tu sitio.

¿Alguna vez has creado un tipo de publicación personalizado o integrado un plugin de terceros, solo para descubrir que su salida ignora por completo el hermoso sistema de diseño que configuraste minuciosamente en theme.json? No estás solo. Por defecto, theme.json solo se aplica a los bloques principales de WordPress y a los estilos de bloques registrados, dejando que los tipos de publicación personalizados y el contenido generado por plugins se las arreglen solos. Esto típicamente resulta en CSS en línea, pilas de fuentes duplicadas o una paleta de colores desajustada que rompe la experiencia del usuario. Pero hay una mejor manera: puedes extender theme.json para cubrir estos elementos personalizados, asegurando un sistema de diseño coherente y mantenible en todo tu sitio. En esta guía, cubriremos cuatro pasos prácticos para lograrlo, completos con ejemplos de código y advertencias del mundo real.

Comprendiendo el Alcance de theme.json

Antes de sumergirnos, es crucial entender que theme.json es un concepto de tema de bloques. Define estilos globales, configuraciones (como paletas de colores y tamaños de fuente) y estilos específicos de bloques para el editor de bloques y el frontend. Sin embargo, su alcance es limitado: solo controla los bloques que declaran explícitamente soporte para las propiedades de theme.json mediante register_block_type o el antiguo add_theme_support. Los tipos de publicación personalizados creados con register_post_type no heredan automáticamente estos estilos a menos que estén construidos con bloques o estilizados explícitamente.

Paso 1: Registrando Tipos de Publicación Personalizados con Soporte del Editor de Bloques

El primer paso es asegurarse de que tu tipo de publicación personalizado utilice el editor de bloques. Al llamar a register_post_type, establece 'show_in_rest' => true e incluye 'editor' en el array supports. Esto habilita el editor de bloques para ese tipo de publicación, permitiendo a los autores usar estilos a nivel de bloque de theme.json. Por ejemplo, aquí hay un CPT "Miembro del Equipo":

function create_team_member_cpt() {
    $args = array(
        'public' => true,
        'show_in_rest' => true,
        'supports' => array( 'title', 'editor', 'thumbnail', 'custom-fields' ),
        'show_in_menu' => true,
        'labels' => array(
            'name' => 'Team Members',
            'singular_name' => 'Team Member',
        ),
        'rewrite' => array( 'slug' => 'team' ),
    );
    register_post_type( 'team_member', $args );
}
add_action( 'init', 'create_team_member_cpt' );

Ahora, cuando edites una publicación de miembro del equipo, verás el editor de bloques con los estilos globales de tu tema aplicados a bloques principales como Párrafo, Título e Imagen. Esto por sí solo a menudo resuelve la mayoría de los problemas de estilo. Si necesitas un control más granular, continúa con el siguiente paso. Para una profundización sobre la construcción de temas de bloques con theme.json, consulta Cómo construir un tema de bloques personalizado de WordPress con theme.json.

Paso 2: Añadiendo Estilos de Bloques Personalizados mediante theme.json

A veces quieres aplicar estilos específicos a todas las instancias del contenido de tu tipo de publicación personalizado—por ejemplo, dar a toda la publicación un color de fondo o un relleno especial. Puedes apuntar a core/post-content o envolver tu contenido en un bloque de grupo personalizado y estilizarlo mediante theme.json. Añade lo siguiente a tu archivo theme.json bajo el objeto styles:

{
  "styles": {
    "blocks": {
      "core/post-content": {
        "css": "background-color: var(--wp--preset--color--light); padding: 2rem;"
      }
    }
  }
}

Esto aplicará un fondo claro y relleno al área de contenido de todas las publicaciones, incluido tu CPT Miembro del Equipo. También puedes definir variaciones específicas de bloques dentro de settings.blocks para proporcionar opciones de estilo en el editor.

Paso 3: Usando Propiedades Personalizadas de theme.json para la Salida de Plugins

Los plugins a menudo generan contenido mediante shortcodes, widgets o bloques personalizados. Para estilizarlos de manera coherente, aprovecha las propiedades personalizadas de CSS que theme.json genera. Por ejemplo, si tu tema define un color primario como --wp--preset--color--primary, puedes usarlo en el CSS de tu plugin:

.my-plugin-button {
    background-color: var(--wp--preset--color--primary);
    font-size: var(--wp--preset--font-size--medium);
}

Esto asegura que cuando el administrador del sitio cambie la paleta de colores en theme.json, el botón de tu plugin se actualice automáticamente. Para hacer esto robusto, siempre usa las variables CSS predefinidas en lugar de codificar valores. Además, si tu plugin registra sus propios bloques, puedes heredar la configuración de theme.json usando useSetting en JavaScript o pasando $attributes en el renderizado PHP, como se cubre en Dominando los Bloques Dinámicos de WordPress.

Paso 4: Manejando Bloques Dinámicos

Para bloques personalizados que generan contenido dinámico (por ejemplo, un slider de testimonios), necesitas registrar el bloque con soporte del editor de bloques y vincularlo explícitamente a theme.json. En PHP, usa register_block_type con $args que incluyan 'render_callback' y asegúrate de que el archivo block.json de tu bloque establezca 'supports' => array( 'color' => true, 'typography' => true ). Luego, en tu callback de renderizado, puedes acceder a los estilos globales mediante wp_get_global_styles() y aplicarlos. Por ejemplo:

function render_testimonial_block( $attributes, $content ) {
    $styles = wp_get_global_styles();
    $color = $styles['elements']['link']['color']['text'] ?? '#000';
    return '<div style="color: ' . esc_attr( $color ) . ';">' . $content . '</div>';
}

Este enfoque asegura que tu bloque personalizado respete los tokens de diseño del tema. Para más información sobre el registro de bloques, consulta Construyendo Plugins Robustos de WordPress.

Advertencias

Si bien extender theme.json es poderoso, ten cuidado con estos escollos:

1. Rendimiento: Añadir demasiados estilos personalizados en theme.json puede inflar el archivo y aumentar el tiempo de análisis de CSS. Limítate a configuraciones globales y usa estilos específicos de bloques con moderación.
2. Conflictos de plugins: Algunos plugins restablecen o anulan la configuración de theme.json. Siempre prueba con un conjunto mínimo de plugins y considera engancharte a after_setup_theme para reaplicar tus personalizaciones.
3. Temas clásicos: Si tu tema no usa el editor de bloques (es decir, es un tema clásico), theme.json tiene un efecto limitado. Considera migrar a un tema de bloques o usar la función wp_enqueue_global_styles para cargar los estilos.
4. Caché del navegador: Los cambios en theme.json pueden no aparecer inmediatamente debido al almacenamiento en caché. Limpia la caché del navegador y usa versionado para tu hoja de estilo.

Conclusión

Para ahora, tienes una hoja de ruta clara para hacer que los tipos de publicación personalizados y las salidas de plugins funcionen bien con tu sistema de diseño de theme.json. La clave es registrar tu CPT con soporte del editor de bloques, definir estilos específicos para el bloque de contenido de la publicación, usar propiedades personalizadas de CSS en la salida del plugin y registrar tus bloques personalizados con una integración adecuada de theme.json. Este enfoque elimina la inconsistencia, reduce el mantenimiento y da a los administradores del sitio el poder de controlar la apariencia desde una única fuente de verdad. Comienza a implementar estos pasos hoy para aportar cohesión a tus proyectos de WordPress.