Diagramas D2
Escribe código fuente D2, transfórmalo a SVG y luego mira el resultado y arregla lo que veas — en un bucle, hasta que el diagrama esté listo para enviar. Un diagrama que no has visto es un diagrama que no has terminado.
Archivos de referencia — cargar bajo demanda
| Archivo | Cuándo leerlo |
|---|---|
references/d2-language.md | Al escribir cualquier D2 no trivial — sintaxis, formas, contenedores, clases, variables, y los peligros silenciosos que compilan bien pero se renderizan mal |
references/layout-engines.md | Al elegir o depurar el diseño: TALA vs ELK vs dagre, licencias, semillas, diferencias de comportamiento por motor |
references/diagram-patterns.md | Al seleccionar un tipo y estructura de diagrama — arquitectura, secuencia, ERD, cuadrícula, C4; temas, iconos, modo oscuro, incrustación en GitHub |
Paso 0 — Verificación de herramientas
Ejecutar una vez por sesión antes del primer renderizado (scripts/ aquí significa el propio directorio de esta skill — en Claude Code ${CLAUDE_SKILL_DIR} resuelve a él):
bash "${CLAUDE_SKILL_DIR}/scripts/setup.sh" --check-only
d2: ok→ continuar.d2: MISSING→ informar al usuario, luego ejecutarscripts/setup.sh(sin banderas) para instalar mediante Homebrew donde esté disponible, o mostrarle los comandos de instalación impresos. No renderices a ciegas — nada más en esta skill funciona sin d2.tala: not installedounlicensed→ está bien. ELK es la alternativa automática y produce buenos diseños. Menciona TALA solo una vez si el diagrama es un diagrama de arquitectura de software (donde TALA es significativamente mejor) y el usuario parece interesado en la calidad del resultado; nunca insistas.
Paso 1 — Planificar antes de escribir
Decide tres cosas primero:
- El mensaje. ¿Qué debería concluir un lector en cinco segundos? Un diagrama argumenta algo — "las solicitudes se ramifican aquí", "este servicio es el cuello de botella", "estas dos rutas nunca se tocan". Si no puedes enunciar el argumento, estás a punto de dibujar una colección de cajas etiquetadas.
- El tipo. Arquitectura/topología → formas y contenedores simples. Interacción en el tiempo →
sequence_diagram. Modelo de datos →sql_table. Alineación rígida (matriz, panel de control, con muchas leyendas) → cuadrícula. Consultareferences/diagram-patterns.mdpara orientación estructural por tipo. - La escala. 5–15 nodos se lee bien; 15–25 necesita contenedores para agrupar; más allá de ~25, divide en múltiples diagramas o usa
layers. Prefiere un segundo diagrama antes que un mural.
Para diagramas técnicos de sistemas reales, usa nombres reales — nombres de servicios reales, nombres de tablas reales, nombres de eventos reales del código base o la descripción del usuario. Busca en el código si está disponible. Servicio A -> Servicio B desperdicia la confianza del lector.
Paso 2 — Escribir el D2
Lee references/d2-language.md antes de escribir cualquier cosa más allá de un diagrama trivial. Las reglas que evitan el 90% de las salidas rotas:
- Conecta claves, no etiquetas. Después de
api: API Gateway, escribeapi -> db, nuncaAPI Gateway -> db— esto último crea silenciosamente una forma duplicada. - Pon entre comillas las etiquetas que contengan
#o;— un#sin comillas inicia un comentario en medio de la etiqueta y un;sin comillas divide la línea en dos formas, y ambos compilan sin error. Poner entre comillas cualquier etiqueta con puntuación es el hábito seguro. - Aplica estilo a través de
classes:, no con estilos por nodo — una definición, aplicada conclass:. Evitastyle.fillen nodos individuales; los rellenos codificados luchan contra el tema y rompen el renderizado en modo oscuro. - Establece
direction: rightpara la mayoría de los flujos de arquitectura (de izquierda a derecha se lee de forma natural). Todos los motores respetan la dirección raíz; TALA además admitedirectionpor contenedor. - Guarda el código fuente como
{nombre}.d2junto a donde pertenece la salida (por defecto:./diagrams/en el proyecto).
Paso 3 — Renderizar
Renderiza siempre a través del script incluido — selecciona el motor de diseño, protege contra salidas con marca de agua y valida primero:
bash "${CLAUDE_SKILL_DIR}/scripts/render.sh" --png input.d2 output.svg
--pngtambién escribeoutput.png— lo necesitas para el Paso 4 (la herramienta Read ve imágenes rasterizadas, no SVG).- El script imprime
engine:(lo que realmente renderizó) yfallback:(por qué, si TALA no se usó). Transmite una nota de una línea al usuario solo cuando preguntó sobre motores o quería TALA explícitamente. - Banderas útiles:
--theme N,--dark-theme 200(el SVG responde al esquema de color del lector),--sketch,--pad N,--seed N(reintento de TALA),--engine tala|elk|dagre(forzar),--allow-watermark(evaluación de TALA). - En caso de fallo, el script imprime el error de compilación de d2 con
archivo:línea:col— corrige el código fuente en esa ubicación y vuelve a ejecutar. Si el error no está claro, consulta la sección de peligros dereferences/d2-language.md.
Nunca renderices la salida de TALA para entrega con una marca de agua a menos que el usuario la acepte explícitamente; el script lo impone al recurrir a ELK.
Paso 4 — Míralo, luego arréglalo (no opcional)
El código fuente .d2 no dice nada sobre cómo quedó realmente el renderizado — el diseño es decisión del motor, no tuya. Abre el PNG con la herramienta Read y examínalo en dos pasadas:
Pasada 1 — ¿transmite el argumento?
- ¿Entra el ojo donde comienza la historia y sale donde termina?
- ¿Es consistente la dirección del flujo (no retrocede ni se lee de abajo arriba involuntariamente)?
- ¿Las agrupaciones de contenedores coinciden con las agrupaciones lógicas que planificaste?
- ¿El elemento más importante es visualmente prominente, o está enterrado?
Pasada 2 — defectos de diseño (los motores de diseño automático producen todos estos):
- Etiquetas de borde que se han alejado mucho de su borde, o son ambiguas sobre qué borde describen
- Bordes que se superponen en recorridos paralelos, cruzan a través de nodos o contenedores, o toman desvíos absurdos
- Texto truncado o colisionando con formas/iconos
- Una región apretada mientras otra está vacía; un contenedor vastamente más grande que su contenido
- Nodo tan pequeño que su etiqueta domina, o tamaños de nodo salvajemente inconsistentes
- Cualquier cosa que tendrías que explicar con disculpas si se lo mostraras al usuario
Arregla con las palancas de D2, no moviendo píxeles (el diseño automático significa que cambias entradas, no coordenadas): cambia direction; agrupa o reagrupa con contenedores; acorta las etiquetas de borde (las etiquetas largas se desvían peor en ELK); fusiona bordes paralelos en un solo borde etiquetado; mueve leyendas/títulos fuera del flujo con near; divide un diagrama sobrecargado en layers; ajusta --pad; en TALA, reintenta con --seed N (prueba 2–3 semillas — los diseños varían significativamente); como último recurso, cambia de motor para la forma de este diagrama (consulta references/layout-engines.md).
Vuelve a renderizar, vuelve a revisar, repite. Presupuesta de dos a cuatro ciclos de renderizado — un primer renderizado que sobreviva a ambas pasadas es raro. Terminado significa: ambas pasadas limpias, y nada en la imagen necesita una disculpa o una explicación.
Paso 5 — Entregar
- Confirma las rutas finales del
.svg(y del código fuente.d2) — da siempre ambos al usuario; el.d2es el artefacto editable. - Si el diagrama vivirá en un README de GitHub o sitio de documentación, ofrece una variante compatible con modo oscuro: vuelve a renderizar con
--dark-theme 200(un solo SVG que sigue el esquema de color del lector). Los patrones para incrustación PNG/<picture>están enreferences/diagram-patterns.md. - Si el usuario va a iterar sobre el diagrama por sí mismo, menciona
d2 --watch input.d2para vista previa en vivo en un navegador.
Solución de problemas
| Síntoma | Causa / solución |
|---|---|
d2: command not found | Ejecuta scripts/setup.sh (instalación guiada) |
D2_LAYOUT "tala" is not bundled | TALA no está en PATH — el script recurre automáticamente a ELK; instala TALA solo si el usuario lo desea |
Texto UNLICENSED en la salida | TALA sin licencia — el script de renderizado vuelve a renderizar con ELK automáticamente; una clave de licencia va en TSTRUCT_TOKEN o ~/.config/tstruct/auth.json |
| La exportación PNG falla, SVG bien | El primer renderizado PNG descarga un navegador sin cabeza; reintenta una vez. Si está bloqueado (sin conexión/CI), entrega SVG e inspecciónalo convirtiendo con cualquier rasterizador SVG disponible |
Error de compilación bajo --layout tala que ELK renderiza bien | Desfase de versión d2/TALA — el script recurre automáticamente; sugiere actualizar ambos |
| Faltan iconos en la salida | La URL del icono devolvió 403/404 — elimina el icono o elige otro de icons.terrastruct.com; prueba los iconos al principio |