---
name: excalidraw-diagrams
description: Genera ficheros .excalidraw a partir de una descripción en lenguaje natural - diagramas de flujo, arquitectura, secuencia, entidad-relación, mapas mentales y carriles por rol. El resultado se abre en Excalidraw y se sigue editando a mano. Úsala cuando haya que explicar un proceso o un sistema con una imagen y no quieras colocar cada caja tú.
version: 1.0.0
license: CC-BY-4.0
updated: 2026-08-17
---

# Diagramas Excalidraw desde una descripción

El valor de un diagrama generado no es ahorrarse el dibujo: es que sale
**editable**. Un PNG generado por una IA se descarta en cuanto cambia algo; un
`.excalidraw` se abre, se arrastran dos cajas y sigue vivo.

## Elegir el tipo, que es la mitad del trabajo

| Lo que se quiere contar | Diagrama |
|---|---|
| Pasos en orden, con decisiones | Flujo |
| Qué se conecta con qué | Relaciones |
| Un concepto y sus ramas | Mapa mental |
| Componentes de un sistema y sus llamadas | Arquitectura |
| Por dónde viajan los datos y dónde se guardan | Flujo de datos |
| Quién hace qué, con traspasos entre roles | Carriles (swimlane) |
| Objetos hablando a lo largo del tiempo | Secuencia |
| Tablas, claves y cardinalidad | Entidad-relación |

Un flujo de datos **no** representa el orden de los pasos, solo por dónde va el
dato. Confundirlo con un diagrama de flujo es el error más habitual, y produce
un diagrama que parece correcto y dice algo falso.

## Cuántos elementos

| Tipo | Cómodo | Techo |
|---|---|---|
| Pasos de un flujo | 3-10 | 15 |
| Entidades relacionadas | 3-8 | 12 |
| Ramas de un mapa mental | 4-6 | 8 |

Por encima de 20 elementos, ningún diagrama se lee. Cuando la petición trae 15
componentes, la respuesta correcta no es dibujarlos todos: es proponer una vista
general de seis y diagramas de detalle por subsistema.

## Estructura del fichero

```json
{
  "type": "excalidraw",
  "version": 2,
  "source": "https://excalidraw.com",
  "elements": [],
  "appState": { "viewBackgroundColor": "#ffffff", "gridSize": 20 },
  "files": {}
}
```

Elementos: `rectangle` para pasos y entidades, `diamond` para decisiones,
`ellipse` para énfasis, `arrow` para conexiones, `text` para etiquetas.

**Todos los textos con `fontFamily: 5`** (Excalifont). Es el detalle que separa
un diagrama que parece hecho en Excalidraw de uno que parece pegado desde otra
herramienta.

## Retícula y color

- Hueco horizontal de 200-300 px, vertical de 100-150 px. Apretarlos es lo que
  produce esos diagramas donde las flechas cruzan por encima de las cajas.
- Texto de 16 px para arriba. Por debajo no se lee en una captura.
- Cuatro colores, con significado, no decorativos:
  `#a5d8ff` principal · `#b2f2bb` secundario · `#ffd43b` lo importante ·
  `#ffc9c9` errores y avisos.
- IDs únicos por elemento. Repetirlos hace que Excalidraw se coma elementos al
  abrir el fichero, en silencio.

Dos disposiciones que resuelven casi todo:

```javascript
// Rejilla, para diagramas de relaciones
const cols = Math.ceil(Math.sqrt(n));
const x = x0 + (i % cols) * 260;
const y = y0 + Math.floor(i / cols) * 130;

// Radial, para mapas mentales
const a = (2 * Math.PI * i) / ramas;
const x = cx + r * Math.cos(a);
const y = cy + r * Math.sin(a);
```

## Iconos de marca

Para arquitecturas de AWS, Azure, GCP o Kubernetes, las librerías de
[libraries.excalidraw.com](https://libraries.excalidraw.com/) dan iconos reales
en lugar de rectángulos con el nombre dentro.

El detalle práctico: **cada icono son entre 200 y 1000 líneas de JSON**. Pegarlos
a mano en el diagrama funciona, pero se come el contexto entero y arriesga
colisiones de ID. Merece la pena un script que reciba nombre de icono y
coordenadas, y haga la transformación de forma determinista.

Si no hay librería instalada, el diagrama sale igual con formas simples y color:
se entiende perfectamente y los iconos se pueden sustituir después.

## Antes de entregar

- [ ] IDs únicos
- [ ] Nada se solapa
- [ ] Texto de 16 px o más, todo con `fontFamily: 5`
- [ ] Las flechas conectan lo que dicen conectar
- [ ] Es JSON válido
- [ ] Menos de 20 elementos

Y decir cómo abrirlo: arrastrar el fichero a [excalidraw.com](https://excalidraw.com)
o abrirlo con la extensión de Excalidraw en VS Code.

## Límites honestos

Las curvas complejas se simplifican, no hay detección de colisiones (de ahí las
distancias de la retícula) y no se incrustan imágenes. Para un diagrama de
veinte cajas con posicionamiento fino, generar la base y ajustarla a mano en
Excalidraw sigue siendo más rápido que iterar sobre el JSON.