Cuadro de advertencia: cuándo y cómo usarlo

Un cuadro de advertencia detiene al lector antes de una acción que podría causar un daño material. No es un estilo de énfasis general. Una advertencia publicable indica el riesgo, la consecuencia y la acción que evita o limita el daño.

El elemento en vivo funciona porque identifica lo que puede salir mal, explica qué se perderá y brinda una secuencia segura antes del control destructivo. «Ten cuidado al eliminar» no sería suficiente: transfiere la evaluación del riesgo al lector sin decirle qué significa un comportamiento cuidadoso.

Por qué es importante este elemento

Las advertencias existen para cambiar una decisión antes de que ocurra un daño. Un lector que sigue instrucciones normalmente se concentra en alcanzar el resultado prometido, por lo que puede pasar por alto las salvedades que parecen información general. Una advertencia claramente delimitada interrumpe ese impulso en el punto donde el lector aún tiene una opción. Crea una pausa deliberada, explica por qué la pausa es importante y proporciona una acción segura a continuación.

Este elemento sirve a la psicología del lector solo mientras los autores lo usen de forma selectiva. Si los consejos rutinarios, las molestias menores y la pérdida irreversible reciben el mismo tratamiento, los lectores aprenden que la señal visual rara vez importa. Empiezan a saltarla. Por lo tanto, la exageración crea exactamente el modo de fallo que una advertencia pretende evitar: el mensaje importante se descuenta cuando lo que está en juego es real. El tono debe informar, no asustar.

La extraíble mediante máquina significa que el software puede aislar la advertencia y preservar su significado fuera de los párrafos circundantes. Un bloque tipificado con una etiqueta textual de advertencia y un cuerpo autocontenido es más fácil de identificar que una frase roja escondida dentro de un paso. La estructura riesgo–consecuencia–acción también sobrevive a los cambios de presentación. Un sistema de publicación automatizado puede mover el contenido entre Markdown, Hugo y WordPress sin inferir qué frase describe el daño o qué debe hacer el lector.

Sigue las reglas de redacción de elementos al mapear el elemento. El color, un icono, el texto en negrita o un encabezado llamado «Importante» no crean semántica de advertencia por sí solos. Las palabras deben permanecer completas cuando se copian como texto plano o se leen sin el estilo visual de la página.

Cuándo usarlo

Usa una advertencia cuando el lector esté a punto de tomar una decisión o realizar una acción con una consecuencia material previsible. El elemento es obligatorio cuando el contenido cubre alguno de estos desencadenantes:

• Acción irreversible: eliminación, sobrescritura, publicación, envío, cierre de cuenta u otra acción que no pueda deshacerse de forma fiable.
• Pérdida o exposición de datos: los registros pueden borrarse, corromperse, divulgarse, transferirse o volverse inaccesibles.
• Implicación de costo: una acción inicia un cobro, renueva un compromiso, consume una asignación pagada o genera un costo que no es obvio en el punto de decisión.
• Riesgo para la seguridad o la salud: seguir, combinar u omitir una instrucción podría causar lesiones, enfermedades o retraso en la atención.
• Exposición legal o de cumplimiento normativo: una acción podría infringir una ley, contrato, política, licencia, regla de retención, requisito de consentimiento o proceso de aprobación regulado.

El desencadenante, no la preferencia del autor ni el recuento de palabras disponible, controla la inclusión. Si aplica alguno, la advertencia no puede reducirse a una etiqueta vaga, trasladarse a un descargo genérico u omitirse para ajustarse a una plantilla. Acorta primero la explicación circundante.

No uses una advertencia para un atajo útil, una buena práctica, una definición, una molestia leve, un requisito previo normal o un error reversible con una recuperación obvia. Estos son casos límite porque pueden ser «importantes» en el lenguaje cotidiano, pero no requieren una decisión de detención. Coloca los requisitos previos necesarios en el procedimiento, las mejoras opcionales en un cuadro de consejo y la recuperación de fallos habitual junto al paso que repara.

No adviertas simplemente porque un resultado sea indeseable. «Los títulos de baja calidad pueden reducir los clics» es una explicación de rendimiento, no una advertencia. Se convierte en material de advertencia solo cuando una acción cercana crea una consecuencia específica y material: por ejemplo, cambiar la estructura de URL de un sitio en vivo sin redirecciones puede romper enlaces entrantes y eliminar destinos indexados. En ese caso, indica la acción preventiva antes del cambio.

Dónde colocarlo

Una advertencia pertenece inmediatamente antes de la primera acción a la que se refiere. «Acción» incluye una instrucción numerada, comando, envío de formulario, control de compra, descarga, recomendación o decisión que un lector pueda ejecutar. Coloca el cuadro después de suficiente contexto para identificar la situación, pero antes de la primera instrucción ejecutable. Nunca reveles el riesgo después de la acción, en notas al final ni solo en una FAQ de cierre.

Si una advertencia rige una secuencia, colócala antes de la secuencia y nombra su alcance: «Los siguientes tres pasos reemplazan la base de datos de producción». No repitas la misma advertencia dentro de cada paso. Si un paso posterior introduce un riesgo diferente, añade una segunda advertencia inmediatamente antes de ese paso.

Una advertencia no debe colocarse directamente junto a otro aviso, una llamada a la acción promocional o un banner decorativo. Los cuadros adyacentes compiten por la atención y pueden hacer que la advertencia parezca parte de un conjunto de marketing. No debe dividir una instrucción de su entrada requerida, una afirmación de su evidencia ni un título de tabla de la tabla. Añade una transición simple o reestructura la sección para que la advertencia califique claramente una decisión.

Coloca el texto legal según la política aplicable, pero mantén la advertencia operativa junto a la acción riesgosa. Trasladar la advertencia a un pie de página porque ya existe un descargo legal anula su propósito.

Anatomía

El elemento renderizado tiene seis regiones semánticas:

1. Etiqueta de gravedad: texto visible que indica que esto es una advertencia; no puede transmitirse solo mediante color o un icono.
2. Título específico: nombra la decisión o el peligro, por ejemplo, «Aviso: exporta los registros antes de eliminar».
3. Riesgo: indica qué acción o condición puede salir mal.
4. Consecuencia: indica el resultado creíble y quién o qué se ve afectado.
5. Acción: le dice al lector cómo evitar, reducir, verificar o escalar el riesgo antes de proceder.
6. Relación de posición: conecta la advertencia con la siguiente acción que rige.

La leyenda permanece como texto vivo de la página en lugar de estar incrustada en la imagen. Esto mantiene cada etiqueta disponible para la tecnología de asistencia y permite que el diseño cambie sin hacer que la especificación sea inexacta.

Ejemplos de diseño

La biblioteca actual admite un nivel de gravedad de advertencia: Hugo lo renderiza con type="important". No existe una variante separada de precaución, advertencia, peligro, crítico o emergencia. Esta simplicidad deliberada hace que la elección del autor sea coherente y reduce la probabilidad de que dos escritores asignen diferentes colores a la misma consecuencia. La desventaja es que el componente no puede distinguir visualmente una pérdida financiera recuperable de un peligro físico inmediato. Los autores deben indicar la gravedad en el título y la consecuencia en lugar de depender de un color más intenso.

Por lo tanto, la galería prueba el único nivel de gravedad bajo sus variaciones de contenido admitidas: la etiqueta predeterminada, un título personalizado específico, un máximo de dos párrafos y una ventana gráfica estrecha. Estos son casos de renderizado, no diferentes niveles de gravedad.

No inventes niveles de gravedad añadiendo emojis, mayúsculas sostenidas, signos de exclamación repetidos, clases personalizadas o valores de tipo no admitidos. Si la biblioteca más adelante incorpora múltiples niveles, sus límites deben basarse en la consecuencia y la respuesta requerida, no en la intensidad con la que el autor siente el pasaje.

Parámetros

El renderizador solo tiene entradas de type, title y cuerpo. El riesgo, la consecuencia y la acción son campos editoriales dentro del cuerpo; mantenerlos explícitos en este contrato evita que un aviso visualmente válido publique una orientación incompleta.

El título debe comenzar con «Aviso:» a menos que un vocabulario regulado requiera otra palabra de gravedad explícita. El cuerpo puede combinar riesgo y consecuencia en una oración, pero las tres tareas deben seguir siendo identificables. Un enlace puede dirigir a una política detallada o instrucciones de recuperación; no puede reemplazar la acción segura inmediata.

Sintaxis y ejemplos de código

Los tres mapeos llevan el mismo tipo, título y cuerpo. La directiva portátil es la forma canónica creada por el autor. Hugo utiliza el shortcode callout existente. WordPress puede implementar el mismo contrato como un bloque registrado; una forma de shortcode es aceptable solo donde esa instalación lo haya registrado.

Directiva portátil de Markdown

:::warning{title="Aviso: exporta los registros antes de eliminar"}
Eliminar el espacio de trabajo elimina permanentemente sus informes almacenados. Exporta los registros que debas conservar y verifica el nombre del espacio de trabajo antes de confirmar la eliminación.
:::

Shortcode de Hugo

{{< callout type="important" title="Aviso: exporta los registros antes de eliminar" >}}Eliminar el espacio de trabajo elimina permanentemente sus informes almacenados. Exporta los registros que debas conservar y verifica el nombre del espacio de trabajo antes de confirmar la eliminación.{{< /callout >}}

Usa los parámetros nombrados juntos. No mezcles el valor posicional important con un parámetro title nombrado.

Bloque o shortcode de WordPress

<!-- wp:amicited/warning {"title":"Aviso: exporta los registros antes de eliminar"} -->
<p>Eliminar el espacio de trabajo elimina permanentemente sus informes almacenados. Exporta los registros que debas conservar y verifica el nombre del espacio de trabajo antes de confirmar la eliminación.</p>
<!-- /wp:amicited/warning -->

[warning title="Aviso: exporta los registros antes de eliminar"]Eliminar el espacio de trabajo elimina permanentemente sus informes almacenados. Exporta los registros que debas conservar y verifica el nombre del espacio de trabajo antes de confirmar la eliminación.[/warning]

La presentación puede diferir entre sistemas, pero la gravedad textual, el riesgo, la consecuencia, la acción y la posición previa a la acción deben sobrevivir a la conversión.

Ejemplos

Bueno: reprocesamiento pago con riesgo de sobrescritura

Este ejemplo nombra dos riesgos concretos, indica ambas consecuencias y proporciona acciones que los previenen. Su tono es fáctico: no afirma que la cuenta se arruinará o que los datos serán irrecuperables si una exportación conservada proporciona una vía de recuperación.

Malo: riesgo sin orientación

El ejemplo malo no identifica la operación, describe la consecuencia creíble ni le dice al lector cómo proceder de forma segura. «Graves» es una afirmación de gravedad no respaldada, mientras que «bajo tu propio riesgo» traslada la responsabilidad en lugar de guiar el comportamiento. Reemplázalo con el cambio de estado exacto, qué puede perderse o vulnerarse, y la verificación, copia de seguridad, aprobación, alternativa o condición de detención requerida antes de la acción.

Otro fallo es el alarmismo excesivo: «¡Nunca toques esta configuración o todo tu sitio podría destruirse!» Incluso si la configuración es importante, la redacción no está delimitada por un resultado probable y no ofrece una ruta segura. Los lectores que descubren que la afirmación es exagerada desestimarán las advertencias posteriores.

Contenido legal y regulado

Un descargo legal y una advertencia realizan funciones diferentes. Un descargo define el alcance, las calificaciones, la incertidumbre, el estatus profesional o los límites de responsabilidad. Una advertencia identifica un peligro previsible en un punto de decisión y cambia lo que el lector debe hacer a continuación. Una no puede sustituir a la otra.

Para material legal, financiero, de salud, seguridad, privacidad u otro material regulado, mantén el descargo aprobado en su ubicación requerida en la página y añade una advertencia antes de cualquier acción específica que pueda generar exposición. Por ejemplo, una declaración general de que un artículo es educativo no elimina la necesidad de advertir antes de indicarle a un lector que suspenda un tratamiento recetado, transfiera datos regulados, publique una afirmación sin aprobación o acepte un cargo recurrente.

Los autores no deben improvisar conclusiones legales dentro de la advertencia. Usa la redacción aprobada por el revisor de la materia o de cumplimiento responsable, conserva cualquier terminología requerida y proporciona la acción operativa que el lector pueda realizar realmente: pausar, obtener consentimiento, conservar registros, consultar a un profesional cualificado, usar un canal aprobado o escalar para revisión. Un vago enlace a «consultar los términos» es insuficiente cuando la página puede indicar la condición de detención inmediata.

Marcado de esquema y accesibilidad

Un cuadro de advertencia no tiene una propiedad dedicada de Marcado de esquema y no debe crear un objeto independiente de JSON-LD . Permanece como contenido visible dentro del artículo que lo contiene. Cuando califica un procedimiento estructurado, su texto completo puede incluirse en la instrucción visible del paso correspondiente y en el HowToStep.text correspondiente; no debe convertirse en un paso falso ni existir solo en datos estructurados.

Las aplicaciones de Internet enriquecidas accesibles (ARIA) comunican el comportamiento de la interfaz a la tecnología de asistencia cuando el HTML nativo no lo proporciona. Las advertencias estáticas presentes cuando la página se carga deben permanecer en el orden normal del documento y no necesitan role="alert". Un rol de alerta provoca un anuncio inmediato y es apropiado solo cuando una advertencia urgente aparece dinámicamente después de una interacción. Aplicarlo a cada aviso estático puede interrumpir a los usuarios de lectores de pantalla y hacer que la entrada rutinaria a la página sea ruidosa. El renderizador actual de Hugo genera un <div> etiquetado sin un rol ARIA, lo cual es aceptable para un bloque estático cuando su texto y ubicación transmiten el significado.

La independencia del color significa que la advertencia sigue siendo reconocible en monocromo, modo de alto contraste, una exportación solo de texto y la salida del lector de pantalla. Usa un título explícito «Aviso:» y describe la gravedad con palabras: «elimina permanentemente», «inicia un cobro recurrente», «puede exponer datos personales» o «requiere atención médica». No escribas «evita la opción roja» ni dependas del texto alternativo de un icono para proporcionar el peligro.

Mantén el título y el cuerpo en orden de lectura antes de la acción regida. Los enlaces necesitan texto de anclaje descriptivo, el acceso por teclado no debe depender del aviso y las instrucciones esenciales no pueden aparecer solo en una captura de pantalla. Si un futuro componente interactivo permite el descarte, el descarte no debe ocultar una advertencia obligatoria mientras la acción permanezca disponible.

Reglas de redacción

Escribe una advertencia específica en 25–90 palabras y no más de dos párrafos cortos. Usa un título de 3–9 palabras, que normalmente comience con «Aviso:». Nombra la acción o condición desencadenante, la consecuencia creíble y la respuesta segura. Pon la razón antes de la regla: los lectores cumplen de forma más fiable cuando entienden lo que la regla previene.

Usa verbos proporcionales. «Elimina permanentemente», «sobrescribe», «cobra», «expone», «invalida» y «puede causar» describen mecanismos o resultados. «Devasta», «desastroso», «aterrador» y «catastrófico» suelen dramatizar en lugar de especificar. Indica la incertidumbre con honestidad cuando el resultado dependa del contexto, y nunca garantices la seguridad simplemente porque el lector siga una precaución.

Mantén un punto de decisión por cuadro. Una lista corta es aceptable solo cuando varias comprobaciones deben ocurrir antes de esa única acción; de lo contrario, usa prosa. No pongas copia promocional, beneficios, testimonios, chistes, emojis decorativos, consejos no relacionados, un procedimiento completo, una tabla comparativa, varios encabezados ni una llamada a la acción dentro de la advertencia. No ocultes instrucciones requeridas detrás de un enlace.

Nunca uses el cuadro para proteger una afirmación no respaldada, intimidar a un lector para que compre o crear urgencia artificial. Si la acción es requerida, mantén la acción en el procedimiento principal además de indicar el paso preventivo en la advertencia. El cuadro cambia la atención; no reemplaza la estructura operativa del documento.

Tipos de publicación que lo usan

El frontmatter postTypes registra los formatos registrados en los que los desencadenantes de advertencia son previsibles. En cada fila, «obligatorio» significa que el autor no tiene discreción una vez que aparece el desencadenante indicado; el elemento no puede eliminarse ni comprimirse por debajo de riesgo, consecuencia y acción para cumplir un objetivo de longitud.

Otros tipos de publicación pueden usar una advertencia siempre que aparezcan los mismos desencadenantes. La tabla define casos recurrentes y no opcionales; no concede una exención a los formatos omitidos de postTypes.

Lista de verificación de control de calidad

Antes de la publicación, verifica todo lo siguiente:

• El cuadro nombra una acción, condición o decisión específica que crea el riesgo.
• La consecuencia indica qué puede suceder y quién o qué se ve afectado sin exageración.
• La acción le dice al lector cómo evitar, reducir, verificar, detener o escalar el riesgo.
• La advertencia aparece antes de la primera acción regida y nombra claramente su alcance.
• Ningún consejo, promoción, banner o segunda advertencia compite directamente con ella.
• No se ha omitido ni acortado un desencadenante obligatorio por diseño o recuento de palabras.
• El tipo important y el título textual específico de advertencia están presentes.
• La gravedad sigue siendo clara sin color, iconos, imágenes ni contexto circundante.
• Una advertencia estática no utiliza un rol de alerta innecesario; una advertencia urgente dinámica se anuncia adecuadamente.
• Cualquier descargo legal permanece separado y no reemplaza la orientación en el punto de acción.
• La redacción regulada y la terminología requerida cuentan con la aprobación del experto en la materia correspondiente.
• Los mapeos de Markdown, Hugo y WordPress conservan el mismo título, cuerpo y posición.
• El cuerpo se mantiene entre 25 y 90 palabras, no contiene lenguaje de marketing y usa no más de un enlace necesario.
• Los comentarios de capturas de pantalla nombran solo las capturas futuras requeridas; no se renderiza ninguna ruta de imagen inexistente.

FAQ

¿Qué debe contener todo cuadro de advertencia? El riesgo específico, su consecuencia creíble y la acción segura deben estar presentes todos. El elemento está incompleto sin cualquiera de ellos.

¿Puede aparecer un cuadro de advertencia después de la acción riesgosa? No. Debe aparecer antes de que el lector pueda actuar, incluso si eso requiere reestructurar los pasos circundantes.

¿Un descargo legal reemplaza un cuadro de advertencia? No. El descargo define el alcance o las limitaciones; la advertencia cambia el comportamiento en un punto de decisión específico. Las páginas reguladas pueden requerir ambos.

¿Debe un cuadro de advertencia usar un rol de alerta? No cuando ya está presente en la carga de la página. Reserva el rol de alerta para información urgente introducida dinámicamente después de una interacción.

¿Cuántos cuadros de advertencia puede contener una página? Usa uno por punto de decisión distinto y consolida las advertencias con el mismo objetivo. Si las advertencias dominan la página, reestructura el procedimiento o reconsidera si la acción debería ofrecerse en absoluto.

Un cuadro de advertencia se gana su prominencia visual solo cuando previene un daño concreto. Indica el riesgo, la consecuencia y la acción con calma, colócalos antes de la decisión y preserva ese significado en cada salida.