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

Un cuadro de nota aísla el contexto que ayuda al lector a interpretar el contenido cercano, pero no cambia lo que el lector debe hacer, qué resultado esperar ni la gravedad de la situación.

Este ejemplo renderizado resuelve una posible pregunta sin añadir un paso. Un lector que lo omita puede seguir usando el informe correctamente. Un lector que note una diferencia horaria obtiene el contexto faltante y puede continuar sin cambiar el flujo de trabajo.

Por qué es importante este elemento

Los lectores escanean una página por prioridad visual. Una nota delimitada dice: «Este contexto puede resolver una duda, pero no es una instrucción nueva». Esa señal reduce el esfuerzo necesario para clasificar un comentario al margen. El lector puede alejarse brevemente del argumento principal, absorber la aclaración y volver al mismo punto sin preguntarse si el proceso ha cambiado.

El elemento funciona solo cuando esa promesa se mantiene fiable. Si los pasos necesarios, los mensajes de venta, las definiciones, las advertencias y los datos complementarios reciben todos el mismo estilo de nota, la etiqueta deja de ayudar. Los lectores deben inspeccionar cada cuadro para descubrir qué significa, lo que añade más carga cognitiva (el esfuerzo mental implicado en procesar información) de la que habría creado el texto normal.

Las etiquetas de gravedad también enseñan comportamiento mediante la repetición. Cuando un contexto inofensivo recibe colores de advertencia, los lectores se encuentran repetidamente con una señal urgente sin ninguna consecuencia real. Aprenden a pasar de largo. La siguiente advertencia genuina compite entonces con un historial de falsas alarmas. Usar mal el estilo de advertencia para las notas no solo hace que una página parezca melodramática; debilita el lenguaje de riesgo de todo el sitio.

Para las máquinas, una nota tipificada proporciona un límite y un propósito explícitos. Una herramienta de migración de contenido puede conservar el bloque como contexto complementario en lugar de fusionarlo en un paso del procedimiento. Un sistema de búsqueda o un agente de IA puede extraer la nota con su etiqueta y cuerpo, y mantenerla subordinada a la afirmación que explica. Esa relación es más difícil de recuperar a partir de un párrafo coloreado en azul con un estilo específico de la página.

La capacidad de extracción sigue dependiendo de la redacción. «Esto puede verse diferente» no es útil fuera de su párrafo porque falta el sujeto. «Las marcas de tiempo de los informes usan UTC, no la hora local del espectador» es autónomo. Las reglas de redacción de elementos tienen prioridad: clasifica el pasaje por su propósito primero, luego aplica el elemento registrado. El énfasis visual nunca crea el tipo semántico.

Cuándo usarlo

Usa una nota solo cuando se cumplan las cuatro condiciones:

1. El pasaje aclara una afirmación, valor, instrucción, ejemplo o secuencia cercanos.
2. Omitirlo no cambia la acción requerida, el resultado esperado, la interpretación correcta de la afirmación principal ni el nivel de riesgo.
3. El contexto responde a una pregunta verosímil del lector que de otro modo interrumpiría la comprensión.
4. El pasaje es lo suficientemente autónomo como para seguir teniendo sentido al extraerse con su etiqueta.

Un buen material para nota incluye una convención de zona horaria, un alias de nomenclatura, un límite de alcance ya implícito en el texto principal, una diferencia de interfaz inofensiva entre versiones o una explicación de un estado de visualización esperado. Por ejemplo: «El botón se etiqueta como Guardar en cuentas mensuales y como Aplicar en cuentas anuales; ambos envían la misma configuración». La acción y el resultado del lector no cambian.

Los casos límite importan porque «información útil adicional» es una definición demasiado amplia:

• Un dato necesario para entender el siguiente párrafo pertenece a la explicación principal. Ocultarlo en una nota hace que la comprensión esencial parezca opcional.
• Un requisito previo pertenece antes del procedimiento. Si no se puede empezar a trabajar sin acceso de administrador, el acceso no es contexto complementario.
• Una técnica opcional que hace el trabajo más rápido o mejor pertenece a un cuadro de consejo . Un consejo cambia la calidad o eficiencia del resultado; una nota no.
• Una condición que impide la eliminación, el costo, la exposición, lesiones o trabajos no válidos pertenece a un cuadro de advertencia . Su propósito es cambiar el comportamiento antes de que se produzca un daño.
• Una definición formal que establece el significado de un término pertenece al elemento de definición o a la explicación principal, no a una nota.
• Una cita debe estar junto a la afirmación que respalda. La evidencia no es un comentario al margen cuando la afirmación depende de ella.
• Una promoción, solicitud de registro o recomendación de producto es una llamada a la acción, no información.

Usa la prueba de «sin cambios» cuando la clasificación sea incierta: «Si el lector aprende este dato, ¿debe cambiar una acción, expectativa, decisión o respuesta de seguridad?». Si la respuesta es sí, no es una nota. Si es no, pregúntate si el dato resuelve una ambigüedad real. Si no es así, elimínalo o mantenlo como texto normal en lugar de crear énfasis artificial.

Dónde colocarlo

Coloca una nota inmediatamente después del bloque de contenido completo que aclara. El destino puede ser un párrafo, elemento de lista, paso, tabla, ejemplo de código o secuencia breve, pero el destino debe tener sentido antes de que aparezca la nota. La nota proporciona entonces contexto complementario sin dividir el destino.

Cuando una nota se aplica a una sección completa, colócala después del párrafo inicial que define el alcance de la sección. Menciona ese alcance en la primera frase de la nota. Cuando se aplica a un procedimiento, colócala después del párrafo introductorio y antes del primer paso solo si no cambia ninguna acción; de lo contrario, el contenido es un requisito previo o una advertencia. Una nota sobre un resultado pertenece después de que se haya introducido el resultado, no varios párrafos después.

Usa un máximo de tres notas por página y una por sección. Tres es un límite máximo. Si varias notas se agrupan alrededor de un mismo pasaje, probablemente al texto principal le falta una explicación o el material merece una subsección dedicada.

Una nota no puede situarse:

• Entre un encabezado y su párrafo inicial.
• Entre una afirmación y la evidencia que la respalda.
• Entre una instrucción y su comprobación de éxito necesaria.
• Directamente junto a un consejo, advertencia, CTA, banner promocional u otra nota.
• Dentro de una celda de tabla, respuesta de FAQ, cita, bloque de código, panel de acordeón u otro cartel.
• En un hero solo para crear interés visual, excepto cuando una especificación de elemento muestre su ejemplo en vivo requerido.
• Al final de una página cuando su destino apareció mucho antes.

Si la adyacencia creara una pila de cuadros, traslada la nota al texto o reestructura la sección. No resuelvas la colisión cambiando una nota a colores de advertencia; la presentación no puede reparar una relación de contenido poco clara.

Anatomía

La nota renderizada tiene cuatro regiones visibles o estructurales:

1. Etiqueta de tipo: La palabra visible «Nota», que identifica el bloque sin depender del color o de un icono.
2. Título opcional: Una frase breve y objetiva que nombre el contexto, como «Zona horaria» o «Etiquetas de interfaz».
3. Cuerpo: Una aclaración autónoma y, cuando sea útil, una frase que la conecte con el contenido cercano.
4. Destino adyacente: El bloque completo o la secuencia nombrada que se está aclarando. La colocación transmite esta relación aunque no sea un campo de texto editado.

Los bordes, fondos, iconos, espaciado y estilos tipográficos pertenecen al renderizador. Los autores aportan significado, no instrucciones de color ni símbolos decorativos.

Ejemplos de diseño

Las variantes compatibles prueban el contenido y el comportamiento adaptable. No crean diferentes niveles de importancia.

Predeterminado: El renderizador proporciona «Nota» y el cuerpo contiene una aclaración. Usa esta forma con más frecuencia.

Título personalizado: Un título objetivo identifica el tema. No aumenta la gravedad ni reemplaza la semántica de nota del componente.

Máximo de dos párrafos: El primer párrafo expone el contexto; el segundo resuelve un límite o una excepción inofensiva. Las explicaciones más largas pasan a ser contenido normal.

Referencia en línea: Un valor de código en línea o un enlace descriptivo puede aclarar el destino. Ninguno debe convertir la nota en documentación dentro de documentación.

Viewport estrecho: La etiqueta, el título y el cuerpo conservan su orden de lectura, se ajustan normalmente y siguen siendo comprensibles sin el borde ni el icono.

Parámetros

El modelo de contenido separa el tipo semántico fijo, la denominación opcional, el cuerpo y la relación con el contenido cercano. «Fuente» indica de dónde obtiene el valor un autor o renderizador.

El título es opcional porque «Nota» suele ser suficiente. El primer encabezado de la directiva portátil puede asignarse a title según las reglas de cuerpo predeterminadas, pero se prefiere la forma concisa de atributo para este elemento. Todo lo demás se asigna a body. La implementación actual de Hugo acepta un tipo posicional o un type nombrado, más un title nombrado opcional; nunca mezcles parámetros posicionales y nombrados.

Sintaxis y ejemplos de código

Estas formas tienen el mismo tipo, título y cuerpo. La presentación en la plataforma puede diferir, pero la aclaración debe seguir siendo una nota.

Directiva Markdown portátil

:::note{title="Time zone"}
Report timestamps use UTC. Filters and calculations do not change when a viewer's local time zone differs.
:::

El nombre de la directiva proporciona el tipo, el atributo proporciona el título opcional y el Markdown encerrado proporciona el cuerpo.

Shortcode de Hugo

{{< callout type="note" title="Time zone" >}}Report timestamps use UTC. Filters and calculations do not change when a viewer's local time zone differs.{{< /callout >}}

Este ejemplo usa solo parámetros nombrados. Sin un título personalizado, la forma posicional callout note es válida y el renderizador proporciona la etiqueta «Nota».

Bloque o shortcode de WordPress

<!-- wp:amicited/note {"title":"Time zone"} -->
<p>Report timestamps use UTC. Filters and calculations do not change when a viewer's local time zone differs.</p>
<!-- /wp:amicited/note -->

[note title="Time zone"]Report timestamps use UTC. Filters and calculations do not change when a viewer's local time zone differs.[/note]

El bloque registrado es la implementación preferida de WordPress. Un shortcode es aceptable cuando esa instalación lo admita explícitamente; los sistemas de importación no deben convertir la nota en una advertencia ni inferir un tipo diferente a partir de sus colores.

Ejemplos

Correcto: variación de interfaz inofensiva

Esto es correcto porque responde a una posible duda sobre la interfaz y, al mismo tiempo, preserva la misma acción y resultado. Nombra ambas etiquetas, indica dónde aparece cada una y confirma su comportamiento equivalente. La nota tiene sentido incluso si se extrae del procedimiento circundante.

Incorrecto: una advertencia disfrazada de información

Nota — Eliminación del espacio de trabajo: Eliminar el espacio de trabajo elimina permanentemente sus informes. Exporta los registros necesarios antes de continuar.

Esto es incorrecto porque la consecuencia exige un cambio de comportamiento antes de una acción irreversible. Un tono calmado y una etiqueta neutral no lo convierten en contenido complementario. Debe ser una advertencia colocada antes del control de eliminación, con el destino, la consecuencia y la acción preventiva indicados explícitamente.

Otra nota incorrecta dice: «La exportación debe contener todas las columnas requeridas». Eso es un criterio de aceptación. Pon las columnas requeridas en la instrucción o en la tabla de especificaciones. Una tercera dice: «Puedes ahorrar tiempo filtrando la exportación primero». Eso es un consejo opcional que mejora el resultado y, por lo tanto, un consejo. La clasificación correcta importa más que la variedad visual.

Marcado de esquema y accesibilidad

Un cuadro de nota no tiene un tipo o propiedad dedicada de Schema.org. Sigue siendo contenido visible dentro del Article, TechArticle, producto u otro esquema veraz a nivel de página que lo contenga. No crees un objeto JSON-LD independiente para él. Cuando una nota aclara un paso, mantenla separada de HowToStep.text a menos que la aclaración sea necesaria para realizar el paso; si es necesaria, no era contenido opcional de nota en primer lugar.

Una nota estática no necesita role="alert", una región ARIA en vivo ni un anuncio forzado. Esos mecanismos comunican urgencia o cambios dinámicos, mientras que una nota está presente en el orden normal del documento y contiene contexto no urgente. Un anuncio agresivo tergiversaría su importancia y haría que la salida de las tecnologías de asistencia fuera más ruidosa.

Renderiza la etiqueta visible como texto en el modelo de objetos del documento (DOM), no como imagen de fondo, tooltip solo con icono ni decoración generada por CSS. Si se usa un rol de región, conecta su nombre accesible con la etiqueta visible o el título personalizado. El orden de lectura es etiqueta, título opcional y luego cuerpo. El color y los iconos pueden reforzar el tipo, pero no pueden ser la única distinción respecto a los consejos y advertencias.

Al 200 % de zoom de texto y en un viewport estrecho, el cuerpo debe ajustarse sin desplazamiento horizontal. Los enlaces requieren texto de anclaje descriptivo y deben ser accesibles por teclado. El código en línea debe seguir siendo legible en alto contraste. La información esencial no puede existir solo en la captura de pantalla de la anatomía o en el texto alternativo de un icono.

Reglas de redacción

Apunta a 15–60 palabras. El máximo absoluto es 90 palabras en no más de dos párrafos breves. Un pasaje más largo generalmente merece integrarse en la explicación principal; una nota extremadamente breve suele ser una etiqueta sin contexto útil.

Escribe una aclaración por cuadro en un tono calmado y objetivo. Indica el tema en la primera frase y luego explica la diferencia o el límite inofensivo. Prefiere una redacción precisa como «Las marcas de tiempo usan UTC» en lugar de frases de relleno conversacionales como «Para que lo sepas». Da la razón antes de cualquier regla interpretativa: «Los proyectos archivados siguen siendo visibles en los informes históricos, por lo que sus totales pueden aparecer aún en rangos de fechas pasados».

Una nota puede contener énfasis simple, hasta dos valores de código breves en línea y como máximo un enlace descriptivo. Nunca debe contener:

• Un paso requerido, requisito previo, regla de validación, criterio de éxito o instrucción de recuperación.
• Un riesgo material, consecuencia irreversible, condición de seguridad, instrucción legal o divulgación de costos.
• Un consejo opcional cuyo propósito sea mejorar la velocidad, calidad, precisión o conveniencia.
• Una definición completa, evidencia necesaria para respaldar una afirmación o una lista de fuentes.
• Más de una aclaración independiente.
• Una tabla, bloque de código, formulario, botón, CTA, testimonio, promoción o elemento anidado.
• Bromas, lenguaje alarmista, emojis decorativos o palabras como «crítico» y «peligro».

No titules cada nota como «Importante». La importancia no es el propósito del elemento y la palabra se acerca falsamente a la gravedad de una advertencia. Usa «Nota» o un título objetivo sobre el tema. Nunca uses una nota para rescatar texto poco claro: repara primero la explicación principal y luego conserva una nota solo si persiste una ambigüedad genuinamente complementaria.

Tipos de publicación que lo usan

Los postTypes del frontmatter enumeran los formatos donde el contexto complementario es recurrente. La inclusión sigue siendo opcional; la tabla define el trabajo y la posición permitidos, no un espacio obligatorio.

Otros tipos de publicación pueden usar una nota cuando superen la misma prueba de «sin cambios». Estar en la lista no justifica añadir una por ritmo visual, y estar omitido no convierte una advertencia en una nota.

Lista de verificación de control de calidad

Antes de publicar, verifica cada elemento:

• El bloque aclara un pasaje cercano y no cambia la acción, el resultado, la prioridad, la interpretación ni el riesgo.
• El contexto responde a una pregunta verosímil del lector en lugar de repetir el destino.
• La información requerida permanece en el contenido principal.
• La nota se sitúa inmediatamente después de su destino completo o después del párrafo de alcance para una secuencia nombrada.
• No separa un encabezado de su introducción, una afirmación de la evidencia, ni una instrucción de su comprobación de éxito.
• Ninguna advertencia, consejo, CTA, banner o segunda nota se sitúa directamente junto a ella.
• La página no tiene más de tres notas y la sección no tiene más de una.
• El cuerpo apunta a 15–60 palabras, se mantiene por debajo de 90 palabras y contiene una aclaración.
• La etiqueta textual visible funciona sin color, borde, icono ni imagen.
• El texto sigue teniendo sentido cuando se extrae con su etiqueta pero sin el estilo circundante.
• El cuadro no usa rol de alerta ni región en vivo cuando está presente al cargar la página.
• Las asignaciones de Markdown, Hugo y WordPress conservan el tipo, título, cuerpo y colocación.
• Los parámetros de Hugo son totalmente posicionales o totalmente nombrados; nunca se mezclan.
• No aparece ningún componente anidado, bloque de código, tabla, formulario ni acción promocional no admitidos en su interior.
• Los marcadores de captura de pantalla solicitan capturas futuras sin renderizar activos inexistentes.

Preguntas frecuentes

¿Cuál es la diferencia entre una nota, un consejo y una advertencia? Una nota aclara sin cambiar nada. Un consejo ofrece una mejora opcional. Una advertencia cambia el comportamiento para evitar daños, pérdidas, costos, exposiciones o trabajos no válidos. Clasifica por la consecuencia de omitir el bloque, no por su color.

¿Puede un cuadro de nota contener información obligatoria? No. La información obligatoria pertenece al contenido principal, donde cada lector la encuentra en secuencia. Una nota puede explicar una variación inofensiva, pero omitirla no puede hacer que la tarea o la interpretación sean incorrectas.

¿Cuántos cuadros de nota debe contener una página? Usa un máximo de tres por página y uno por sección. La mayoría de las páginas necesitan menos. Las notas repetidas indican que la explicación principal necesita reestructurarse.

¿Debe un cuadro de nota usar colores de advertencia o un rol de alerta? No. La presentación de advertencia señala una consecuencia material, y role="alert" señala información dinámica urgente. Aplicar cualquiera de ellos a un contexto rutinario enseña a las personas a ignorar la señal real y engaña a los usuarios de tecnologías de asistencia.

¿Puede un cuadro de nota contener enlaces o código? Puede contener un enlace descriptivo o hasta dos valores de código breves en línea cuando estos aclaren directamente el destino. Usa el contenido principal para bloques de código, tablas, formularios o documentación de varios pasos.

Una nota se gana su límite resolviendo una ambigüedad real sin alterar el curso del lector. Mantenla calmada, adyacente, autónoma y visualmente distinta de los consejos y los riesgos.