Creador de Diagramas HTML
Genera archivos .html autocontenidos con un único <svg> en línea que argumentan visualmente, no solo muestran información. Luego los captura como PNG con Playwright, inspecciona la imagen y corrige hasta que quede limpio.
Archivos en Esta Skill
| Archivo | Propósito | Cuándo leerlo |
|---|---|---|
references/color-palette.md | Todos los colores y estilos de marca: la fuente única de verdad | Antes de cada diagrama |
references/visual-patterns.md | Bocetos de cada patrón de diseño (abanico, línea de tiempo, árbol...) | Paso 2 de Diseño |
references/starter.html | Esqueleto de página: tokens CSS, clases de texto/formas, marcadores de flecha, un ejemplo de cada convención | Cópialo como inicio de cada diagrama |
scripts/render.py | Captura el HTML a PNG y valida la geometría | Ejecutar después de cada edición (ver Renderizar y Validar) |
examples/ | Dos diagramas terminados con sus PNG | Cuando quieras una referencia de densidad y estilo |
Para cambiar el estilo de todos los diagramas para una marca, edita color-palette.md (y los tokens correspondientes en starter.html). Todo lo demás es método universal.
Dos Decisiones Ya Tomadas (No las Vuelvas a Cuestionar por Cada Diagrama)
1. Todo es SVG. HTML es solo la página alrededor.
Cajas, texto, flechas y bloques de código viven en un único <svg id="diagram">. No construyas cajas con HTML/CSS (divs con flexbox/grid) con una capa SVG superpuesta para conectores.
Por qué: un diagrama es un problema de geometría, y las flechas necesitan coordenadas exactas para ambos extremos. Con SVG completo, cada nodo y cada flecha comparten un sistema de coordenadas que está escrito en el archivo, por lo que puedes calcular un punto final de flecha con aritmética y corregirlo editando un número. Con cajas HTML, las posiciones provienen del motor de diseño del navegador: no están en el código fuente, cambian con las fuentes y el ancho de la ventana gráfica, y los conectores necesitan JavaScript que mida las cajas en tiempo de ejecución. Eso es un segundo programa que depurar, y la ventana gráfica del lector puede diferir de la que tú validaste. Los costos de usar solo SVG son reales pero menores: el texto SVG no se ajusta (divide las líneas tú mismo con <tspan>) y su ancho no se conoce hasta que se renderiza (el lint lo mide e informa desbordamiento).
<foreignObject> (HTML dentro de SVG) está desactivado por defecto: es el único lugar donde obtendrías ajuste de texto, pero se renderiza de forma inconsistente fuera de los navegadores y el lint no puede verificarlo. Úsalo solo si el usuario necesita párrafos dentro de una forma.
2. No uses Graphviz o D2 para el diseño. Coloca las coordenadas a mano.
Por qué: la metodología exige que el diseño refleje el concepto: abanicos, líneas de tiempo, ciclos, comparaciones lado a lado, anotaciones flotantes, bloques de código colocados junto al paso que ilustran. Los motores de diseño automático optimizan para un objetivo diferente (grafos en capas con pocos cruces de aristas), por lo que aplanan cada diagrama en la misma jerarquía de arriba abajo, que es exactamente la salida de "cajas uniformes" que esta skill busca evitar. También agregan una dependencia binaria y producen SVG que es incómodo de cambiar de estilo y anotar.
La excepción: un tema genuinamente en forma de grafo (aproximadamente 15+ nodos con muchas conexiones cruzadas, como un grafo de dependencias) donde los cruces son el problema principal. En ese caso, ejecuta dot -Tplain (Graphviz) solo para obtener las coordenadas de los nodos, luego dibuja los nodos tú mismo con los estilos y convenciones de esta skill. Di que estás haciendo esto y por qué.
Filosofía Central
Los diagramas deben ARGUMENTAR, no MOSTRAR.
Un diagrama no es texto formateado. Es un argumento visual que muestra relaciones, causalidad y flujo que las palabras solas no pueden expresar. La forma DEBE ser el significado.
La Prueba del Isomorfismo: Si eliminaras todo el texto, ¿la estructura por sí sola comunicaría el concepto? Si no, rediseña.
La Prueba Educativa: ¿Podría alguien aprender algo concreto de este diagrama, o solo etiqueta cajas? Un buen diagrama enseña: muestra formatos reales, nombres de eventos reales, ejemplos concretos.
Evaluación de Profundidad (Haz Esto Primero)
Antes de diseñar, determina qué nivel de detalle necesita este diagrama:
Diagramas Simples/Conceptuales
Usa formas abstractas cuando:
- Expliques un modelo mental o filosofía
- La audiencia no necesite detalles técnicos
- El concepto SEA la abstracción (ej., "separación de preocupaciones")
Diagramas Integrales/Técnicos
Usa ejemplos concretos cuando:
- Diagrames un sistema, protocolo o arquitectura real
- El diagrama se usará para enseñar o explicar (ej., video de YouTube)
- La audiencia necesite entender cómo se ven las cosas realmente
- Estés mostrando cómo se integran múltiples tecnologías
Para diagramas técnicos, DEBES incluir artefactos de evidencia (ver más abajo).
Mandato de Investigación (Para Diagramas Técnicos)
Antes de dibujar algo técnico, investiga las especificaciones reales.
Si estás diagramando un protocolo, API o framework:
- Busca los formatos JSON/datos reales
- Encuentra los nombres de eventos reales, nombres de métodos o endpoints de API
- Entiende cómo se conectan realmente las piezas
- Usa terminología real, no marcadores de posición genéricos
Malo: "Protocolo" → "Frontend" Bueno: "AG-UI transmite eventos (RUN_STARTED, STATE_DELTA, A2UI_UPDATE)" → "CopilotKit renderiza mediante createA2UIMessageRenderer()"
La investigación hace que los diagramas sean precisos Y educativos.
Artefactos de Evidencia
Los artefactos de evidencia son ejemplos concretos que demuestran que tu diagrama es preciso y ayudan a los espectadores a aprender. Inclúyelos en diagramas técnicos.
Tipos de artefactos de evidencia (elige lo que sea relevante para tu diagrama):
| Tipo de Artefacto | Cuándo Usarlo | Cómo Renderizarlo |
|---|---|---|
| Fragmentos de código | APIs, integraciones, detalles de implementación | Rectángulo oscuro + texto coloreado por sintaxis (ver paleta de colores para colores de artefactos de evidencia) |
| Ejemplos de datos/JSON | Formatos de datos, esquemas, cargas útiles | Rectángulo oscuro + texto coloreado (ver paleta de colores) |
| Secuencias de eventos/pasos | Protocolos, flujos de trabajo, ciclos de vida | Patrón de línea de tiempo (línea + puntos + etiquetas) |
| Maquetas de UI | Mostrar salida/resultados reales | Rectángulos anidados imitando UI real |
| Contenido de entrada real | Mostrar qué ENTRA en un sistema | Rectángulo con contenido de muestra visible |
| Nombres de API/métodos | Llamadas de función reales, endpoints | Usa nombres reales de la documentación, no marcadores de posición |
Ejemplo: Para un diagrama sobre un protocolo de streaming, podrías mostrar:
- Los nombres de evento reales de la especificación (no solo "Evento 1", "Evento 2")
- Un fragmento de código que muestra cómo conectarse
- Cómo se ven realmente los datos transmitidos
Ejemplo: Para un diagrama sobre un pipeline de transformación de datos:
- Muestra datos de entrada de muestra (formato real, no "Entrada")
- Muestra datos de salida de muestra (formato real, no "Salida")
- Muestra estados intermedios si son relevantes
El principio clave: muestra cómo se ven las cosas realmente, no solo cómo se llaman.
Arquitectura de Múltiples Zoom
Los diagramas integrales operan en múltiples niveles de zoom simultáneamente. Piensa en ello como un mapa que muestra tanto las fronteras del país como los nombres de las calles.
Nivel 1: Flujo Resumido
Una visión general simplificada que muestra el pipeline o proceso completo de un vistazo. A menudo se coloca en la parte superior o inferior del diagrama.
Ejemplo: Entrada → Procesamiento → Salida o Cliente → Servidor → Base de datos
Nivel 2: Límites de Sección
Regiones etiquetadas que agrupan componentes relacionados. Estas crean "salas" visuales que ayudan a los espectadores a entender qué pertenece junto.
Ejemplo: Agrupación por responsabilidad (Backend / Frontend), por fase (Configuración / Ejecución / Limpieza) o por equipo (Usuario / Sistema / Externo)
Nivel 3: Detalle Dentro de las Secciones
Artefactos de evidencia, fragmentos de código y ejemplos concretos dentro de cada sección. Aquí es donde reside el valor educativo.
Ejemplo: Dentro de una sección "Backend", podrías mostrar el formato de respuesta de API real, no solo una caja etiquetada como "Respuesta de API"
Para diagramas integrales, apunta a incluir los tres niveles. El resumen da contexto, las secciones organizan y los detalles enseñan.
Malo vs Bueno
| Malo (Mostrar) | Bueno (Argumentar) |
|---|---|
| 5 cajas iguales con etiquetas | Cada concepto tiene una forma que refleja su comportamiento |
| Diseño de cuadrícula de tarjetas | Estructura visual coincide con la estructura conceptual |
| Iconos decorando texto | Formas que SON el significado |
| Mismo contenedor para todo | Vocabulario visual distinto por concepto |
| Todo en una caja | Texto flotante con contenedores selectivos |
Simple vs Integral (Sabe Cuál Necesitas)
| Diagrama Simple | Diagrama Integral |
|---|---|
| Etiquetas genéricas: "Entrada" → "Proceso" → "Salida" | Específico: muestra cómo se ve realmente la entrada/salida |
| Cajas con nombre: "API", "Base de datos", "Cliente" | Cajas con nombre + ejemplos de solicitudes/respuestas reales |
| Etiqueta "Eventos" o "Mensajes" | Línea de tiempo con nombres de eventos/mensajes reales de la especificación |
| Rectángulo "UI" o "Panel" | Maqueta que muestra elementos de UI y contenido reales |
| ~30 segundos para explicar | ~2-3 minutos de contenido didáctico |
| El espectador aprende la estructura | El espectador aprende la estructura Y los detalles |
Los diagramas simples son adecuados para conceptos abstractos, resúmenes rápidos o cuando la audiencia ya conoce los detalles. Los diagramas integrales son necesarios para arquitecturas técnicas, tutoriales, contenido educativo o cuando quieres que el diagrama mismo enseñe.
Contenedor vs. Texto Flotante
No cada pieza de texto necesita una forma alrededor. Por defecto, usa texto flotante. Agrega contenedores solo cuando tengan un propósito.
| Usa un Contenedor Cuando... | Usa Texto Flotante Cuando... |
|---|---|
| Es el punto focal de una sección | Es una etiqueta o descripción |
| Necesita agrupación visual con otros elementos | Es detalle de apoyo o metadatos |
| Las flechas necesitan conectarse a él | Describe algo cercano |
| La forma misma tiene significado (diamante de decisión, etc.) | La tipografía por sí sola crea jerarquía suficiente |
| Representa una "cosa" distinta en el sistema | Es un título de sección, subtítulo o anotación |
Tipografía como jerarquía: Usa tamaño de fuente, peso y color para crear jerarquía visual sin cajas. Un título de 28px no necesita un rectángulo alrededor.
La prueba del contenedor: Para cada elemento con caja, pregúntate "¿Funcionaría esto como texto flotante?" Si es así, elimina el contenedor.
Proceso de Diseño (Haz Esto ANTES de Escribir SVG)
Paso 0: Evalúa la Profundidad Requerida
Antes de cualquier otra cosa, determina si necesita ser:
- Simple/Conceptual: Formas abstractas, etiquetas, relaciones (modelos mentales, filosofías)
- Integral/Técnico: Ejemplos concretos, fragmentos de código, datos reales (sistemas, arquitecturas, tutoriales)
Si es integral: Investiga primero. Busca especificaciones reales, formatos, nombres de eventos, APIs.
Paso 1: Comprende Profundamente
Lee el contenido. Para cada concepto, pregúntate:
- ¿Qué HACE este concepto? (no qué ES)
- ¿Qué relaciones existen entre conceptos?
- ¿Cuál es la transformación o flujo central?
- ¿Qué necesitaría VER alguien para entender esto? (no solo leer sobre ello)
Paso 2: Mapea Conceptos a Patrones
Para cada concepto, encuentra el patrón visual que refleje su comportamiento. Los bocetos y notas de uso para cada patrón están en references/visual-patterns.md.
| Si el concepto... | Usa este patrón |
|---|---|
| Genera múltiples salidas | Abanico (flechas radiales desde el centro) |
| Combina entradas en una | Convergencia (embudo, flechas que convergen) |
| Tiene jerarquía/anidamiento | Árbol (líneas + texto flotante) |
| Es una secuencia de pasos | Línea de tiempo (línea + puntos + etiquetas flotantes) |
| Se repite o mejora continuamente | Espiral/Ciclo (flecha que vuelve al inicio) |
| Es un estado o contexto abstracto | Nube (elipses superpuestas) |
| Transforma entrada en salida | Línea de montaje (antes → proceso → después) |
| Compara dos cosas | Lado a lado (paralelo con contraste) |
| Se separa en fases | Espacio/Ruptura (separación visual entre secciones) |
Paso 3: Asegura Variedad
Para diagramas con múltiples conceptos: cada concepto principal debe usar un patrón visual diferente. Sin tarjetas o cuadrículas uniformes.
Paso 4: Boceta el Flujo
Antes de escribir el marcado, traza mentalmente cómo se mueve el ojo a través del diagrama. Debe haber una historia visual clara.
Paso 5: Construye el HTML/SVG
Solo ahora escribe el archivo, empezando desde references/starter.html. Diseña sobre una cuadrícula de 20px y anota las coordenadas clave (columnas, filas, centros de nodos) antes de colocar cualquier cosa. Ver más abajo cómo manejar diagramas grandes.
Paso 6: Renderiza y Valida (OBLIGATORIO)
Después de escribir el archivo, DEBES ejecutar el bucle renderizar-ver-corregir hasta que el diagrama se vea bien. Esto no es opcional; consulta la sección Renderizar y Validar a continuación para el proceso completo.
Estrategia para Diagramas Grandes / Integrales
Para diagramas integrales o técnicos, construye el SVG una sección a la vez. No escribas todo el archivo en una sola pasada. Un diagrama integral puede exceder el límite de salida por respuesta, e incluso cuando quepa, una sección por pasada le da a cada sección la atención que merece.
El Flujo de Trabajo Sección por Sección
Fase 1: Construye cada sección
- Crea el archivo desde
references/starter.html: establece el<title>, elviewBoxy agrega la primera sección. - Agrega una sección por edición, cada una en su propio
<g id="sec-...">. Piensa en el diseño de esta sección, su espaciado y cómo se conecta con lo que ya está ahí. - Usa ids descriptivos (
data-node="trigger",id="sec-backend") para que los bordes entre secciones sean legibles:data-from="trigger" data-to="router". - Mantén un plan de coordenadas en un comentario HTML en la parte superior del svg (x de columnas, y de filas, límites de sección). Cada sección posterior y cada borde lo leen, y así corriges el espaciado sin adivinar.
Fase 2: Revisa el conjunto
Lee el archivo completo y verifica:
- ¿Cada
data-from/data-tonombra undata-nodeque existe? - ¿El espaciado está equilibrado, o algunas secciones están apretadas mientras otras están dispersas?
- ¿El
viewBoxcontiene todo, con un margen de ~40px?
Fase 3: Renderiza y valida (a continuación).
Límites de Sección
…
[truncado para traducción]