Construcción de temas WordPress
El objetivo es un tema donde el diseño está fijado en código y el contenido es editable en el editor. El texto codificado directamente en las plantillas es la razón más común por la que los clientes vuelven para hacer cambios triviales.
Elegir el enfoque
| Enfoque | Cuándo elegirlo |
|---|---|
Tema de bloques (theme.json, plantillas HTML) | Nuevo proyecto, el cliente edita en el Editor del Sitio, el contenido es principalmente bloques estándar |
Tema clásico híbrido (plantillas PHP más theme.json y patrones de bloques) | Marcado personalizado complejo o animaciones pesadas que requieren control exacto del HTML |
| Tema hijo | Modificar un tema existente; nunca editar un tema padre directamente, ya que las actualizaciones lo sobrescriben |
Para sitios con animaciones y diseño orientado a marketing, el enfoque híbrido suele ser el pragmático: marcado preciso en PHP, contenido editable a través de patrones, campos y el editor de bloques.
Estructura mínima
mi-tema/
├── style.css # comentario de cabecera del tema (obligatorio)
├── functions.php # configuración, encolados, registros
├── theme.json # paleta, escala tipográfica, espaciado, anchos de layout
├── index.php # plantilla de respaldo (clásico/híbrido)
├── front-page.php # página de inicio
├── header.php footer.php
├── template-parts/ # un archivo por sección
├── patterns/ # patrones de bloques (registrados automáticamente)
├── assets/css assets/js assets/media
└── screenshot.png # 1200x900
Cabecera de style.css:
/*
Theme Name: Mi Tema
Author: Tu Nombre
Version: 1.0.0
Requires at least: 6.4
Requires PHP: 8.0
Text Domain: mi-tema
*/
Flujo de conversión
- Congelar la construcción estática. Terminar HTML, CSS y JS primero y validarlo. Convertir un objetivo en movimiento duplica el trabajo.
- Dividir en partes. El encabezado y el pie van a
header.phpyfooter.phpconwp_head()ywp_footer(). Cada sección de la página de inicio se convierte en un archivo entemplate-parts/, cargado conget_template_part(). - Mover los tokens a
theme.json(paleta, tamaños de fuente, espaciado, ancho de contenido) para que el editor muestre las mismas opciones que el frontend. Mantén los mismos valores que las propiedades personalizadas de CSS; WordPress genera variables--wp--preset--*que puedes alias. Si la CLIwebcraftestá disponible,webcraft tokens "#brand" --format theme-json -o theme.jsonescribe un archivo versión 3 a partir de los mismos valores quetokens.css. - Encolar, nunca codificar, los assets:
add_action('wp_enqueue_scripts', function () {
$v = wp_get_theme()->get('Version');
$uri = get_theme_file_uri('assets');
wp_enqueue_style('mi-tema', "$uri/css/main.css", [], $v);
wp_enqueue_script('gsap', "$uri/js/vendor/gsap.min.js", [], '3', ['strategy' => 'defer', 'in_footer' => true]);
wp_enqueue_script('mi-tema', "$uri/js/main.js", ['gsap'], $v, ['strategy' => 'defer', 'in_footer' => true]);
});
Agrupa las librerías localmente en lugar de desde una CDN cuando sea posible; evita una solicitud de terceros y un problema de consentimiento. 5. Hacer editable el contenido. Elegir por sección:
- Elementos repetitivos con sus propias páginas (servicios, portafolio, testimonios): un tipo de contenido personalizado consultado con
WP_Query. - Texto e imágenes de secciones únicas: patrones de bloques que el cliente inserta y edita, o campos personalizados.
- Elementos globales (teléfono, enlaces sociales, texto del pie): el Personalizador o una pequeña página de opciones.
- Navegación:
register_nav_menus()ywp_nav_menu().
- Escapar todo en la salida:
esc_html(),esc_attr(),esc_url(),wp_kses_post()para texto enriquecido. Encierra las cadenas en__()oesc_html__()con el dominio de texto. - Imágenes: usa
wp_get_attachment_image()para que se generensrcset,sizes, dimensiones y carga diferida. Registra los tamaños necesarios conadd_image_size(). - Soportes del tema:
title-tag,post-thumbnails,editor-styles,responsive-embeds,html5,wp-block-styles.
Animaciones dentro de WordPress
- Los scripts que ocultan contenido no deben ejecutarse en el editor de bloques. Encolarlos solo en el frontend (
wp_enqueue_scripts, noenqueue_block_assets). - La barra de administración desplaza los encabezados fijos 32px (46px en móvil); compensar con
body.admin-bar .header { top: var(--wp-admin--admin-bar--height, 32px); }. - Los plugins de caché y optimización que difieren o combinan JS pueden romper el orden de carga. Declara las dependencias correctamente para que sean respetadas, y prueba con el plugin activado.
- El contenido añadido en el editor no tendrá tus atributos de animación. Aplica las animaciones por clase de bloque en JS, o proporciona patrones que incluyan los atributos.
No hacer
- Editar el núcleo de WordPress o un tema padre.
- Poner funcionalidad que deba sobrevivir a un cambio de tema (tipos de contenido personalizados, shortcodes) en el tema cuando el cliente pueda cambiar de tema; un pequeño plugin es el lugar adecuado.
- Hacer consultas dentro de bucles sin reiniciar (
wp_reset_postdata()). - Entregar con avisos de
WP_DEBUG. Desarrollar conWP_DEBUGactivado. - Agrupar plugins de pago o assets cuya licencia no permita la redistribución.
Lista de verificación de entrega
- El cliente puede cambiar cada texto visible, imagen, elemento del menú y detalle de contacto sin tocar código.
- Página de inicio configurada en Ajustes, Lectura; enlaces permanentes configurados como nombre de entrada.
- Favicon (icono del sitio), plantilla 404, plantilla de búsqueda, página de privacidad presentes.
- Una guía de edición de una página con capturas de pantalla.
- Luego ejecutar la habilidad
launch-qa.