Módulo KB (Esferic): glosario flotante accesible + tema oscuro

Resumen

Módulo public/informes/_kb/ que centraliza la identidad visual de Esferic Labs en los reportes estáticos: tema oscuro unificado y un sistema de “glosa” (glosario flotante) que marca acrónimos y términos técnicos con tooltips accesibles de bajo impacto.

El globo flotante reutilizable (kb-tip) aparece al pasar el ratón o enfocar con teclado sobre cualquier <abbr data-kb="...">, escapando contenedores recortados mediante position: fixed. Apagable por página (<html data-kb-off>) o globalmente (KB_ENABLED = false).

Componentes

kb.css (111 líneas)

Paleta oscura derivada del tema del workspace (globals.css), calibrada para lectura larga sin deslumbrar:

• Colores base: near-black (#0a0d12 bg, #e7edf5 fg), azul de marca (#2962ff accent), cyan (#22d3ee accent-2).
• Tokens semánticos: --kb-surface-2 para el globo, --kb-accent-ink (#6ea8ff) para texto legible en oscuro, --kb-border-soft para separadores sutiles.
• Glosa visual: [data-kb] se marca con subrayado punteado (text-decoration: underline dotted) en --kb-accent-ink al 60%, espesor 1px, offset 3px (low-impact).
• Globo flotante: max-width: 300px, box-shadow de doble capa (10px blur + 0px inner), transition: opacity 0.14s ease-out, z-index: 2147483000 (semántico, por encima de todo).
• Accesibilidad: :focus-visible con outline 2px + outline-offset, role="tooltip" en el DOM, respeta prefers-reduced-motion: reduce.

kb.js (100 líneas)

Comportamiento del glosario:

• Binding: al cargar, busca todos los [data-kb] y liga event listeners (mouseenter/mouseleave + focus/blur). Preserva tabindex="0" si no existe.
• Show/Hide: una única instancia de div.kb-tip (reutilizada) que se posiciona dinamáticamente:
  • Arriba del elemento por defecto, 8px de separación.
  • Si no cabe arriba (top < pad), cambia a debajo (r.bottom + pad).
  • Centra horizontalmente, clampea a viewport (nunca sale fuera de pantalla).
• Contenido dinámico: <span class="kb-tip-term"> con el término (.textContent del elemento), seguido del contenido de data-kb (la definición).
• Apagado: global con KB_ENABLED = true/false o por página con <html data-kb-off> (no liga event listeners si está presente).
• Cierre: Escape key, scroll (oculta pero no destruye), resize.

Integración en reportes

Ambos reportes (roast/ y storm/) ahora incluyen:

<link rel="stylesheet" href="/informes/_kb/kb.css" />
<script src="/informes/_kb/kb.js" defer></script>

Y marcan términos específicos con <abbr data-kb="...">:

• DCIM: “Data Center Infrastructure Management: software para gestionar y vigilar en vivo la infraestructura de un datacenter — qué equipo hay, dónde está y cómo funciona”
• on-premise: “On-premise: que corre en la propia infraestructura del cliente, dentro de su red, sin depender de la nube de nadie”

Además, ambos reportes aplican tema oscuro forzado:

• roast/: <html lang="es" data-theme="dark"> (el atributo data-theme es para referencia; el CSS oscuro de kb.css ya tiene soberanía de orden).
• storm/: bloque CSS adicional que sobrescribe colores clave (:root con --ink, --bg-soft, --blue, etc.) + body { background: #05070a; } + .page { background: #0b0e14; }.

Decisiones de diseño

1. Un único tooltip (DOM reuse): en lugar de crear un globo por término, reutiliza una instancia única (tip), lo que reduce overhead y evita conflictos de z-index.

2. Position: fixed + viewport clamping: el globo puede vivir dentro de cualquier contenedor (iframe, scroll, overflow:hidden) sin ser recortado. Se recalcula posición al medir su tamaño real (no usa valores hardcodeados).

3. Low-impact visual: el subrayado punteado + color --kb-accent-ink 60% es visible sin ser invasivo. Respeta prefers-reduced-motion.

4. Apagado granular: KB_ENABLED permite desactivar globalmente sin editar HTML, y <html data-kb-off> permite excepción por página.

5. Accesibilidad nativa: role="tooltip", tabindex="0" automático, focus-visible con outline, cierre con Escape, sin dependencias de ARIA adicional compleja.

Extensibilidad

El módulo es agnóstico: cualquier página del workspace puede importarlo añadiendo las dos líneas de <link> y <script>, y luego marcar sus propios términos con <abbr data-kb="...">. Caso de uso típico:

• Reportes técnicos (roast, storm, etc.).
• Documentación interna con glosario dinámico.
• Páginas públicas que quieran identidad Esferic.

Véase también

• [[concept—ux—accesibilidad-nativa]]
• [[concept—design—low-impact-ui]]
• [[feature—informes—roast-appliance-2026]]
• [[feature—informes—storm-appliance-2026]]
• [[entity—public—style—global-tokens]]