CommunityImagengithub.com

diagramas-unicode

Dibuja diagramas de arquitectura, diseño de sistemas y flujos como arte Unicode con caracteres de recuadro (┌─┐ │ └─┘ ░ sombras), no ASCII simple. Úsalo cuando se te pida un diagrama de texto, ASCII o de recuadro, o un diagrama en un documento de diseño o README.

¿Qué es diagramas-unicode?

Esta habilidad permite a un agente de IA (como Claude Code, Cursor o Codex) crear diagramas de arquitectura y diseño de sistemas utilizando caracteres Unicode de recuadro en formato de texto plano. Es útil para documentar diseños en archivos README, documentos de diseño o herramientas que no admiten gráficos (Mermaid, SVG). El agente utiliza un motor Python (`textdiagram.py`) que coloca cajas, flechas y etiquetas en una cuadrícula siguiendo reglas estrictas de estilo (mayúsculas, sombras, tipos de caja). Soporta diagramas con encabezados, componentes con sombras, flechas rectas y curvas, buses de distribución, y etiquetas en línea, todo ello en un bloque de código delimitado.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/rohalrafael/unicode-diagrams/tree/HEAD

Installed? Explore more Imagen skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Diagramas Unicode

Dibuja diagramas como texto plano con caracteres Unicode de recuadro, en un estilo homogéneo. Construye siempre el diagrama con el motor de cuadrícula textdiagram.py que se muestra a continuación. No dibujes a mano: los diagramas dibujados a mano se desalinean.

Reglas de estilo

  • Texto plano en un bloque de código delimitado. Nada de Mermaid, SVG, imágenes ni emojis.
  • Ancho: 80 columnas por defecto. Para cambiarlo, pasa max_width al constructor, por ejemplo D(max_width=100). El motor lanza un error si una línea es más larga.
  • Todo el texto está en MAYÚSCULAS. El motor hace esto por ti: escribe el texto normal en el script. Excepción: las unidades cuyo caso cambia el significado se mantienen tal cual, cuando las escribes exactamente así: Hz kHz MHz GHz, kB MB GB TB KiB MiB GiB TiB, kb Mb Gb Tb kbps Mbps Gbps, ms µs ns. Otras palabras, como NGINX o K8S, están en mayúsculas.
  • Caja COMPONENTE (una parte del sistema: servicio, cliente, base de datos, cola, trabajador): líneas ligeras ┌─┐ │ └─┘ más una sombra ligera ░, una columna a la derecha y una fila hacia abajo. Para agrupar partes, divide una caja en secciones: divisores ligeros ├───┤, un marco, una sombra.
  • Caja TÍTULO (el título principal del documento, uno por diagrama): líneas dobles ╔═╗ ║ ╚═╝, sin sombra. Un elemento por línea (nombre, tipo de documento, versión), cada línea centrada en la caja. Créala con d.header(...): el motor centra la caja sobre todo el diagrama. Opcional: una caja de metadatos a la izquierda (empresa, RFC, fecha) y una caja de sello a la derecha (estado). Las tres tienen la misma altura; las líneas de relleno de la caja de título tienen un punto centrado ·. Ninguna flecha puede comenzar o terminar en una caja de encabezado.
  • Caja MARCO (encabezado de sección, nota, llamada): líneas ligeras, sin sombra. Nota / llamada: coloca el nombre en el borde superior, como ┌─ NOTA ───┐. No añadas una leyenda: el estilo es el mismo en todos los diagramas.
  • Texto libre (d.annotate): una observación breve sin caja, al lado del diagrama. Úsalo con poca frecuencia. Una línea no debe cruzarlo.
  • Flecha horizontal: etiqueta dentro de la línea, un espacio a cada lado: ── HTTPS ──▶. Ambos extremos tocan una caja: la línea comienza en la columna de sombra de la caja emisora y la cabeza toca la caja receptora.
  • Flecha vertical: la línea comienza desde ┬ en el borde inferior, termina con ▼. La etiqueta va a la derecha de la línea, una fila debajo de la sombra. O inserta la etiqueta en la línea (inline=True): línea, fila en blanco, líneas de etiqueta centradas en la línea, fila en blanco, línea.
  • Flecha curvada (d.route): cualquier número de curvas, en cualquier dirección (▲ ▼ ◀ ▶). La etiqueta va dentro de un segmento horizontal, o al lado (o, con inline=True, insertada en) un segmento vertical. Las líneas que se cruzan o unen forman una unión (┼ ├ ┤ ┬ ┴). Una línea nunca atraviesa una caja.
  • Bus (d.fan_out): una línea desde una caja que se divide en una flecha por destino. La etiqueta va en la línea compartida.
  • Cabezas de flecha: rellenas ▶ ◀ ▲ ▼ para el flujo principal. Huecas ▷ ◁ △ ▽ para un segundo tipo de relación (asíncrona, opcional, evento). Usa huecas solo si el diagrama necesita dos tipos, y nombra el significado en una etiqueta o una nota, no en una leyenda.
  • Etiqueta cada flecha con lo que fluye (protocolo, evento, datos).
  • Si no está claro qué rol tiene una caja: COMPONENTE para partes del sistema, TÍTULO para el título principal, MARCO para todo lo demás.

Flujo de trabajo

  1. Enumera los componentes, marcos y flechas antes de dibujar.
  2. Escribe el motor en /tmp/textdiagram/textdiagram.py (código fuente completo al final de este archivo, cópialo exactamente). Escríbelo de nuevo en cada sesión, para que nunca se use una versión antigua.
  3. Escribe un script Python corto que importe el motor y construya el diagrama. Usa las ayudas de diseño para colocar cajas (no adivines coordenadas):
    • Diagram.x_right_of(a, label) — x para la siguiente caja a la derecha, con espacio para la etiqueta de la flecha.
    • Diagram.x_left_of(a, lines, label) — x para una nueva caja a la izquierda de a, con espacio para la etiqueta.
    • Diagram.y_below(a) — y para una caja debajo de a. Con etiqueta en línea: Diagram.y_below(a, lines=N).
    • Diagram.x_centered_under(a, lines) — x para que una caja quede centrada debajo de a (necesario para arrow_v).
    • Para carriles de ruta, usa los bordes de las cajas: a.right + 4, a.bottom + 2.
  4. Ejecútalo. Si lanza DiagramError, corrige el diseño como indique el mensaje y vuelve a ejecutarlo.
  5. Pega la salida en un bloque de código exactamente como se imprimió. No la edites a mano. Para un cambio, edita el script y vuelve a ejecutarlo.

Ejemplo 1: encabezado, secciones, rutas

import sys; sys.path.insert(0, "/tmp/textdiagram")
from textdiagram import Diagram as D

d = D()                                                   # max_width=80 es el valor por defecto
t = d.header(["Plataforma de Pedidos", "Arquitectura"],
             left=["Acme Inc", "RFC 9000", "Nov 2026"],
             right=["*~~~~~~~~~*", "Análisis Profundo", "*~~~~~~~~~*"])
y = t.bottom + 2
cli = d.box(0, y, ["Cliente"])                             # role="component" es el valor por defecto
gw = d.box(D.x_right_of(cli, "HTTPS"), y, ["Puerta de Enlace"])
d.arrow_h(cli, gw, "HTTPS")
svc = d.box(gw.x + 16, D.y_below(gw) + 2,                 # secciones: una caja, una sombra
            [["Auth"], ["Pedidos"], ["Facturación"]], title="Servicios")
d.route(gw, "bottom", svc, "top", via=[gw.bottom + 3], label="Llamadas")  # forma de S
cache = d.box(D.x_left_of(svc, ["Caché"], "Lecturas"), svc.rows[1] - 1, ["Caché"])
d.arrow_h(svc, cache, "Lecturas", row=svc.rows[1])           # conectar a una sección
aud = d.box(svc.right + 9, y, ["Auditoría"])
d.route(svc, "right", aud, "bottom", a_row=svc.rows[0], label="Eventos")  # una curva
d.route(svc, "right", cli, "bottom", a_row=svc.rows[2],   # bucle: 3 curvas
        via=[svc.right + 4, svc.bottom + 2], label="Reintento")
print(d.render())

Salida:

┌────────────┐               ╔══════════════════╗            ┌───────────────┐
│  ACME INC  │               ║  PLATAFORMA DE   ║            │  *~~~~~~~~~*  │
│  RFC 9000  │               ║     PEDIDOS      ║            │   ANÁLISIS    │
│  NOV 2026  │               ║  ARQUITECTURA    ║            │   PROFUNDO    │
└────────────┘               ║        ·         ║            │  *~~~~~~~~~*  │
                             ╚══════════════════╝            └───────────────┘

┌──────────┐            ┌───────────┐                             ┌─────────┐
│  CLIENTE │── HTTPS ──▶│  PUERTA   │░                            │ AUDIT.  │░
└──────────┘░           │  DE ENLACE│░                            └─────────┘░
 ░░░░░▲░░░░░░            └─────┬─────┘░                             ░░░░▲░░░░░░
      │                       │                                        │
      │                       │                                        │
      │                       └───── LLAMADAS ─────┐                   │
      │                                         │                      │
      │                                         ▼                      │
      │                               ┌─ SERVICIOS ───┐               │
      │                               │  AUTH         │─── EVENTOS ───┘
      │          ┌─────────┐          ├───────────────┤░
      │          │  CACHÉ  │◀─ LECT.─│  PEDIDOS      │░
      │          └─────────┘░         ├───────────────┤░
      │           ░░░░░░░░░░░        │  FACTURACIÓN  │────┐
      │                              └───────────────┘░   │
      │                               ░░░░░░░░░░░░░░░░░   │
      │                                                    │
      └───────────────────── REINTENTO ───────────────────┘

Ejemplo 2: bus, cabezas huecas, etiqueta en línea, texto libre

import sys; sys.path.insert(0, "/tmp/textdiagram")
from textdiagram import Diagram as D

d = D()
t = d.header(["Bus de Eventos", "Diseño"], left=["Acme Inc", "ADR 12", "Nov 2026"],
             right=["*~~~~~~~*", "Borrador", "*~~~~~~~*"])
y = t.bottom + 4
pub = d.box(0, y, ["Publicador"])
s1 = d.box(36, y - 2, ["Facturación"])
s2 = d.box(36, y + 4, ["Auditoría"])
s3 = d.box(36, y + 10, ["Búsqueda"])
d.fan_out(pub, [s1, s2, s3], trunk=28, label="Eventos", head="hollow")  # bus, cabezas huecas
arc = d.box(D.x_centered_under(pub, ["Archivo"]), D.y_below(pub, lines=2), ["Archivo"])
d.arrow_v(pub, arc, "Copia\nnocturna", inline=True)       # etiqueta insertada en la línea
d.annotate(46, y + 16, ["Al menos una", "entrega"])     # texto libre, sin caja
print(d.render())

Salida:

┌────────────┐        ╔═════════════╗       ┌─────────────┐
│  ACME INC  │        ║  BUS DE     ║       │  *~~~~~~~*  │
│  ADR 12    │        ║  EVENTOS    ║       │   BORRADOR  │
│  NOV 2026  │        ║   DISEÑO    ║       │  *~~~~~~~*  │
└────────────┘        ║      ·      ║       └─────────────┘
                      ╚═════════════╝

                                    ┌───────────┐
                            ┌──────▷│ FACTURAC. │░
┌─────────────┐             │       └───────────┘░
│ PUBLICADOR  │── EVENTOS ───┤        ░░░░░░░░░░░░░
└──────┬──────┘░            │
 ░░░░░░│░░░░░░░░            │
                            │       ┌─────────┐
     COPIA                  ├──────▷│ AUDIT.  │░
     NOCTURNA               │       └─────────┘░
                            │        ░░░░░░░░░░░
       │                    │
       ▼                    │
 ┌───────────┐              │       ┌──────────┐
 │  ARCHIVO  │░             └──────▷│ BÚSQUEDA │░
 └───────────┘░                     └──────────┘░
  ░░░░░░░░░░░░░                      ░░░░░░░░░░░░


                                              AL MENOS UNA
                                              ENTREGA

Referencia de la API

  • D(max_width=80) — crea un diagrama; max_width es el límite de columnas.
  • d.box(x, y, lines, role="component"|"frame"|"title", title=None, w=None, align="left") → Box (.x .y .w .h .right .bottom .cx .rows; right/bottom incluyen la sombra). lines es una lista de líneas, o una lista de secciones (listas de líneas) para dividir la caja. box.rows contiene la fila de flecha de cada sección. align="center" centra el texto.
  • d.header(title, left=None, right=None, y=0) → caja Box de título. Cada argumento es una lista de líneas. Las cajas obtienen su x final en el momento del renderizado. Un encabezado por diagrama.
  • d.arrow_h(a, b, label="", row=None, head="filled") — a y b lado a lado; funciona en ambas direcciones. row selecciona una fila de sección (a.rows[i]). head es "filled" o "hollow".
  • d.arrow_v(a, b, label="", head="filled", inline=False) — b debajo de a, centrado debajo. Una etiqueta puede tener más de una línea ("\n"). Con inline=True, deja espacio con Diagram.y_below(a, lines=N).
  • d.route(a, a_side, b, b_side, via=(), label="", label_seg=None, a_row=None, b_row=None, head="filled", inline=False) — los lados son "left" "right" "top" "bottom". La línea sale de a_side de a y entra en b_side de b. Tiene len(via) + 2 segmentos, que alternan entre horizontales y verticales, empezando con la dirección que sale de a_side. Cada valor de via es el carril de un segmento medio: una x para un segmento vertical, una y para un segmento horizontal. via=[] es una curva, un valor es dos curvas (forma de S o U), dos valores son tres curvas (un bucle). a_row / b_row seleccionan una fila de sección. label_seg selecciona el segmento (desde 0) que lleva la etiqueta.
  • d.fan_out(a, targets, trunk, a_side="right", b_side="left", label="", head="filled", a_row=None, inline=False) — un bus. trunk es el carril de la línea compartida: una x para lados izquierdo/derecho, una y para superior/inferior.
  • d.arrow_elbow(a, b, label="", mode="vh"|"hv", head="filled") — una curva, una forma abreviada de route. vh: sale de la parte inferior de a, gira hacia el lado de b. hv: sale del lado de a, gira hacia la parte superior de b. La dirección sigue la posición de b.
  • d.annotate(x, y, lines, align="left") → Box (rol "text") — texto libre, en mayúsculas. lines es una cadena ("\n" comienza una nueva línea) o una lista.
  • d.text(x, y, s) — texto sin formato (no en mayúsculas).
  • d.render() — devuelve el diagrama; coloca el encabezado; comprueba el ancho y los caracteres anchos.
  • El motor lanza DiagramError en caso de superposiciones, espacios pequeños, valores de carril incorrectos o líneas que superan el ancho máximo.

Si no hay un shell disponible

Dibuja a mano con las mismas reglas. Luego cuenta las columnas de cada línea y verifica que: la sombra derecha está una columna a la derecha de la caja; la fila de sombra inferior comienza una columna a la derecha del borde izquierdo de la caja y termina en la columna de sombra; todos los bordes de la caja están alineados.

Código fuente del motor: textdiagram.py

"""textdiagram: dibuja diagramas de caja Unicode alineados en una cuadrícula de caracteres.

Estilo:
  Todo el texto está en mayúsculas, excepto las unidades en KEEP.
  Caja COMPONENTE: líneas ligeras + sombra ligera (░) una columna a la derecha, una fila hacia abajo.
  Caja TÍTULO: líneas dobles, sin sombra, centrada sobre el diagrama (colocada en el renderizado).
  Caja MARCO: líneas ligeras, sin sombra (nota, llamada).
  Encabezado: caja de título con una caja de metadatos opcional (izquierda) y una caja de sello (derecha);
  las líneas de relleno de la caja de título tienen un punto centrado.
  Secciones: una caja dividida por divisores ligeros, una sombra para toda la caja.
  Flecha horizontal: etiqueta dentro de la línea, ambos extremos tocan una caja:  ── ETIQUETA ──▶
  Flecha vertical: etiqueta a la derecha de la línea, una fila debajo de la sombra.
  Ruta: flecha con cualquier número de curvas, establecida por coordenadas de carril (via).
  Cabeza: rellena (▶) o hueca (▷). fan_out: una línea que se divide en varias flechas.
  Etiqueta en una línea vertical: al lado de la línea, o insertada en ella (inline=True).
  annotate: texto libre sin caja.
"""
import re
import unicodedata

SHADOW = "░"
MIN_DASH = 2  # guiones a cada lado de una etiqueta de flecha
HEADER_GAP = 2  # columnas entre las cajas de encabezado

# Unidades cuyo caso cambia el significado (MB = byte, Mb = bit, ms = mili, MS = mega).
# Una palabra se conserva solo si está escrita exactamente como una de estas.
KEEP = {
    "Hz", "kHz", "MHz", "GHz",
    "kB", "MB", "GB", "TB", "KiB", "MiB", "GiB", "TiB",
    "kb", "Mb", "Gb", "Tb", "kbps", "Mbps", "Gbps",
    "ms", "µs", "ns",
}

# Caracteres de dibujo de caja como conjuntos de brazos: donde se encuentran dos líneas de flecha, los brazos
# se unen en un carácter de unión (┼, ├, ...).
ARMS = {"─": "LR", "│": "UD", "┌": "RD", "┐": "LD", "└": "RU", "┘": "LU",
        "├": "UDR", "┤": "UDL", "┬": "LRD", "┴": "LRU", "┼": "UDLR"}
BY_ARMS = {frozenset(v): 

…

[truncado para traducción]

Skills relacionados