Adiós a los diagramas genéricos de Mermaid: diagram-design le da a Claude Code un sistema de diseño (y tu paleta)
Le pides a Claude Code un diagrama de arquitectura y ya sabes exactamente qué vuelve: un bloque de Mermaid que renderiza cajas redondeadas idénticas, flechas que se cruzan en diagonal, una paleta violeta sobre fondo oscuro que nadie eligió y una tipografía que no combina con nada más de lo que publicas. Se entiende. También es el equivalente visual de una foto de stock — y si ese diagrama va a tu documentación, tu README o un post, terminas abriendo Figma treinta minutos o directamente descartando el diagrama.
diagram-design es un skill de Claude Code que ataca ese hueco exacto. En vez de enseñarle al modelo una sintaxis de diagramas, le entrega un sistema de diseño: qué puede contener un diagrama, cuántos elementos antes de dejar de comunicar, qué color va dónde y una lista de cosas que nunca debe hacer. La salida no es Mermaid: es un archivo HTML autocontenido con SVG y CSS inline que abres directo en el navegador.
Lo publicó hace días Cathryn Lavery (fundadora de BestSelf.co, escribe en littlemight.com), tiene licencia MIT y llegó al puesto #13 del trending diario de Trendshift el 9 de agosto de 2026. Hoy (verificado en vivo el 12 de agosto de 2026) está en casi 10.000 estrellas — para un repo tan nuevo, eso es una señal de tracción fuerte, no un número de redondeo.
Qué produce realmente
La unidad de salida es un archivo .html. Sin build step, sin JavaScript, sin imágenes externas: el SVG va inline, el CSS va inline, y la única dependencia externa es Google Fonts para las tres tipografías. Lo abres en el navegador, le sacas screenshot o lo metes en un sitio de docs.
Cada tipo viene en tres variantes: minimal light, minimal dark y full-editorial (esta última agrega summary cards alrededor del diagrama). El repo incluye una galería con tabs en skills/diagram-design/assets/index.html donde puedes recorrer todas antes de instalar nada — vale la pena abrirla primero, porque es la forma más rápida de decidir si la estética es la tuya.
Cuántos tipos, exactamente
Acá la documentación del propio proyecto se contradice, y conviene saberlo antes de instalar:
- La galería del README muestra 14 tipos con screenshots (architecture, flowchart, sequence, state machine, ER, timeline, swimlane, quadrant, nested, tree, org chart, Venn, layer stack, pyramid/funnel, más un “consultant 2×2” especial).
- El
SKILL.mdque efectivamente se instala — el archivo que lee Claude — lista una guía de selección de 27 tipos. - La descripción del repositorio en GitHub dice 29.
Los tres números no son tanto una contradicción como la foto de un proyecto que envía código más rápido de lo que documenta. Los tipos que existen en SKILL.md pero no están en la galería del README son los analíticos y de plataforma de datos: radar/spider, loop/flywheel, bar chart, line chart, Gantt, scatter plot, IT current-state, high-level data stack, process, medallion (almacenamiento multi-capa con niveles de calidad), data flow por rol, topología de integración de plataforma de datos y una matriz de seguridad por rol. Si juzgaras el skill por su README concluirías que no hace gráficos ni roadmaps. Sí los hace.
Consecuencia práctica: lee skills/diagram-design/SKILL.md, no el README, para saber qué le puedes pedir.
Instalación
Dos rutas, y la elección importa más de lo que parece.
Ruta 1 — clone y symlink (recomendada si piensas personalizar):
git clone git@github.com:cathrynlavery/diagram-design.git ~/code/diagram-design
ln -s ~/code/diagram-design/skills/diagram-design ~/.claude/skills/diagram-design
Fíjate que el symlink apunta al directorio interno. La raíz del repo es un wrapper para que el mismo árbol funcione como plugin de Claude Code, plugin de Codex y skill standalone; el skill en sí vive en skills/diagram-design/. Reinicia Claude Code y queda registrado como diagram-design.
Ruta 2 — como plugin (más rápida, pero el skill queda en el plugin cache, así que las ediciones a mano de references/style-guide.md no sobreviven a una actualización del plugin):
/plugin marketplace add cathrynlavery/diagram-design
/plugin install diagram-design@diagram-design
En Claude Cowork: Customize → Directory → Plugins → + → pegas cathrynlavery/diagram-design → Sync, y después lo instalas desde la lista Personal.
En Codex:
npx skills add https://github.com/cathrynlavery/diagram-design --skill diagram-design
Si vas a tocar el style guide a mano — y la sección siguiente argumenta que deberías — toma la ruta 1.
Tu primer diagrama
No hay comando que memorizar. El skill se activa por intención:
“Hazme un diagrama de arquitectura de mi app: frontend, backend, PostgreSQL y un cache Redis.”
“Necesito un quadrant de los proyectos del Q2 por impacto vs. esfuerzo.”
“Dame un sequence diagram del handshake de OAuth.”
Claude elige el tipo, carga solo el archivo de referencia de ese tipo, construye el HTML y lo guarda. También puedes partir de un scaffold y editarlo a mano:
cp assets/template.html my-diagram.html # minimal light
cp assets/template-full.html my-diagram.html # editorial, con summary cards
La parte que hace que se vea como tu proyecto
Esta es la feature que justifica la instalación. De fábrica los diagramas renderizan con la paleta neutra del propio skill. Sesenta segundos de onboarding la reemplazan por la tuya:
“onboard diagram-design to https://yoursite.com”
Claude hace fetch de tu homepage, extrae la paleta dominante y el font stack, y mapea lo que encontró a roles semánticos en vez de a valores hex crudos:
| Detectado en tu sitio | Se convierte en |
|---|---|
Fondo de <body> |
paper |
| Color de texto principal | ink |
| Texto secundario / caption | muted |
| Cards o contenedores | paper-2 |
| Color de marca más usado (CTA, link, heading) | accent |
Familia tipográfica del <h1> |
font title |
Familia tipográfica del <body> |
font node-name |
Font de <code> / <pre> |
font sublabel |
Te muestra el diff propuesto antes de escribir nada, y verifica contraste WCAG AA de ink sobre paper antes de confirmar. Ese chequeo no es decorativo: las etiquetas de un diagrama renderizan a 9–12px, y un color que pasa como texto de cuerpo en tu sitio puede fallar a ese tamaño. Si falla, el skill propone un valor ajustado y te explica por qué.
Todo lo que viene después — los 27 tipos, el primitive de anotación, la galería — lee desde references/style-guide.md y se refiere a roles (accent), nunca a hex. Cambias una línea ahí y todos los diagramas siguen.
También hay un first-run gate para que no envíes sin querer diagramas con la paleta por defecto a un proyecto con marca: en el primer diagrama de un proyecto nuevo, si el style guide sigue intacto, el skill se detiene y te ofrece las opciones (traerlo de una URL, extraerlo de un skill instalado, extraerlo de una carpeta local de design system, pegar tokens a mano, o seguir con el default).
Un detalle encontrado al verificar esta nota: el gate decide si ya fue personalizado comparando accent contra el valor literal #b5523a (el default “neutral stone + rust” que describe SKILL.md), mientras que el README describe el default instalado como “jet-black + atomic-tangerine” con otro accent. Si el accent de marca de tu proyecto coincide con alguno de esos valores, o si editas la paleta sin tocar accent, el gate puede leerse como ya-personalizado cuando no lo está. Es trivial de sortear — corres el onboarding explícitamente — pero conviene saber que es una comparación de valor, no un chequeo real de “¿esto fue editado?”.
El sistema de diseño, condensado
Las reglas son el producto. Incluso si nunca instalas el skill, esto es un checklist usable:
- Un solo accent color, sobre un máximo de dos elementos focales por diagrama. El accent le dice al lector dónde mirar primero; en todos los nodos no le dice nada.
- Tres familias tipográficas, cada una con su trabajo: una serif para títulos y callouts en itálica, una sans para nombres de nodo, y una mono estrictamente para contenido técnico (puertos, URLs, tipos de campo) — no como estética “de dev” genérica.
- Bordes hairline de 1px, cero sombras, border radius con tope en 10px.
- Cada coordenada, ancho y gap divisible por 4. El style guide es explícito en que eso es lo que evita que los diagramas se lean como generados por IA.
- Densidad objetivo 4/10: técnicamente completo, sin necesitar leyenda para entenderlo. La filosofía declarada es que el diagrama no está listo cuando se agregó todo, sino cuando ya no se puede quitar nada.
Y aplica complexity budgets duros, que es justo la regla que le falta a la mayoría de los prompts caseros:
| Restricción | Límite |
|---|---|
| Nodos por diagrama | 9 |
| Flechas / transiciones | 12 |
| Elementos con accent | 2 |
| Lifelines de sequence | 5 |
| Lanes de swimlane | 5 |
| Ítems en quadrant | 12 |
| Entidades ER | 8 |
| Profundidad de tree | 4 |
| Nodos / profundidad de org chart | 12 / 4 |
| Capas de layer stack | 6 |
| Círculos de Venn | 3 |
| Tareas de Gantt | 12 |
| Puntos de scatter | 30 |
| Callouts de anotación | 2 |
La lista de anti-patterns vale robársela aparte
SKILL.md trae una lista explícita de cosas que nunca hay que hacer. Léela como diagnóstico de por qué los diagramas generados por IA se ven como se ven:
- dark mode con glow cyan/violeta
- una monospace usada como estética “de dev” transversal
- cajas idénticas para todos los nodos
- una leyenda flotando dentro del área del diagrama
- etiquetas de flecha sin rectángulo de máscara
- texto vertical con
writing-modesobre las flechas - tres summary cards del mismo ancho como layout por defecto
- sombra en cualquier elemento
rounded-2xlen las cajas- accent en todos los nodos “importantes”
- conectores diagonales entre nodos fuera de eje
- una etiqueta de flecha tocando su propio conector
- dos conectores superpuestos o compartiendo trazado
- dos conectores compartiendo un mismo punto de anclaje en una caja
- un conector ruteado por detrás de una caja que no es su endpoint
Los conectores tienen además reglas obligatorias propias: trazados en ángulo recto redondeado, 6–10px de margen alrededor de las etiquetas, y cada flecha trazable de forma independiente.
Dos primitives
- Annotation callout — una nota en serif itálica con línea guía Bézier punteada, para acotaciones editoriales al margen. Tope de dos por diagrama.
- Sketchy filter — un filtro SVG de turbulence + displacement map que da aspecto dibujado a mano. El skill lo recomienda explícitamente para ensayos y lo desaconseja para documentación técnica.
Cuándo no usarlo
El skill documenta sus propios límites, lo que es más raro de lo que debería:
- Diagramas rápidos en unicode para un tweet o salida de terminal → otra herramienta más liviana.
- Una lista de cualquier cosa → una tabla o bullets.
- Comparaciones antes/después → una tabla.
- Una sola caja con una etiqueta → escribe la frase y ya.
Su propio encuadre antes de dibujar cualquier cosa: ¿el lector aprendería más de esto que de un párrafo bien escrito? Si no, no lo dibujes.
Dónde te deja esto
El valor acá no son los 27 tipos: es que alguien escribió las restricciones. La mayoría de nosotros prompteamos “hazme un diagrama de arquitectura lindo” y volvemos a discutir espaciado, color y densidad cada vez. Este skill convierte eso en un archivo: budgets que topean la complejidad, una lista de anti-patterns que nombra los modos de falla, y una capa de tokens que hace que “tu marca” sea una edición y no un search-and-replace sobre cada diagrama que generaste en tu vida.
Instálalo por clone + symlink si vas a tocar el style guide, lee SKILL.md en vez del README para conocer el catálogo real de tipos, y corre el onboarding antes de tu primer diagrama en cualquier proyecto que tenga marca.
Y tú, ¿dibujas diagramas para tu documentación, o los saltas porque dejarlos presentables cuesta más que escribir el párrafo?