Imagebox: Reglas y ejemplos del recuadro de imagen

Un imagebox empareja una imagen con una explicación enfocada para que los lectores las procesen como una sola unidad editorial. La imagen puede aportar evidencia que el texto interpreta, o puede ilustrar una idea que el texto explica por completo. El autor debe declarar qué función cumple, porque esa elección controla el texto, el texto alternativo, el pie de foto, los datos estructurados y si el elemento sigue funcionando sin visión.

Esta es la variante de imagen de contenido: la fecha y el estado visibles son evidencia, mientras que el texto adyacente interpreta su relación. Si la imagen fuera meramente un calendario decorativo, el texto necesitaría plantear todo el punto de actualidad de forma independiente y la imagen usaría texto alternativo vacío.

Por qué es importante este elemento

Los lectores no procesan automáticamente una imagen y un párrafo distante como una sola idea. Cuando una imagen aparece sin una relación textual explícita, deben decidir qué inspeccionar, por qué es importante y si respalda la afirmación circundante. Un imagebox reduce esa incertidumbre al colocar un elemento visual y una explicación dentro de un límite claro. El título nombra el punto; la imagen lo muestra; el texto le dice al lector qué notar o comprender.

El beneficio psicológico es la atención conjunta: el diseño dirige la atención a un objeto visual mientras que el texto establece su relevancia. Un recorte de gráfico podría sugerir un aumento, volatilidad o un límite de fecha; la explicación adyacente selecciona la lectura relevante.

La extractabilidad automatizada es la capacidad del software de aislar una unidad de contenido sin perder la relación entre sus partes. Un imagebox semántico expone una imagen, descripción accesible, pie de foto, encabezado, explicación y rol de imagen declarado en un solo contenedor. El texto debe contener la afirmación: la visión por computadora no debe ser la única vía para acceder a un número, instrucción, limitación o conclusión.

Las reglas de escritura de elementos rigen la sintaxis de directiva compartida, el mapeo del cuerpo, las rutas y la precedencia. Esta página tiene prioridad donde define la distinción específica de imagebox entre contenido e ilustración, sus campos permitidos y su límite de una sola imagen.

Cuándo usarlo

Usa un imagebox cuando una imagen y una explicación tienen una relación directa y necesaria, y ninguna merece una sección independiente completa. Los usos sólidos incluyen un recorte de interfaz enfocado emparejado con una interpretación, un detalle de producto emparejado con una explicación de por qué afecta el ajuste, una fotografía de proceso emparejada con una regla de control de calidad, o una ilustración conceptual simple emparejada con una explicación concisa.

Primero decide si la imagen es de contenido o de ilustración:

• Imagen de contenido: el lector debe inspeccionar la imagen para verificar una afirmación, identificar una característica, comparar un estado o comprender un hecho visual. El texto nombra el detalle relevante y explica su importancia. El texto alternativo es significativo y normalmente hay un pie de foto.
• Imagen ilustrativa: la imagen refuerza el tono, la memoria o la comprensión, pero el texto adyacente proporciona la afirmación completa. Eliminar la imagen hace que el bloque sea menos atractivo, no menos preciso. El texto alternativo está vacío a menos que la ilustración en sí misma comunique información adicional.

Usa la prueba de eliminación. Si una solicitud de imagen fallida elimina evidencia o hace que la explicación sea incompleta, declara role=content. Si solo elimina el refuerzo visual, declara role=illustration.

Los casos límite son comunes:

• Usa una imagen independiente cuando el elemento visual necesita todo el ancho de lectura y el texto solo la identifica.
• Usa una captura de pantalla anotada cuando los lectores deban localizar múltiples regiones de la interfaz.
• Usa una tabla para criterios de comparación repetidos, un diagrama para un sistema o secuencia, y una galería para imágenes pares.
• Usa prosa ordinaria cuando el elemento visual meramente repite una oración.

No uses un imagebox para hacer que una sección débil parezca diseñada. Una fotografía de stock de personas señalando una laptop no explica «colaboración», y un robot genérico no hace más concreta una afirmación sobre inteligencia artificial. Si la imagen pudiera intercambiarse por una imagen no relacionada sin cambiar el texto, el emparejamiento no tiene un contrato editorial.

Dónde colocarlo

Coloca el imagebox inmediatamente después del párrafo que introduce la afirmación o concepto que desarrolla. En un procedimiento, colócalo después de la acción y antes de su verificación de éxito, para que la evidencia visual no interrumpa la instrucción.

Puede colocarse directamente debajo de un H2 solo cuando su título interno es más específico. Mantén una cita o calificación junto a la afirmación que limita; nunca insertes el imagebox entre ellas.

No debe colocarse directamente junto a otro imagebox, galería, figura de ancho completo, video, tabla o infobox de dos columnas. Inserta interpretación entre contenedores visuales, combina pares reales o crea subsecciones separadas.

No lo coloques dentro de una viñeta, paso, llamada, celda de tabla, acordeón o tarjeta cliqueable. No pongas una llamada a la acción dentro del bloque ni entre su imagen y explicación.

En escritorio, la imagen puede aparecer antes o después del texto. En móvil, preserva un orden predecible de fuente, teclado y lector de pantalla; no confíes en un reordenamiento contradictorio de CSS.

Anatomía

La anatomía se define por el significado, no por el color, la sombra o el ancho de columna.

1. Contenedor: Agrupa exactamente una figura y una explicación como una sola unidad editorial.
2. Imagen: Muestra evidencia o proporciona ilustración según el rol declarado.
3. Texto alternativo: Comunica el propósito visual relevante para una imagen de contenido; está vacío para una ilustración decorativa redundante.
4. Pie de foto: Identifica lo que muestra una imagen de contenido y proporciona contexto esencial como estado, fecha o escala.
5. Título: Expresa la idea o el tema, no el nombre del archivo ni una etiqueta genérica como «Ejemplo».
6. Explicación: Le dice al lector qué notar, por qué es importante y cualquier limitación de la interpretación.
7. Crédito: Nombra al creador o la fuente cuando los derechos, la procedencia o la política editorial lo requieren.
8. Orden de lectura: Preserva una relación coherente entre figura y texto cuando dos columnas se reducen a una.

La explicación debe referirse al tema directamente en lugar de usar coordenadas como «la imagen de la izquierda». La posición cambia entre puntos de ruptura, traducciones y sindicación. «El estado desactualizado y la fecha de actualización identifican el objetivo de revisión» sigue siendo cierto en todas partes.

Ejemplos de diseño

El sistema de diseño admite cuatro combinaciones de rol y posición. Ninguna cambia los requisitos de contenido.

Imagen de contenido, imagen al inicio

Usa esta opción por defecto cuando los lectores deben inspeccionar la evidencia antes de su interpretación.

Imagen de contenido, imagen al final

Usa esta opción cuando la explicación debe establecer un enfoque antes de la evidencia.

Ilustración, imagen al inicio

Usa esta opción cuando un visual específico del concepto mejora el reconocimiento mientras el texto transmite el significado completo.

Ilustración, imagen al final

Usa esta opción cuando la explicación es primordial y la ilustración actúa como cierre visual.

Comportamiento en viewport estrecho

Cada variante se convierte en una columna sin desplazamiento horizontal ni recortes que cambien el significado. El pie de foto permanece adjunto a su figura.

Parámetros

El contrato de contenido separa el significado editorial de la presentación. Las proporciones de ancho, espacios, bordes, fondos, radio, sombras y puntos de ruptura pertenecen al renderizador.

Publica src solo después de que el activo exista. Una captura pendiente usa un comentario de captura de pantalla y screenshotsPending = true. role no tiene valor por defecto porque tratar silenciosamente la evidencia como decoración crea un fallo de accesibilidad.

El primer encabezado del cuerpo se convierte en title; todo lo que sigue es content. El cuerpo permite párrafos, énfasis, código en línea y un enlace contextual. Rechaza listas, encabezados anidados, tablas, medios, botones, formularios, citas, acordeones y componentes.

Sintaxis y ejemplos de código

Las tres notaciones preservan el mismo rol, imagen, título, explicación, pie de foto, crédito y orden de lectura. Estos son contratos de adaptador portátiles; no implican que ya exista un shortcode o bloque local registrado.

Directiva Markdown portátil

:::imagebox{src="/cdn-assets/seo-playbook/examples/freshness-status.png" role=content position=image-start alt="Fila de informe de actualidad que muestra un estado desactualizado junto a una fecha de actualización del 12 de febrero de 2026" caption="El estado desactualizado se evalúa contra la fecha de actualización registrada."}
## Comprende por qué la página necesita revisión

La fecha de actualización visible explica por qué la auditoría clasificó esta URL como desactualizada. Verifica si la página ha cambiado desde esa fecha antes de asignar una reescritura.
:::

La ruta de ejemplo demuestra solo la sintaxis. La validación en producción debe rechazarla hasta que ese activo exista.

Shortcode de Hugo

{{< imagebox src="/cdn-assets/seo-playbook/examples/freshness-status.png" role="content" position="image-start" alt="Fila de informe de actualidad que muestra un estado desactualizado junto a una fecha de actualización del 12 de febrero de 2026" caption="El estado desactualizado se evalúa contra la fecha de actualización registrada." >}}
## Comprende por qué la página necesita revisión

La fecha de actualización visible explica por qué la auditoría clasificó esta URL como desactualizada. Verifica si la página ha cambiado desde esa fecha antes de asignar una reescritura.
{{< /imagebox >}}

El adaptador usa solo parámetros nombrados. Hasta que esté registrado, usa un <figure> semántico seguido de prosa. El adaptador valida el activo y preserva el mapeo del cuerpo de la directiva.

Bloque de WordPress

<!-- wp:amicited/imagebox {"src":"/cdn-assets/seo-playbook/examples/freshness-status.png","role":"content","position":"image-start","alt":"Fila de informe de actualidad que muestra un estado desactualizado junto a una fecha de actualización del 12 de febrero de 2026","caption":"El estado desactualizado se evalúa contra la fecha de actualización registrada."} -->
<figure class="wp-block-image">
  <img src="/cdn-assets/seo-playbook/examples/freshness-status.png" alt="Fila de informe de actualidad que muestra un estado desactualizado junto a una fecha de actualización del 12 de febrero de 2026">
  <figcaption>El estado desactualizado se evalúa contra la fecha de actualización registrada.</figcaption>
</figure>
<div class="imagebox__content">
  <h2>Comprende por qué la página necesita revisión</h2>
  <p>La fecha de actualización visible explica por qué la auditoría clasificó esta URL como desactualizada. Verifica si la página ha cambiado desde esa fecha antes de asignar una reescritura.</p>
</div>
<!-- /wp:amicited/imagebox -->

WordPress debe exponer un campo de Medios y una región de texto restringida. Si no está disponible, usa los bloques nativos de Imagen, Encabezado y Párrafo; preserva el significado incluso sin diseño lado a lado.

Ejemplos

Ejemplo correcto: la imagen es evidencia

Esto funciona porque la imagen prueba dos detalles físicos y el texto explica su consecuencia operativa. El título expresa la idea, el pie de foto identifica la evidencia visible y la explicación se mantiene específica sin intentar inventariar toda la fotografía.

Ejemplo incorrecto: decoración genérica presentada como prueba

Trabaja de forma más inteligente con datos claros Imagen: una persona genérica sonriendo frente a una laptop junto a gráficos coloridos. Nuestra plataforma innovadora transforma los datos en información procesable para que cada equipo pueda tomar mejores decisiones y lograr más.

Esto falla porque ninguna de las dos mitades aporta información verificable. La imagen podría anunciar cualquier producto de software, mientras que el texto contiene resultados amplios sin un mecanismo, detalle de interfaz, restricción o ejemplo. El emparejamiento crea prominencia visual pero ningún significado que un lector o una máquina pueda extraer. Reemplázalo con un estado de producto enfocado y una explicación de una decisión que respalde, o elimina el imagebox y escribe la afirmación como prosa ordinaria con evidencia.

Marcado de esquema y accesibilidad

Un imagebox no tiene un tipo dedicado de Schema.org. Su texto sigue siendo parte de la entidad de página circundante. Una imagen de contenido puede ser un ImageObject cuando tiene un contentUrl estable, pie de foto preciso, dimensiones y metadatos de crédito o licencia requeridos. Las ilustraciones decorativas no necesitan una entidad separada.

El esquema a nivel de página puede hacer referencia a la misma imagen representativa. Una fotografía de detalle de producto puede alimentar la propiedad image del producto visible, pero un recorte de gráfico no se convierte en Dataset y una captura de pantalla no se convierte en SoftwareApplication.

Usa un <figure> y <figcaption> más una región explicativa etiquetada. Establece width y height intrínsecos; la salida responsiva no debe desplazarse horizontalmente ni recortar el detalle nombrado.

El texto alternativo nombra el tema relevante, el estado y el detalle decisivo de una imagen de contenido. No comiences con «imagen de», no dupliques el pie de foto ni incluyas palabras clave. Las ilustraciones redundantes usan alt=""; omitir el atributo puede exponer el nombre del archivo.

No confíes únicamente en la posición, el color o los píxeles. Repite en texto todos los números, etiquetas, advertencias y conclusiones decisivas. Mantén los enlaces accesibles por teclado, no conviertas toda la caja en un enlace, preserva el orden de origen y prueba con un zoom del 200%.

Reglas de escritura

Escribe la explicación antes de seleccionar la imagen, luego elige el recorte más ajustado que preserve el contexto necesario.

• Escribe un título de 3 a 10 palabras que exprese la idea, el tema o la relación. Evita «Imagen», «Resumen», «Más información» y «Véalo en acción».
• Mantén el texto explicativo entre 40 y 140 palabras en uno o dos párrafos. El elemento admite un punto, no un artículo en miniatura.
• Mantén los pies de foto entre 5 y 25 palabras. Identifica lo que se muestra y el contexto necesario para interpretarlo; pon el razonamiento en el cuerpo.
• Usa de 40 a 180 caracteres para el texto alternativo significativo, con 250 como máximo estricto. Prioriza la precisión sobre llenar el rango.
• Incluye exactamente una imagen y no más de un enlace de texto contextual. Enlaza solo cuando un destino profundice materialmente la explicación.
• Usa una sola voz y tiempo verbal en el título, el pie de foto y el cuerpo. Prefiere sustantivos y verbos concretos sobre adjetivos promocionales.
• Declara la limitación junto a la interpretación cuando la imagen muestre solo un estado, fecha, recorte, dispositivo o ejemplo.

Nunca pongas una lista, tabla, testimonio, precio, formulario, medio, descarga, botón, instrucción de múltiples pasos, descargo de responsabilidad o llamada a la acción en el interior. No uses dos imágenes, incrustes texto esencial en píxeles, expongas datos del cliente ni publiques arte con derechos desconocidos.

Evita escribir «como puedes ver». Un lector puede no ver la imagen, e incluso un lector vidente necesita saber qué observación es importante. Dilo directamente: «La lengüeta de bloqueo queda al ras cuando el conector está completamente insertado».

Tipos de publicación que lo usan

Las filas siguientes se generan a partir del frontmatter postTypes. «Uso» describe un rol adecuado, no un requisito de forzar un imagebox en cada página.

Lista de verificación de control de calidad

Antes de la publicación, verifica el elemento completo:

• La imagen y la explicación plantean un solo punto y pertenecen a una sola unidad editorial.
• role está explícitamente como content o illustration, elegido con la prueba de eliminación.
• El archivo fuente existe, está aprobado y no utiliza datos privados, derechos desconocidos ni activos placeholder.
• El título expresa la idea en 3–10 palabras y el cuerpo la explica en 40–140 palabras.
• Una imagen de contenido tiene texto alternativo significativo y un pie de foto conciso; una ilustración redundante usa texto alternativo vacío.
• El texto indica cada número, etiqueta, instrucción, advertencia y conclusión decisiva que no puede depender de la vista.
• El pie de foto identifica la imagen sin duplicar el cuerpo ni el texto alternativo.
• Cualquier enlace requerido de creador, fuente, licencia o crédito es preciso y visible.
• El bloque contiene una imagen, una explicación y como máximo un enlace de texto contextual.
• No contiene listas anidadas, tablas, medios, botones, formularios, llamadas a la acción ni tarjetas interactivas.
• No reemplaza una mejor captura de pantalla anotada, comparación, diagrama, galería o figura de ancho completo.
• Los diseños de escritorio y móvil preservan el orden semántico de origen, la adjunción del pie de foto y el orden del teclado.
• El recorte significativo resiste el redimensionamiento responsivo, el zoom al 200 % y el fallo de carga de imagen.
• El ancho y el alto reservan espacio, mientras que la carga diferida no retrasa una imagen visible sin desplazamiento.
• Los datos estructurados, si se emiten, coinciden con el contenido visible y no describen la decoración como una entidad separada.
• Los mapeos de Markdown portátil, Hugo y WordPress retienen el mismo rol, campos y significado.

Preguntas frecuentes

La plantilla del academy renderiza las cinco preguntas revisadas almacenadas en el frontmatter [[faq]] de esta página. Cubren la prueba de contenido versus ilustración, el texto alternativo decorativo, el alcance descriptivo, las llamadas a la acción y el esquema ImageObject.

Un imagebox tiene éxito cuando el lector puede responder dos preguntas de inmediato: «¿Qué aporta esta imagen?» y «¿Por qué importa esa contribución aquí?». Si alguna respuesta es vaga, fortalece la relación o elimina la caja.