Sintaxe de fluxogramas Mermaid: guia completo com exemplos

Principais pontos: Um fluxograma Mermaid é um diagrama que você escreve como texto em vez de desenhar à mão. Você digita algo como A --> B, e o Mermaid renderiza duas caixas conectadas. Este guia abrange todas as partes da sintaxe, desde os tipos básicos de nó até estilização e eventos de clique, além de mostrar como transformar esse código em um diagrama real e editável na Miro.

Seu fluxograma já está desatualizado

Você já sabe como funciona. Você passa 20 minutos em uma ferramenta de diagramas alinhando as caixas, evitando que as setas se sobreponham e escolhendo cores que pareçam pensadas. Você exporta, coloca na wiki e segue em frente. Três semanas depois, o processo mudou e ninguém atualizou a imagem. Agora a "fonte da verdade" é uma captura de tela de algo que não é mais verdade desde o último sprint.

Esse é o problema de tratar diagramas como imagens em vez de código. Uma imagem não pode ser comparada via diff, nem ser versionada ou gerada por um agente de IA que acabou de ler seu código real. Um fluxograma Mermaid pode.

O que é um fluxograma Mermaid?

Um fluxograma Mermaid é um fluxograma que você define usando sintaxe em texto simples em vez de um canvas de arrastar e soltar. Você escreve algumas linhas descrevendo seus nós e como eles se conectam, e o Mermaid renderiza o diagrama automaticamente, com layout, setas e formas.

Faz parte do Mermaid, uma sintaxe open-source para diagramas que também abrange diagramas de sequência, diagramas de classes, linhas do tempo e muitos outros tipos de diagramas. Fluxogramas são os mais comuns do grupo, e com razão: quase todo processo, árvore de decisão ou fluxo de trabalho pode ser mapeado como nós e conexões.

O Mermaid ganhou novo fôlego recentemente por um motivo simples: modelos de IA escrevem sintaxe Mermaid com fluência. Peça a um agente de codificação com IA para diagramar seu sistema e há uma boa chance de ele entregar sintaxe Mermaid, porque esse é o formato que praticou mais. Além disso, texto é mais fácil para um modelo de linguagem processar do que uma imagem bidimensional, por isso um agente pode fazer uma edição precisa no seu diagrama em vez de redesenhar tudo do zero.

Sintaxe básica: direção e declaração

Todo fluxograma Mermaid começa com uma palavra‑chave de direção. Essa linha única determina se o diagrama será lido de cima para baixo ou da esquerda para a direita, e é a primeira coisa que você escreverá.

• TD or TB: de cima para baixo
• BT: de baixo para cima
• LR: da esquerda para a direita
• RL: da direita para a esquerda

1flowchart TD2    A --> B3    B --> C4  style A fill:#fff6b65  style B fill:#fff6b66  style C fill:#fff6b6

1flowchart LR2    Start --> Medium3    Medium --> End4  style A fill:#fff6b65  style B fill:#fff6b66  style C fill:#fff6b6

Nós nomeados e descritivos (Start, Medium, End) ficam muito melhores do que letras isoladas quando o fluxograma ultrapassa alguns passos. Use letras para esboços rápidos e troque por rótulos reais para qualquer coisa que for compartilhar.

Formas dos nós: a sintaxe de colchetes determina a forma

Os colchetes ao redor do texto do nó determinam a forma que ele assume. Não se escolhe a forma em um menu. Basta digitar os símbolos corretos, e o Mermaid resolve o resto.

1flowchart TD2    A[Rectangle]3    B(Rounded)4    C([Stadium])5    D[[Subroutine]]6    E[(Cylindrical)]7    F((Circle))8    G>Asymmetric]

Algumas dessas formas correspondem a casos de uso específicos que vale conhecer. Use um retângulo [Text] para um passo padrão do processo, uma forma de estádio ([Text]) para o início ou o fim, e uma subrotina [[Text]] quando um nó for, na verdade, uma chamada para um processo separado e definido. Use um cilindro [(Text)] quando estiver representando um banco de dados ou repositório de dados, e um círculo ((Text)) para um ponto único e autocontido no fluxo.

Mermaid abrange mais algumas formas que vale conhecer, incluindo o losango para decisões e o hexágono para passos de preparação. Caracteres especiais como barras ou pontos de interrogação precisam de aspas ao redor da etiqueta:

1flowchart TD2H{Rhombus}3    I{<!-- -->{Hexagon}}4    J["s3/"]5    K["s4!"]6    L(("s5?"))

Links e setas: conectando seus nós

Uma seta mostra ao leitor como um passo leva ao próximo, e o Mermaid oferece mais de uma opção, dependendo do quão forte ou opcional essa conexão for.

1flowchart td2A --> B          %% solid arrow3A --- B          %% solid line4A -.-> B         %% dotted5A ==> B          %% thick6A -->|label| B   %% with text7A -- text --> B  %% alt label8style A fill:#e7e7e79style B fill:#c6dcff10  linkStyle 5 stroke:#bd0a0a11  linkStyle 4 color:#bd0a0a,stroke:#6631d7

Cada uma indica algo diferente: --> é uma seta sólida padrão, --- é uma linha contínua sem ponta de seta para uma associação mais solta, -.-> é uma seta pontilhada para caminhos opcionais ou assíncronos e ==> é uma seta mais espessa para sinalizar um caminho crítico.

Para adicionar uma etiqueta a uma seta, use -->|etiqueta| ou -- etiqueta -->. As duas formas fazem a mesma coisa. O linkStyle, ao direcionar uma seta pela sua posição no diagrama (0 para a primeira, 1 para a segunda e assim por diante), permite recolorir uma conexão específica em vez de todas as setas do board.

Também é possível conectar vários nós em uma única linha em vez de escrever cada par separadamente:

1flowchart td2A & B --> C & D  %% multi3style A fill:#fff6b64  style B fill:#c6dcff5  style C fill:#edfaf26  style D fill:#ffc6c67​

Essa única linha faz o mesmo que quatro declarações separadas de setas. É um detalhe pequeno, mas ajuda a manter o código de um diagrama carregado legível.

Subgrafos: agrupamento e aninhamento

Sistemas reais têm seções: um frontend, um backend, uma etapa de pagamento que na verdade são três etapas disfarçadas de uma. Os subgrafos permitem agrupar nós relacionados em uma mesma caixa e até atribuir a essa caixa sua própria direção de fluxo interna.

1flowchart TB2    subgraph frontend3        direction LR4        UI --> API5    end6    subgraph backend7        API --> DB8    end9    frontend --> backend

Duas coisas a lembrar aqui. Primeiro, a direção dentro de um subgrafo substitui a direção do fluxograma pai, então seu frontend pode seguir da esquerda para a direita mesmo que o diagrama geral vá de cima para baixo. Segundo, um subgrafo pode ser ligado como qualquer outro nó, o que explica como frontend --> backend funciona acima, mesmo que ambos os lados sejam caixas cheias de outras caixas.

Temas e diretivas %%{init}%%

Se quiser que as cores do fluxograma combinem com sua marca, com a gravidade de um incidente ou simplesmente com seu gosto, uma diretiva %%{init}%% permite definir isso antes de desenhar qualquer nó. Ela deve ficar exatamente na primeira linha do diagrama.

1%%{init: {2  "theme": "base", 3  "themeVariables": {4    "primaryColor": "#ADF0C7",5    "primaryTextColor": "#067429",6    "edgeLabelBackground": "#FFFEEE",7    "lineColor": "#36352F"8  }9}}%%10flowchart LR11    A[Start] --> B{Choice}12    B -->|yes| C[Done]13    B -->|no| D[Retry]

Mermaid vem com cinco temas integrados: default, dark, forest, neutral e base. Somente o tema base oferece acesso completo ao objeto themeVariables, então se quiser cores personalizadas em vez de uma paleta predefinida, esse é o tema para começar.

Interação: eventos de clique e callbacks

Um fluxograma não precisa ser estático. Você pode conectar um nó para abrir um link, executar uma função JavaScript ou mostrar uma dica ao passar o mouse, o que é útil quando o diagrama também serve como documentação.

1flowchart TD2    A[Visit Miro]3    B[Hover Tooltip]4    C[Open Docs]5​6    click A "https://miro.com" _blank7    click B callback "Tooltip"8    click C href "/docs" "Open docs"9​10​11%% JS callback12%% <script>13%%   const callback = (id) =>14%%     alert('Clicked ' + id);15%% </script>

O nó A abre um link em uma nova guia. O nó B aciona uma função JavaScript chamada callback e mostra o texto de dica "Tooltip." O nó C abre um link relativo na guia atual com seu próprio texto de dica. Você verá esse padrão com mais frequência na documentação interna, quando um nó do diagrama aponta diretamente para o runbook ou ticket que representa.

Estilos: cores, classes e etiquetas em Markdown

Estilos pontuais funcionam bem para um único nó, mas ficam repetitivos rápido. classDef permite definir um estilo uma vez e reaproveitá-lo em todo o diagrama, o que faz diferença assim que seu fluxograma tem mais de cinco ou seis nós.

1flowchart LR2    A[Node A]3    B[Node B]4    C[Node C]5    D[Node D] --> E[Node E]6​7    %% Inline style8    style A fill:#f9f,stroke:#333,stroke-width:2px9​10    %% Reusable class definition11    classDef error fill:#fdd,stroke:#c00,color:#90012    classDef success fill:#dfd,stroke:#0a013​14    %% Assign class15    class A,B error16    class C success17​18    %% Shorthand class assignment19    D:::success --> E:::error

É possível atribuir uma classe de duas formas: usando class A,B error em sua própria linha, ou inline com a forma abreviada D:::success. Ambas fazem a mesma coisa. Escolha a que deixar seu código mais legível.

Para etiquetas mais ricas, o Mermaid também suporta formatação básica em markdown dentro dos nós e das arestas, desde que você desabilite primeiro as etiquetas HTML:

1---2config:3  htmlLabels: false4---5flowchart LR6subgraph "One"7  a("`The **cat**8  in the hat`") -- "edge label" --> b{<!-- -->{"`The **dog** in the hog`"}}9end10subgraph "`**Two**`"11  c("`The **cat**12  in the hat`") -- "`Bold **edge label**`" --> d("The dog in the hog")13end

Juntando tudo: um exemplo completo

Este fluxo de login reúne a maior parte do que foi abordado acima em um único diagrama: formas, subgrafos, classes de estilo, um loop de nova tentativa e um evento de clique.

1flowchart TD2    Start((Start)) --> Login[/Enter creds/]3    Login --> Check{Valid?}4    Check -->|yes| Home[Dashboard]:::ok5    Check -->|no| Err[Show error]:::bad6    Err -.retry.-> Login7    Home ==> Logout([Logout])8​9    subgraph auth10        direction LR11        Login --> Check12    end13​14    classDef ok fill:#dfd,stroke:#0a015    classDef bad fill:#fdd,stroke:#c0016    click Home "/dashboard" _self

Repare como há pouco de novo aqui. São as mesmas formas, setas, subgrafos e o padrão classDef das seções anteriores, combinados em algo que você usaria no trabalho de verdade. A única forma nova aqui é Login[/Enter creds/], um paralelogramo que, pela convenção do Mermaid, costuma ser usado para uma etapa de entrada. A verdadeira habilidade ao escrever Mermaid não é memorizar cada símbolo. É saber quais poucos padrões cobrem a maior parte dos seus diagramas.

Veja todos os exemplos de sintaxe no nosso Guia rápido de fluxogramas Mermaid.

Onde os fluxogramas Mermaid ficam ainda melhores: Miro

Escrever o código é só metade do trabalho. Ainda é preciso que alguém revise, questione uma decisão e atualize o código conforme o processo muda. É aí que o Mermaid costumava travar: você renderizava um diagrama, colocava um screenshot em algum lugar e perdia a conexão entre código e imagem assim que alguém os alterava.

A Miro fecha essa lacuna com o Structured Diagrams with Mermaid, atualmente em Beta público. Cole a sintaxe Mermaid em um board na Miro ou peça a um agente de IA, como o Claude Code, para gerar um diretamente a partir da sua base de código, e ela é renderizada como formas reais e editáveis no board, não como uma imagem estática. O código Mermaid permanece como fonte da verdade: ao editar o diagrama visualmente, o código subjacente também é atualizado, para que os dois nunca se desencontrem.

Isso importa por alguns motivos. Seu time pode trabalhar no diagrama em vez de contorná-lo: comentar diretamente em um nó em vez de abrir um tópico paralelo no Slack, e todos permanecem no contexto da própria decisão. Como o diagrama continua sendo Mermaid nos bastidores, um agente de IA pode lê-lo, fazer uma edição pontual ou redigir um documento, como um registro de decisão de arquitetura, a partir dos comentários do seu time, pronto para abrir como pull request. E você não fica preso ao layout de outra pessoa. Altere a direção do fluxo, ajuste o espaçamento ou abra o painel de código e edite a sintaxe manualmente, tudo sem sair do board.

Os fluxogramas já têm a experiência completa de edição visual. Diagramas de sequência, de classes e entidade-relacionamento também são renderizados como formas nativas, mas, por enquanto, trate-os como orientados a código até que a edição visual os alcance.

Como criar um fluxograma Mermaid na Miro

1. Abrir a barra de criação, selecionar Formatos, depois Diagrama e clicar em Criar com código.
2. Colar a sintaxe Mermaid que já tiver, começar a partir de um template ou pedir ao seu agente de IA para gerar um fluxograma diretamente da sua base de código ou de um conjunto de requisitos.
3. Ver o diagrama renderizado como formas nativas da Miro com layout automático, evitando ajustar manualmente as caixas para que as linhas não se cruzem.
4. Abrir o diagrama no modo foco para editar diretamente: clicar em uma forma para alterar a etiqueta ou o estilo, ajustar a direção do fluxo ou abrir o painel de código e editar a sintaxe Mermaid manualmente.
5. Convidar seu time para comentar diretamente no diagrama, no exato ponto em que a decisão acontece.
6. Ao terminar, exportar como imagem, copiar o código Mermaid de volta para o repositório ou permitir que seu agente leia o diagrama e os comentários do seu time por meio do servidor MCP da Miro.

Se você já conhece o Mermaid, pode começar a digitar diretamente no painel de código. Se não, comece por um template e aprenda a sintaxe editando algo que já funciona.

Mais exemplos de fluxogramas Mermaid para você testar

Não precisa criar seu primeiro fluxograma Mermaid do zero. Cada um desses templates é um board Mermaid real que você pode abrir, ler e editar, assim você aprende a sintaxe mudando algo que já funciona em vez de encarar um canvas em branco.

Introdução aos diagramas Mermaid na Miro

Este é o que você deve abrir primeiro se nunca escreveu uma linha de Mermaid. Ele percorre a sintaxe no mesmo ritmo deste guia: palavras‑chave de direção, formas de nó, tipos de seta e alguns exemplos estilizados, cada um acompanhado do diagrama renderizado logo ao lado do código. Como é um board ao vivo e não uma página de referência estática, você pode alterar a etiqueta de um nó ou trocar uma forma e ver a renderização atualizar imediatamente. Esse ciclo de feedback imediato é a maneira mais rápida de aprender o que cada símbolo realmente faz, em vez de decorar uma tabela de sintaxe.

Fluxo de autenticação de usuário com código Mermaid

Este template fornece um fluxo de login funcionando já pronto: o usuário insere as credenciais, o aplicativo as verifica e o diagrama se ramifica em um caminho de sucesso até o painel ou em um caminho de falha que retorna para tentar novamente. Segue a mesma ideia do exemplo completo mostrado anteriormente neste guia e é um bom template para usar se você estiver documentando qualquer tipo de fluxo de autenticação, criação de conta ou aprovação que inclua uma etapa de validação no meio. Basta trocar as etiquetas dos nós e a lógica de ramificação e você terá seu próprio diagrama de autenticação sem mexer no layout.

Arquitetura técnica de microserviços

Este template é ideal quando seu diagrama deixa de caber em um fluxo linear simples. Ele é construído em torno de subgrafos, a mesma técnica de agrupamento abordada anteriormente neste guia, para que você possa agrupar serviços, APIs e repositórios de dados em seções com etiquetas claras, em vez de deixar cada nó solto em um único diagrama plano. É um ponto de partida sólido para documentação de integração, revisões de arquitetura ou qualquer diagrama em que seja preciso mostrar como vários serviços realmente se comunicam entre si, e não apenas o que cada um faz isoladamente.

Fluxo de pedidos de e-commerce

Este template mapeia todo o processo de e-commerce: navegação pelo catálogo, processamento de pagamentos, atendimento de pedidos no backend e e-mails transacionais automatizados.

Escolha um desses templates, substitua pelos seus próprios passos e terá um fluxograma funcionando em minutos, em vez de começar com um canvas em branco.

Perguntas frequentes

O que é um fluxograma Mermaid? Um fluxograma Mermaid é um fluxograma definido em texto simples usando a sintaxe do Mermaid, em vez de desenhado à mão. Você descreve os nós e as setas que os conectam, e o Mermaid renderiza o diagrama automaticamente, incluindo layout e formas.

Como criar um fluxograma com Mermaid? Comece com uma palavra-chave de direção como flowchart TD, depois adicione nós e setas, por exemplo A[Start] --> B[End]. Adicione formas com colchetes, etiquetas nas setas com -->|label| e agrupe passos relacionados com subgraph.

Posso estilizar um fluxograma Mermaid? Sim. Use estilo inline para alterações pontuais, classDef e class para estilos reutilizáveis em vários nós, e a diretiva %%{init}%% no topo do diagrama para definir um tema e cores personalizadas.

Como usar fluxogramas Mermaid na Miro? Abra a barra de criação, escolha Formatos, depois Diagrama e selecione Criar com código. Cole sua sintaxe Mermaid ou peça a um agente de IA para gerá-la e a Miro renderiza um diagrama nativo editável que você pode estilizar, comentar e compartilhar.

O que a Miro oferece para fluxogramas Mermaid? O Structured Diagrams with Mermaid da Miro renderiza o código Mermaid como formas reais e editáveis, mantém o código e o diagrama sincronizados à medida que um ou outro muda e permite que agentes de IA gerem ou leiam diagramas por meio do servidor MCP da Miro.

Tente você mesmo

A maneira mais rápida de aprender a sintaxe de fluxogramas Mermaid é escrever um e ver como ele é renderizado. Abra o editor de diagramas Mermaid na Miro, cole um dos exemplos acima e comece a alterá-lo até que pareça com seu processo real.