CommunityImagemgithub.com

unicode-diagrams

Desenhe diagramas de arquitetura, design de sistemas e fluxos como arte Unicode com caracteres de desenho de caixas (┌─┐ │ └─┘ ░ sombras), não ASCII simples. Use quando solicitado um diagrama de texto, ASCII ou box-drawing, ou um diagrama em um documento de design ou README.

O que é unicode-diagrams?

Esta skill permite que agentes de IA (como Claude Code, Cursor ou Codex) gerem diagramas de arquitetura e fluxo usando caracteres Unicode de desenho de caixas, produzindo arte de texto alinhada e de alta qualidade. Diferente de ASCII simples ou Mermaid, esta skill utiliza um motor Python dedicado (`textdiagram.py`) que garante alinhamento, estilos de caixa consistentes (COMPONENT, TITLE, FRAME) e suporte a sombras, setas e layouts complexos. O desenvolvedor ou agente escreve um script curto que chama funções de layout (como `D.x_right_of`, `D.y_below`) para posicionar caixas sem coordenadas fixas, depois renderiza o diagrama em um bloco de código. A saída final é texto puro em um bloco de código, ideal para READMEs, documentação técnica em consoles ou ferramentas sem suporte a imagens.

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

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

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Diagramas Unicode

Desenhe diagramas como texto puro com caracteres Unicode de desenho de caixas, em um estilo único. Sempre construa o diagrama com o motor de grade textdiagram.py abaixo. Não desenhe à mão: diagramas desenhados manualmente perdem o alinhamento.

Regras de estilo

  • Texto puro em um bloco de código cercado. Sem Mermaid, SVG, imagens ou emojis.
  • Largura: 80 colunas por padrão. Para alterar, passe max_width para o construtor, por exemplo D(max_width=100). O motor gera um erro em uma linha mais longa.
  • Todo texto é em MAIÚSCULAS. O motor faz isso por você: escreva texto normal no script. Exceção: unidades cuja caixa altera o significado permanecem como escritas, quando você as escreve exatamente assim: Hz kHz MHz GHz, kB MB GB TB KiB MiB GiB TiB, kb Mb Gb Tb kbps Mbps Gbps, ms µs ns. Outras palavras, como NGINX ou K8S, ficam em maiúsculas.
  • Caixa COMPONENTE (uma parte do sistema: serviço, cliente, banco de dados, fila, trabalhador): linhas leves ┌─┐ │ └─┘ mais uma sombra leve ░, uma coluna à direita e uma linha abaixo. Para agrupar partes, divida uma caixa em seções: divisores leves ├───┤, um quadro, uma sombra.
  • Caixa TÍTULO (o título principal do documento, um por diagrama): linhas duplas ╔═╗ ║ ╚═╝, sem sombra. Um item por linha (nome, tipo de documento, versão), cada linha centralizada na caixa. Faça com d.header(...): o motor centraliza a caixa sobre todo o diagrama. Opcional: uma caixa de metadados à esquerda (empresa, RFC, data) e uma caixa de selo à direita (status). Todas as três têm a mesma altura; linhas de preenchimento da caixa de título seguram um ponto centralizado ·. Nenhuma seta pode começar ou terminar em uma caixa de cabeçalho.
  • Caixa MOLDURA (cabeçalho de seção, nota, chamada): linhas leves, sem sombra. Nota / chamada: coloque o nome na borda superior, como ┌─ NOTA ───┐. Não adicione legenda: o estilo é o mesmo em todo diagrama.
  • Texto livre (d.annotate): um breve comentário sem caixa, ao lado do diagrama. Use raramente. Uma linha não deve cruzá-lo.
  • Seta horizontal: rótulo dentro da linha, um espaço de cada lado: ── HTTPS ──▶. Ambas as extremidades tocam uma caixa: a linha começa na coluna de sombra da caixa emissora e a cabeça toca a caixa receptora.
  • Seta vertical: linha começa de ┬ na borda inferior, termina com ▼. O rótulo vai à direita da linha, uma linha abaixo da sombra. Ou corte o rótulo na linha (inline=True): linha, linha em branco, linhas de rótulo centralizadas na linha, linha em branco, linha.
  • Seta curvada (d.route): qualquer número de curvas, em qualquer direção (▲ ▼ ◀ ▶). O rótulo vai dentro de um segmento horizontal, ou ao lado (ou, com inline=True, cortado em) um segmento vertical. Linhas que se cruzam ou juntam formam uma junção (┼ ├ ┤ ┬ ┴). Uma linha nunca passa através de uma caixa.
  • Barramento (d.fan_out): uma linha de uma caixa que se divide em uma seta por destino. O rótulo vai na linha compartilhada.
  • Cabeças de seta: preenchidas ▶ ◀ ▲ ▼ para o fluxo principal. Vazadas ▷ ◁ △ ▽ para um segundo tipo de relação (assíncrona, opcional, evento). Use vazadas apenas se o diagrama precisar de dois tipos, e nomeie o significado em um rótulo ou nota, não em uma legenda.
  • Rotule cada seta com o que flui (protocolo, evento, dados).
  • Se não estiver claro qual função uma caixa tem: COMPONENTE para partes do sistema, TÍTULO para o título principal, MOLDURA para todo o resto.

Fluxo de trabalho

  1. Liste os componentes, molduras e setas antes de desenhar.
  2. Escreva o motor em /tmp/textdiagram/textdiagram.py (código fonte completo no final deste arquivo, copie exatamente). Escreva-o novamente a cada sessão, para que uma versão antiga nunca seja usada.
  3. Escreva um script Python curto que importa o motor e constrói o diagrama. Use os auxiliares de layout para posicionar caixas (não adivinhe coordenadas):
    • Diagram.x_right_of(a, label) — x para a próxima caixa à direita, com espaço para o rótulo da seta.
    • Diagram.x_left_of(a, lines, label) — x para uma nova caixa à esquerda de a, com espaço para o rótulo.
    • Diagram.y_below(a) — y para uma caixa abaixo de a. Com um rótulo inline: Diagram.y_below(a, lines=N).
    • Diagram.x_centered_under(a, lines) — x para que uma caixa fique centralizada sob a (necessário para arrow_v).
    • Para faixas de rota, use as bordas das caixas: a.right + 4, a.bottom + 2.
  4. Execute. Se levantar DiagramError, corrija o layout conforme a mensagem e execute novamente.
  5. Cole a saída em um bloco de código exatamente como impresso. Não edite manualmente. Para uma alteração, edite o script e execute novamente.

Exemplo 1: cabeçalho, seções, rotas

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

d = D()                                                   # max_width=80 é o padrão
t = d.header(["Plataforma de Pedidos", "Arquitetura"],
             left=["Acme Inc", "RFC 9000", "Nov 2026"],
             right=["*~~~~~~~~~*", "Mergulho Profundo", "*~~~~~~~~~*"])
y = t.bottom + 2
cli = d.box(0, y, ["Cliente"])                             # role="component" é padrão
gw = d.box(D.x_right_of(cli, "HTTPS"), y, ["Gateway"])
d.arrow_h(cli, gw, "HTTPS")
svc = d.box(gw.x + 16, D.y_below(gw) + 2,                 # seções: uma caixa, uma sombra
            [["Auth"], ["Pedidos"], ["Cobrança"]], title="Serviços")
d.route(gw, "bottom", svc, "top", via=[gw.bottom + 3], label="Chamadas")  # Forma S
cache = d.box(D.x_left_of(svc, ["Cache"], "Leituras"), svc.rows[1] - 1, ["Cache"])
d.arrow_h(svc, cache, "Leituras", row=svc.rows[1])           # anexar a uma seção
aud = d.box(svc.right + 9, y, ["Auditoria"])
d.route(svc, "right", aud, "bottom", a_row=svc.rows[0], label="Eventos")  # uma curva
d.route(svc, "right", cli, "bottom", a_row=svc.rows[2],   # laço: 3 curvas
        via=[svc.right + 4, svc.bottom + 2], label="Reenvio")
print(d.render())

Saída:

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

┌──────────┐            ┌───────────┐                             ┌─────────┐
│ CLIENTE  │── HTTPS ──▶│  GATEWAY  │░                            │AUDITORIA│░
└──────────┘░           └─────┬─────┘░                            └─────────┘░
 ░░░░░▲░░░░░░            ░░░░░│░░░░░░░                             ░░░░▲░░░░░░
      │                       │                                        │
      │                       │                                        │
      │                       └── CHAMADAS ──┐                         │
      │                                         │                      │
      │                                         ▼                      │
      │                                 ┌─ SERVIÇOS ───┐              │
      │                                 │  AUTH        │── EVENTOS ──┘
      │          ┌─────────┐            ├───────────────┤░
      │          │  CACHE  │◀─ LEITURAS─│  PEDIDOS      │░
      │          └─────────┘░           ├───────────────┤░
      │           ░░░░░░░░░░░           │  COBRANÇA     │────┐
      │                                 └───────────────┘░   │
      │                                  ░░░░░░░░░░░░░░░░░   │
      │                                                      │
      └─────────────────────── REENVIO ──────────────────────┘

Exemplo 2: barramento, cabeças vazadas, rótulo inline, texto livre

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

d = D()
t = d.header(["Barramento de Eventos", "Design"], left=["Acme Inc", "ADR 12", "Nov 2026"],
             right=["*~~~~~~~*", "Rascunho", "*~~~~~~~*"])
y = t.bottom + 4
pub = d.box(0, y, ["Publicador"])
s1 = d.box(36, y - 2, ["Cobrança"])
s2 = d.box(36, y + 4, ["Auditoria"])
s3 = d.box(36, y + 10, ["Pesquisa"])
d.fan_out(pub, [s1, s2, s3], trunk=28, label="Eventos", head="hollow")  # barramento, cabeças vazadas
arc = d.box(D.x_centered_under(pub, ["Arquivo"]), D.y_below(pub, lines=2), ["Arquivo"])
d.arrow_v(pub, arc, "Cópia\nnoturna", inline=True)       # rótulo cortado na linha
d.annotate(46, y + 16, ["Entrega pelo", "menos uma vez"])     # texto livre, sem caixa
print(d.render())

Saída:

┌────────────┐        ╔════════════════╗      ┌─────────────┐
│  ACME INC  │        ║ BARRAMENTO DE  ║      │  *~~~~~~~*  │
│  ADR 12    │        ║   EVENTOS      ║      │   RASCUNHO  │
│  NOV 2026  │        ║    DESIGN      ║      │  *~~~~~~~*  │
└────────────┘        ║       ·        ║      └─────────────┘
                      ╚════════════════╝

                                    ┌───────────┐
                            ┌──────▷│ COBRANÇA  │░
┌─────────────┐             │       └───────────┘░
│ PUBLICADOR  │── EVENTOS ──┤        ░░░░░░░░░░░░░
└──────┬──────┘░            │
 ░░░░░░│░░░░░░░░            │
                            │       ┌─────────┐
    CÓPIA                   ├──────▷│AUDITORIA│░
    NOTURNA                 │       └─────────┘░
                            │        ░░░░░░░░░░░
       │                    │
       ▼                    │
 ┌───────────┐              │       ┌──────────┐
 │  ARQUIVO  │░             └──────▷│ PESQUISA │░
 └───────────┘░                     └──────────┘░
  ░░░░░░░░░░░░░                      ░░░░░░░░░░░░


                                          ENTREGA PELO
                                          MENOS UMA VEZ

Referência da API

  • D(max_width=80) — cria um diagrama; max_width é o limite de colunas.
  • 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 incluem a sombra). lines é uma lista de linhas, ou uma lista de seções (listas de linhas) para dividir a caixa. box.rows contém a linha de seta de cada seção. align="center" centraliza o texto.
  • d.header(title, left=None, right=None, y=0) → caixa de título Box. Cada argumento é uma lista de linhas. As caixas obtêm seu x final no momento da renderização. Um cabeçalho por diagrama.
  • d.arrow_h(a, b, label="", row=None, head="filled") — a e b lado a lado; funciona em ambas as direções. row seleciona uma linha de seção (a.rows[i]). head é "filled" ou "hollow".
  • d.arrow_v(a, b, label="", head="filled", inline=False) — b abaixo de a, centralizado sob ela. Um rótulo pode ter mais de uma linha ("\n"). Com inline=True, deixe espaço com 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) — lados são "left" "right" "top" "bottom". A linha sai de a_side de a e entra em b_side de b. Tem len(via) + 2 segmentos, que alternam entre horizontais e verticais, começando com a direção que sai de a_side. Cada valor de via é a faixa de um segmento do meio: um x para um segmento vertical, um y para um segmento horizontal. via=[] é uma curva, um valor são duas curvas (forma S ou U), dois valores são três curvas (um laço). a_row / b_row selecionam uma linha de seção. label_seg seleciona o segmento (de 0) que carrega o rótulo.
  • d.fan_out(a, targets, trunk, a_side="right", b_side="left", label="", head="filled", a_row=None, inline=False) — um barramento. trunk é a faixa da linha compartilhada: um x para lados esquerdo/direito, um y para topo/base.
  • d.arrow_elbow(a, b, label="", mode="vh"|"hv", head="filled") — uma curva, uma forma curta de route. vh: sai da base de a, vira para o lado de b. hv: sai do lado de a, vira para baixo no topo de b. A direção segue a posição de b.
  • d.annotate(x, y, lines, align="left") → Box (role "text") — texto livre, em maiúsculas. lines é uma string ("\n" começa uma nova linha) ou uma lista.
  • d.text(x, y, s) — texto bruto (não em maiúsculas).
  • d.render() — retorna o diagrama; posiciona o cabeçalho; verifica largura e caracteres largos.
  • O motor levanta DiagramError em sobreposições, lacunas pequenas, valores de faixa errados ou linhas acima da largura máxima.

Se nenhum shell estiver disponível

Desenhe à mão com as mesmas regras. Em seguida, conte as colunas em cada linha e verifique se: a sombra direita está uma coluna à direita da caixa; a linha de sombra inferior começa uma coluna à direita da borda esquerda da caixa e termina na coluna de sombra; todas as bordas da caixa se alinham.

Código fonte do motor: textdiagram.py

"""textdiagram: desenhe diagramas de caixa Unicode alinhados em uma grade de caracteres.

Estilo:
  Todo texto é em maiúsculas, exceto as unidades em KEEP.
  Caixa COMPONENTE: linhas leves + sombra leve (░) uma coluna à direita, uma linha abaixo.
  Caixa TÍTULO: linhas duplas, sem sombra, centralizada sobre o diagrama (posicionada na renderização).
  Caixa MOLDURA: linhas leves, sem sombra (nota, chamada).
  Cabeçalho: caixa de título com uma caixa de metadados opcional (esquerda) e caixa de selo (direita);
  linhas de preenchimento da caixa de título seguram um ponto centralizado.
  Seções: uma caixa dividida por divisores leves, uma sombra para toda a caixa.
  Seta horizontal: rótulo dentro da linha, ambas as extremidades tocam uma caixa:  ── RÓTULO ──▶
  Seta vertical: rótulo à direita da linha, uma linha abaixo da sombra.
  Rota: seta com qualquer número de curvas, definidas por coordenadas de faixa (via).
  Cabeça: preenchida (▶) ou vazada (▷). fan_out: uma linha que se divide em várias setas.
  Rótulo em uma linha vertical: ao lado da linha, ou cortado nela (inline=True).
  annotate: texto livre sem caixa.
"""
import re
import unicodedata

SHADOW = "░"
MIN_DASH = 2  # traços de cada lado de um rótulo de seta
HEADER_GAP = 2  # colunas entre as caixas do cabeçalho

# Unidades cuja caixa altera o significado (MB = byte, Mb = bit, ms = mili, MS = mega).
# Uma palavra é mantida apenas se escrita exatamente como uma destas.
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 desenho de caixa como conjuntos de braços: onde duas linhas de seta se encontram,
# os braços são unidos em um caractere de junção (┼, ├, ...).
ARMS = {"─": "LR", "│": "UD", "┌": "RD", "┐": "LD", "└": "RU", "┘": "LU",
        "├": "UDR", "┤": "UDL", "┬": "LRD", "┴": "LRU", "┼": "UDLR"}
BY_ARMS = {frozenset(v): k for k, v in ARMS.items()}

# ... [código truncado para tradução]

Habilidades Relacionadas