¿Qué hace UltraExplainer?
Convierte código, sistemas, diffs, planes, datos y conceptos en una única página HTML autocontenida que hace obvia la idea importante en la primera pantalla, respaldándola con evidencia anclada. UltraExplainer es tres cosas que trabajan juntas:
- Un método de síntesis (el cerebro): cómo decidir qué mostrar, qué enfatizar, qué omitir y cómo nunca dibujar una estructura que no esté en la fuente. Consulta
references/synthesis-method.md. - El estudio camaleón (la artesanía): un contrato de componentes estable y agnóstico al lenguaje de diseño (
assets/core.css) reestilizado por siete lenguajes de diseño completos (assets/themes.css). El mismo diff se renderiza como un margen de IDE bajo Terminal, una nota al margen bajo Blueprint, una figura bajo Editorial. Tú eliges el lenguaje que se adapte al tema; el brillo es una opción (Luminous), nunca la predeterminada. Consultareferences/aesthetic-languages.mdyreferences/component-contract.md. - Una capa de interactividad (
assets/ux.js): un motor compartido estado→renderizado que alimenta deslizadores, alternancia de escenarios, recorridos paso a paso, tablas ordenables/filtrables, navegación de desplazamiento y gráficos nodo-arista enrutados. Consultareferences/interactivity.md.
Identidad: verdad + el lenguaje de diseño correcto + artesanía verificada. No "todo brilla", no "sopa de cajas y flechas", no "un muro de tarjetas idénticas".
Cuándo usar esta habilidad
Recurre a una página HTML cuando el resultado sea inherentemente visual, relacional o manipulable y ASCII/Markdown lo distorsione:
- Un diagrama, visión general de arquitectura o gráfico nodo-arista de cómo algo se conecta o fluye.
- Un diff / revisión de PR (código cambiado + por qué importa + alcance del impacto).
- Un plan / auditoría de requisitos o matriz de comparación.
- Un panel de control de métricas, o cualquier tabla con 4+ filas / 3+ columnas.
- Un explicador de conceptos que enseñe un mecanismo, o un modelo interactivo que el lector debe sentir al cambiar una entrada.
- Una presentación de diapositivas, o un resumen de proyecto para cambio de contexto.
Si la respuesta honesta cabe en una oración o un solo número, dila en el chat — no fabriques una página (la regla del explicador mínimo viable). Cuando construyas, da un resumen de una línea en el chat y entrega el archivo.
Dos modos — decide al inicio
Indica en cuál estás (para que el usuario pueda corregirlo):
- EXPLICAR (predeterminado) — tesis primero, para revisores / tomadores de decisiones / personas que cambian de contexto y necesitan la conclusión rápida. Se aplican límites de saliencia (T0 ≤ 3, T1 ≤ 7).
- ENSEÑAR — pregunta primero, para estudiantes que necesitan un modelo mental ejecutable. Concreto antes que abstracto, predecir y luego revelar, termina con una verificación de transferencia. Consulta
references/teaching.md.
El método, en resumen
Lee references/synthesis-method.md antes de generar algo no trivial. La forma breve:
- Chárter — una oración: "Esto explica a altitud <A0–A4> para para que puedan ," más el modo (EXPLICAR/ENSEÑAR). Mantén una altitud.
- Tesis con tensión — una afirmación declarativa que el lector aún no sabe (no un tema). Elige la columna vertebral (el único eje que el ojo sigue).
- Registro de evidencia — lee la fuente real; para cada nodo/arista/etiqueta/número registra
{afirmación, ancla (archivo:línea / símbolo / referencia git / métrica+fecha), confianza (verificado|inferido|asumido)}. Sin ancla → no se renderiza como hecho. Para modelos interactivos, cada rango/valor predeterminado del deslizador y la función entrada→salida está anclada o marcada "modelo ilustrativo, no medido". - Reconciliar — contrasta la tesis con la evidencia contradictoria; revisa, limita o muestra la contradicción. Nunca la descartes en silencio.
- Verificación mínima viable — no sobre-renderices. Respuesta simple → oración principal + una visualización.
- Jerarquía de saliencia — T0 (tesis + columna vertebral, ≤3) / T1 (soporte estructural, ≤7) / T2 (comprobantes, en
<details>/hover). Si superas un límite → divide o degrada, nunca reduces para que quepa. (El modo ENSEÑAR intercambia límites por un presupuesto de dificultad deseable). - Elige el lenguaje de diseño — puntúa los 7 lenguajes según tema × audiencia × medio y registra una línea:
LENGUAJE: <nombre> porque <tema + audiencia + medio>. Ver abajo. - Representa — pregúntate primero por la manipulabilidad ("¿debería el lector sentir una relación al cambiar una entrada?"); si es así, recurre a un modelo/pasos/escenario. De lo contrario, elige la forma estática de menor tinta. Codifica la magnitud cuantitativamente (tamaño/longitud/posición), no con cajas iguales.
- Comprime — la omisión es la artesanía; colapsa la repetición ("×12 manejadores"); extrae las líneas clave, no archivos completos.
- Puertas — pasa las tres antes de entregar (abajo).
Tres puertas de entrega — la verdad está por encima de todo
- VERDAD — cada nodo/arista/número se remonta a un ancla real; el contenido inferido/asumido está visiblemente acotado; la tesis se reconcilió con la evidencia contradictoria; reabriste las anclas. Un "no pude confirmar X" claramente marcado es mejor que una fabricación segura. Una mentira interactiva (un deslizador que recorre una relación fabricada) es el pecado capital.
- ARTESANÍA — la prueba de la mirada: desde el otro lado de la habitación se lee como un lenguaje de diseño deliberado, no como una plantilla recoloreada. Exactamente un punto focal T0.
- OBSERVADO — realmente renderizaste la página y la miraste. Constrúyela, ábrela (captura de pantalla sin cabeza a ~1280 y ~360), captura errores de consola, asegúrate de que no haya desplazamiento horizontal y que la tesis esté en el primer viewport, luego autocorrige. Deja de afirmar propiedades de lista de verificación que nunca mediste.
Cómo construir una página (ensamblaje)
Las páginas se ensamblan mediante scripts/build.mjs a partir de un fragmento de cuerpo en templates/_src/<nombre>.body.html. El camino más rápido: copia la plantilla más cercana, cambia la preset y adapta el contenido.
- Directiva de línea 1 (JSON en un comentario HTML) selecciona el lenguaje y la afinación:
<!--ux: {"title":"…","preset":"blueprint","theme":"light","fx":"flat","head":"<style>…</style>"} -->preset:blueprint | editorial | terminal | instrument | notebook | swiss | luminous(predeterminadoluminous)presets: ["…","…"]→ emite un archivo por lenguaje (demostraciones de camaleón)theme:light | dark(predeterminado según la afinación natural de la preset)fx:glow | flat(solo Luminous)head/foot: marcado adicional; los sidecars<nombre>.head.html/<nombre>.foot.htmltambién se fusionan
- La compilación en línea
core.css+themes.css+ux.js, enlaza las fuentes de la preset, establecedata-theme-preset/data-theme/data-fxantes de pintar (sin FOUC) y emitetemplates/<nombre>.html. - Ejecuta:
node scripts/build.mjs <filtro-nombre>(el filtro es una subcadena; omítelo para compilar todo). - Las únicas solicitudes externas de la página son Google Fonts (con respaldos del sistema — el diseño nunca depende de ellas) y, para páginas Mermaid, el CDN de Mermaid. Debe verse bien incluso si fallan.
CRÍTICO al incluir en línea cualquier JS que contenga la cadena literal
</script>(por ejemplo, un fragmento de ejemplo): escápalo como</script>o cerrará la etiqueta antes de tiempo y volcará el código fuente en la página.
Elegir el lenguaje de diseño
Decide según los méritos, registra el motivo. Puntuación completa + perfiles por lenguaje en references/aesthetic-languages.md.
| Tema | Lenguaje predeterminado |
|---|---|
| Arquitectura, esquemas, protocolos, topología de infra | Blueprint |
| Conceptos, ADRs, autopsias, narrativas ejecutivas | Editorial |
| Diffs, PRs, herramientas CLI, pipelines CI, registros | Terminal |
| Métricas, benchmarks, auditorías, paneles de control | Instrument |
| Enseñanza, tutoriales, incorporación, explicadores suaves | Notebook |
| Comparaciones, páginas de principios/manifiesto, informes de estado | Swiss |
| Demos de flujo de sistema, visión de producto, resúmenes impactantes | Luminous (nunca por defecto) |
Desempates: respeta las solicitudes explícitas del usuario ("hazlo como terminal"); rota para evitar monotonía en la sesión; nunca elijas Luminous solo porque sea llamativo.
Elegir la representación
Decide según el trabajo cognitivo y la forma de los datos, no el tipo de contenido. Manipulabilidad primero. Catálogo completo + enrutamiento en references/representations.md; gráficos honestos en references/charts-honesty.md.
| Trabajo | Representación (componente) |
|---|---|
| Una conclusión dominante / sí-no | Héroe de tesis tipográfica (.ux-thesis), quizás una visualización debajo |
| El lector debe sentir una relación | Modelo de parámetros ([data-playground]) — deslizadores + lecturas vinculadas |
| El orden / estado intermedio es el significado | Recorrido paso a paso ([data-stepper]) — código↔datos sincronizados |
| Se comporta diferente según configuraciones | Alternancia de escenario (.ux-seg[data-scenario-ctl]) que reilumina un diagrama |
| Secuencia lineal verdadera | Lista numerada / tira de flujo (.ux-spine) — no un diagrama de flujo |
| Flujo ramificado / fusionado / cíclico | Gráfico nodo-arista (.ux-graph, ≤12 nodos) o Mermaid con tema |
| Relaciones densas entre pares | Mapa de calor matricial (.ux-matrix) — mejor que un gráfico enmarañado |
| Cambio de código / PR | Diff anotado + veredicto (.ux-diff + .ux-verdict) + alcance del impacto |
| Concepto / concepto erróneo | Paneles de naïve-vs-correcto (.ux-compare) + un ejemplo resuelto |
| Comparación / auditoría / matriz | Tabla ordenable y filtrable (.ux-table, th[data-sort], data-ux-filter) |
| Métricas cuantitativas | Fila de KPIs con delta (.ux-kpis) + gráfico honesto mínimo (.ux-bars/.ux-linechart) |
| Plan / hoja de ruta | Bloque de estado actual→objetivo + línea de tiempo con niveles de riesgo (.ux-timeline) |
| Presentación | Presentación de diapositivas (templates/slides) |
| Nada encaja | SVG inline personalizado con tokens del tema |
Plantillas (templates/, con fuentes en templates/_src/)
| Plantilla | Lenguaje | Demuestra |
|---|---|---|
chameleon.<preset>.html | todos los 7 | la MISMA explicación renderizada en cada lenguaje — la prueba de la mirada |
blueprint → playground | Blueprint | modelo basado en parámetros (deslizadores, KPIs/barras vinculados, ajustes predefinidos) |
terminal-diff | Terminal | revisión de PR: diff anotado + veredicto + alcance del impacto |
instrument-dashboard | Instrument | cabecera de KPI + gráficos de líneas/barras honestos + tabla ordenable/filtrable |
editorial-concept | Editorial | explicador de conceptos: navegación de desplazamiento + SVG personalizado + naïve-vs-correcto + notas al margen |
notebook-teach | Notebook | modo ENSEÑAR: paso a paso + predecir y revelar + verificación de transferencia |
swiss-comparison | Swiss | matriz de decisión: números extra grandes + tabla de comparación ordenable |
luminous-flow | Luminous | alternancia de escenarios (acierto/fallo) + gráfico enrutado + brillo opcional |
mermaid | cualquiera | Mermaid con tema con zoom/pan/expandir |
slides | cualquiera | presentación a pantalla completa con navegación por teclado/desplazamiento |
Enrutamiento de referencias — lee solo lo que la salida actual necesita
| Necesidad | Lee |
|---|---|
| Cómo decidir qué/mostrar (el cerebro) | references/synthesis-method.md |
| Los 7 lenguajes, puntuación de selección, prueba de la mirada | references/aesthetic-languages.md |
Niveles de token, cada componente .ux-, compilación/ensamblaje | references/component-contract.md |
| Catálogo de representaciones + enrutamiento forma de datos × trabajo | references/representations.md |
| Deslizadores, alternancias de escenarios, pasos, gráficos, navegación de desplazamiento — la API JS | references/interactivity.md |
| Gráficos honestos: registro de números, ranking de canales, reglas de ejes | references/charts-honesty.md |
| Modo ENSEÑAR: estado del aprendiz, concreto primero, predecir-revelar, transferencia | references/teaching.md |
| Manuales por trabajo (revisión de PR, autopsia, ADR, perfil de rendimiento, …) | references/playbooks.md |
| Autocontención, seguridad de desbordamiento, bucle de verificación, lista de entrega | references/self-contained.md |
| Mermaid con tema (cuándo + cómo) | references/mermaid.md |
| Presentaciones de diapositivas | references/slides.md |
Invariantes
- La verdad está por encima de la belleza y la artesanía. Ancla u omite; acota el contenido inferido/asumido; nunca inventes capas, simetría, aristas o justificaciones. Los rangos/funciones interactivas están anclados o marcados "modelo ilustrativo".
- Un lenguaje por página, elegido según los méritos y registrado. Debe pasar la prueba de la mirada. El brillo es solo para Luminous, enrutado a través de
--fx-*para quedata-fx="flat"lo elimine limpiamente; sin respiración/pulsación continua en contenido estático. - Sin desplazamiento horizontal de página.
min-width:0en hijos de grid/flex; el contenido ancho (diffs, tablas, Mermaid) se desplaza dentro de su propio contenedoroverflow-x:auto. Verifica a 360px. - Ambos temas se ven compuestos. El claro está reajustado, no invertido. La página se abre en su tema elegido y el lector puede alternar (persistido por preset); respeta
prefers-reduced-motion; mantén el foco del teclado visible; seguro para impresión. - Los componentes consumen solo tokens semánticos +
--fx-*— nunca hexadecimal. Los nuevos aspectos provienen de paquetes de tema, no de colores en línea. - Nunca definas una clase
.nodea nivel de página — Mermaid la usa internamente. Todas las clases de UltraExplainer tienen prefijo.ux-. - Observa antes de entregar. Renderiza la página, mírala, corrige lo que esté mal. No afirmes lo que no mediste.
Lista de verificación final
Documento autocontenido en la ruta correcta · compilado con la preset elegida · sin errores de consola · sin desbordamiento horizontal en escritorio ni a 360px · las fuentes se degradan con gracia · la tesis es obvia en el primer viewport con exactamente un punto focal · las tablas/diffs/diagramas se desplazan dentro de sus propios contenedores · los cambios de tema (y el brillo de Luminous) funcionan · cada afirmación está anclada o acotada · la página fue realmente renderizada e inspeccionada.