Tooltip · ayuda contextual diferida
El Tooltip es la nota de ayuda más fácil de abusar. Su regla cardinal: nunca contiene información crítica. Si la necesita, no es Tooltip; es Popover, Drawer o Modal. Esta ficha documenta esa frontera y los tres anti-patrones más caros que el sistema ha visto en producción.
Decomposición del componente
Las seis capas del componente
01 · Átomo color.neutral.950 · color.neutral.50 · space.2 · space.3 · duration.500 Primitivos. El delay 500ms es el único que el sistema impone a overlays.
02 · Compuesto color.tooltip.bg · color.tooltip.fg · size.tooltip.maxwidth · motion.tooltip.delay Semánticos. maxwidth 16rem; si el contenido excede, no es Tooltip.
03 · Regla activable por hover y focus · no información crítica · policy anti-nesting con Modal Governance. La regla 'no información crítica' se verifica cualitativamente por lint editorial.
04 · Pieza <Tooltip content='...' placement='auto'>...</Tooltip> Wrapper sobre un trigger. El contenido es texto plano; no admite elementos interactivos.
05 · Familia Overlays · sibling de Popover, Modal, Toast Tooltip es pasivo y efímero; Popover es pasivo pero persistente hasta dismiss; Modal bloquea; Toast aparece sin trigger.
06 · Estado appearing · visible · dismissing · agent-aware Sin estado clickable: rompería la propia naturaleza del Tooltip.
Tokens consumidos
Semánticos
color.tooltip.bg oklch(0.18 0 0) Fondo oscuro, alto contraste con el texto
color.tooltip.fg oklch(0.99 0.005 75) Texto crema sobre fondo oscuro
size.tooltip.maxwidth 16rem Ancho máximo, 256px. Si el contenido excede, no es Tooltip
motion.tooltip.delay 500ms Delay antes de aparecer, evita parpadeo en hover accidental
Técnicas de governance aplicadas
Técnicas activas
No información crítica
El contenido no puede contener acciones, links, ni datos sin los cuales el flujo se rompe. La regla operativa: si quitas el Tooltip y el flujo sigue funcionando, el contenido es válido. Si no, hay que promover a otro componente.
Activable por focus, no solo hover
El Tooltip aparece tanto con mouseover como con focus por teclado. Sin esto, los usuarios de teclado y de SR pierden la ayuda contextual.
No anidable en Modal
Tooltip dentro de Modal multiplica capas de overlay y rompe focus management. La policy lo rechaza con sugerencia: usar texto descriptivo inline o aria-describedby.
Estado físico
Agentic-consumable desde noviembre de 2025. La policy de “no información crítica” se chequea cualitativamente vía lint editorial humano cada release; el agente no puede decidir solo si su tooltip es crítico.
Estados soportados
appearing (delay 500ms), visible, dismissing, agent-aware. Sin estado clickable: el tooltip no se interactúa.
Composiciones prohibidas
Reglas activas
Información crítica dentro del Tooltip
Si el contenido contiene acción, link o dato sin el cual el flujo se rompe, se rechaza. Alternativa: Popover, Drawer o Modal.
Tooltip anidado en Modal
Rompe focus management del Modal y colisiona overlays. Alternativa: texto descriptivo inline o aria-describedby.
Tooltip solo activable por hover
Sin focus listener, usuarios de teclado y SR pierden la ayuda. La policy exige focus + hover.
Tooltip con longitud >280 caracteres
Si el contenido supera la maxwidth canónica de forma persistente, el componente no es Tooltip: es Popover con header + body.
Interoperabilidad
- Consumido por: cualquier componente con trigger (IconButton, Badge icon-only, FormField helper). Se adjunta al trigger, no al contenido.
- Consume: texto plano. No Heading, no Button, no Link.
- Con qué compone mal: con Button (si el botón necesita ayuda, replantear el label), dentro de Modal (anti-pattern documentado), con Toast simultáneo.
- Sustituibles por:
Popoversi el contenido es interactivo;aria-describedby+ texto inline si basta con ayuda textual estática para SR.
Medición propuesta
Eventos planificados
tooltip.shown
Trigger, ruta, duración visible. Detecta tooltips con duración breve (hover accidental) para ajustar el delay canónico.
tooltip.truncation_detected
Casos donde el contenido fue truncado visualmente por exceder el ancho. Candidatos a promoción a Popover.
Mutación plástica (Estado 3)
Qué muta y qué permanece
Placement position = derive(espacio-disponible × pointer) Floating UI decide arriba/abajo/izquierda/derecha. Agnóstico al lector.
Delay delay = derive(touch) En touch no hay hover: el tooltip solo aparece por long-press (500ms). En desktop hover, delay 500ms también.
Dismiss dismiss = Escape + blur del trigger · forzado por click fuera Siempre disponible. Agnóstico.
Fijo por contract no info crítica · activable por focus · maxwidth 16rem · no interactivo Contract inviolable.
Rollback si la mutación propone activar el Tooltip sin delay (genera parpadeo en hover accidental) o si el contenido pretende albergar un link o botón.
Genealogía
Árbol de evolución
Tooltip nativo HTML title
Atributo title en elementos. Sin estilo, sin control, inaccesible en mobile.
Consumidor Diseñador y desarrollador
Tooltip custom con Floating UI
Implementación accesible con focus + hover. Posicionamiento con autoflip.
Consumidor Producto · 16 productos
Tooltip governable + policy de uso
Lint editorial. Auditoría que detectó 12 casos de información crítica en Tooltip y los promovió a otros componentes.
Consumidor Producto · 26 productos
Tooltip.AI · expuesto vía MCP
Schema con regla de longitud máxima y prohibición de elementos interactivos.
Consumidor Humano + agente
Notas del editor
Descartes catalogados
Variants rechazadas
variant='clickable' Tooltip con click handler. Si es clickable, no es Tooltip: es Popover. Movido a componente <Popover /> separado con su gestión de focus propia.
variant='persistent' Tooltip que no se cierra automáticamente. Indistinguible de Popover. Reescrito como Popover.
Referencias cruzadas
- Familia: Overlays.
- Componente hermano: Nº 0253 · Modal.
- Componente hermano: Nº 0257 · Toast.