Ir al contenido
Portal de documentación del EGD
Menú de la sección

Tooltips de iconos del SGD

Fuente y referencia

Se reutiliza @radix-ui/react-tooltip, ya instalado, mediante src/components/ui/tooltip.tsx. La captura muestra un icono con hover circular tenue y un tooltip compacto, oscuro, con texto blanco y flecha hacia el icono. Los otros tres lados, el tiempo de aparición, el movimiento reducido y el comportamiento ante colisiones son decisiones del SGD para completar ese patrón.

Uso

TooltipProvider se monta una vez en el layout. Button size="icon" muestra automáticamente un tooltip con su title o aria-label, usa ese texto como nombre accesible si faltaba y retira el atributo title del DOM para evitar el tooltip nativo duplicado. Preferir aria-label para el nombre del control. tooltipSide indica el lado preferido (top, bottom, left, right); el componente compartido elige otro cuando falta espacio. Los botones con número visible, como la paginación, no reciben tooltip automáticamente si no se les da etiqueta. Los botones deshabilitados conservan el nombre accesible, pero no abren tooltip porque no admiten foco ni interacción.

En menús que se contraen a solo iconos conservando otro size, usar tooltip={collapsed ? label : undefined}. Esta propiedad sigue la misma implementación y elimina el title nativo.

<Button variant="ghost" size="icon" aria-label="Editar documento">
  <Icon name="edit" size={18} />
</Button>

<Button variant="ghost" size="icon" tooltipSide="right" title="Abrir opciones">
  <Icon name="more_vert" size={18} />
</Button>

Para un icono que no use Button, componer las primitivas existentes Tooltip, TooltipTrigger asChild y TooltipContent; el disparador debe tener un nombre accesible y no debe conservar title nativo. No crear otro componente ni proveedor.

Apariencia y comportamiento

--sgd-tooltip-background es negro casi puro y --sgd-tooltip-foreground es blanco en Theme LATAM, Theme Adobe Spectrum y Theme Institucional, tanto en claro como en oscuro. La tipografía utiliza Inter y --sgd-font-help (12 px); el padding es 4 × 8 px, el radio es --sgd-radius-control y la separación del icono es 8 px. TooltipPrimitive.Arrow comparte el fondo y se orienta según el lado real. Los botones ghost de solo icono tienen hover circular tenue mediante --sgd-icon-hover.

El componente compartido toma el viewport y, si el disparador está dentro de un diálogo, también el rectángulo del diálogo como límites, con 8 px de margen. Prueba el lado solicitado, el opuesto y los dos perpendiculares; elige el primero con espacio y ajusta la alineación transversal junto al borde. Radix conserva el posicionamiento final, la flecha, el portal, las colisiones y el seguimiento del disparador. La medición permanece activa mientras el tooltip está abierto para responder a scroll, redimensionamiento y movimiento del contenedor. El texto puede ocupar varias líneas y su ancho máximo se limita al espacio del diálogo o viewport. No se corrigen recortes mediante overflow: hidden ni aumentando solo el z-index; la capa ya está por encima de menús y modales.

Con el mouse el tooltip aparece tras una pausa de 1 s (TOOLTIP_DELAY_MS): pasar el cursor no lo muestra; hay que mantenerlo sobre el control. Si el cursor sale antes, no aparece (el temporizador se cancela), y al recorrer varios controles no aparecen tooltips sucesivos ni parpadean: skipDelayDuration = 0, así que cada control nuevo respeta la pausa completa aunque otro tooltip acabe de cerrarse. Con foco de teclado se muestra de inmediato (sin pausa). Un único TooltipProvider (ui/tooltip.tsx, usado en layout.tsx) fija este criterio para favoritos, botones, tablas, menús y modales; no se configura por pantalla. Al cerrar un panel o modal no quedan tooltips ni temporizadores pendientes. La entrada y salida se desvanecen en 160/120 ms; prefers-reduced-motion elimina la animación. Radix abre por mouse o foco, mantiene abierto el tooltip al mover el puntero a su contenido y permite cerrarlo con Escape. El foco permanece en el botón.

La sección «Tooltips de iconos» de /design-system/componentes permite probar los cuatro lados, los cuatro bordes, texto largo, un menú, una tabla con desbordamiento y un modal con controles en sus cuatro esquinas. Al ajustar este patrón, comprobar las seis combinaciones de paleta/modo, Dashboard y un ancho móvil cercano a 375 px.

Eliminación de tooltips redundantes (Regla de uso estricto)

Los tooltips (tanto flotantes de Radix como nativos del navegador mediante el atributo title) solo deben aparecer cuando aportan información indispensable no visible de forma directa.

  • No repetir texto visible: Queda expresamente prohibido inyectar title o <Tooltip> sobre elementos cuyo texto ya es legible y visible en pantalla (por ejemplo, opciones de columnas como «Diario», badges de estado con texto claro como «Pendiente» o «Normal», inputs con placeholder visible o títulos de sección).
  • Cuándo sí usar Tooltip:
    1. Controles o botones de solo icono (size="icon") que carecen de etiqueta textual visible.
    2. Textos o descripciones largas truncadas (line-clamp o elipsis en celdas de tabla donde el texto real sobrepasa el ancho asignado, ej: TableCellDescription para textos largos).
    3. Aclaraciones funcionales o advertencias no evidentes en la etiqueta (ej: columna fija no ocultable).
  • Evitar interferencias en la interacción: Elementos interactivos como agarradores de redimensionamiento de columnas (TableColumnResizer) no deben mostrar un tooltip con title, pues la propia forma del cursor (cursor: col-resize) comunica la acción y el tooltip flotante bloquea la visibilidad del encabezado.