Introducción: por qué diseñar callouts para notas y advertencias

En posts técnicos de WordPress, los callouts —cajitas visuales que contienen notas, advertencias, consejos o información importante— mejoran la lectura, la comprensión y la jerarquía visual. Bien diseñados, ayudan al lector a identificar rápidamente información crítica sin romper el flujo del artículo. Este tutorial explica con detalle cómo diseñar callouts accesibles, consistentes y fáciles de mantener en un sitio WordPress, con ejemplos prácticos para CSS, shortcode PHP y uso en el editor de bloques.

Principios de diseño a seguir

• Claridad: el mensaje debe leerse con facilidad evita frases largas dentro del callout.
• Contraste: suficiente contraste texto/fondo para cumplir accesibilidad (AA/AAA cuando sea posible).
• Consistencia: usar estilos y colores coherentes a través del blog.
• Semántica y accesibilidad: usar roles ARIA apropiados y elementos semánticos para lectores de pantalla.
• Adaptabilidad: que funcionen bien en móvil y en impresión.

Decisiones previas

• ¿Usar clases CSS simples o crear un bloque de Gutenberg? Para proyectos pequeños, las clases CSS shortcodes son suficientes. Para un ecosistema editorial profesional, un bloque de Gutenberg ofrece control visual dentro del editor.
• ¿Iconos SVG o fuentes de iconos? SVG inline permite controlar color y accesibilidad sin cargas externas.
• ¿Animaciones? Úsalas con moderación para interacciones no esenciales evita animaciones que distraigan.

Implementación 1 — CSS y HTML simples (recomendado como base)

La opción más rápida y flexible es añadir CSS al tema (o a un CSS personalizado) y usar clases en los bloques del editor (Grupo, Parrafo) o en shortcodes. A continuación un CSS base con variantes.

/ Callout base /
.callout {
  display: flex
  gap: 1rem
  align-items: flex-start
  padding: 1rem
  border-radius: 6px
  border: 1px solid transparent
  font-size: 0.95rem
  line-height: 1.4
  margin: 1rem 0
}

/ Icon container /
.callout__icon {
  flex: 0 0 36px
  width: 36px
  height: 36px
  display: inline-grid
  place-items: center
  border-radius: 50%
  font-size: 1.1rem
}

/ Content /
.callout__content {
  flex: 1 1 auto
}

/ Variantes /
.callout--note {
  background: var(--callout-note-bg, #eef7ff)
  color: var(--callout-note-color, #044b8b)
  border-color: rgba(4,75,139,0.12)
}
.callout--warning {
  background: var(--callout-warning-bg, #fff6e6)
  color: var(--callout-warning-color, #7a4b00)
  border-color: rgba(122,75,0,0.12)
}
.callout--tip {
  background: var(--callout-tip-bg, #eefaf0)
  color: var(--callout-tip-color, #0f6b3a)
  border-color: rgba(15,107,58,0.12)
}

/ Accesibilidad: foco visible si el callout es interactivo /
.callout[tabindex=0]:focus {
  outline: 3px solid rgba(21,156,228,0.25)
  outline-offset: 2px
}

/ Responsividad /
@media (max-width: 540px) {
  .callout {
    gap: 0.75rem
    padding: 0.75rem
  }
  .callout__icon {
    width:32px height:32px font-size:1rem
  }
}

Este CSS usa variables CSS (opcional) para facilitar personalización desde el tema. Añade estas variables en :root o en un selector de tema si quieres controlarlas desde el Customizer.

Ejemplo de HTML (para insertar en el editor como HTML o plantilla)

  
⚠️
  

    Advertencia: Antes de ejecutar este script, haz una copia de seguridad de la base de datos.
  

Implementación 2 — Shortcode en functions.php (para editores clásicos o bloques)

Un shortcode permite editar contenido sin tocar HTML y reutilizar callouts con parámetros para tipo, título y icono.

/ Añadir al functions.php del tema hijo o plugin personalizado /
function mi_callout_shortcode( atts, content = null ) {
    atts = shortcode_atts( array(
        type => note,      // note  warning  tip
        title => ,         // título opcional
        icon => ,          // carácter emoji o HTML de SVG
    ), atts, callout )

    type = esc_attr( atts[type] )
    title_html = atts[title] ?  . esc_html( atts[title] ) .   : 
    icon_html = atts[icon] ?  . atts[icon] .  : ℹ️

    html  = 

    html .= icon_html
    html .= 

    html .= title_html . do_shortcode( content )
    html .= 

    return html
}
add_shortcode( callout, mi_callout_shortcode )

Uso en editor (bloques o clásico):

[callout type=warning title=Advertencia icon=⚠️]Este cambio es irreversible. Asegúrate de tener copia de seguridad antes de continuar.[/callout]

Notas sobre seguridad

• Asegúrate de sanear atributos y contenido (como en el ejemplo con esc_html/esc_attr y do_shortcode) para evitar XSS.
• Si permites HTML en iconos, controla el contenido permitido con wp_kses si procede.

Implementación 3 — Patrón o bloque de Gutenberg (opcional avanzado)

Para una experiencia de edición visual coherente, crea un patrón reutilizable (pattern) o un bloque personalizado. Si quieres una solución rápida sin JavaScript, define un patrón JSON o PHP que contenga la estructura HTML con clases y agrégalo a los patterns del tema.

1. Crear un patrón con la estructura del callout (Grupo Icono Párrafo) y registrar en functions.php.
2. Para bloques personalizados que expongan controles (selección de tipo, icono, título), crea un bloque con registerBlockType y atributos esto requiere JavaScript (React/JSX).

Ejemplo de registro de pattern simple (functions.php):

register_block_pattern(
  mi-tema/callout-warning,
  array(
    title       => Callout — Advertencia,
    content     => 
⚠️
Advertencia: Texto del aviso...
,
  )
)

Accesibilidad y consideraciones semánticas

• Usa role=region o role=alert con cuidado: role=alert notifica automáticamente a lectores de pantalla y solo es adecuado para mensajes asíncronos para contenido estático mejor role=region y aria-label/aria-labelledby.
• Asegura contraste mínimo 4.5:1 para texto normal (AA) o 3:1 para texto grande.
• Provee foco visible si el callout puede recibir foco (ejemplo: tabindex=0).
• Si el callout contiene enlaces, comprueba que sean navegables con teclado.

Opciones de personalización y mantenimiento

• Variables CSS: expón colores en :root o en un selector de tema para que el equipo editorial pueda cambiar colores sin tocar CSS.
• Customizer: añade opciones en el Customizer para colores principales de callouts y pinta variables CSS desde PHP.
• Bloques reutilizables: crea bloques reutilizables en el editor para que editores no técnicos inserten callouts con contenido personalizado.

Ejemplo de variables CSS en :root

:root{
  --callout-note-bg: #eef7ff
  --callout-note-color: #044b8b
  --callout-warning-bg: #fff6e6
  --callout-warning-color: #7a4b00
  --callout-tip-bg: #eefaf0
  --callout-tip-color: #0f6b3a
}

Print y consideraciones móviles

• Para impresión, simplifica estilos y considera color de fondo: muchos navegadores no imprimen fondo por defecto. Añade un borde visible para distinguir el callout en papel.
• En móviles, reduce padding y tamaño de icono para evitar que el callout ocupe demasiado espacio vertical.

Tabla rápida de variantes y usos sugeridos

Ejemplos prácticos listos para usar

Fragmentos directos para pegar en functions.php (shortcode), CSS y ejemplo de uso en el editor.

/ Shortcode completo (versión resumida) /
function mi_callout_shortcode( atts, content = null ) {
    atts = shortcode_atts( array(type=>note,title=>,icon=>), atts, callout )
    type = preg_replace(/[^a-z0-9_-]/, , atts[type])
    title = atts[title] ?  . esc_html( atts[title] ) .   : 
    icon  = atts[icon] ?  . atts[icon] .  : ℹ️
    return 
 . icon . 
 . title . do_shortcode( content ) . 
}
add_shortcode(callout,mi_callout_shortcode)

/ CSS mínimo para que funcione inmediatamente /
.callout{display:flexgap:0.75rempadding:0.9remborder-radius:6pxborder:1px solid transparent}
.callout__icon{flex:0 0 36pxdisplay:inline-gridplace-items:centerborder-radius:50%}
.callout__content{flex:1}
.callout--note{background:#eef7ffcolor:#044b8bborder-color:rgba(4,75,139,0.12)}
.callout--warning{background:#fff6e6color:#7a4b00border-color:rgba(122,75,0,0.12)}
.callout--tip{background:#eefaf0color:#0f6b3aborder-color:rgba(15,107,58,0.12)}

[callout type=note title=Nota icon=💡]Recuerda actualizar el plugin a la última versión antes de probar esto.[/callout]

[callout type=warning title=Advertencia icon=⚠️]No uses este método en sitios en producción sin revisión previa.[/callout]

Buenas prácticas finales

• Documenta en el estilo editorial cuándo usar cada variante (nota vs advertencia vs tip).
• Incluye los estilos en tu tema hijo para que las actualizaciones del tema padre no los reemplacen.
• Usa patrones o bloques reutilizables para mantener consistencia entre autores.
• Prueba con lectores de pantalla y herramientas de contraste antes de publicar.

Recursos

Documentación oficial de WordPress sobre shortcodes y patterns está disponible en el sitio de WordPress: https://wordpress.org