siddik-web/wp-block-theme-converter

Convertidor de Temas de Bloques de WordPress

Convierte proyectos HTML/CSS/JavaScript en temas de bloques de WordPress listos para producción con soporte de Edición Completa del Sitio (FSE), esquema theme.json v3, patrones de bloques, plantillas y compatibilidad con WooCommerce.

---\n

Principios de Comportamiento

Estos cuatro principios rigen cada decisión durante la generación del tema. No son negociables y anulan cualquier tentación de "simplemente hacerlo rápido".

Compensación: Estos principios se inclinan hacia la precaución sobre la velocidad. Para solicitudes triviales (una edición de un solo bloque, una corrección de CSS de una línea), usa el criterio — no toda tarea necesita el rigor completo.

1. Piensa Antes de Codificar

No asumas. No ocultes la confusión. Expón las compensaciones.

Antes de generar CUALQUIER archivo:

• Declara las suposiciones explícitamente. Si el usuario no especificó una paleta de colores, pila de fuentes o estrategia de diseño — dímelo. No inventes decisiones de diseño en silencio.
• Si existen múltiples interpretaciones, preséntalas. "Tu sección de héroe podría ser un bloque core/cover (con capacidad de paralaje) o un core/group con imagen de fondo (más simple). ¿Cuál prefieres?"
• Rechaza cuando sea necesario. Si el usuario pide algo que creará un tema pobre (por ejemplo, JS en línea en patrones, Alpine.js para un simple interruptor), dímelo y sugiere la alternativa nativa de WordPress.
• Si algo no está claro, detente. Nombra lo que es confuso. Pregunta. No generes 50 archivos basados en una suposición.

2. Simplicidad Primero

Código mínimo que resuelve el problema. Nada especulativo.

• Sin características más allá de lo solicitado. Si el usuario quiere un tema de página de aterrizaje, no incluyas soporte WooCommerce, modo oscuro o un patrón de boletín "por si acaso".
• Sin abstracciones para código de un solo uso. No crees una clase ThemeHelper para una sola función. No crees un config.php que solo se lee una vez.
• Sin "flexibilidad" que no fue solicitada. No agregues paneles de opciones del tema, configuraciones del personalizador o variaciones de bloques adicionales que el usuario no pidió.
• Si 200 líneas podrían ser 50, reescríbelo. Cada línea debe ganarse su lugar.
• Prefiere bloques centrales sobre patrones personalizados. Un bloque core/media-text es mejor que un patrón personalizado de medios+texto que reimplementa lo mismo.
• Prefiere theme.json sobre CSS. Si un estilo se puede expresar en theme.json, DEBE serlo. No escribas CSS para lo que theme.json maneja de forma nativa.

La prueba: ¿Un revisor senior de temas de WordPress diría que esto es demasiado complicado? Si es así, simplifica.

3. Cambios Quirúrgicos

Toca solo lo que debes. Limpia solo tu propio desorden.

Cuando el usuario tiene un tema EXISTENTE y quiere modificaciones:

• No "mejores" código adyacente. Si se te pide agregar un patrón de pie de página, no refactorices el patrón de encabezado.
• No refactorices cosas que no están rotas. Si el tema existente usa wp_enqueue_script() para algo, no lo migres a la Interactivity API a menos que se te pida.
• Iguala el estilo existente. Si el tema usa tabulaciones para la indentación, usa tabulaciones. Si usa snake_case para nombres de funciones, sigue el ejemplo.
• Si notas problemas no relacionados, menciónalos — no los arregles. "Noté que tu patrón de encabezado tiene un atributo style en línea. ¿Quieres que lo arregle también?"

Cuando TUS cambios crean huérfanos:

• Elimina importaciones/variables/funciones que TUS cambios dejaron sin usar.
• No elimines código muerto preexistente a menos que se te pida.

La prueba: Cada línea cambiada debe remontarse directamente a la solicitud del usuario.

4. Ejecución Orientada a Objetivos

Define criterios de éxito. Itera hasta verificar.

Para cada tarea, define criterios de éxito verificables ANTES de escribir código:

Tarea	Criterios de Éxito
Convertir página de aterrizaje a tema WP	El tema se activa sin errores. La página principal se renderiza visualmente idéntica a la fuente. Todos los patrones editables en el Editor del Sitio.
Generar theme.json	El JSON se valida contra el esquema v3. La paleta de colores coincide con la fuente. La escala tipográfica coincide con la fuente.
Crear un patrón de bloque	El patrón aparece en el insertador bajo la categoría correcta. El contenido es editable. Sin estilos en línea. Todas las cadenas traducibles.
Agregar soporte WooCommerce	Las plantillas de archivo de producto/producto individual/carrito/finalizar compra se renderizan. Compatibilidad HPOS declarada. Los bloques WC se cargan correctamente.
Corregir paridad del editor	Cada regla CSS del frontend tiene una regla coincidente en editor.css. La diferencia visual entre editor y frontend es cero.

Transforma las descripciones imperativas de tareas en objetivos verificables antes de comenzar:

En lugar de...	Transforma a...
"Haz que se vea bien"	"La página principal se renderiza visualmente coincidiendo con el HTML fuente. Sin estilos en línea."
"Arregla el error PHP"	"WP_DEBUG activado, error reproducido, corrección aplicada — debug.log limpio."
"Agrega soporte WooCommerce"	"El carrito, la finalización de compra y el archivo de producto se renderizan sin advertencias. HPOS declarado."
"Haz que los patrones sean editables"	"Todos los patrones en el insertador del Editor del Sitio. Cada elemento de texto/imagen editable sin tocar el archivo de patrón."

Para tareas de múltiples pasos, indica un plan breve con verificación en cada paso:

1. Auditar HTML fuente → verificar: mapa de componentes producido, sin ambigüedad restante
2. Generar theme.json → verificar: JSON validado, todos los tokens de diseño mapeados
3. Crear plantillas → verificar: todas las páginas tienen plantillas FSE correspondientes
4. Registrar patrones → verificar: los patrones aparecen en el insertador, el contenido es editable
5. Encolar assets → verificar: sin errores de consola, los estilos se cargan correctamente
6. Pasada de accesibilidad → verificar: el enlace de salto funciona, las relaciones de contraste pasan, los atributos ARIA presentes

Los criterios de éxito sólidos te permiten trabajar de forma independiente. Los criterios débiles ("haz que se vea bien") requieren aclaración constante.

---

Cuándo Usar Esta Habilidad

Activa esta habilidad cuando el usuario quiera:

• Convertir HTML/CSS/JS estático en un tema de WordPress
• Construir un tema de Edición Completa del Sitio (FSE) desde cero
• Escalar theme.json, patrones de bloques o plantillas de bloques
• Portar un sitio de aterrizaje, portafolio o comercio electrónico existente a WordPress
• Crear un tema de bloques compatible con WooCommerce
• Generar patrones de bloques individuales o plantillas a partir de fragmentos HTML

Comandos Slash Personalizados

Comando	Propósito	Archivo de Referencia
/convert-to-wp-theme	Conversión completa de proyecto HTML/CSS/JS a tema de bloques completo	commands/convert-to-wp-theme.md
/scaffold-wp-theme	Crear esqueleto de tema de bloques vacío (sin conversión de fuente)	commands/scaffold-wp-theme.md
/wp-pattern	Convertir una sección HTML individual en un patrón de bloque registrado	commands/wp-pattern.md
/wp-theme-json	Generar theme.json a partir de un sistema de diseño / propiedades personalizadas CSS	commands/wp-theme-json.md
/wp-template	Convertir una página HTML individual en una plantilla FSE	commands/wp-template.md
/wp-block	Escalar un bloque personalizado (block.json, edit.js, save.js/render.php, CSS)	commands/wp-block.md
/wp-migrate	Migrar contenido WP existente (Editor Clásico, ACF, widgets, CPTs, shortcodes) a tema de bloques	commands/wp-migrate.md
/wp-plugin-theme	Declarar dependencias de plugins y generar CSS / código de compatibilidad específico del plugin	commands/wp-plugin-theme.md
/wp-variation	Generar una variación de estilo (styles/*.json) — modo oscuro, intercambio de paleta de colores, intercambio de fuentes	commands/wp-variation.md
/wp-classic-to-fse	Convertir un tema clásico de WordPress existente (plantillas PHP) a tema de bloques FSE	commands/wp-classic-to-fse.md
/wp-debug	Depurar sistemáticamente problemas de temas de bloques de WordPress (pantalla blanca, errores del editor, regresiones de estilo)	commands/wp-debug.md

Cuando el usuario escriba uno de estos comandos, lee el archivo de comando correspondiente en commands/ y ejecuta el flujo de trabajo definido allí.

---

Flujo de Trabajo Principal

Para CUALQUIER solicitud de conversión (ya sea activada por comando slash o lenguaje natural):

Paso 1: Piensa — Captura y Clarifica (Principio 1)

Recopila estas entradas (pregunta solo si no se proporcionan):

• Identidad del tema (nombre, slug, autor, descripción)
• Tipo de proyecto fuente (página de aterrizaje, blog, comercio electrónico, portafolio, SaaS)
• Archivos HTML a convertir
• Tokens de diseño (colores, fuentes, espaciado)
• Preferencia del sistema de compilación (Vite 6 predeterminado, o wp-scripts, o ninguno)
• Soporte WooCommerce (sí/no)

Antes de proceder, declara explícitamente:

• Lo que estás asumiendo (por ejemplo, "Asumo que quieres licencia GPL-2.0-o-posterior ya que mencionaste el envío a WordPress.org")
• Lo que NO estás haciendo (por ejemplo, "No incluiré soporte WooCommerce ya que no mencionaste comercio electrónico")
• Cualquier ambigüedad que necesite resolverse (por ejemplo, "Tu héroe usa un fondo de video — ¿debería ser un core/cover con video o un patrón personalizado con una etiqueta <video>?")

Para valores predeterminados cuando el usuario guarda silencio, usa la tabla en references/defaults.md.

Paso 2: Planifica — Define Criterios de Éxito (Principios 1 + 4)

Antes de escribir cualquier código, produce un Plan de Conversión que mapee:

• Cada archivo HTML fuente → plantilla de WordPress
• Cada sección repetida → patrón de bloque
• Encabezado/pie de página → partes de plantilla
• Componentes interactivos → estrategia JS (Interactivity API preferida, encolado clásico para librerías complejas — lee references/modern-blocks.md)
• Tokens de diseño → estructura de theme.json
• Necesidades de datos dinámicos → candidatos de Block Bindings API

También declara los criterios de éxito para esta conversión específica:

CRITERIOS DE ÉXITO:
1. El tema se activa en WordPress [versión] sin errores o avisos PHP
2. [Lista de páginas] se renderizan visualmente coincidiendo con el HTML fuente
3. Todos los patrones aparecen en el insertador del Editor del Sitio bajo [categorías]
4. Todos los componentes interactivos funcionan (enuméralos)
5. Sin estilos en línea en el marcado de bloques
6. Todas las cadenas listas para traducción
7. PHPCS WordPress-Extra pasa con cero errores
8. [Cualquier criterio específico del proyecto]

Muestra este plan al usuario. Obtén confirmación antes de proceder a la generación de archivos (a menos que el usuario diga explícitamente "solo constrúyelo").

Paso 3: Ejecuta — Metodología de 10 Fases (Principio 2)

Sigue las fases documentadas en references/methodology.md. Aplica Simplicidad Primero en cada fase — genera solo lo que el proyecto necesita:

1. Auditar y Extraer — analiza la fuente, identifica componentes reutilizables
2. theme.json — genera esquema v3 con configuraciones + estilos completos (incl. Estilos de Sección, dimensiones, posición)
3. Plantillas y Partes — convierte páginas HTML a marcado de bloques FSE
4. Patrones de Bloque — registra secciones como patrones reutilizables
5. Estilos y Variaciones de Bloque — registra variantes personalizadas a través de theme.json + PHP
6. Integración JavaScript — Interactivity API para patrones interactivos; wp_enqueue_script() solo para librerías complejas. Lee references/modern-blocks.md PRIMERO.
7. functions.php y inc/ — archivos de arranque siguiendo los Estándares de Codificación de WordPress
8. Accesibilidad y Rendimiento — WCAG 2.1 AA + Core Web Vitals + carga de CSS por bloque + precarga de fuentes
9. i18n — cadenas listas para traducción en todas partes
10. README y Documentación — readme.txt en formato WordPress.org

Verificaciones de simplicidad durante la ejecución:

• ¿Estoy generando un archivo que no es necesario para este proyecto específico? → Elimínalo.
• ¿Estoy agregando un patrón que el usuario no pidió? → Elimínalo.
• ¿Estoy escribiendo CSS para algo que theme.json maneja? → Muévelo a theme.json.
• ¿Estoy creando una abstracción usada solo una vez? → Enlínea.
• ¿Puede este archivo de 200 líneas ser de 50 líneas? → Reescríbelo.

Paso 4: Archivos de Salida (Principio 3)

Usa la estructura de archivos documentada en references/file-structure.md. Muestra cada archivo con un encabezado claro:

=== FILE: {{theme-slug}}/path/to/file.ext ===
<contenido>

Para proyectos grandes (10+ páginas HTML o temas WooCommerce), divide la entrega en 3 turnos usando references/multi-turn-strategy.md.

Precisión quirúrgica para temas existentes: Si se modifica un tema existente, muestra SOLO los archivos cambiados. Incluye un resumen de diferencias que muestre exactamente qué cambió y por qué.

Paso 5: Verifica — Post-Generación (Principio 4)

Ejecuta el doctor automático primero. Antes de proporcionar la salida al usuario, ejecuta:

node scripts/doctor.mjs <theme-dir>

Esto ejecuta las cuatro comprobaciones de calidad (validación de theme.json, lint de marcado de bloques, comprobación de registro de patrón, cobertura i18n). No declares éxito hasta que el doctor salga con 0. Si sale con código distinto de cero, regresa a la fase relevante y corrige cada infracción reportada antes de continuar.

Luego proporciona:

• Instrucciones de instalación
• Lista de verificación posterior a la instalación (activar, configurar página principal, instalar plugins necesarios)
• Comandos de compilación (npm install, npm run dev, npm run build)
• Sección "Decisiones Tomadas" — cada suposición listada con su razón
• Pasos de verificación — cómo confirmar que se cumplió cada criterio de éxito:

VERIFICACIÓN:
✅ node scripts/doctor.mjs <theme-dir> → sale con 0 (todas las comprobaciones pasan)
✅ Activar tema → Confirmar que no hay errores PHP en debug.log
✅ Visitar página principal → Confirmar coincidencia visual con la fuente
✅ Abrir Editor del Sitio → Confirmar que todas las plantillas están listadas
✅ Insertar bloque → Confirmar que todos los patrones aparecen bajo las categorías correctas
✅ Ejecutar `npx phpcs --standard=WordPress-Extra .` → Confirmar cero errores
✅ Verificar consola del navegador → Confirmar cero errores JS
✅ Ejecutar Lighthouse → Confirmar puntuación de accesibilidad ≥ 90

Si algún paso de verificación falla, regresa a la fase relevante y arréglalo antes de reportar como terminado. No declares éxito después de una comprobación fallida.

Si el usuario reporta un problema con un tema generado, dirígelo a /wp-debug. Consulta references/troubleshooting.md para la referencia completa de síntoma → causa raíz → corrección.

---

Reglas de Calidad — No Negociables

Estas reglas se aplican a CADA archivo generado. Consulta references/quality-rules.md para más detalles.

❌ NUNCA:

• Atributos style="" en línea en el marcado de bloques
• Etiquetas <style> o <script> dentro de plantillas/partes/patrones
• Colores/espaciado hardcodeados en CSS — usa var(--wp--preset--color--{slug})
• Funciones obsoletas de WordPress
• Salida sin escapar (usa siempre esc_htm

...