Dialog

El Modal Dialog es una ventana superpuesta que interrumpe la página para pedir una confirmación, mostrar un resultado importante o completar una tarea breve sin salir del flujo. Se abre sobre un fondo atenuado y bloquea el contenido de atrás hasta que la persona responde.

Propiedades y configuraciones

Cuando usarlo

Úsalo cuando la persona debe responder antes de seguir: confirmar una acción irreversible (anular una solicitud, eliminar un documento), verificar su identidad con un código o completar un dato breve sin perder el contexto del trámite.

Si solo necesitas informar el resultado de una acción sin bloquear, usa Snackbar; si el mensaje debe quedar visible en la página, usa Alert; si la tarea es larga o tiene varios pasos, llévala a una página propia (con Stepper) en vez de un diálogo.

Buenas prácticas

Recomendado: Reserva el diálogo para decisiones que no pueden esperar

Interrumpir tiene un costo. Úsalo para confirmar acciones con consecuencias, no para avisos que la persona puede leer después.

Recomendado: Escribe un título que diga qué pasa y botones que digan qué hacen

La persona debe entender la decisión leyendo solo el título y los botones. Usa verbos concretos en vez de “Sí / No”.

Recomendado: Mantén el contenido breve y enfocado en una sola tarea

Un diálogo resuelve una cosa: confirmar, ingresar un código o elegir una opción.

Recomendado: Usa el ícono de estado según el significado real

Éxito, error e info refuerzan el título. Para formularios o selección, usa el diálogo neutral, sin ícono.

Recomendado: Comunica con claridad las acciones destructivas

Nombra la acción y el objeto en el título, explica la consecuencia y si se puede revertir, y repite el mismo verbo en el botón que confirma.

Malas prácticas

No recomendado: No abras diálogos sin que la persona lo haya pedido

Un diálogo que aparece al entrar a la página bloquea la tarea que la persona vino a hacer y suele cerrarse sin leer.

No recomendado: No uses botones ambiguos como “Sí” y “No”

Frente a una pregunta larga, “Sí / No” obliga a releer para saber qué hace cada botón y aumenta el riesgo de error.

No recomendado: No metas un formulario largo ni un trámite completo en el diálogo

Muchos campos obligan a hacer scroll en un espacio reducido y es fácil perder lo ingresado al cerrarlo. Un trámite completo merece su propia página.

No recomendado: No abras un diálogo sobre otro diálogo

Apilar diálogos confunde sobre qué se está confirmando y a dónde vuelve la persona al cerrar.

Recomendaciones de accesibilidad

Ábrelo siempre con showModal()
Solo así el navegador lo trata como modal: mueve el foco dentro, vuelve inerte el contenido de atrás, dibuja el ::backdrop y permite cerrar con Escape. El atributo open estático es solo para referencias visuales.

Dale un nombre accesible
El <dialog> debe tener nombre: en los ejemplos del kit se usa aria-label con el mismo texto del título. También puedes usar aria-labelledby apuntando al id de .cl-dialog__title.

Pon el foco inicial en el lugar correcto
Al abrir, el foco debe caer en el primer elemento útil (el campo del código, o el botón menos destructivo en una confirmación). En acciones irreversibles, evita que el foco inicial esté en “Eliminar”.

Devuelve el foco al cerrar
Al cerrar con el botón, con Escape o tras la acción, el foco debe volver al control que abrió el diálogo para que la persona no pierda su lugar en la página.

Nombra el botón de cierre
El botón con ícono de cierre necesita aria-label (p. ej. “Cerrar diálogo”) y el ícono va con aria-hidden="true".

No dependas solo del ícono o del color del estado
El ícono de éxito, error o info es decorativo (aria-hidden="true"): el significado debe estar en el título y el cuerpo (“No pudimos enviar tu solicitud”).

Etiqueta los campos del cuerpo
Si el diálogo incluye .cl-field u .cl-otp, cada input debe tener su label asociado y las instrucciones visibles en el hint, igual que fuera de un diálogo.