Diagram Design: una skill de agente con un sistema de diseño de verdad

Todos los diagramas generados por IA se parecen. Ya sabes a qué me refiero: cajas de esquinas redondeadas, un degradado de morado a azul en algún sitio, sombras en todo, flechas que terminan un poco antes del borde de la caja y una tipografía que grita «valor por defecto». Es el equivalente visual de una nota de prensa. Técnicamente comunica. Nadie quiere leerlo.

Diagram Design, una skill de agente de Cathryn Lavery, ataca ese aspecto de frente. Su lema es sorprendentemente directo para un README: un único archivo HTML con SVG integrado, con tu marca, 45 tipos de diagrama, sin sombras, sin las chapuzas de Mermaid.

Esa última frase es la tesis. El proyecto no intenta que la generación de diagramas sea más lista. Intenta que el resultado parezca obra de alguien con criterio.

Qué produce en realidad

Describes el diagrama que quieres, el agente escribe un único archivo HTML con SVG en línea y tú haces doble clic. Sin paso de compilación, sin canal de renderizado, sin dependencia de ningún servicio. El archivo se abre sin conexión y se verá igual dentro de cinco años.

La biblioteca cubre un espectro amplísimo: diagramas de arquitectura y de cambios de arquitectura, despliegue, grafos de dependencias, clases UML, esquemas de base de datos, diagramas de flujo, de secuencia, máquinas de estados, swimlanes, flujo de datos, más toda una batería de gráficos (barras, líneas, dispersión, treemap, radar, polar, cascada, mapa de calor, sankey) y formas estructurales (árboles, organigramas, pilas de capas, Venn, pirámides, medallones). En estrategia y planificación hay cuadrantes, mapas de Wardley, Gantt, líneas de tiempo, kanban, story maps y recorridos de usuario. Incluso hay una axonometría explotada para trabajo espacial.

Cada tipo viene en tres variantes estáticas: minimal clara, minimal oscura y un tratamiento editorial completo. Una pequeña incoherencia que merece mención: el título del repositorio dice 44 tipos, el cuerpo del texto dice 45 y la galería va numerada del 01 al 44. Un proyecto tan obsesionado con su propia retícula tiene una errata. Pasa.

La parte que lo hace funcionar: las reglas

El esfuerzo se fue al sistema de diseño, y está enunciado en números, no en adjetivos.

Un solo color de acento por diagrama. El acento sirve para atraer la atención hacia uno o dos elementos. Todo lo demás es tinta, papel y gris apagado. Esta única regla elimina la mayor parte del ruido visual que hace que un diagrama de IA parezca un panel de 2016.

Tres tipografías, cada una con una función. Instrument Serif para títulos y anotaciones en cursiva. Geist sans para los nombres de nodos. Geist Mono para las subetiquetas técnicas: puertos, URL, tipos de campo. Reservar la monoespaciada para el detalle técnico es lo que hace un diseñador en activo por instinto y lo que un generador no hace jamás.

Una retícula de 4 píxeles. Cada coordenada, ancho, separación y relleno debe ser divisible entre cuatro. La autora lo llama la clave para que el resultado no parezca generado por IA. Tiene razón, y el motivo es sutil: la desalineación es la delación. No te das cuenta de que una caja mide 137 píxeles. Notas que algo no cuadra y no sabes qué.

Filetes, sin sombras, radio máximo 10px. Los bordes hacen el trabajo que suelen hacer las sombras, y lo hacen sin fingir que el diagrama es un objeto físico apoyado sobre una superficie.

Densidad de información objetivo: 4 sobre 10. Es la regla a la que más equipos se resistirán y por la que más lectores les darán las gracias. El principio declarado: el movimiento de mayor calidad suele ser borrar.

La accesibilidad tampoco es un añadido de última hora. La salida SVG lleva role="img", aria-labelledby y elementos title/description; se respetan las preferencias de movimiento reducido; el contraste WCAG AA (4.5:1 para texto, 3:1 para marcas clave) se verifica en CI. La paleta por defecto es negro azabache y mandarina sobre un papel blanco ahumado.

La incorporación de marca es la función tapada

Le das la URL de tu web. Extrae los colores y las tipografías y los asigna a roles semánticos: paper, ink, muted, accent, link. Después te entrega un recibo de fidelidad que dice qué dedujo y dónde adivinó.

Esa segunda parte importa mucho más que el raspado. Las herramientas de extracción de marca suelen darte una paleta y callarse. Enseñarte la inferencia es lo que te permite corregirla antes de producir cuarenta diagramas en el naranja equivocado.

También hay una vía de importación: apúntala a un archivo de Mermaid, draw.io o Excalidraw y redibuja el diagrama con el sistema de diseño, con cuatro mandos —formato, tamaño, detalle, audiencia— y un libro de fidelidad. Migrar un wiki lleno de gráficos de Mermaid es exactamente el caso de uso para el que se construyó esto.

Dónde encaja y dónde no

La instalación es deliberadamente aburrida. npx skills add cathrynlavery/diagram-design para cualquier cosa que lea Agent Skills; comandos del marketplace de plugins para Claude Code, Codex, GitHub Copilot y Factory Droid; enlaces simbólicos o importaciones de subdirectorio para Cursor, Cline, Gemini CLI, Windsurf, Amp, Zed, Kiro y OpenCode. Hay comandos de barra para exportar, importar, perfilar y un chequeo doctor.

La autora es refrescantemente clara sobre los límites, y son los límites correctos.

La calidad depende del modelo. El mismo prompt puede dar dos maquetaciones distintas, porque lo que recibes es geometría generada, no una plantilla rellenada. No hay fuente editable: ni lienzo que arrastrar, ni texto que puedas comparar en un diff dentro de un pull request. Para documentación que cambia cada semana, recomienda Mermaid: se le puede hacer diff, GitHub lo renderiza de forma nativa, y eso vale más que la belleza.

También plantea una pregunta que más autores de herramientas deberían hacerse: ¿sacará el lector más de este diagrama que de un párrafo? Si el «diagrama» es una caja con una etiqueta, escribe la frase. Si estás comparando dos listas, usa una tabla. Si quieres arte ASCII para una terminal, esta no es la herramienta.

El resultado es un archivo, no un servicio

Hay una decisión de diseño que parecerá más inteligente cada año: el entregable es un único archivo HTML con SVG en línea, y se abre sin conexión. Sin cuenta, sin script incrustado, sin dependencia de un proveedor que quizá suba el precio de su API el próximo trimestre. Mételo en un repositorio, adjúntalo a un ticket, imprímelo, envíalo por correo a un cliente que usa un portátil bloqueado.

Para quien haya visto a un SaaS de diagramas ser adquirido y luego degradarse, esto no es una función menor. Es la diferencia entre un artefacto y una suscripción.

El intercambio es que no puedes editarlo como editarías un lienzo. No hay arrastrar y soltar, ni panel de capas, ni pila de deshacer. Si la maquetación está mal, regeneras o retocas las coordenadas a mano, y como todo se apoya en una retícula de 4px, el retoque manual es sobrevivible de una forma que no lo sería en un documento de formato libre.

Cómo juzgar una skill de diagramas en diez minutos

Pídele algo con una forma incómoda: un sistema con un nodo obviamente importante, tres servicios de apoyo y una base de datos que todo el mundo olvida. Una buena salida usa el único acento para marcar el nodo importante y deja que el resto retroceda. Una mala salida lo colorea todo, porque colorearlo todo es lo que hacen los generadores cuando no tienen prioridades.

Luego pídele el mismo diagrama dos veces. Una salida idéntica significa que estás mirando una plantilla. Una salida distinta significa que estás mirando generación, que es más honesto y también la razón por la que importa el modelo que uses.

Por último, mira los números. Cuenta los espacios. Si no son múltiplos de cuatro, se están ignorando las restricciones, y probablemente el resto del sistema de diseño también.

El argumento de fondo

Hay una versión de este proyecto que habría sido solo un prompt de estilo. «Hazlo editorial, sin sombras, minimalista». Esa versión habría producido basura inconsistente, porque los prompts no sobreviven al contacto con un diagrama de arquitectura de cuarenta nodos.

Lo interesante de Diagram Design es que codifica el criterio como restricciones que una máquina puede comprobar: divisible entre cuatro, un solo acento, tres tipografías, ratio de contraste, sin sombras. La estética no está en el modelo. Está en la especificación.

Es una idea más portátil que la skill en sí. Hagas lo que hagas para generar visuales —diagramas, diapositivas, portadas, miniaturas— la diferencia entre una salida que parece diseñada y una que parece generada suele ser una lista corta de reglas que alguien se tomó la molestia de escribir.