Flowy, Habilidad de Diagramación Nativa para IA
Flowy genera archivos HTML autocontenidos que renderizan diagramas SVG interactivos. Cada archivo incluye CSS, JavaScript y datos de diagrama incrustados, sin dependencias: solo haz doble clic para abrirlo en cualquier navegador.
Ubicaciones de los Archivos
- Diagramas:
docs/diagrams/*.html(p. ej.,docs/diagrams/upload-flow.html). Crea la carpeta en el primer uso; puede que aún no exista. Si un proyecto ya guarda diagramas en otro lugar, sigue la convención de ese proyecto. - Plantilla HTML:
${CLAUDE_SKILL_DIR}/references/html-template.html, el renderizador canónico, y el único archivo de referencia que incluye esta habilidad. La ruta se resuelve a la propia carpeta de esta habilidad dondequiera que esté instalada (plugin, personal o proyecto), por lo que no depende del proyecto actual.
No hay deliberadamente ningún archivo de esquema, carpeta de ejemplos ni editor visual. Las versiones
anteriores de esta habilidad apuntaban a flowy/schema.ts, flowy/examples/,
flowy/editor.html y un repositorio fuente Flowy en disco. Ninguno de ellos existe, las
rutas estaban obsoletas, y seguirlas hacía perder tiempo. La plantilla HTML anterior es la
fuente de verdad para la estructura; léela antes de escribir un diagrama.
Verificación Previa
Antes de crear o editar un diagrama Flowy:
- Lee
${CLAUDE_SKILL_DIR}/references/html-template.htmlpara tener el código del renderizador actual - Lista los diagramas existentes en
docs/diagrams/para evitar conflictos de nombres - Si estás actualizando un diagrama existente, léelo primero y extrae el objeto
DIAGRAM
Esquema
Cada diagrama es un objeto JavaScript con tres campos:
{
meta: { title, description, type, tags[], created, updated },
nodes: [...],
edges: [...]
}
meta
| Campo | Tipo | Requerido | Notas |
|---|---|---|---|
| title | string | sí | Título legible |
| description | string | no | Qué muestra el diagrama |
| type | string | sí | "flowchart" o "ui-mockup" |
| tags | string[] | no | Para organización |
| created | string | no | Fecha ISO (YYYY-MM-DD) |
| updated | string | no | Fecha ISO, establecer a hoy al crear/actualizar |
nodes
| Campo | Tipo | Requerido | Notas |
|---|---|---|---|
| id | string | sí | único, snake_case (p. ej., "step1_upload") |
| type | string | sí | "box", "circle", "diamond", "note", "group" |
| label | string | sí | Texto principal mostrado en la forma |
| sublabel | string | no | Texto secundario mostrado en tooltip al pasar el cursor |
| position | { x, y } | sí | Esquina superior izquierda en píxeles |
| size | { width, height } | sí | Dimensiones en píxeles |
| style | object | no | Ver campos de estilo de nodo a continuación |
| group | string | no | id del nodo grupo padre (solo agrupación visual) |
Campos de estilo de nodo: fill, stroke, strokeWidth, color (texto), fontSize, borderRadius, opacity
edges
| Campo | Tipo | Requerido | Notas |
|---|---|---|---|
| id | string | sí | único (p. ej., "e_upload_to_extract") |
| source | string | sí | id del nodo origen |
| target | string | sí | id del nodo destino |
| label | string | no | texto en la flecha (p. ej., "sí", "error") |
| sourceHandle | string | no | "top", "right", "bottom" (predeterminado), "left" |
| targetHandle | string | no | "top" (predeterminado), "right", "bottom", "left" |
| style | object | no | Ver campos de estilo de arista a continuación |
Campos de estilo de arista: stroke, strokeWidth, strokeDasharray, markerEnd
Reglas de Renderizado de Nodos
| Tipo | Elemento SVG | Detalles |
|---|---|---|
| box | <rect> | Esquinas redondeadas mediante rx/ry desde borderRadius. Predeterminado: 8px |
| circle | <ellipse> | cx = x + width/2, cy = y + height/2, rx = width/2, ry = height/2 |
| diamond | <polygon> | 4 puntos: superior-centro, derecha-centro, inferior-centro, izquierda-centro |
| note | <path> | Rectángulo con esquina plegada (superior-derecha). Tamaño del pliegue: 12px |
| group | <rect> | Borde discontinuo (stroke-dasharray: 6,3). Renderizado DETRÁS de todos los demás nodos. Etiqueta en la esquina superior izquierda. Opacidad baja |
Reglas de Renderizado de Aristas
- Calcular punto de origen: centro del lado del identificador especificado del nodo origen (predeterminado: inferior)
- Calcular punto de destino: centro del lado del identificador especificado del nodo destino (predeterminado: superior)
- Dibujar una curva bezier cúbica (comando
C) con puntos de control desplazados 50px en la dirección del identificador - Añadir una punta de flecha usando una definición SVG
<marker> - Si
strokeDasharrayestá establecido, renderizar como línea discontinua - Si
labelexiste, renderizar en el punto medio de la bezier con un pequeño rectángulo de fondo blanco detrás
Reglas de Diseño
Dirección del Flujo
- Diagramas de flujo: De arriba a abajo (predeterminado)
- Mockups de UI: De arriba a abajo dentro de un contenedor de grupo, anotaciones a la derecha
Espaciado
- Mínimo 70px vertical entre centros de nodos
- Mínimo 60px horizontal entre nodos paralelos
- Relleno de grupo: 40px dentro de los límites del grupo
Diamantes de Decisión
- Rama izquierda = ruta principal / sí
- Rama derecha = ruta secundaria / no / error
Notas de Error/Advertencia
- Colocar a la DERECHA del flujo principal
- Conectar con aristas rojas discontinuas (
strokeDasharray: "6,3", stroke:#991b1b)
Tamaños Estándar
| Tipo | Ancho | Alto |
|---|---|---|
| box | 200 | 50 |
| circle | 90 | 40 |
| diamond | 120 | 60 |
| note | 180 | 44 |
Paleta de Colores
| Propósito | Relleno | Borde | Texto |
|---|---|---|---|
| Acciones | #ffffff | #2d6a4f | #1f2937 |
| Acciones primarias | #d1fae5 | #065f46 | #065f46 |
| Decisiones | #fef3c7 | #92400e | #1f2937 |
| Errores | #fee2e2 | #991b1b | #991b1b |
| Terminales | #40916c | #2d6a4f | #ffffff |
| Grupos | #f5f5f2 | #e6e4df | #374151 |
| Información/secundaria | #dbeafe | #1e40af | #1e40af |
| Aristas predeterminadas | , | #6b7280 | , |
Estructura del Archivo HTML
Cada archivo HTML de Flowy sigue esta estructura. Lee la referencia de la plantilla HTML para el código completo funcional.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>{título del diagrama}</title>
<style>
/* Todo el CSS en línea, barra de herramientas, lienzo, tooltips, resaltados de selección */
</style>
</head>
<body>
<div id="toolbar">
<!-- [Ajustar] [-] 100% [+] Título insignia [Descargar JSON] -->
</div>
<div id="canvas-wrap">
<svg id="canvas">
<defs><!-- marcadores de punta de flecha --></defs>
<g id="diagram-root"></g>
</svg>
</div>
<div id="tooltip"></div>
<script>
const DIAGRAM = { meta: {...}, nodes: [...], edges: [...] };
// Código de renderizado e interactividad
</script>
</body>
</html>
Barra de Herramientas
- Fija en la parte superior, 48px de alto, fondo blanco, borde inferior
- Izquierda: Botón Ajustar zoom, alejar, % de zoom, acercar
- Centro: Título del diagrama (negrita) + insignia de tipo (píldora gris)
- Derecha: Botón Descargar JSON (azul)
Interactividad (todo JavaScript vainilla)
- Zoom: La rueda del ratón escala el viewBox del SVG. Rango: 0.2x a 5x. Zoom hacia la posición del cursor.
- Desplazamiento: Arrastrar con clic en el lienzo vacío traslada el viewBox.
- Pasar el cursor: Al pasar el cursor sobre un nodo, se muestra su
sublabelen un tooltip cerca del cursor. - Clic: Al hacer clic en un nodo, se resalta (borde azul) y todas las aristas conectadas. Haz clic en el espacio vacío para anular la selección.
- Ajustar zoom: El botón calcula el cuadro delimitador de todos los nodos y establece el viewBox con un relleno de 60px.
- Descargar JSON: Serializa el objeto
DIAGRAMcomo JSON formateado y descarga un archivo.
Crear un Nuevo Diagrama
Cuando el usuario pida un nuevo diagrama de flujo o mockup de IU:
- Lee la plantilla: Lee el archivo de referencia de la plantilla HTML para obtener el código del renderizador actual
- Analiza la solicitud: Identifica nodos (pasos, decisiones, errores) y aristas (conexiones)
- Asigna posiciones usando las reglas de diseño (cuadrícula de arriba a abajo, espaciado estándar)
- Aplica colores usando la paleta de colores (terminales = verde, decisiones = ámbar, errores = rojo, etc.)
- Genera el archivo HTML completo: Copia la estructura de la plantilla, reemplaza el objeto
DIAGRAMcon los nuevos datos - Guarda en
docs/diagrams/{nombre-en-kebab-case}.html - Dile al usuario: "Abre
docs/diagrams/{nombre}.htmlen tu navegador para ver el diagrama."
Nomenclatura de Archivos
- Ubicación:
docs/diagrams/{nombre}.html - Formato:
kebab-case.html(p. ej.,docs/diagrams/upload-flow.html,docs/diagrams/checkout-screen.html) - Establece
meta.updateda la fecha ISO de hoy
Actualizar un Diagrama Existente
Cuando el usuario pida modificar un diagrama:
- Lee el archivo HTML existente
- Extrae el objeto
DIAGRAMdel bloque<script> - Modifica los nodos/aristas según lo solicitado
- Actualiza
meta.updateda la fecha de hoy - Regenera el archivo HTML completo con los datos actualizados (vuelve a leer la plantilla para el último renderizador)
- Guarda de nuevo en la misma ruta
Leer un Diagrama
Cuando se te pida analizar o describir un diagrama:
- Lee el archivo HTML
- Busca el bloque
const DIAGRAM = { ... }; - Lista los nodos por tipo y etiqueta
- Rastrea las aristas para describir el flujo en lenguaje natural
- Resalta los puntos de decisión y sus ramas
Ejemplos
"Crea un diagrama de flujo para el flujo de inicio de sesión"
Acción: Crear docs/diagrams/login-flow.html con:
start(círculo, verde) →enter_credentials(caja) →validate(diamante, ámbar)validate→ sí/izquierda →dashboard(círculo, verde)validate→ no/derecha →show_error(nota, roja) → flecha discontinua de vuelta aenter_credentials
"Actualiza el mockup de configuración para añadir un conmutador de modo oscuro"
Acción: Lee docs/diagrams/settings-screen.html, extrae DIAGRAM, añade un nuevo nodo de caja "section_dark_mode" con la etiqueta "Modo Oscuro" posicionado después de la sección Tema, actualiza meta.updated, regenera el HTML.
"Añade manejo de errores al paso 3 del flujo de carga"
Acción: Lee el HTML, encuentra el paso 3 en el arreglo de nodos, añade un nodo de nota de error a la derecha, añade una arista roja discontinua desde el paso 3 a la nota de error, regenera.
Restricciones Importantes
- Sin dependencias: Sin npm, sin enlaces CDN, sin scripts/estilos externos
- Funciona sin conexión: Debe renderizarse sin acceso a internet
- Archivo único: Cada diagrama es UN archivo
.html - Nativo del navegador: Solo HTML5 estándar, CSS3, SVG y JavaScript ES6+ vainilla
- Amigable para LLM: El JSON de DIAGRAMA debe tener un formato limpio, no minificado
Automantenimiento
Si descubres un patrón útil al crear diagramas, un nuevo truco de diseño, un color que funciona bien para un propósito específico, una mejora de renderizado, actualiza este archivo de habilidad para incluirlo. Mantén la habilidad precisa y procesable.