Cuadro de consejo: Cuándo y cómo usarlo

Un cuadro de consejo resalta una técnica opcional que hace que una acción cercana sea más fácil, rápida, clara o fiable. No es un resumen decorativo: el lector puede saltárselo y seguir completando la tarea correctamente.

Ese ejemplo en vivo contiene una idea, aparece junto a la práctica que mejora y explica el beneficio. Esas tres propiedades —no el borde de color— hacen que sea un consejo.

Por qué este elemento es importante

Los lectores no asignan la misma atención a cada frase. En una página instructiva o con muchas decisiones, primero buscan el camino obligatorio, luego escanean atajos y técnicas que mejoren el trabajo. Un cuadro de consejo le da a una idea opcional inusualmente útil un límite estable. La etiqueta le indica al lector, antes de que invierta atención, «esto puede mejorar tu resultado, pero no cambia lo que cuenta como completo».

Esa distinción reduce la carga cognitiva, es decir, la cantidad de información que una persona debe retener y clasificar mientras lee. Sin una etiqueta, los lectores deben inferir si un comentario es un requisito, contexto o recomendación. Sin embargo, con demasiadas etiquetas, la página crea una segunda ruta de lectura que compite. Por lo tanto, la escasez es parte de la función del elemento: el contraste solo funciona cuando la mayor parte del contenido no está encuadrado.

La capacidad de extracción automática es la habilidad del software de aislar una unidad de contenido y conservar su propósito fuera de la página circundante. Un consejo tipificado le da a un sistema de búsqueda, herramienta de migración de contenido o agente de IA un type delimitado, un title opcional y un body. Puede preservar el hecho de que el consejo es opcional en lugar de aplanarlo como un paso obligatorio. El texto debe seguir siendo autónomo: «Prueba esto también» no es extraíble porque falta el objeto, mientras que «Prueba un cambio de título a la vez para que el resultado tenga una causa plausible» sigue siendo útil al citarse por separado.

El recuadro no es evidencia de importancia por sí mismo. Las reglas de redacción de elementos exigen que el significado determine el componente. Los redactores deben primero clasificar el consejo como opcional y que mejora el resultado, y luego aplicar la presentación de consejo. Elegir un recuadro porque la página se ve visualmente plana invierte ese proceso y genera ruido.

Cuándo usarlo

Usa un consejo cuando se cumplan las cuatro condiciones:

1. El consejo es opcional: omitirlo no hace que la tarea sea incorrecta, insegura o incompleta.
2. Mejora un resultado específico, como velocidad, claridad, precisión, confianza o facilidad de recuperación.
3. Modifica una instrucción, explicación o decisión cercana, no todo el artículo.
4. Es lo suficientemente útil como para que un lector que se saltó el párrafo circundante quisiera que estuviera señalado.

La cuarta condición es la prueba de salto. Pregunta: «¿Un lector que se saltó este párrafo querría que esta idea estuviera señalada?» Si la respuesta honesta es no, deja la frase en el texto. Si el lector no puede saltársela de forma segura, es un requisito o advertencia, no un consejo. Un recuadro solo se gana en el espacio estrecho entre esos resultados.

Los casos cercanos más comunes incluyen:

• Un requisito previo como acceso de administrador. Pertenece antes del procedimiento porque la tarea no puede comenzar sin él.
• Un criterio de éxito como «el estado debe mostrar Conectado». Pertenece al paso porque determina si la acción funcionó.
• Una definición necesaria para entender secciones posteriores. Define el término en el texto principal; no hagas que la comprensión necesaria parezca opcional.
• Un dato o cita de respaldo. Mantenlo junto a la afirmación que respalda, donde la relación de evidencia permanezca clara.
• Un recordatorio agradable como «recuerda escribir para tu audiencia». Es demasiado amplio para cambiar una acción específica.
• Un atajo útil que conlleva un riesgo significativo. Si la consecuencia pudiera causar pérdida o un cambio irreversible, indícalo como advertencia, incluso cuando el atajo en sí sea opcional.

Nunca uses un cuadro de consejo para repetir el párrafo que tiene al lado. La repetición consume la atención del lector sin añadir una decisión o técnica. Nunca pongas una llamada a la acción (CTA) —una invitación a registrarse, comprar, contactar o continuar hacia un paso comercial— dentro de él. La promoción cambia el propósito de ayuda práctica a conversión. Nunca uses un consejo para rescatar una sección que no supo explicarse por sí misma. Reescribe la sección para que su lógica obligatoria quede clara, luego decide si queda alguna mejora opcional genuina.

¿Consejo, nota o advertencia?

Estas tres etiquetas expresan consecuencias, no estados de ánimo ni opciones de color. Clasifica el contenido según lo que sucede cuando el lector lo ignora.

El componente actual de Hugo nombra el tratamiento de advertencia como important; el significado editorial sigue siendo advertencia. No suavices una advertencia real convirtiéndola en un consejo porque el tratamiento de consejo parezca más amigable. Del mismo modo, no uses el estilo de advertencia para hacer que un consejo opcional parezca urgente. Usar el estilo de advertencia para un consejo entrena a los lectores a ignorar las advertencias. Cuando luego aparezca un riesgo genuino, el lenguaje visual ya habrá perdido credibilidad.

Usa la prueba de consecuencia cuando la clasificación no esté clara. Si omitir el recuadro simplemente renuncia a una mejora, elige consejo. Si omitirlo no cambia nada y solo elimina contexto, elige nota. Si omitirlo puede causar daños, pérdidas, una acción irreversible o un resultado inválido, elige advertencia y haz explícita la consecuencia.

Dónde colocarlo

Un consejo se coloca inmediatamente después del párrafo, paso, instrucción de configuración del producto o criterio de compra completo al que modifica. El objetivo debe permanecer lo suficientemente cerca como para que el lector no tenga que inferir la conexión. Cuando se usa un título personalizado, nombra la acción objetivo en lugar de inventar un eslogan: «Comparar coste anual» es más claro que «Jugada maestra».

Usa no más de dos cuadros de consejo por página y uno por sección. Dos es un techo, no una cuota. Tres cuadros de consejo en un artículo hace que ninguno se lea como excepcional; convierte el grupo en prosa ordinaria o en una subsección breve. Si dos consejos fueran a estar adyacentes, quédate con el consejo más útil e integra la otra idea en el texto principal.

No coloques un consejo:

• Entre un encabezado y el párrafo inicial que explica ese encabezado.
• En el hero antes de que el lector conozca la tarea o decisión, excepto cuando esta especificación renderice el elemento en sí mismo como la demostración en vivo requerida.
• Dentro de otra llamada, celda de tabla, respuesta de FAQ, cita o bloque de código.
• Entre una afirmación y su evidencia, o entre una instrucción y su verificación de éxito requerida.
• Directamente junto a una advertencia. Los mensajes opcional y obligatorio compiten, y el recuadro de menor gravedad puede diluir la advertencia.
• Directamente junto a una CTA, banner promocional o propuesta de producto. El consejo práctico no debe parecer patrocinado por la acción.
• Dentro de un paso ordenado cuando hace que el límite del paso no esté claro. Termina el paso, incluyendo su condición de éxito, luego coloca el consejo debajo.

Si un consejo aplica a una sección completa, colócalo después del primer párrafo que establezca el contexto relevante y nombra el alcance en la primera frase. No dejes un consejo genérico al final de una sección larga y esperes que los lectores deduzcan cuál de las seis acciones anteriores modifica.

Anatomía

La anatomía tiene tres regiones de contenido visibles y una relación documental. La captura de pantalla etiqueta las regiones renderizadas; la explicación permanece como texto vivo para que siga siendo seleccionable, traducible y accesible.

Leyenda renderizada

1. Etiqueta de tipo: La palabra visible «Consejo». Comunica el estado opcional y debe existir como texto, no solo como color o icono.
2. Título opcional: Una frase corta que nombra la acción o decisión que se mejora. Cuando se omite, la etiqueta de tipo actúa como título.
3. Cuerpo: Una técnica autónoma seguida de su beneficio práctico o la ineficiencia que evita.
4. Objetivo adyacente: La instrucción o explicación completa inmediatamente antes del recuadro. La posición es parte del significado aunque no sea un campo de texto.

El borde, fondo, icono, espaciado y tipografía pertenecen al renderizador. Los autores no describen colores en el código fuente ni añaden emojis como etiquetas sustitutas.

Ejemplos de diseño

La galería admitida prueba la presión del contenido y el comportamiento responsivo, no diferentes significados. Cada versión sigue siendo un consejo y sigue los mismos límites editoriales.

Predeterminado: La etiqueta es «Consejo», el título se omite y el cuerpo contiene un par acción-beneficio conciso.

Título personalizado: El título identifica una decisión cercana específica. La semántica de consejo debe permanecer disponible incluso si el diseño visible enfatiza el título personalizado.

Máximo de dos párrafos: El primer párrafo da la técnica; el segundo explica el beneficio o límite. Este es el máximo, no el objetivo.

Viewport estrecho: La etiqueta, el título y el cuerpo conservan el orden de lectura, contraste suficiente y ajuste cómodo sin desplazamiento horizontal.

Parámetros

La interfaz separa el tipo semántico, el nombre opcional, el contenido y la colocación. «Fuente» identifica de dónde proviene el valor en el modelo de contenido portátil.

El cuerpo es el único contenido de autor obligatorio en la implementación actual de Hugo. El renderizador del sitio acepta un tipo posicional o un type nombrado, más un title nombrado opcional. No mezcles parámetros posicionales y nombrados en el mismo shortcode.

Sintaxis y ejemplos de código

Los mismos valores semánticos deben sobrevivir en todo sistema de publicación. Estos ejemplos usan copia idéntica para que una prueba de implementación pueda comparar tipo, título y cuerpo directamente.

Directiva Markdown portátil

:::tip{title="Prueba un cambio"}
Cambia una variable a la vez para que puedas conectar un movimiento en el resultado con una edición específica.
:::

El nombre de la directiva proporciona type="tip"; el atributo proporciona el título opcional; el Markdown encerrado proporciona el cuerpo.

Shortcode de Hugo

{{< callout type="tip" title="Prueba un cambio" >}}Cambia una variable a la vez para que puedas conectar un movimiento en el resultado con una edición específica.{{< /callout >}}

Esto usa solo parámetros nombrados. La forma posicional callout tip es válida cuando no se necesita un título personalizado, como se muestra en el ejemplo en vivo al inicio de esta página.

Bloque o shortcode de WordPress

[tip title="Prueba un cambio"]Cambia una variable a la vez para que puedas conectar un movimiento en el resultado con una edición específica.[/tip]

Una implementación de WordPress puede almacenar los mismos campos en un bloque personalizado en su lugar. Los controles del editor pueden cambiar la presentación, pero no deben cambiar el tipo semántico ni permitir que la etiqueta visible desaparezca.

Ejemplos

Esto es correcto porque el consejo es opcional, concreto y está junto a un flujo de trabajo de prueba. Contiene una idea —registrar la línea base— y explica exactamente cómo mejora la interpretación posterior. Un lector puede aplicarlo sin buscar en la página circundante el tema.

Mal consejo — Mantén tu trabajo seguro: Haz una copia de seguridad de la base de datos antes de ejecutar la migración. Si la migración falla sin una copia de seguridad, los registros de clientes podrían perderse permanentemente.

Esto es incorrecto porque el texto describe una salvaguarda obligatoria y una pérdida irreversible. Debe ser una advertencia colocada antes de la migración, no un consejo opcional colocado después. La etiqueta de tipo amigable minimiza la consecuencia.

Un segundo mal ejemplo no necesita renderizarse: «Consejo: usa encabezados claros». Si está junto a un párrafo que ya le dice al lector que escriba encabezados claros, simplemente repite ese párrafo. Añade una técnica opcional específica —como leer solo los encabezados para probar si forman un esquema útil— o elimina el recuadro.

Un tercer fallo es un recuadro que contiene una propuesta de función y un botón: «Consejo: inicia una prueba gratuita para automatizar esta verificación». Eso es una CTA, no un consejo editorial. Coloca la acción comercial en la posición de CTA designada de la página y mantén el consejo centrado en la ejecución.

Marcado de esquema y accesibilidad

Un cuadro de consejo no alimenta una propiedad dedicada de Schema.org, y no existe un tipo de datos estructurados TipBox. Sigue siendo contenido visible dentro del Article, TechArticle, página de producto u otro esquema veraz a nivel de página que lo engloba. JSON-LD —datos estructurados escritos en Notación de Objetos JavaScript para Datos Enlazados— no debe promocionar el consejo a un HowToStep obligatorio. Hacerlo cambiaría un consejo opcional a parte del procedimiento.

ARIA, el estándar de Accesibilidad para Aplicaciones de Internet Enriquecidas, añade nombres, roles y estados donde el HTML nativo no expresa suficiente información. Un consejo estático no necesita role="alert", porque no es urgente ni aparece de forma repentina. Renderízalo en el orden normal del documento como un contenedor etiquetado. Si se usa un rol de región genérica, conecta su nombre accesible a la etiqueta o título visible. No añadas un rol solo para que un lector de pantalla anuncie el recuadro de forma más agresiva.

La etiqueta es contenido, no decoración. Debe aparecer en el Modelo de Objetos del Documento (DOM), el árbol estructurado que leen los navegadores y las tecnologías de asistencia. Un borde verde, icono de bombilla o cambio de color de fondo pueden apoyar el reconocimiento, pero ninguno puede reemplazar el texto «Consejo». El orden de lectura debe ser etiqueta, título opcional y luego cuerpo. Los enlaces necesitan texto de anclaje descriptivo, y el componente debe seguir siendo comprensible con zoom de texto y cuando los colores personalizados no están disponibles.

Reglas de redacción

La banda de longitud normal es de 20 a 60 palabras. El máximo absoluto es de 80 palabras en no más de dos párrafos cortos. Por debajo de 20 palabras, los consejos suelen convertirse en eslóganes vagos; por encima de 80, suelen contener varias ideas o suficiente razonamiento como para merecer una subsección. Cuenta el significado en lugar de forzar relleno: una instrucción precisa de 14 palabras puede ser aceptable cuando su objetivo y beneficio son ambos inequívocos.

Usa una idea por recuadro. Un patrón útil es acción + razón: dile al lector qué técnica opcional probar, luego indica cómo mejora el resultado. Empieza con un verbo como «Registra», «Compara», «Previsualiza» o «Prueba». Usa un lenguaje tranquilo y apropiado para un consejo opcional. Palabras como «debes», «crítico», «peligro» y «nunca» suelen indicar que el contenido ha sido mal clasificado.

Un consejo puede contener énfasis simple, código en línea y como máximo un enlace descriptivo. Nunca debe contener:

• Un paso obligatorio, requisito previo, criterio de aceptación, condición legal o requisito de seguridad.
• Más de una recomendación independiente.
• Una CTA, botón, formulario, tarjeta de producto, cupón u oferta promocional.
• Una llamada anidada, tabla, encabezado, cita larga, galería de imágenes, vídeo o lista de varios pasos.
• El mismo consejo ya indicado en el párrafo adyacente.
• Urgencia infundada, una estadística inventada o una afirmación cuya evidencia no quepa junto a la prosa relevante.
• Un eslogan vago como «trabaja de forma más inteligente» o «crea contenido de alta calidad».

La escasez es una regla editorial, no solo una preferencia de diseño. Usa de cero a dos consejos por página y no más de uno por sección. Si un borrador supera el límite, aplica la prueba de salto a cada recuadro, quédate con el consejo que un lector apresurado lamentaría más perderse, e integra o elimina el resto. No combines consejos no relacionados en un solo recuadro solo para cumplir con el límite; eso viola la regla de una sola idea.

Tipos de publicación que lo usan

El frontmatter postTypes enumera los formatos registrados en los que este elemento puede ganarse un lugar. No exige el elemento en cada página de esos tipos.

Los tutoriales usan el contrato de guía práctica porque ambos formatos mueven al lector a través de una tarea ordenada. Las guías de compra usan más a menudo el contrato de lo mejor para X porque el consejo mejora la evaluación en lugar de reemplazar la evidencia. La configuración de producto también pertenece normalmente a una guía práctica; una página de producto puede usar un consejo solo cuando la guía de configuración genuina es parte del contenido principal de la página.

El cuadro de consejo explícitamente no es un elemento predeterminado en todo artículo. Noticias, opinión, glosarios, casos de estudio y páginas informativas simples a menudo no necesitan ninguno. No añadas uno para satisfacer una ranura de plantilla o crear variedad visual.

Lista de verificación de control de calidad

Antes de la publicación, un revisor verifica:

• Tipo correcto: Omitir el consejo no puede hacer que la tarea sea insegura, incorrecta, incompleta o inválida.
• Énfasis ganado: Un lector que hojeó el párrafo cercano realmente querría que esta idea estuviera señalada.
• Idea única: El recuadro contiene una técnica opcional y su beneficio, no una minisubsección.
• Escasez: La página contiene no más de dos consejos y la sección no más de uno.
• Colocación adyacente: La instrucción o explicación completa que se mejora está inmediatamente antes del recuadro.
• Sin colisión: El consejo no está junto a una advertencia, CTA, panel promocional, llamada anidada o consejo competidor.
• Sin repetición: El cuerpo añade una técnica o límite útil en lugar de repetir la prosa cercana.
• Longitud y tono: El cuerpo apunta a 20–60 palabras, nunca supera 80 y no usa urgencia falsa.
• Semántica visible: La etiqueta de texto «Consejo» existe en el DOM; el significado no depende del color o un icono.
• Calidad de extracción: El título y el cuerpo tienen sentido al citarse sin la página circundante.
• Contenido seguro: No hay pasos obligatorios, controles de riesgo, tablas, formularios, botones o componentes anidados dentro.
• Mapeo portátil: Las representaciones en Markdown, Hugo y WordPress preservan el mismo tipo, título y cuerpo.
• Sintaxis de parámetros: Hugo usa parámetros posicionales o nombrados, nunca una mezcla.

Si el recuadro falla la verificación de tipo o escasez, cambiar su color no es una solución. Reclasifica el contenido, devuélvelo a la narrativa principal o elimínalo.

FAQ

El frontmatter contiene las entradas de FAQ publicables para esta página. Refuerzan las decisiones operativas que los revisores necesitan con más frecuencia: cantidad máxima, clasificación semántica, pasos obligatorios, enlaces y si una página necesita un consejo o no.