```meta
title: "@diagram"
description: "Uma figura desenhada de uma lista, no jeito editorial do diagram-design: camadas, pirâmide, funil, nas cores e fontes da página, com um item em destaque e, se quiser, os itens entrando um a um."
```

_flows.md · documentação · [Blocos](/@docs/blocks)_

Uma figura desenhada de uma lista. Cada tipo segue a geometria de referência do [diagram-design](https://github.com/cathrynlavery/diagram-design) (uma skill de diagramas editoriais, MIT), desenhada aqui pela própria página: as cores e as fontes vêm do tema, no claro e no escuro; o grid é de 4 px; um item só fica em destaque, na cor de acento; a figura tem nome e descrição para um leitor de tela; e o zoom e a tela cheia são os de qualquer diagrama.

## Camadas

Faixas de largura inteira, empilhadas de cima para baixo: uma pilha, o modelo OSI, níveis de abstração. Cada linha é `- Nome · detalhe`, com uma etiqueta à esquerda (`{tag:L5}`) e o detalhe em mono à direita. `top:` e `bottom:` nomeiam a direção na margem; `{focal}` marca a camada em destaque; uma linha `> citação` vira a legenda em itálico.

```@diagram type:layers
title: AI app stack · Where the work actually happens
top: Abstraction
bottom: Silicon
- UI surface · chat, editor, canvas {tag:L5}
- Agent harness · tools, memory, loop {focal tag:L4}
- Prompt layer · system, few-shot, caching {tag:L3}
- SDK / client · auth, retries, streaming {tag:L2}
- Model weights · opus, sonnet, haiku {tag:L1}
> The harness is where most product differentiation actually lives — tools, memory, and the loop that stitches model calls into useful work.
```

~~~text
```@diagram type:layers
title: AI app stack · Where the work actually happens
top: Abstraction
bottom: Silicon
- UI surface · chat, editor, canvas {tag:L5}
- Agent harness · tools, memory, loop {focal tag:L4}
- Prompt layer · system, few-shot, caching {tag:L3}
- SDK / client · auth, retries, streaming {tag:L2}
- Model weights · opus, sonnet, haiku {tag:L1}
> The harness is where most product differentiation actually lives — tools, memory, and the loop that stitches model calls into useful work.
```
~~~

## Pirâmide e funil

Trapézios que estreitam até um ápice. Numa `pyramid`, o primeiro item é o ápice, o mais raro ou mais valioso; num `funnel`, o primeiro é a boca, o mais largo. `{side:~48/ano}` escreve uma nota ao lado da camada (`_` vira espaço). Com `{value:N}` em todos os itens, as larguras ficam proporcionais aos valores: a largura honesta de um funil de conversão. `left:` escreve um eixo girado na margem. A primeira linha `> citação` é a legenda em itálico sob a base; a segunda, a nota da faixa de legenda, cujas palavras vêm de `legend: focal=Ápice, layer=Camada de apoio`. Onde a mão da galeria sai da regra, um pino diz onde: `{x:776 y:112}` num item move a nota lateral, `{y:216}` na linha `left:` move o rótulo do eixo e `legend: 40, 280, 560` dá o x de cada entrada da legenda e da nota.

```@diagram type:pyramid
title: Content pyramid · what compounds
left: Rarer · fewer · compounds ↑ {y:216}
legend: focal=Apex — rarest, highest leverage, layer=Supporting layer — the volume work
legend: 40, 280, 560
- Flagship book · every 3–5 years {focal side:the_apex x:656 y:112}
- Long-form guides · quarterly · 4,000+ words {side:~4/yr x:716}
- Essays · weekly · 800–1,500 words {side:~48/yr x:776}
- Short posts · daily · ~200 words {side:~240/yr}
> The base funds the apex. The apex defines the base.
> Layer width is honest: narrower = rarer shipping cadence.
```

~~~text
```@diagram type:pyramid
title: Content pyramid · what compounds
left: Rarer · fewer · compounds ↑ {y:216}
legend: focal=Apex — rarest, highest leverage, layer=Supporting layer — the volume work
legend: 40, 280, 560
- Flagship book · every 3–5 years {focal side:the_apex x:656 y:112}
- Long-form guides · quarterly · 4,000+ words {side:~4/yr x:716}
- Essays · weekly · 800–1,500 words {side:~48/yr x:776}
- Short posts · daily · ~200 words {side:~240/yr}
> The base funds the apex. The apex defines the base.
> Layer width is honest: narrower = rarer shipping cadence.
```
~~~

```@diagram type:funnel
title: Funil de cadastro · outubro
- Visitantes · da página inicial {value:1000 side:1.000}
- Cadastros · criaram um space {value:400 side:400 · −60%}
- Publicaram · uma página pública {value:120 side:120 · −70%}
- Assinaram · o plano Pro {value:30 focal side:30 · −75%}
```

~~~text
```@diagram type:funnel
title: Funil de cadastro · outubro
- Visitantes · da página inicial {value:1000 side:1.000}
- Cadastros · criaram um space {value:400 side:400 · −60%}
- Publicaram · uma página pública {value:120 side:120 · −70%}
- Assinaram · o plano Pro {value:30 focal side:30 · −75%}
```
~~~

## Fluxo de dados

Como o dado atravessa os papéis de um time: até 4 raias (os papéis) por até 6 etapas numeradas, um nó onde uma raia encontra uma etapa, e as fichas nos pés de cada nó dizendo que forma o dado tem ao entrar e ao sair. A gramática é a do processo: cada grupo separado por `---` é uma raia, nomeada pelo item `{lane}` (`- Data engineer · ENG {lane}`, a sigla vira o crachá de cada nó); os outros itens são os nós, `- Nome · o que entra → o que sai · ferramenta {step:3 in:DB out:TB}`, com `step:` a coluna, `in:` e `out:` as fichas (`LS` stream, `DB` dataset, `TB` tabela, `FL` relatório, `WB` web) e `{focal}` no único nó em destaque. `steps: Ingest, Store, Transform` nomeia as colunas. As setas: `Capture Events -> Land Records`, por nome ou por coluna, com um rótulo depois de um ponto e uma tag `{accent}` (a passagem central, uma só, com rótulo), `{trigger}` (tracejada, um gatilho de governança) ou `{link}` (a saída publicada). Sem linhas de seta, cada nó aponta para o primeiro nó da coluna seguinte. Quando o que entra e sai tem um ponto no meio (`events · orders`), `{sub:2}` diz que o detalhe leva duas partes e a ferramenta fica com o resto. Para reproduzir uma colocação feita à mão: `{label:392,65,48}` numa seta fixa o centro e a linha de base do rótulo (e a largura da máscara); `legend: 180, 272, 360 | 180, 252, 500 | 180, 324` fixa o x de cada item da legenda, uma linha por `|` (passos, tipos de dado e a dica, setas); `legend: FL=Dashboard` troca a palavra de uma ficha ou de um estilo de seta; `legend-rows: 17, 38, 60` põe as linhas da legenda a essas distâncias do topo dela (16, 37 e 59 sem a linha); `legend-key: 164 end` alinha as palavras STEPS, DATA TYPE e FLOW nesse x e por esse lado.

```@diagram type:data-flow
# Role-scoped analytics data flow
steps: Ingest, Store, Transform, Analyze, Publish
- Data engineer · ENG {lane}
- Capture Events · shop events → batch · NiFi ingest {step:1 in:LS out:DB}
- Land Records · events · orders · Object storage {sub:2 step:2 in:DB out:DB}
---
- Data scientist · SCI {lane}
- Clean & Model · raw → trusted table · Trino · notebooks {step:3 in:DB out:TB focal}
- Curate Metrics · conversion · revenue · Trino SQL {sub:2 step:4 in:TB out:TB}
---
- Analytics analyst · ANL {lane}
- Publish Dashboard · metrics → decisions · BI workspace {step:5 in:TB out:FL}
Capture Events -> Land Records
Land Records -> Clean & Model · raw table {accent}
Clean & Model -> Curate Metrics
Curate Metrics -> Publish Dashboard {link}
```

~~~text
```@diagram type:data-flow
# Role-scoped analytics data flow
steps: Ingest, Store, Transform, Analyze, Publish
- Data engineer · ENG {lane}
- Capture Events · shop events → batch · NiFi ingest {step:1 in:LS out:DB}
- Land Records · events · orders · Object storage {sub:2 step:2 in:DB out:DB}
---
- Data scientist · SCI {lane}
- Clean & Model · raw → trusted table · Trino · notebooks {step:3 in:DB out:TB focal}
- Curate Metrics · conversion · revenue · Trino SQL {sub:2 step:4 in:TB out:TB}
---
- Analytics analyst · ANL {lane}
- Publish Dashboard · metrics → decisions · BI workspace {step:5 in:TB out:FL}
Capture Events -> Land Records
Land Records -> Clean & Model · raw table {accent}
Clean & Model -> Curate Metrics
Curate Metrics -> Publish Dashboard {link}
```
~~~

Uma fila que recebe de várias fontes e gargala num só serviço é o mesmo desenho com `motion:step`: cada coluna é um passo, então a fila enche, transborda, é atendida e se acalma em cinco entradas, e as setas aparecem com a coluna que alcançam. Um desenho livre, fora da grade de raias e colunas, é posto em px quando o bloco diz `size: 1160x620`: cada item vira uma caixa, `- Título · linha 2 {px:60,96 200x72 rx:6 at:76,128,148}` (as palavras numa linha por y de `at:`, a última ficando com o que sobrar; `anchor:middle` centraliza; `zone`, `accent` e `focal` dão o tom), ou uma linha com seta e palavras, `- Palavras {from:40,584 to:65,584 at:73,588}`; uma seta `A -> B {from:260,132 via:316,132,316,234 to:340,234}` passa por esses pontos com dobras de 8 px, e `{step:N}` em qualquer um diz quando ele entra.

```@diagram type:data-flow motion:step
# Fan-in queue and bottleneck
steps: Arrive, Spike, Shed, Process, Settle
- Sources · SRC {lane}
- Web + mobile · 7 req/s steady · HTTP {step:1 out:LS}
- Webhooks + ERP · 20 req/s spike · batch {step:2 out:LS}
---
- Queue · QUE {lane}
- Buffer 2/5 · slots 1–2 · bounded FIFO {step:1 in:LS out:LS}
- Buffer 5/5 · full · WARN · bounded FIFO {step:2 in:LS out:LS}
- Equilibrium · worker protected · backpressure on {step:5}
---
- Service · WRK {lane}
- 429 sink · 19 req/s shed · rate limiter {step:3 in:LS}
- Worker · 8 req/s max · FIFO {step:4 in:LS out:DB focal}
---
- Downstream · DWN {lane}
- Database + API · 200 OK · core API {step:4 in:DB}
Web + mobile -> Buffer 2/5
Webhooks + ERP -> Buffer 5/5
Buffer 5/5 -> 429 sink · 429 {trigger}
Buffer 5/5 -> Worker · 8 req/s
Worker -> Database + API {link}
Worker -> Equilibrium
```

~~~text
```@diagram type:data-flow motion:step
# Fan-in queue and bottleneck
steps: Arrive, Spike, Shed, Process, Settle
- Sources · SRC {lane}
- Web + mobile · 7 req/s steady · HTTP {step:1 out:LS}
- Webhooks + ERP · 20 req/s spike · batch {step:2 out:LS}
---
- Queue · QUE {lane}
- Buffer 2/5 · slots 1–2 · bounded FIFO {step:1 in:LS out:LS}
- Buffer 5/5 · full · WARN · bounded FIFO {step:2 in:LS out:LS}
- Equilibrium · worker protected · backpressure on {step:5}
---
- Service · WRK {lane}
- 429 sink · 19 req/s shed · rate limiter {step:3 in:LS}
- Worker · 8 req/s max · FIFO {step:4 in:LS out:DB focal}
---
- Downstream · DWN {lane}
- Database + API · 200 OK · core API {step:4 in:DB}
Web + mobile -> Buffer 2/5
Webhooks + ERP -> Buffer 5/5
Buffer 5/5 -> 429 sink · 429 {trigger}
Buffer 5/5 -> Worker · 8 req/s
Worker -> Database + API {link}
Worker -> Equilibrium
```
~~~

## Matriz de acesso

Quem pode fazer o quê numa plataforma de dados: os papéis (grupos do AD) são as colunas, com uma faixa escura no topo, e os componentes são as linhas; cada célula diz o nível de acesso num vocabulário fechado, `full`, `rw`, `read` ou `none`, que define a cor. O primeiro grupo são os papéis, `- Nome · CÓDIGO-DO-GRUPO`. Cada `---` começa um componente, nomeado pelo título com uma dica opcional (`# Armazenamento de objetos · S3`), e cada item é uma célula na ordem das colunas: `- Write {level:rw}` (`write` e `admin` valem como `rw` e `full`). Sem a tag, o nível sai do texto: Admin/Full é `full`, Read/SELECT/Login é `read`, None/No access/— é `none`, o resto é `rw`. Célula que falta vira `none` com o rótulo da linha `none:` (padrão "No access"). `{focal}` marca a única célula que a matriz existe para mostrar, com o detalhe como segunda linha; `corner: Componente · vs. grupo` nomeia a célula do canto. A legenda lista os níveis usados com a palavra da primeira célula de cada um; `legend: focal=partner read boundary` troca a palavra de um item e `legend: 96, 200, 304, 408, 504` fixa o x de cada um. Nenhuma seta: a informação está toda nas células.

```@diagram type:dp-security-matrix
# Data platform access matrix
legend: focal=partner read boundary
legend: 96, 200, 304, 408, 504
- Data Engineer · GRP-DATA-ENG
- Data Scientist · GRP-DATA-SCI
- Analyst · GRP-ANALYST
- Administrator · GRP-ADMIN
- External Partner · GRP-PARTNER
---
# Object storage · S3
- Write {level:rw}
- Read {level:read}
- None {level:none}
- Admin {level:full}
- None {level:none}
---
# Query engine · SQL
- Write {level:rw}
- Read {level:read}
- Read {level:read}
- Admin {level:full}
- Read {level:read}
---
# Notebooks · PY
- Write {level:rw}
- Write {level:rw}
- None {level:none}
- Admin {level:full}
- None {level:none}
---
# BI tool · DASH
- Write {level:rw}
- Read {level:read}
- Write {level:rw}
- Admin {level:full}
- Read · shared dashboards {focal}
---
# Orchestrator · DAG
- Write {level:rw}
- Read {level:read}
- None {level:none}
- Admin {level:full}
- None {level:none}
```

~~~text
```@diagram type:dp-security-matrix
# Data platform access matrix
legend: focal=partner read boundary
legend: 96, 200, 304, 408, 504
- Data Engineer · GRP-DATA-ENG
- Data Scientist · GRP-DATA-SCI
- Analyst · GRP-ANALYST
- Administrator · GRP-ADMIN
- External Partner · GRP-PARTNER
---
# Object storage · S3
- Write {level:rw}
- Read {level:read}
- None {level:none}
- Admin {level:full}
- None {level:none}
---
# Query engine · SQL
- Write {level:rw}
- Read {level:read}
- Read {level:read}
- Admin {level:full}
- Read {level:read}
---
# Notebooks · PY
- Write {level:rw}
- Write {level:rw}
- None {level:none}
- Admin {level:full}
- None {level:none}
---
# BI tool · DASH
- Write {level:rw}
- Read {level:read}
- Write {level:rw}
- Admin {level:full}
- Read · shared dashboards {focal}
---
# Orchestrator · DAG
- Write {level:rw}
- Read {level:read}
- None {level:none}
- Admin {level:full}
- None {level:none}
```
~~~

Limites: de 2 a 6 papéis e de 2 a 14 componentes; uma linha não tem mais células do que papéis. Acima disso, divida: papéis humanos de contas de serviço, componentes por domínio.

## Loop

Um ciclo que se alimenta: um hub no meio, a memória que acumula o estado de cada volta, e de 5 a 8 estações num anel em volta dele, no sentido horário a partir do topo. O anel flui em arcos com setas, de uma estação à seguinte e da última de volta à primeira; de cada estação sai um raio tracejado para o hub, a escrita de volta. O primeiro grupo da lista é o hub (um item só); depois de um `---`, as estações, uma por linha, `- Nome · detalhe`. `{focal}` destaca uma estação, no máximo uma; `{spoke:SINAIS}` escreve um rótulo ao lado do raio dela (`_` vira espaço), numa máscara a 12 px do traço; `label:X,Y` (ou `label:X,Y,W`) fixa o canto de cima da máscara (e a largura) onde a mão da galeria o pôs, e `label:X,Y,W,H` a altura também (padrão 16; a palavra fica 12 abaixo do topo). Um exemplo desenhado fora da grade de 4 px diz `grid: off` na cabeça, e só nele os números podem ter decimais; `baseline: +0.5` desce todas as palavras da figura nesse tanto (sem `grid: off`, um múltiplo de 4), e `{text:337.5}` no hub fixa a linha de base do nome dele. Uma linha `> citação` vira uma nota em itálico embaixo.

```@diagram type:loop
title: The self-improving loop
- Shared memory · one record, every loop
---
- Capture · signals in / intake {spoke:SIGNALS}
- Research · evidence pulled
- Decide · human approves {focal}
- Act · work ships {spoke:OUTCOMES label:460,464}
- Measure · outcomes logged
- Learn · playbook updated
```

~~~text
```@diagram type:loop
title: The self-improving loop
- Shared memory · one record, every loop
---
- Capture · signals in / intake {spoke:SIGNALS}
- Research · evidence pulled
- Decide · human approves {focal}
- Act · work ships {spoke:OUTCOMES label:460,464}
- Measure · outcomes logged
- Learn · playbook updated
```
~~~

## Aninhado

Hierarquia por contenção: de 2 a 6 anéis arredondados, um dentro do outro, o de fora o mais amplo, o de dentro o mais específico — escopos, zonas de confiança, pastas, raio de uma falha. Um item por anel, do mais externo para o mais interno, `- Nome`; o nome fica no canto de cima de cada anel, sobre a borda, do jeito que foi escrito (um caminho continua um caminho). O anel de dentro é o de destaque, na cor de acento, e o item dele pode trazer `· Nome legível · detalhe`, escritos no centro; `{focal}` em outro anel move o destaque para lá, um só. Até duas linhas `> citação`: a primeira é uma nota em itálico embaixo à esquerda; a segunda fica em cima à direita, com um traço pontilhado até o anel de destaque. A máscara de cada nome mede 16 + 9 px por caractere, na grade de 4 px; `{mask:148}` fixa outra largura.

```@diagram type:nested
title: The Project Guidance Hierarchy
- ~/.claude/ (global)
- ~/vault/ (notes) {mask:148}
- /business
- /marketing
- /project · PROJECT GUIDANCE · inherits every level above
> structure IS the index
> no imports, no configuration
```

~~~text
```@diagram type:nested
title: The Project Guidance Hierarchy
- ~/.claude/ (global)
- ~/vault/ (notes) {mask:148}
- /business
- /marketing
- /project · PROJECT GUIDANCE · inherits every level above
> structure IS the index
> no imports, no configuration
```
~~~

## Processo

Quem faz o quê, em que ordem: até 6 raias horizontais (os times) cruzadas por até 12 colunas numeradas (as etapas), um nó onde uma raia encontra uma etapa. Cada grupo separado por `---` é uma raia, e o item marcado `{lane}` dá o nome dela e a sigla de três letras que aparece em cada nó (`- Customer · CUS {lane}`). Os outros itens do grupo são os nós: `- Nome · o que entra → o que sai · ferramenta {step:3 in:DB out:LS}`, onde `step:` é a coluna, `in:` e `out:` são as fichas do tipo de dado nos pés do nó (`LS` lista ou tarefa, `DB` registros, `TB` tabela, `FL` documento, `WB` web), e `{focal}` marca o único nó em destaque, com a coluna dele pintada no acento. Uma linha `steps: Order, Verify, Allocate` nomeia as colunas. As setas saem pela direita e entram por cima ou por baixo do próximo nó, com uma só curva: sem nenhuma linha de seta, cada nó aponta para o primeiro nó da coluna seguinte; para escolher, escreva `Place order -> Verify order`, por nome ou por coluna (`2 -> 3`), com um rótulo depois de um ponto (`· rótulo`) e uma tag `{trigger}` (tracejada, um gatilho) ou `{link}` (uma saída publicada). As setas que tocam o nó em destaque saem no acento. A legenda espaça os itens pelo tamanho das palavras e lista os tipos de dado na ordem em que as etapas os usam; `legend: 208, 300, 496 532 | 220, 856 | 200, 360` fixa o x de cada item, uma lista por linha (etapas, tipos de dado, fluxos) separada por `|`, e um segundo número num item fixa o x do rótulo dele. Com `motion:step`, cada coluna é um passo.

```@diagram type:process
# Order fulfillment across four teams
steps: Order, Verify, Allocate, Pick, Pack, Pay, Receive, Close
legend: 208, 300, 392, 496 532, 576 612, 656 692, 736 780, 832 | 220, 328, 428, 552, 688, 856 | 200, 360
- Customer · CUS {lane}
- Place order · cart → order · storefront {step:1 out:DB}
- Receive shipment · receipt → confirmed · delivery portal {step:7 in:TB out:WB}
---
- Support · SUP {lane}
- Verify order · order → cleared · service desk {step:2 in:DB out:DB}
- Close order · confirmed → closed · service desk {step:8 in:WB}
---
- Warehouse · WHS {lane}
- Allocate stock · order → pick list · inventory system {step:3 in:DB out:LS focal}
- Pick items · list → picked · handheld scanner {step:4 in:LS out:LS}
- Pack order · picked → shipment · packing station {step:5 in:LS out:FL}
---
- Finance · FIN {lane}
- Capture payment · shipment → receipt · payment gateway {step:6 in:FL out:TB}
Place order -> Verify order
Verify order -> Allocate stock
Allocate stock -> Pick items
Pick items -> Pack order
Pack order -> Capture payment
Capture payment -> Receive shipment
Receive shipment -> Close order
```

~~~text
```@diagram type:process
# Order fulfillment across four teams
steps: Order, Verify, Allocate, Pick, Pack, Pay, Receive, Close
legend: 208, 300, 392, 496 532, 576 612, 656 692, 736 780, 832 | 220, 328, 428, 552, 688, 856 | 200, 360
- Customer · CUS {lane}
- Place order · cart → order · storefront {step:1 out:DB}
- Receive shipment · receipt → confirmed · delivery portal {step:7 in:TB out:WB}
---
- Support · SUP {lane}
- Verify order · order → cleared · service desk {step:2 in:DB out:DB}
- Close order · confirmed → closed · service desk {step:8 in:WB}
---
- Warehouse · WHS {lane}
- Allocate stock · order → pick list · inventory system {step:3 in:DB out:LS focal}
- Pick items · list → picked · handheld scanner {step:4 in:LS out:LS}
- Pack order · picked → shipment · packing station {step:5 in:LS out:FL}
---
- Finance · FIN {lane}
- Capture payment · shipment → receipt · payment gateway {step:6 in:FL out:TB}
Place order -> Verify order
Verify order -> Allocate stock
Allocate stock -> Pick items
Pick items -> Pack order
Pack order -> Capture payment
Capture payment -> Receive shipment
Receive shipment -> Close order
```
~~~

## Blueprint de serviço

Como um serviço roda de fato ao longo de algumas etapas: o que o cliente faz, o que ele vê e o que fica escondido. As etapas são as colunas, em ordem narrativa; as camadas são as linhas, de cima para baixo: evidência (opcional), cliente, palco e bastidores (obrigatórias) e suporte (opcional). A linha de visibilidade, mais grossa, separa o palco dos bastidores; as camadas abaixo dela ficam num fundo levemente tingido. O primeiro grupo são as etapas, `- Cadastro`. Cada `---` começa uma camada, nomeada pelo título em inglês ou português (`# Evidence`/`# Evidência`, `# Customer`/`# Cliente`, `# Frontstage`/`# Palco`, `# Backstage`/`# Bastidores`, `# Support`/`# Suporte`); grupos sem título ocupam as obrigatórias na ordem, depois suporte e evidência. Cada item é a célula sob uma etapa, `- Nome · sistema · espera` (o detalhe é a segunda linha, em mono) ou `- —` para um vão; uma linha curta se completa com `—`. `{focal}` marca a única célula que a figura existe para mostrar, em geral na linha de visibilidade ou abaixo dela; `visibility: Linha de visibilidade` renomeia a linha na legenda, e `legend: visibility=…, backstage=…, focal=…` troca as palavras dos três itens dela; `size: 1280x720` fixa o tamanho da tela (a referência usa 1280 × 720 nos exemplos mínimos; sem a linha, a tela termina sob a legenda). Sem setas: a ordem das etapas é a sequência.

```@diagram type:service-blueprint
# Trial to paid — what the customer never sees
size: 1280x720
legend: backstage=Backstage layer, focal=Focal cell · timeout
- Sign up
- Activate
- Hit the limit
- Upgrade
- First invoice
---
# Evidence
- Welcome email
- Product UI
- Paywall
- Checkout form
- PDF invoice
---
# Customer
- Create account
- Use product
- Retry payment
- Pick plan
- Read bill
---
# Frontstage
- Welcome
- In-app nags
- Pay modal
- Checkout
- Receipt
---
# Backstage
- CRM write
- Usage meter
- dunning-job timeout · dunning-job · 4h {focal}
- Tax calc
- Ledger
---
# Support
- Email
- Analytics
- Card processor
- —
- GL
```

~~~text
```@diagram type:service-blueprint
# Trial to paid — what the customer never sees
size: 1280x720
legend: backstage=Backstage layer, focal=Focal cell · timeout
- Sign up
- Activate
- Hit the limit
- Upgrade
- First invoice
---
# Evidence
- Welcome email
- Product UI
- Paywall
- Checkout form
- PDF invoice
---
# Customer
- Create account
- Use product
- Retry payment
- Pick plan
- Read bill
---
# Frontstage
- Welcome
- In-app nags
- Pay modal
- Checkout
- Receipt
---
# Backstage
- CRM write
- Usage meter
- dunning-job timeout · dunning-job · 4h {focal}
- Tax calc
- Ledger
---
# Support
- Email
- Analytics
- Card processor
- —
- GL
```
~~~

Limites: de 2 a 6 etapas e de 3 a 5 camadas; uma linha não tem mais células do que etapas, e cada célula tem no máximo duas linhas de texto.

## Mapa de histórias

Um mapa de histórias de usuário (Jeff Patton): a espinha dorsal de atividades em ordem narrativa, da esquerda para a direita, os passos de cada uma logo abaixo, e as fatias de release de cima para baixo, com a linha de corte depois da primeira. O primeiro grupo é a espinha dorsal, uma atividade por linha com os passos no detalhe separados por ` / ` (`- Achar os dados · Buscar conjuntos / Ver linhas`). Cada `---` começa uma fatia, nomeada pelo seu título (`# MVP`, `# RELEASE 2`, `# LATER`, os nomes padrão), e cada item é um cartão: `- Título · RPT-114 · 3pt {activity:4 risk}`. `activity:N` põe o cartão sob a N-ésima atividade (ou o nome dela); sem a tag, o cartão ocupa a posição dele na fatia. `risk` (ou `focal`) marca o único cartão mais arriscado, em acento; a linha de corte sob a primeira fatia é o outro acento. Linhas pontilhadas ligam cada coluna à sua atividade quando uma fatia tem vazio.

```@diagram type:story-map
# Reporting, first release
- Find the data · Search datasets / Preview rows
- Build the report · Pick columns / Add a chart
- Share it · Send a link
- Trust it · Check freshness
---
# MVP
- Keyword search · RPT-101 · 3pt {activity:1}
- Table + one chart · RPT-102 · 5pt {activity:2}
- Public link · RPT-103 · 2pt {activity:3}
- Last-updated stamp · RPT-104 · 1pt {activity:4}
---
# RELEASE 2
- Saved filters · RPT-110 · 3pt {activity:1}
- Scheduled email · RPT-112 · 5pt {activity:3}
- Row-level permissions · RPT-114 · 3pt {activity:4 risk}
---
# LATER
- Natural-language query · RPT-120 · 8pt {activity:1}
- Alerting on anomalies · RPT-121 · 5pt {activity:4}
```

~~~text
```@diagram type:story-map
# Reporting, first release
- Find the data · Search datasets / Preview rows
- Build the report · Pick columns / Add a chart
- Share it · Send a link
- Trust it · Check freshness
---
# MVP
- Keyword search · RPT-101 · 3pt {activity:1}
- Table + one chart · RPT-102 · 5pt {activity:2}
- Public link · RPT-103 · 2pt {activity:3}
- Last-updated stamp · RPT-104 · 1pt {activity:4}
---
# RELEASE 2
- Saved filters · RPT-110 · 3pt {activity:1}
- Scheduled email · RPT-112 · 5pt {activity:3}
- Row-level permissions · RPT-114 · 3pt {activity:4 risk}
---
# LATER
- Natural-language query · RPT-120 · 8pt {activity:1}
- Alerting on anomalies · RPT-121 · 5pt {activity:4}
```
~~~

Limites: de 2 a 5 atividades, até 3 fatias, até 4 cartões por fatia e 12 no total. Fatias se nomeiam pelo escopo (MVP, próxima, depois), não por data.

## Linha do tempo

Uma linha horizontal com os eventos em pontos sobre ela, cada um onde o tempo o põe: o espaço entre dois pontos é o tempo entre eles, a escala honesta da referência. Cada linha é `- QUANDO · Nome · detalhe`, o quando primeiro: um ano (`2025`), um mês (`2025-02`, `Feb 2025`, `fev 2025`, `Apr '26`), um dia (`2025-02-15`), um trimestre (`Q3 2025`, `2025-Q3`) ou um número (um sprint, o dia de um incidente). Se algum quando não se lê como tempo, os eventos ficam igualmente espaçados. Os rótulos alternam embaixo e em cima da linha; `{major}` marca um marco, com o ponto maior na cor de acento e o nome em 14 px; `{now}` escreve " · now" depois da data. As viradas de ano ganham um traço e o ano em marca d'água; uma linha `> citação` vira a nota em itálico da legenda. Onde a mão da galeria sai da escala honesta, um pino diz onde: `{x:240}` num evento (o x do ponto, na grade de 4 px) e `years: 2026=680` para o traço de um ano (e a marca d'água dele).

```@diagram type:timeline
title: Product launch · fourteen months
years: 2026=680
- Feb 2025 · First post
- Apr 2025 · Design v1 {x:240}
- Sep 2025 · Design v2 · typography pass
- Jan 2026 · Design v3 · complexity budget {major x:740}
- Apr 2026 · Schematic skill · eight diagram types {major now}
> Spacing is proportional to real elapsed time.
```

~~~text
```@diagram type:timeline
title: Product launch · fourteen months
years: 2026=680
- Feb 2025 · First post
- Apr 2025 · Design v1 {x:240}
- Sep 2025 · Design v2 · typography pass
- Jan 2026 · Design v3 · complexity budget {major x:740}
- Apr 2026 · Schematic skill · eight diagram types {major now}
> Spacing is proportional to real elapsed time.
```
~~~

## Figura

Uma figura de arquitetura colocada à mão: quem escreve (uma pessoa ou um agente) põe cada nó numa célula de uma grade grossa e nomeia as ligações; a página desenha as caixas, as zonas e as setas no jeito do diagram-design e traça cada ligação em ângulo reto, com uma curva em cada dobra, sem passar por trás de caixa alheia. É o nosso nível "colocado", entre os tipos de lista (camadas, pirâmide) e um diagrama livre: reproduz os exemplos 01 (architecture), 01d (containment, com zonas planas), 40 (deployment) e 03 (IT current-state) da galeria. Cada nó é uma linha `- id coluna,linha tipo "Nome" "detalhe" "TAG"`: o tipo é `focal`, `backend`, `store`, `external`, `input`, `optional` ou `security` (`backend` se omitido); o detalhe sai em mono embaixo do nome; a TAG é a etiqueta pequena no canto. `cols: N` fixa o número de colunas (6 se omitido; as linhas crescem conforme os nós). `zone RÓTULO: c1-c2, l1-l2` desenha uma zona atrás dessas células, com o rótulo em cima. Uma ligação é `de -> para RÓTULO {accent|link|dashed}`: o rótulo tem até 14 caracteres e sai em maiúsculas; `accent` é o fluxo principal (na cor de acento), `link` uma chamada HTTP ou externa, `dashed` um retorno, algo opcional ou assíncrono. `{step:N}` num nó revela o nó e as ligações que chegam nele no passo N. Orçamento: 2 a 9 nós, até 12 ligações, até 2 acentos (nós `focal` e ligações `accent` somados), até 3 zonas. Entre duas colunas vizinhas cabem 32 px de rótulo (24 px ao lado de um nó focal): numa ligação reta entre vizinhas, prefira rótulos de até 6 letras. Quando duas ligações precisam se cruzar, a menos importante pula a outra com um pequeno arco (uma ponte de 8 px de raio): a tracejada pula a contínua, a comum pula a `link` e a `accent`, e entre iguais a declarada depois pula a declarada antes — nunca as duas.

```@diagram type:figure
title: Content site in production
cols: 4
- reader 1,2 input "Reader" "Browser" "EXT"
- cf 2,2 external "Cloudflare" "Pages · cache" "EDGE"
- astro 3,2 focal "Astro Origin" "SSR + MDX" "ORIG"
- mdx 4,1 backend "MDX Bundle" "src/content/*.mdx" "BUN"
- cms 4,3 store "Content CMS" "assets · og images" "CMS"
zone CONTENT: 4-4, 1-3
reader -> cf HTTPS {link}
cf -> astro SSR {accent}
astro -> mdx READ MDX
astro -> cms QUERY
cf -> reader RESP {dashed}
```

~~~text
```@diagram type:figure
title: Content site in production
cols: 4
- reader 1,2 input "Reader" "Browser" "EXT"
- cf 2,2 external "Cloudflare" "Pages · cache" "EDGE"
- astro 3,2 focal "Astro Origin" "SSR + MDX" "ORIG"
- mdx 4,1 backend "MDX Bundle" "src/content/*.mdx" "BUN"
- cms 4,3 store "Content CMS" "assets · og images" "CMS"
zone CONTENT: 4-4, 1-3
reader -> cf HTTPS {link}
cf -> astro SSR {accent}
astro -> mdx READ MDX
astro -> cms QUERY
cf -> reader RESP {dashed}
```
~~~

### Contenção: bandas administrativas e caixas de tráfego

Quando a hierarquia de rede é o que a figura quer dizer (o que está dentro de qual escopo), as zonas viram escopos aninhados, no contrato de contenção do diagram-design: uma zona que diz seu tipo entre chaves. `zone RÓTULO: c1-c2, l1-l2 {admin}` é uma banda administrativa (cobrança, permissões, ciclo de vida: tracejada, com cabeçalho de 24 px, não carrega tráfego); `zone RÓTULO: c1-c2, l1-l2 {traffic}` é uma caixa de tráfego (uma fronteira que pacotes não cruzam sem regra: a caixa de zona de sempre). Os escopos se aninham pelas células que ocupam; `in:RÓTULO` diz o pai de propósito (espaços do rótulo viram hífens, `in:RESOURCE-GROUP`), obrigatório quando dois escopos ocupam as mesmas células. O tipo de um nó pode ser um papel: `compute` (carga de trabalho, dentro de uma caixa de tráfego), `endpoint` (ponto de acesso privado dentro de uma caixa de tráfego, com `{target:id}` apontando o serviço gerenciado que alcança) ou `managed` (um serviço PaaS: mora numa banda, **nunca** dentro de uma caixa de tráfego — a página recusa, porque desenhar o banco dentro da subnet diz ao leitor que ele está atrás das regras dela, e não está). `{focal}` num nó o destaca na cor de acento. Duas caixas de tráfego lado a lado podem ser pareadas: `VNET-HUB <-> VNET-SPOKE PEERING` traça, de uma borda à outra, um caminho tracejado sem seta (um pareamento liga, não flui), em ângulo reto, com as portas distribuídas na borda do escopo como nas de um nó e o rótulo numa máscara; sai com `data-peering`, `data-from` e `data-to` (os ids dos dois escopos; `{id:NOME}` troca o id, `{step:N}` revela no passo N). As duas pontas têm de ser caixas de tráfego — uma banda, uma zona comum ou um escopo que contém o outro é recusado. Com escopos, a célula cresce para 224 × 136 px para caber quatro níveis (cada nível entra 8 px e o cabeçalho de cada um empilha 32 px acima do primeiro), as irmãs de tráfego sob uma banda dividem um eixo, e o SVG sai com `data-grammar="architecture-containment"`, cada escopo com `data-scope-id`, `data-scope-kind` e `data-parent`, cada nó com seu papel em `data-kind`, o escopo mais interno em `data-parent` e o alvo em `data-target`. Orçamento da contenção: até 2 bandas, até 4 caixas de tráfego, até 8 nós. Escopos são colocados por célula: contenção e posição em pixels (abaixo) não se misturam.

```@diagram type:figure
title: The database is not in the subnet
cols: 4
- sql 1,1 managed "SQL" "managed" "DB"
- kv 2,1 managed "Key Vault" "managed" "KV"
- app 2,2 compute "Checkout API" "snet-app" "APP" {focal}
- pesql 3,2 endpoint "PE · SQL" "snet-pe" "PE" {target:sql}
- pekv 4,2 endpoint "PE · Vault" "snet-pe" "PE" {target:kv}
zone SUBSCRIPTION: 1-4, 1-2 {admin}
zone RESOURCE GROUP: 1-4, 1-2 {admin in:SUBSCRIPTION}
zone VNET-HUB: 1-2, 2-2 {traffic}
zone VNET-SPOKE: 3-4, 2-2 {traffic}
zone SNET-APP: 1-2, 2-2 {traffic in:VNET-HUB}
zone SNET-PE: 3-4, 2-2 {traffic in:VNET-SPOKE}
VNET-HUB <-> VNET-SPOKE PEERING
app -> pesql SQL:1433 {accent}
pesql -> sql PRIVATE {link dashed}
pekv -> kv PRIVATE {link dashed}
> Private endpoints sit in the subnet; the database and the vault sit in the resource group, outside every traffic boundary.
```

~~~text
```@diagram type:figure
title: The database is not in the subnet
cols: 4
- sql 1,1 managed "SQL" "managed" "DB"
- kv 2,1 managed "Key Vault" "managed" "KV"
- app 2,2 compute "Checkout API" "snet-app" "APP" {focal}
- pesql 3,2 endpoint "PE · SQL" "snet-pe" "PE" {target:sql}
- pekv 4,2 endpoint "PE · Vault" "snet-pe" "PE" {target:kv}
zone SUBSCRIPTION: 1-4, 1-2 {admin}
zone RESOURCE GROUP: 1-4, 1-2 {admin in:SUBSCRIPTION}
zone VNET-HUB: 1-2, 2-2 {traffic}
zone VNET-SPOKE: 3-4, 2-2 {traffic}
zone SNET-APP: 1-2, 2-2 {traffic in:VNET-HUB}
zone SNET-PE: 3-4, 2-2 {traffic in:VNET-SPOKE}
VNET-HUB <-> VNET-SPOKE PEERING
app -> pesql SQL:1433 {accent}
pesql -> sql PRIVATE {link dashed}
pekv -> kv PRIVATE {link dashed}
> Private endpoints sit in the subnet; the database and the vault sit in the resource group, outside every traffic boundary.
```
~~~

### Posição em pixels

Quando o desenho já existe (um exemplo da galeria, uma figura aprovada) e a página tem de sair número por número, cada nó dá a própria caixa em vez de uma célula: `- id px:x,y LxA tipo "Nome" "detalhe" "TAG"` (x e y do canto superior esquerdo, depois largura×altura), e uma zona `zone RÓTULO: px:x,y LxA`. Todo número na grade de 4 px — um 42 é recusado. Uma figura é toda por célula ou toda em pixels; misturar as duas é recusado. `size: LxA` fixa o viewBox (sem ele, o viewBox sai do contorno do conteúdo mais as margens); com `size`, a legenda ancora na borda de baixo, como a galeria desenha. O roteador trabalha com as caixas como foram postas: uma coluna por fileira de caixas que se sobrepõem em x, uma linha por fileira que se sobrepõem em y, e os corredores são os vãos entre elas — as seis regras de ligação valem iguais (portas distribuídas, curvas de 8 px, máscara de rótulo, trânsito tracejado, pulo no cruzamento). Onde a galeria escolhe à mão o que a regra decidiria, a ligação fixa a própria rota: `{from:N}` e `{to:N}` fixam a coordenada da porta em cada ponta (y numa borda lateral, x em cima ou embaixo), `from:left`/`to:top` fixam a borda por onde a ligação sai ou entra (as duas juntas, `to:left:124`), e `via:N` fixa o corredor do segmento do meio (x entre duas bordas laterais, y entre cima e baixo; `via:X,Y` os dois corredores de um S que sai por um lado e entra por cima ou por baixo). Uma porta fora da grade de 4 px ou fora da borda da caixa é recusada, uma palavra que não é borda também, e as seis regras continuam valendo sobre o resultado: uma rota fixada que passa por trás de uma caixa, encosta num canto ou empilha num traço é apontada, nunca desenhada em silêncio. Sem as chaves, a ligação segue a regra como antes. O exemplo 01 da galeria, escrito como o SVG dele:

```@diagram type:figure
title: Content site in production
size: 1000x480
- reader px:40,240 128x64 input "Reader" "Browser" "EXT"
- cf px:220,240 144x64 external "Cloudflare" "Pages · cache" "EDGE"
- astro px:416,240 160x64 focal "Astro Origin" "SSR + MDX" "ORIG"
- mdx px:628,160 144x64 backend "MDX Bundle" "src/content/*.mdx" "BUN"
- cms px:628,320 144x64 store "Content CMS" "assets · og images" "CMS"
zone CONTENT: px:616,128 164x272
reader -> cf HTTPS {link from:272 to:272}
cf -> astro SSR {accent}
astro -> mdx READ MDX
astro -> cms QUERY
cf -> reader RESP {dashed from:288 to:288}
```

~~~text
```@diagram type:figure
title: Content site in production
size: 1000x480
- reader px:40,240 128x64 input "Reader" "Browser" "EXT"
- cf px:220,240 144x64 external "Cloudflare" "Pages · cache" "EDGE"
- astro px:416,240 160x64 focal "Astro Origin" "SSR + MDX" "ORIG"
- mdx px:628,160 144x64 backend "MDX Bundle" "src/content/*.mdx" "BUN"
- cms px:628,320 144x64 store "Content CMS" "assets · og images" "CMS"
zone CONTENT: px:616,128 164x272
reader -> cf HTTPS {link from:272 to:272}
cf -> astro SSR {accent}
astro -> mdx READ MDX
astro -> cms QUERY
cf -> reader RESP {dashed from:288 to:288}
```
~~~

As cinco caixas, a zona, o viewBox e as cinco ligações saem iguais aos do exemplo: os dois cotovelos do nó focal (`M 576,260 H 692 Q 700,260 700,252 V 224` e `M 576,284 H 692 Q 700,284 700,292 V 320`) pela regra, e HTTPS e RESP nas portas 272 e 288 que o exemplo escolheu à mão (`from:272 to:272`, `from:288 to:288`; a regra sozinha as poria em 260 e 284). O mesmo vale para `type:architecture-delta`: os dois painéis em px (`size: LxA` dá o tamanho do painel), nunca um por célula e o outro em pixels. Com isso, a arquitetura, o deployment e o estado atual de TI do showcase reproduzem cada ligação da galeria com as chaves — o deployment fixa as portas e o corredor que encosta no ingress (`from:196 to:120 via:296`), o estado atual de TI leva as duas fontes para a borda esquerda do drive (`to:left:124 via:316`, `to:left:140 via:332`) e passa por cima do portal (`to:top:808 via:662,64`); as máscaras dos rótulos, que a galeria dimensiona à mão, vêm com `mask:X,Y,L`.

### Outra mão e fora da grade

Alguns exemplos da galeria foram desenhados em outra mão, e uma figura reproduz essa mão só no bloco que pede. `look: drawio` é a mão da importação do draw.io (01b): cada dobra vira um arco `A 8,8`, o nome fica a 3/8 da altura da caixa (+4 com detalhe, +12 sozinho), o rótulo da zona sai solto em x+16, y+24, sem máscara, e a palavra LEGEND vai na linha dos itens, com amostras 16 × 10 e traços de 32 px. `look: chips` é a do paved road (01c): nenhum papel embaixo da caixa, as palavras alinhadas à esquerda em x+16, y+32 com 20 px entre o nome e cada detalhe, o rótulo da zona em x+20, y+32, os rótulos das ligações como fichas contornadas de 18 px com até 20 caracteres, e a legenda sem filete nem palavra. `look: it-state` é a do estado atual de TI (03, type-it-state.md): o rótulo da zona numa faixa de papel de 16 px em x+20, y−8, um ícone de 24 px em x+12 e as palavras em x+44, no centro − 2, máscaras de rótulo de 16 px, margem de 16 px, e só os nós `focal` contam no orçamento de acentos (até 2). `grid: off` deixa aquele bloco escrever qualquer número, decimais inclusive, onde a grade de 4 px é a regra. Num nó, `{tx:N}` dá o recuo das palavras alinhadas à esquerda, `{ty:N,N…}` a linha de base do nome e, em seguida, a de cada detalhe, `{icon:NOME}` desenha o ícone e `{iy:N}` o topo dele; um quarto `""` vazio deixa dois detalhes sem TAG. Numa ligação, `{h:N}` e `{rx:N}` dão a altura e o canto da máscara do rótulo e `{tx:N}` o x da palavra. Na legenda, `chip=Palavra` lista a ficha do rótulo quando a figura desenha algum.

## Vista explodida

As peças de um objeto só, afastadas ao longo de um eixo: o que há dentro de um telefone, o que sai da caixa e em que ordem, as camadas de um produto vistas como partes físicas de uma coisa. Cada peça é um prisma em projeção axonométrica 2:1 (face de cima, face esquerda iluminada, face direita na sombra), com cantos arredondados que projetam como quartos de elipse; as peças se empilham de baixo para cima com uma mesma distância entre os **níveis**; de cada peça sai uma linha-guia horizontal para o nome dela, numa coluna só à direita, com um detalhe técnico em mono embaixo; linhas tracejadas sobem pelas bordas da peça de baixo até a de cima. Um item por peça, **a de cima primeiro**: `- Nome · detalhe {focal h:24 w:160 d:96 r:12}`, onde `h` é a espessura, `w` a largura, `d` a profundidade (sem elas, 200 × 200 × 16) e `r` o raio do canto (sem ele, uma caixa de cantos vivos; `shape:cylinder` faz um cilindro, `r` igual à metade do lado). Uma peça menor fica centrada sobre a maior, ou onde `x:` e `y:` disserem (em unidades do modelo, a partir do canto de trás da maior). Peças que ficam lado a lado no objeto montado dividem um nível e sobem juntas: `level:1` nas duas, uma após a outra (a placa e a bateria de um telefone). `kind:housing` faz da peça uma bandeja: a metade de trás (borda, cavidade, fundo) é pintada antes das peças que ficam dentro dela, e as paredes da frente depois, para o objeto montado mostrar o que está dentro. `face:` desenha um detalhe na face de cima: `screen` (uma tela 4 unidades para dentro, com a ilha da câmera), `chips` (o bloco das câmeras com duas lentes e três chips), `cell` (o contorno de uma célula de bateria e o terminal), `keys` e `switches` (uma grade de teclas ou de switches, um prisma por tecla; a peça declara só o envelope da grade, 13 × 5 teclas quando o objeto tem 228 × 100), `cutouts` e `sockets` (um recorte ou um soquete no centro de cada tecla), e os detalhes dos outros exemplos da galeria: `logo` (um painel impresso 14 para dentro e a marca no centro de uma tampa), `grille` (num cilindro, cinco anéis na frente, um anel na tampa e um botão no centro), `coil` (um cabo enrolado, dois laços), `wells` (um nicho moldado para cada peça do nível de cima que cabe nela, a planta da peça crescida de `well:N`, 3 sem a tag), `lock` (um painel e um disco com anel e pino no centro, um cofre), `pads` (nove pastilhas e quatro pinos), `cards` (seis cartões com uma barra de título e três linhas), `pins` (um chip de 60 com cinco pinos de cada lado) e `terminal` (uma tela escura com linhas de prompt e um cursor); `ports` vai num `kind:housing` e abre os dois vãos (o conector e o alto-falante) na parede direita. `{focal}` pinta uma peça no acento, no máximo uma. Linhas de cabeçalho: `lift: 160` é a distância entre os níveis (sem ela, metade da altura da face de cima ou três vezes a espessura da peça sólida mais grossa, o que for maior, arredondado para cima de 4 em 4; `k: 0.75` sobe o fator de 0.5, como a referência faz quando uma peça alta esconderia a focal; a distância sobe de 4 em 4 até nenhuma linha-guia cruzar outra peça e os rótulos ficarem a 36 px uns dos outros) `axis: Assembly order ↓` escreve o rótulo do eixo em cima da coluna de nomes, e `focal: layer` troca o substantivo da etiqueta da nota ("Focal part" sem ela — a galeria escreve "Focal layer" nas pilhas). Uma linha `> citação` vira uma nota em itálico embaixo. Com `motion:step`, o nível de cima sobe primeiro, cada peça exatamente a distância entre a posição montada e a explodida (`closed:N` diz a altura montada quando a regra não sabe — empilhada sobre a de baixo, ou no fundo de uma bandeja, ou na borda dela — como as teclas que afundam na bandeja de um teclado); o nível de baixo fica parado e o rótulo dele e as linhas tracejadas chegam por último. Se as camadas são só uma lista, sem pé nem espessura, use `type:layers`.

```@diagram type:exploded
# App stack · Three layers, one product
axis: Assembly order ↓
- Interface · web app, mobile {r:12}
- Logic · api, workers, queue {focal r:12}
- Data · postgres, object store {r:12}
> Logic is where the product decisions live; the other two layers are swappable.
```

~~~text
```@diagram type:exploded
# App stack · Three layers, one product
axis: Assembly order ↓
- Interface · web app, mobile {r:12}
- Logic · api, workers, queue {focal r:12}
- Data · postgres, object store {r:12}
> Logic is where the product decisions live; the other two layers are swappable.
```
~~~

Um telefone aberto, o da galeria: a carcaça é uma bandeja, a placa e a bateria dividem um nível dentro dela, a tela sai por cima, e as peças entram uma a uma:

```@diagram type:exploded motion:step
# Phone teardown · What sits under the glass
lift: 160
axis: Assembly order ↓
- Display · oled, cover glass {h:6 w:140 d:280 r:24 face:screen}
- Battery · li-ion cell {h:8 w:120 d:132 r:6 x:10 y:136 level:1 face:cell}
- Logic board · soc, cameras {focal h:4 w:124 d:104 r:4 x:8 y:8 level:1 face:chips}
- Housing · aluminium frame {h:20 w:140 d:280 r:24 kind:housing face:ports}
> The logic board is the part that changes between models; the rest is packaging.
```

~~~text
```@diagram type:exploded motion:step
# Phone teardown · What sits under the glass
lift: 160
axis: Assembly order ↓
- Display · oled, cover glass {h:6 w:140 d:280 r:24 face:screen}
- Battery · li-ion cell {h:8 w:120 d:132 r:6 x:10 y:136 level:1 face:cell}
- Logic board · soc, cameras {focal h:4 w:124 d:104 r:4 x:8 y:8 level:1 face:chips}
- Housing · aluminium frame {h:20 w:140 d:280 r:24 kind:housing face:ports}
> The logic board is the part that changes between models; the rest is packaging.
```
~~~

Um teclado mecânico, também o da galeria: duas grades (switches e teclas) pintadas um prisma por tecla dentro do envelope que cada peça declara, a placa com um recorte por tecla, a PCB com um soquete por tecla, e `closed:` nas peças que a regra de montagem não adivinha:

```@diagram type:exploded
# Mechanical keyboard · Five layers under your fingers
lift: 116
- Keycaps · pbt, 51 keys {h:9 w:206 d:78 r:2 x:11 y:11 face:keys closed:19}
- Switches · mechanical, linear {focal h:9 w:204 d:76 r:1 x:12 y:12 face:switches closed:10}
- Plate · steel, one cutout per key {h:3 w:216 d:88 r:3 x:6 y:6 face:cutouts closed:12}
- PCB · hot-swap sockets {h:4 w:216 d:88 r:3 x:6 y:6 face:sockets}
- Case · aluminium tray {h:22 w:228 d:100 r:6 kind:housing}
```

~~~text
```@diagram type:exploded
# Mechanical keyboard · Five layers under your fingers
lift: 116
- Keycaps · pbt, 51 keys {h:9 w:206 d:78 r:2 x:11 y:11 face:keys closed:19}
- Switches · mechanical, linear {focal h:9 w:204 d:76 r:1 x:12 y:12 face:switches closed:10}
- Plate · steel, one cutout per key {h:3 w:216 d:88 r:3 x:6 y:6 face:cutouts closed:12}
- PCB · hot-swap sockets {h:4 w:216 d:88 r:3 x:6 y:6 face:sockets}
- Case · aluminium tray {h:22 w:228 d:100 r:6 kind:housing}
```
~~~

## Integração da plataforma de dados

A topologia de integração de uma plataforma de dados: quais sistemas entram, quais superfícies saem, e por qual protocolo cada fio fala. As fontes ficam numa coluna à esquerda, os consumidores numa coluna à direita, a plataforma é uma zona no meio com barras que a atravessam (orquestração) e fileiras de nós, e um rodapé de serviços transversais (identidade, logs) fica embaixo da zona, cada um ligado à borda inferior dela com `AUTH`, nunca a um componente. Este tipo passa de propósito do orçamento usual de 9 nós (de 14 a 20): a afirmação do desenho é o número de superfícies. Os grupos, separados por `---`: `# Sources` e `# Consumers` (até 6 cada), `- Nome · tipo · detalhe`, com o tipo em `db`, `sftp`, `mail`, `mainframe`, `file`, `stream`, `monitor`, `chart`, `globe`, `api`; `# Platform · Rótulo da zona`, onde um item `{bar}` é uma barra na largura da zona (`{focal}` a deixa mais alta, em acento) e um item com ` | ` entre nomes é uma fileira de nós (`- NiFi · ETL {role:INGEST} | MinIO · S3 {focal role:STORE}`), com até duas superfícies focais, e `x:400` num nó da fileira fixa a borda esquerda dele em pixels (os outros ficam no passo da fileira), para reproduzir uma posição escolhida à mão, como as duas da galeria; `# Footer` (até 3) são os serviços transversais. Os fios são linhas `A -> B PROTOCOLO` (ou `A -> B, C` para abrir em leque); tocar uma superfície focal torna o fio acento, sair de uma barra o torna tracejado, e uma tag `{federated}` o pinta como consulta federada. Uma linha `> citação` vira uma nota em itálico embaixo. Onde a galeria coloca à mão, cada chave fixa só o número que nomeia e, sem ela, a fórmula vale: `{mask:X,Y,L}` num fio põe a máscara do protocolo nesse x, y e largura (ou `{mask:L}`, só a largura, centrada como antes), com a palavra centrada nela; `badge:L` num item da plataforma dá a largura da etiqueta `role:`; `{mask:X,Y,L}` num item do `# Footer` põe a máscara do `AUTH` dele onde a mão pôs. Uma linha `legend: title=Tipos, focal=Palavra` dá o título da legenda e as palavras de um item (`source`, `focal`, `bar`, `primary`, `federated`, `auth`), e uma linha `legend: 128, 296, 492` o x de cada item; com qualquer uma das duas, a legenda é desenhada como a do 33 da galeria (amostras 16 × 12, linhas de 32 px, as palavras numa só linha). Os ícones são definidos uma vez no `<defs>` da figura, com o id dela, e colocados com `<use>`; uma linha `icon-ids: bare` escreve os ids sem o da figura (`#ico-db`), como a galeria, e duas figuras assim na mesma página dividem os ícones da primeira.

```@diagram type:dp-integration
title: Generic data platform integration topology
# Sources
- CRM · db · customer records
- POS exports · file · daily CSV batches
- Event stream · stream · near-real-time events
---
# Platform · Data platform
- Orchestrator · schedules · retries · lineage {bar role:DAG}
- Object storage · versioned data objects {focal role:STORE x:400} | Query engine · federated SQL access {focal role:SQL x:656}
---
# Consumers
- BI tool · chart · dashboards · reports
- Notebooks · notebook · Python · exploration
- Partner API · api · scoped data products
---
# Footer
- Identity provider · key · SSO · service identities · policy groups
- Centralized logging · log · platform events · audit trail · retention
---
CRM -> Object storage REST
POS exports -> Object storage CSV
Event stream -> Object storage EVENTS
Object storage -> Query engine READ
Query engine -> BI tool JDBC
Query engine -> Notebooks KERNEL
Query engine -> Partner API HTTPS
Orchestrator -> Object storage, Query engine
```

~~~text
```@diagram type:dp-integration
title: Generic data platform integration topology
# Sources
- CRM · db · customer records
- POS exports · file · daily CSV batches
- Event stream · stream · near-real-time events
---
# Platform · Data platform
- Orchestrator · schedules · retries · lineage {bar role:DAG}
- Object storage · versioned data objects {focal role:STORE x:400} | Query engine · federated SQL access {focal role:SQL x:656}
---
# Consumers
- BI tool · chart · dashboards · reports
- Notebooks · notebook · Python · exploration
- Partner API · api · scoped data products
---
# Footer
- Identity provider · key · SSO · service identities · policy groups
- Centralized logging · log · platform events · audit trail · retention
---
CRM -> Object storage REST
POS exports -> Object storage CSV
Event stream -> Object storage EVENTS
Object storage -> Query engine READ
Query engine -> BI tool JDBC
Query engine -> Notebooks KERNEL
Query engine -> Partner API HTTPS
Orchestrator -> Object storage, Query engine
```
~~~

## Visão de alto nível

A visão de ponta a ponta de uma pilha de dados: uma faixa de setas (chevrons) com os estágios no topo, e ela é a legenda, porque cada componente fica centrado no estágio dele. Sob o primeiro chevron, uma zona tracejada com as fontes externas; sob os demais, o cluster com os componentes, uma barra de orquestração atravessando o topo dele e um componente focal em acento. Barras transversais (identidade, observabilidade) ficam embaixo do cluster, na largura toda. O corpo vem em grupos separados por `---`, cada um nomeado pelo título: `# Stages` lista os chevrons, um por linha, com um peso opcional de largura (`- Ingestion · 2`); `# Sources` lista as fontes (até 4), `- Nome · detalhe · tipo`, com o tipo em `db`, `ftp`, `web`, `legacy` ou `api`; cada grupo seguinte é um estágio (pelo nome, ou na ordem), com os componentes `- Nome · detalhe {kind:node|bar focal role:SIGLA}`: `{bar}` é a barra de orquestração, `{focal}` o único componente em destaque, `role:` a etiqueta no canto; um grupo `# Cross-cutting` (ou `{cross}` num item) vira barra embaixo do cluster. Uma linha `cluster: Kubernetes` nomeia o cluster. As ligações são linhas `A -> B` (ou `A -> B, C` para abrir em leque, no máximo 3 por nó); o estilo sai da topologia (toca o focal: acento; sai da barra: tracejado), ou de uma tag `{primary|secondary|trigger|query}`. Uma linha `> citação` vira uma nota em itálico embaixo. Onde a galeria coloca à mão o que a fórmula decidiria, cada item fixa só o número que nomeia, tudo na grade de 4 px: `{px:x,y LxA}` num componente, numa fonte, na barra ou numa barra transversal dá a posição e o tamanho (`rx:N` o raio do canto), o mesmo `{px:…}` no título `# Sources` e na linha `cluster:` fixa as duas zonas, e uma ligação fixa a própria rota com as mesmas chaves da figura — `{from:borda:N to:borda:N via:N}`, a borda (`top`, `bottom`, `left`, `right`) e a coordenada da porta em cada ponta, `via:N` o corredor do segmento do meio — e `{legend:off}` tira o estilo dela da legenda; sem as chaves, a fórmula vale. Numa rota fixada, `{arc:K:A,B}` corta a K-ésima curva A px antes do canto e B depois (sem a chave, o mesmo raio dos dois lados), para a curva desigual que a galeria às vezes desenha. Um `icon:NOME-dd` desenha o ícone como o próprio exemplo da galeria o traz, quando ele não é o da referência (outra versão do Tabler, uma marca que o arquivo corta pela metade): o nome sem `-dd` continua o da referência. O exemplo abaixo reproduz o 29 da galeria número a número.

```@diagram type:high-level
title: High-level architecture · End-to-end stack
cluster: Kubernetes {px:164,40 832x336}
# Stages
- Data sources
- Ingestion
- Storage
- Transformation & Analysis
- Visualization
---
# Sources {px:4,40 152x336}
- WEB · Census · Survey · Admin · web {px:12,60 132x64}
- FTP · Census · Business · ftp {px:12,140 132x64}
- DB Connection · CDC · SQL · API · db {px:12,220 132x64}
- Legacy System · Trade data · legacy {px:12,304 132x64}
---
# Ingestion
- Orchestration / Workflow Automation · (Apache Airflow) {bar px:176,52 808x44}
- Apache NiFi · Collect · route · transform {role:COLL px:176,112 152x80}
---
# Storage
- Trino · SQL · data virtualization {role:VIRT px:372,104 160x72}
- MinIO / S3 · Object store · S3-API {focal role:STORE px:372,208 160x80 rx:8}
---
# Transformation & Analysis
- Data Modeling · Notebook · Python · R {role:ANLZ px:600,144 164x80}
---
# Visualization
- Dashboards · Superset · reports {role:DASH px:820,144 152x80}
---
# Cross-cutting
- Identity Manager · (Active Directory) {px:4,388 992x40}
---
WEB -> Apache NiFi {from:bottom:128 to:132}
FTP -> Apache NiFi {to:172}
DB Connection -> Apache NiFi {to:bottom:204}
Legacy System -> Apache NiFi {to:bottom:228}
Orchestration / Workflow Automation -> Trino, Data Modeling, Dashboards
Apache NiFi -> Trino {from:140}
Apache NiFi -> MinIO / S3 {from:164 via:352}
Trino -> MinIO / S3
MinIO / S3 -> Trino {query legend:off}
Trino -> Data Modeling {to:168 via:564}
MinIO / S3 -> Data Modeling {to:200 via:564}
Data Modeling -> Dashboards
```

~~~text
```@diagram type:high-level
title: High-level architecture · End-to-end stack
cluster: Kubernetes {px:164,40 832x336}
# Stages
- Data sources
- Ingestion
- Storage
- Transformation & Analysis
- Visualization
---
# Sources {px:4,40 152x336}
- WEB · Census · Survey · Admin · web {px:12,60 132x64}
- FTP · Census · Business · ftp {px:12,140 132x64}
- DB Connection · CDC · SQL · API · db {px:12,220 132x64}
- Legacy System · Trade data · legacy {px:12,304 132x64}
---
# Ingestion
- Orchestration / Workflow Automation · (Apache Airflow) {bar px:176,52 808x44}
- Apache NiFi · Collect · route · transform {role:COLL px:176,112 152x80}
---
# Storage
- Trino · SQL · data virtualization {role:VIRT px:372,104 160x72}
- MinIO / S3 · Object store · S3-API {focal role:STORE px:372,208 160x80 rx:8}
---
# Transformation & Analysis
- Data Modeling · Notebook · Python · R {role:ANLZ px:600,144 164x80}
---
# Visualization
- Dashboards · Superset · reports {role:DASH px:820,144 152x80}
---
# Cross-cutting
- Identity Manager · (Active Directory) {px:4,388 992x40}
---
WEB -> Apache NiFi {from:bottom:128 to:132}
FTP -> Apache NiFi {to:172}
DB Connection -> Apache NiFi {to:bottom:204}
Legacy System -> Apache NiFi {to:bottom:228}
Orchestration / Workflow Automation -> Trino, Data Modeling, Dashboards
Apache NiFi -> Trino {from:140}
Apache NiFi -> MinIO / S3 {from:164 via:352}
Trino -> MinIO / S3
MinIO / S3 -> Trino {query legend:off}
Trino -> Data Modeling {to:168 via:564}
MinIO / S3 -> Data Modeling {to:200 via:564}
Data Modeling -> Dashboards
```
~~~

## Medalhão

As camadas de um armazenamento por qualidade (bronze, prata, ouro; bruto, anonimizado, agregado, arquivo): de 3 a 6 cartões da esquerda para a direita, cada um com o nome, o bucket, até três campos rotulados (ferramenta, formato, quem escreve) e uma ou duas linhas de exemplo; uma camada focal em acento. As promoções entre camadas são arcos por cima dos cartões, do centro do topo de um ao do seguinte, com o rótulo dentro do arco; o arco que chega na camada focal é o acento, `{lifecycle}` torna um arco tracejado. Cada grupo separado por `---` é uma camada, nomeada pelo título `# Nome · bucket`, com `{focal}` (ou uma linha `focal: Nome`) na única camada em destaque e `{cold}` na camada de arquivo (fundo cinza, borda tracejada); os itens são `- tool · Spark`, `- format · Parquet`, `- writer · ingest job` e `- example · texto` (até dois). Uma linha `example: Rótulo` nomeia o bloco de exemplos. As promoções são linhas `Bronze -> Silver CLEANSE`, com o rótulo de até 14 caracteres depois do destino; sem elas, cada camada promove para a seguinte, sem rótulo. Um grupo final `# Paths` (até dois itens `- TAG · título · detalhe`) desenha os métodos de escrita embaixo das camadas. Uma linha `> citação` vira uma nota em itálico embaixo.

```@diagram type:medallion
title: Five-tier e-commerce analytics medallion
example: E-commerce example
# Raw · raw-commerce
- tool · NiFi ingest
- format · JSON · Parquet
- writer · Data Engineer
- example · clickstream events
- example · order records
---
# Anonymized · anon-commerce
- tool · Trino SQL
- format · Iceberg · partitioned
- writer · Data Engineer
- example · session pseudonyms
- example · masked customer IDs
---
# Staging · staging-commerce
- tool · Trino · notebooks
- format · Iceberg · cleaned
- writer · Data Scientist
- example · joined order facts
- example · validated event rows
---
# Aggregated · analytics-marts {focal}
- tool · Trino INSERT
- format · Iceberg · metrics
- writer · Data Scientist
- example · daily conversion rate
- example · revenue by channel
---
# Archive · archive-commerce {cold}
- tool · Object storage lifecycle
- format · Cold tier · immutable
- writer · Data Engineer
- example · retained clickstream
- example · closed order snapshots
---
Raw -> Anonymized MASK IDS
Anonymized -> Staging CLEAN + JOIN
Staging -> Aggregated AGGREGATE
Aggregated -> Archive LIFECYCLE {lifecycle}
---
# Paths
- SQL PATH · Trino INSERT INTO … SELECT · filter · join · aggregate — repeatable transforms
- NOTEBOOK PATH · Python notebooks on object storage · explore · validate · model — interactive analysis
```

~~~text
```@diagram type:medallion
title: Five-tier e-commerce analytics medallion
example: E-commerce example
# Raw · raw-commerce
- tool · NiFi ingest
- format · JSON · Parquet
- writer · Data Engineer
- example · clickstream events
- example · order records
---
# Anonymized · anon-commerce
- tool · Trino SQL
- format · Iceberg · partitioned
- writer · Data Engineer
- example · session pseudonyms
- example · masked customer IDs
---
# Staging · staging-commerce
- tool · Trino · notebooks
- format · Iceberg · cleaned
- writer · Data Scientist
- example · joined order facts
- example · validated event rows
---
# Aggregated · analytics-marts {focal}
- tool · Trino INSERT
- format · Iceberg · metrics
- writer · Data Scientist
- example · daily conversion rate
- example · revenue by channel
---
# Archive · archive-commerce {cold}
- tool · Object storage lifecycle
- format · Cold tier · immutable
- writer · Data Engineer
- example · retained clickstream
- example · closed order snapshots
---
Raw -> Anonymized MASK IDS
Anonymized -> Staging CLEAN + JOIN
Staging -> Aggregated AGGREGATE
Aggregated -> Archive LIFECYCLE {lifecycle}
---
# Paths
- SQL PATH · Trino INSERT INTO … SELECT · filter · join · aggregate — repeatable transforms
- NOTEBOOK PATH · Python notebooks on object storage · explore · validate · model — interactive analysis
```
~~~

## Delta de arquitetura

Duas fotos da mesma arquitetura, **antes** e **depois**, lado a lado e sincronizadas: uma migração, a extração de um serviço, a troca de uma fila. Os dois painéis usam a mesma grade da figura (célula 176 × 112, caixa 144 × 64) e um nó com o mesmo `id` fica na mesma célula nos dois, para o olho acompanhar; embaixo vem o **livro de mudanças**, uma linha numerada por diferença, calculada a partir dos dois modelos. O corpo são dois grupos com as linhas da figura (`type:figure`): `# Before · subtítulo` e `# After · subtítulo`, cada um com nós `- id coluna,linha tipo "Nome" "detalhe"`, zonas `zone RÓTULO: c1-c2, l1-l2` e ligações `de -> para RÓTULO`. Uma ligação ganha identidade pela tag `{id:r2}`; sem ela, a identidade é o par de pontas. A diferença sai sozinha: nó só no depois é **ADDED** (acento, com um retângulo interno), só no antes é **REMOVED** (tracejado, apagado), em outra célula é **MOVED** (contorno pontilhado), com outro nome, detalhe ou tipo é **CHANGED** (um filete de 3 px na borda esquerda); ligação com o mesmo `id` e outras pontas é **REWIRED** (traço 8 3 2 3), com as mesmas pontas e outro rótulo é CHANGED. Cada nó escreve a própria situação em cima do nome (`= storefront · UNCHANGED`, `+ queue · ADDED`), para que a cor nunca seja a única pista. `cols: N` fixa as colunas (sem ela, a maior coluna usada); um título é um `#` que não seja Before, After ou Changes; `> citação` vira a nota em itálico. Um grupo `# Changes` com linhas `- CHANGED api · texto` substitui o livro calculado (a palavra e o id, quando existem, viram os metadados da entrada). Com `motion:step`, cada entrada do livro e o objeto do painel Depois que ela nomeia entram juntos, uma mudança por passo. Orçamento: 2 a 8 componentes únicos, até 10 ligações únicas, até 8 entradas no livro (um nó mudado e movido gasta duas); passou disso, divida a migração em fases.

Com os dois painéis em px (`size: LxA`), o delta segue os três painéis da referência — Antes · Mudanças · Depois —, com o livro entre dois filetes no vão do meio, 60 px por entrada, e a legenda embaixo (o exemplo 02, número por número); por célula, o livro continua embaixo dos painéis. `# Changes · subtítulo` dá o título e o subtítulo da coluna do meio. Ali o rótulo de uma ligação diz o `id` e a mudança (`r2 · REWIRED`), ou o protocolo quando nada mudou (`r1 · HTTPS`), numa máscara de 16 px que `mask:X,Y,L` posiciona. `note px:X,Y "linha" "linha"`, dentro de um grupo, escreve palavras soltas no painel, 20 px por linha. `preserved: TEXTO` troca as palavras da linha dos preservados, e `legend: 24, 220, …` dá o x de cada item da legenda.

```@diagram type:architecture-delta
# Order fulfilment, before and after
cols: 3
# Before · Synchronous dispatch · v1
- storefront 2,1 "Storefront" "web:v1"
- api 2,2 "Orders API" "/orders · v1"
- legacy 2,3 "Legacy dispatcher" "dispatcher:v1"
- worker 1,4 "Fulfilment worker" "fulfilment:v1"
- db 2,5 store "Orders database" "PostgreSQL"
storefront -> api HTTPS
api -> legacy SUBMIT {id:r2}
legacy -> worker DISPATCH
worker -> db SQL
# After · Queued fulfilment · v2
- storefront 2,1 "Storefront" "web:v1"
- api 2,2 "Orders API" "/orders · v2"
- queue 2,3 store "Order queue" "durable · at-least-once"
- worker 3,4 "Fulfilment worker" "fulfilment:v1"
- db 2,5 store "Orders database" "PostgreSQL"
storefront -> api HTTPS
api -> queue SUBMIT {id:r2}
queue -> worker DELIVER
worker -> db SQL
> IDs persist across snapshots. Dashed and dotted strokes encode change, not protocol.
```

~~~text
```@diagram type:architecture-delta
# Order fulfilment, before and after
cols: 3
# Before · Synchronous dispatch · v1
- storefront 2,1 "Storefront" "web:v1"
- api 2,2 "Orders API" "/orders · v1"
- legacy 2,3 "Legacy dispatcher" "dispatcher:v1"
- worker 1,4 "Fulfilment worker" "fulfilment:v1"
- db 2,5 store "Orders database" "PostgreSQL"
storefront -> api HTTPS
api -> legacy SUBMIT {id:r2}
legacy -> worker DISPATCH
worker -> db SQL
# After · Queued fulfilment · v2
- storefront 2,1 "Storefront" "web:v1"
- api 2,2 "Orders API" "/orders · v2"
- queue 2,3 store "Order queue" "durable · at-least-once"
- worker 3,4 "Fulfilment worker" "fulfilment:v1"
- db 2,5 store "Orders database" "PostgreSQL"
storefront -> api HTTPS
api -> queue SUBMIT {id:r2}
queue -> worker DELIVER
worker -> db SQL
> IDs persist across snapshots. Dashed and dotted strokes encode change, not protocol.
```
~~~

## Planta axonométrica

Um andar ou um terreno visto de cima, em ângulo, com o que está em pé nele: um escritório e suas salas, um galpão e suas zonas, um campus e seus prédios. A planta é uma grade de células (`grid: 9x6`, colunas × linhas; sem ela, 8 × 6, crescendo até caber as áreas), e cada célula tem 40 unidades (`cell: 1` escreve a planta em unidades, para reproduzir uma geometria exata). A placa é a grade inteira, uma laje de 6 (`plate: site` faz um terreno: laje de 8, cantos arredondados, sem paredes). Num andar, a placa veste o anel de parede externo e cada **área** é dona da parede do seu lado leste e sul, 6 de espessura e 22 de altura (cortada na altura de uma mesa, para nenhuma sala esconder a outra), de modo que duas vizinhas dividem uma parede só e as paredes se encontram sem se sobrepor; onde não há vizinha, a área fecha o seu lado norte ou oeste. Uma porta é um vão que a tag `door:` abre na parede: `door:south` centraliza um vão de 28 nesse lado, `door:east:2` centraliza o vão na segunda célula do lado, `door:south:40-76` abre o vão entre essas unidades ao longo da parede; várias portas vêm separadas por vírgula. Cada **item** é uma caixa em pé na placa, 8 unidades para dentro da sua célula, com 12 de altura (ou `{h:N}`); `kind:` diz o que é: `desk` e `table` (o tampo ganha uma linha interna; `r:12` arredonda a planta, uma mesa redonda), `post` (um poste de fila, redondo, 18 de altura), `rack` (uma prateleira a cada 14 unidades, um montante a cada 30), `tree` (um disco 8 unidades acima do tronco), `building` (uma caixa alta, 40 sem `h:`, com a etiqueta no telhado), `crate` (uma caixa fechada com a linha da tampa: um palete, um carrinho, um eletrodoméstico), `road`, `dock` e `flat` (uma marca rasa no chão da placa, sem altura; a estrada leva uma linha de centro tracejada). Tudo é projetado pela mesma função da vista explodida (dimétrica 2:1) e pintado de trás para a frente, na ordem topológica da referência: a placa, as marcas rasas, os pisos, cada caixa e, por último, as etiquetas (nome em cima, detalhe em mono embaixo, num fundo de papel de 32 px), cada uma no piso da área que nomeia, no centro ou no ponto livre mais próximo quando um móvel está no centro; uma etiqueta nunca cobre outra. `tag:12,40` numa área fixa a etiqueta nessa posição (unidades do modelo a partir do canto de trás da área, dentro do piso), e `tag:roof` num `building` fixa a dele no centro do telhado — para reproduzir exatamente uma colocação feita à mão, como as da galeria; sem a tag, vale a regra; `tag:none` deixa a área (ou o prédio) sem etiqueta, como as zonas de um terreno. `{open}` numa área faz dela uma zona sem parede própria (o piso vai até a borda da planta dela; o anel externo e as paredes das vizinhas ficam), e `{open:dashed}` marca o limite leste e sul dela com uma linha tracejada no chão, como a fita de um galpão. `wall: south:6-454` fixa onde corre uma parede do anel externo (o lado e o intervalo em unidades ao longo dele; várias separadas por vírgula), para reproduzir uma parede que a galeria deixou curta, como o canto sudeste aberto do galpão; sem a linha, o anel é fechado. Uma área por linha no primeiro grupo, `- Nome · detalhe coluna,linha LxA {focal door:south}` (a primeira célula e o tamanho em células; `LxA` é 1x1 se omitido); os itens de uma área vêm num grupo `# Nome` logo abaixo, `- Item · nota coluna,linha [LxA] {kind:rack h:52}`, com a célula contada na planta. `{focal}` pinta uma área no acento (o piso e a etiqueta; os itens dela ficam neutros) ou um `building`; no máximo um. `axis: North ↑` escreve a bússola no canto superior esquerdo; `focal: zone` troca o substantivo da etiqueta da nota ("Focal room" ou "Focal building" sem ela); `> citação` vira a nota em itálico embaixo. Com `motion:step`, as áreas entram na ordem em que estão escritas, cada uma com os seus itens e a sua etiqueta (paredes e pisos ficam); `{step:N}` numa área ou num item fixa o passo dele, e `{step:0}` deixa o elemento parado (as árvores de um campus que entra por fases). Orçamento: 2 a 12 áreas, até 32 itens. Áreas não se sobrepõem na grade, e um item fica dentro do piso da área do seu grupo. Se as peças se afastam ao longo de um eixo, use `type:exploded`; se é só contenção, sem geografia, `type:nested`.

```@diagram type:axonometric-plan
# Level 3 office · Where the team actually sits
grid: 9x6
axis: North ↑
- Open office · 24 desks 1,1 5x3 {door:east:2,south:2,south:5}
- Meeting room · 12 seats 6,1 4x2 {focal door:south:2}
- Kitchen · café, lockers 6,3 4x4
- Lobby · reception 1,4 4x3 {door:south}
- Booth · 1 person 5,4 1x3
# Open office
- Desk 1,1 {kind:desk h:10}
- Desk 3,1 {kind:desk h:10}
- Desk 5,1 {kind:desk h:10}
- Desk 1,3 {kind:desk h:10}
- Desk 3,3 {kind:desk h:10}
- Desk 5,3 {kind:desk h:10}
# Meeting room
- Table · 12 seats 7,1 2x1 {kind:table h:10}
# Kitchen
- Counter 9,3 1x4 {h:16}
- Lockers 7,5 {h:14}
# Lobby
- Reception desk 1,5 2x1 {h:14}
> Walls cut at desk height so every room reads from one view; the meeting room is the one under discussion.
```

~~~text
```@diagram type:axonometric-plan
# Level 3 office · Where the team actually sits
grid: 9x6
axis: North ↑
- Open office · 24 desks 1,1 5x3 {door:east:2,south:2,south:5}
- Meeting room · 12 seats 6,1 4x2 {focal door:south:2}
- Kitchen · café, lockers 6,3 4x4
- Lobby · reception 1,4 4x3 {door:south}
- Booth · 1 person 5,4 1x3
# Open office
- Desk 1,1 {kind:desk h:10}
- Desk 3,1 {kind:desk h:10}
- Desk 5,1 {kind:desk h:10}
- Desk 1,3 {kind:desk h:10}
- Desk 3,3 {kind:desk h:10}
- Desk 5,3 {kind:desk h:10}
# Meeting room
- Table · 12 seats 7,1 2x1 {kind:table h:10}
# Kitchen
- Counter 9,3 1x4 {h:16}
- Lockers 7,5 {h:14}
# Lobby
- Reception desk 1,5 2x1 {h:14}
> Walls cut at desk height so every room reads from one view; the meeting room is the one under discussion.
```
~~~

Um galpão de fulfillment: as docas são vãos na parede externa (`door:west:2`) com uma marca rasa no chão (`kind:dock`), as estantes altas são `kind:rack`, e a zona de embalagem é a focal:

```@diagram type:axonometric-plan
# Fulfillment floor · Dock to dock
grid: 12x8
axis: North ↑
- Receiving · 3 dock doors 1,1 3x8 {door:west:2,west:4,west:6}
- Storage · 6 racks 4,1 5x5
- Pick zone · carts, flow rack 4,6 5x3
- Packing · 3 stations 9,1 2x8 {focal}
- Shipping · 3 dock doors 11,1 2x8 {door:east:2,east:4,east:6}
# Receiving
- Dock 1,2 {kind:dock}
- Dock 1,4 {kind:dock}
- Dock 1,6 {kind:dock}
- Pallet 2,2 {h:14}
- Pallet 2,4 {h:18}
- Pallet 2,6 {h:12}
# Storage
- Rack 4,1 2x1 {kind:rack h:52}
- Rack 7,1 2x1 {kind:rack h:52}
- Rack 4,3 2x1 {kind:rack h:52}
- Rack 7,3 2x1 {kind:rack h:52}
- Rack 4,5 2x1 {kind:rack h:52}
- Rack 7,5 2x1 {kind:rack h:52}
# Pick zone
- Flow rack 4,6 5x1 {kind:rack h:24}
- Cart 4,8 {h:14}
- Cart 6,8 {h:14}
- Cart 8,8 {h:14}
# Packing
- Station 9,2 {kind:desk h:14}
- Station 9,4 {kind:desk h:14}
- Station 9,6 {kind:desk h:14}
- Conveyor 10,1 1x8 {h:8}
# Shipping
- Pallet 11,2 {h:20}
- Pallet 11,4 {h:16}
- Pallet 11,6 {h:22}
- Dock 12,2 {kind:dock}
- Dock 12,4 {kind:dock}
- Dock 12,6 {kind:dock}
> Goods move left to right; packing is where most orders wait, so it gets the accent.
```

~~~text
```@diagram type:axonometric-plan
# Fulfillment floor · Dock to dock
grid: 12x8
axis: North ↑
- Receiving · 3 dock doors 1,1 3x8 {door:west:2,west:4,west:6}
- Storage · 6 racks 4,1 5x5
- Pick zone · carts, flow rack 4,6 5x3
- Packing · 3 stations 9,1 2x8 {focal}
- Shipping · 3 dock doors 11,1 2x8 {door:east:2,east:4,east:6}
# Receiving
- Dock 1,2 {kind:dock}
- Dock 1,4 {kind:dock}
- Dock 1,6 {kind:dock}
- Pallet 2,2 {h:14}
- Pallet 2,4 {h:18}
- Pallet 2,6 {h:12}
# Storage
- Rack 4,1 2x1 {kind:rack h:52}
- Rack 7,1 2x1 {kind:rack h:52}
- Rack 4,3 2x1 {kind:rack h:52}
- Rack 7,3 2x1 {kind:rack h:52}
- Rack 4,5 2x1 {kind:rack h:52}
- Rack 7,5 2x1 {kind:rack h:52}
# Pick zone
- Flow rack 4,6 5x1 {kind:rack h:24}
- Cart 4,8 {h:14}
- Cart 6,8 {h:14}
- Cart 8,8 {h:14}
# Packing
- Station 9,2 {kind:desk h:14}
- Station 9,4 {kind:desk h:14}
- Station 9,6 {kind:desk h:14}
- Conveyor 10,1 1x8 {h:8}
# Shipping
- Pallet 11,2 {h:20}
- Pallet 11,4 {h:16}
- Pallet 11,6 {h:22}
- Dock 12,2 {kind:dock}
- Dock 12,4 {kind:dock}
- Dock 12,6 {kind:dock}
> Goods move left to right; packing is where most orders wait, so it gets the accent.
```
~~~

## Árvore

Uma hierarquia: a raiz no topo e os filhos abrindo embaixo, um andar por nível — taxonomias, árvores de dependência, decomposição em blocos, árvores de habilidades. A hierarquia é a indentação da lista: dois espaços a mais por nível (`- Raiz`, `  - Filho`, `    - Neto`), uma raiz só, até 4 andares e 5 nós por andar. Os nós têm 160 × 48 (`node: 160x52` muda os dois), os andares ficam 128 px um do outro (`pitch: 140`), e cada fileira segue uma regra só: um nó fica centrado; uma fileira que cabe se distribui por igual entre as margens de 140 (`spread: 200`); uma que ficaria mais apertada que 20 px se empilha com esse espaço a partir da margem de 40. `x:`/`y:` num nó movem só ele; `y:` na raiz move os andares com ela. Os conectores são ortogonais, 1 px: o primeiro filho carrega a descida do pai até um barramento no meio do intervalo, os outros saem dele, e um filho bem embaixo do pai ganha uma reta. A raiz é o nó em destaque (acento) a não ser que `{focal}` aponte outro — um só; um nó de galho é branco com borda de tinta, e o último andar, a partir de três, é folha (tinta a 5 %, borda fina); `kind:optional|security|external` dá a um nó o tratamento da referência. `tag:ROOT` escreve uma etiqueta mono no canto do nó; `id:PAY-001` faz o mesmo e leva o id para `data-block-id`/`data-block-parent` (a decomposição em blocos rastreável). Onde a mão da galeria pôs diferente, linhas na cabeça fixam, sem mudar o padrão: `bus: 50` põe cada barramento 50 px acima da fileira que ele alimenta (padrão: o meio do intervalo); `connectors: parent` faz cada conector sair do pai, escrito em V e H; `badge-y: 6` põe as etiquetas 6 px abaixo do topo do nó (padrão 8); `name-y: 30` põe todo nome 30 px abaixo do topo do nó; e `{badge:46}` num nó dá a largura da etiqueta dele. Os andares têm nome na margem esquerda, `TIER 0 · ROOT`, `TIER 1`…; linhas `tier: NOME {y:N}`, em ordem, renomeiam e podem fixar a linha de base. A legenda fecha a figura (`legend: none` tira; `legend: focal=Root · focal, backend=Category branch, store=Leaf skill` escolhe as entradas e os rótulos) e a linha `> citação` é a nota em itálico dela.

```@diagram type:tree
title: Claude Code skill taxonomy
tier: TIER 0 · ROOT
tier: TIER 1 {y:224}
tier: TIER 2 {y:324}
legend: focal=Root · focal, backend=Category branch, store=Leaf skill
- Skills {tag:ROOT}
  - Design · ui · visual · ux {tag:CAT}
    - polish · align · space · rhythm {x:60}
    - critique · hierarchy · density
  - Engineering · ship · review · test {tag:CAT}
    - review · pre-land diff · sql
    - ship · merge · deploy · verify
  - Research · investigate · analyze {tag:CAT}
    - investigate · root cause · evidence
> Orthogonal connectors only. Coral marks the root — every branch descends from one idea.
```

~~~text
```@diagram type:tree
title: Claude Code skill taxonomy
tier: TIER 0 · ROOT
tier: TIER 1 {y:224}
tier: TIER 2 {y:324}
legend: focal=Root · focal, backend=Category branch, store=Leaf skill
- Skills {tag:ROOT}
  - Design · ui · visual · ux {tag:CAT}
    - polish · align · space · rhythm {x:60}
    - critique · hierarchy · density
  - Engineering · ship · review · test {tag:CAT}
    - review · pre-land diff · sql
    - ship · merge · deploy · verify
  - Research · investigate · analyze {tag:CAT}
    - investigate · root cause · evidence
> Orthogonal connectors only. Coral marks the root — every branch descends from one idea.
```
~~~

## Organograma

Um mapa de responsabilidade: quem é dono do quê, como se aciona cada um e onde estão as lacunas — times, agentes, filas de escalonamento. Use-o em vez da árvore quando os nós são pessoas, agentes, times ou papéis. A hierarquia é a indentação da lista (dois espaços por nível), uma raiz só, até 12 nós, 4 andares e 5 subordinados diretos por nó. A porta de entrada fica no topo, centrada, 200 × 48, o único nó em destaque (acento) a não ser que `{focal}` aponte outro; os pods embaixo têm 160 × 48, brancos com borda de tinta; o último andar são os responsáveis, 136 × 56, tinta a 5 % com borda fina. A figura tem 1040 de largura; uma fileira segue a regra da árvore: um nó centrado, uma fileira que cabe distribuída por igual entre as margens de 120, uma mais apertada que 24 px empilhada a partir da margem de 40 (`x:`/`y:` num nó movem só ele). Os conectores são ortogonais, com o barramento 48 px acima dos filhos e cada descida entrando no centro do nó; `{drop:N}` num nó muda o x em que o conector entra pelo topo dele (múltiplo de 4, dentro da borda de cima; a raiz não recebe conector). Cada andar tem nome na margem (`COMMAND CENTER`, `WORKSTREAMS`, `SPECIALISTS`; linhas `tier: NOME {y:N}` renomeiam) e um fio separa os andares. `tag:FRONT` escreve a etiqueta mono no canto do nó; `kind:optional` é um responsável ainda não ligado (tracejado, a lacuna fica visível), `kind:security` um portão de aprovação, `kind:external` alguém de fora. Cada linha `> citação` vira uma faixa tracejada embaixo dos responsáveis — regras de escalonamento e aprovação, lacunas de setup; `Rótulo: o resto` põe o rótulo em negrito — no máximo duas. A legenda fecha a figura (`legend: none` tira; `legend: focal=front door, backend=pod / owner, optional=needs setup / gap` escolhe as entradas e os rótulos).

```@diagram type:org-chart
title: Agent team org chart
legend: focal=front door, backend=pod / owner, optional=needs setup / gap
- Athena · @athena · route ambiguous work {tag:FRONT}
  - Growth · ads · analytics {tag:POD}
    - Media Buyer · Google · Meta
    - Maximo · offers · strategy
  - Content · email · blog · SEO {tag:POD}
    - Rory · copy · newsletter
  - Commerce · shopify · CRO {tag:POD}
    - Porter · Shopify admin
    - Atlas · theme · APIs
  - Systems · agents · runtime {tag:POD}
    - Hermes · Paperclip health
> Setup gaps stay visible: specialists without Slack bots · approval gates · backend name mismatches
```

~~~text
```@diagram type:org-chart
title: Agent team org chart
legend: focal=front door, backend=pod / owner, optional=needs setup / gap
- Athena · @athena · route ambiguous work {tag:FRONT}
  - Growth · ads · analytics {tag:POD}
    - Media Buyer · Google · Meta
    - Maximo · offers · strategy
  - Content · email · blog · SEO {tag:POD}
    - Rory · copy · newsletter
  - Commerce · shopify · CRO {tag:POD}
    - Porter · Shopify admin
    - Atlas · theme · APIs
  - Systems · agents · runtime {tag:POD}
    - Hermes · Paperclip health
> Setup gaps stay visible: specialists without Slack bots · approval gates · backend name mismatches
```
~~~

## Grafo de dependências

O que depende do quê entre pacotes, módulos ou serviços — e, em especial, as duas coisas que uma árvore não consegue dizer: um nó em que vários outros convergem (o selo de *fan-in* no canto de cada caixa, `4 IN`) e um ciclo (o único acento da figura). Se todo nó tem um pai só e nada aponta para cima, use uma árvore. Cada nó é uma linha `- id tipo "Nome" "detalhe" "TAG"`: o tipo é `internal` (padrão), `external` (terceiros: ponha a versão e o registro no detalhe, `v3.23 · npm`) ou `leaf` (sem dependências; um nó sem seta saindo vira folha sozinho); a TAG é a etiqueta pequena do canto. Uma dependência é `de -> para`, sem rótulo; a página calcula a profundidade de cada nó (a fila 0 em cima, 120 px entre filas, cada fila centrada, 40 px entre caixas de 160 × 56), afunda as folhas na última fila e desenha cada ligação em ângulo reto: uma reta quando as caixas dividem a coluna (ou a fila, se vizinhas), um cotovelo pelo corredor entre as filas nos outros casos, com uma ponte de 8 px onde uma passa por cima da outra. Uma ligação que pula uma fila dá a volta por fora, pela margem. O ciclo é `{cycle}` numa ligação (ou a única que aponta para trás, se nenhuma estiver marcada): sai tracejado na cor de acento, dá a volta por fora e entra pelo lado da caixa, com `CYCLE` escrito na volta de baixo; um segundo ciclo é recusado. Quando a regra não coloca uma ligação onde você quer, `{side:left|right}` escolhe o lado da porta de um cotovelo, `{y:N}` a altura da sua corrida horizontal e `{nohop:N}` deixa de fora a ponte no cruzamento cujo x (numa corrida) ou y (numa descida) é N — vários separados por vírgula; uma ponte que a ligação não tem é recusada; num nó, `{rank:N}` fixa a fila e `{x:N}` a posição (múltiplos de 4). Orçamento: 2 a 9 nós, até 14 ligações, até 4 filas, um ciclo. Uma linha `> nota` vira a frase em itálico da legenda. O exemplo abaixo é o da galeria (41), com quatro ajustes que reproduzem a mão do autor onde a regra escolheria o outro lado ou 16 px entre as corridas.

```@diagram type:dependency
title: TypeScript monorepo dependency graph
- web "web" "apps/web" "APP"
- admin "admin" "apps/admin" "APP"
- api "api" "services/api" "SVC"
- ui-kit "ui-kit" "packages/ui-kit" "PKG"
- shared-types "shared-types" "packages/shared-types" "PKG"
- db "db" "services/db" "SVC"
- tokens "tokens" "packages/tokens" "PKG"
- utils "utils" "packages/utils" "PKG"
- zod external "zod" "v3.23 · npm" "EXT"
web -> api
web -> ui-kit {side:left}
admin -> ui-kit
admin -> api {side:right}
api -> shared-types
api -> db
ui-kit -> shared-types
ui-kit -> tokens
db -> shared-types
shared-types -> utils {y:408}
shared-types -> zod {y:396}
utils -> shared-types {cycle}
> Badges show fan-in — a tree can't express convergence.
```

~~~text
```@diagram type:dependency
title: TypeScript monorepo dependency graph
- web "web" "apps/web" "APP"
- admin "admin" "apps/admin" "APP"
- api "api" "services/api" "SVC"
- ui-kit "ui-kit" "packages/ui-kit" "PKG"
- shared-types "shared-types" "packages/shared-types" "PKG"
- db "db" "services/db" "SVC"
- tokens "tokens" "packages/tokens" "PKG"
- utils "utils" "packages/utils" "PKG"
- zod external "zod" "v3.23 · npm" "EXT"
web -> api
web -> ui-kit {side:left}
admin -> ui-kit
admin -> api {side:right}
api -> shared-types
api -> db
ui-kit -> shared-types
ui-kit -> tokens
db -> shared-types
shared-types -> utils {y:408}
shared-types -> zod {y:396}
utils -> shared-types {cycle}
> Badges show fan-in — a tree can't express convergence.
```
~~~

## Gráfico polar

Uma série numérica em 4 a 8 categorias cuja ordem no sentido horário significa algo — horas do dia, meses, pontos da bússola. Cada categoria é um raio a partir do centro, do comprimento do seu valor, com uma bolinha na ponta (um "pirulito" radial); cinco anéis marcam 20, 40, 60, 80 e 100 % da escala, a escala está escrita uma vez só, ao lado do primeiro eixo, e o nome e o número de cada categoria ficam fora do anel maior, na horizontal, sempre legíveis. A escala começa em zero por regra (uma escala radial cortada mente sobre os raios) e nada é preenchido (uma área competiria com o raio). Cada categoria é uma linha `- Rótulo · valor`; `{focal}` destaca uma, no máximo uma, na cor de acento. Linhas de cabeçalho: `unit: % of daily peak` escreve a unidade e a escala em cima; `max: 100` fixa o teto (sem ele, o maior valor); `start: -90` é o ângulo da primeira categoria em graus (−90 é meio-dia, o padrão); `clockwise: false` gira ao contrário. Uma linha `> nota` vira a fonte, em baixo, sobre um fio. Um valor zero não desenha raio nem bolinha, só o `0`; uma categoria sem valor é recusada, porque zero e "não sei" não são a mesma coisa. Várias séries pedem um radar; mais de oito pontos ordenados, uma linha; categorias sem ordem circular, barras.

```@diagram type:polar
title: Request demand by UTC window
unit: % of daily peak
max: 100
- 00–03 · 32
- 03–06 · 18
- 06–09 · 24
- 09–12 · 58
- 12–15 · 100 {focal}
- 15–18 · 82
- 18–21 · 76
- 21–24 · 45
> Illustrative normalized workload profile
```

~~~text
```@diagram type:polar
title: Request demand by UTC window
unit: % of daily peak
max: 100
- 00–03 · 32
- 03–06 · 18
- 06–09 · 24
- 09–12 · 58
- 12–15 · 100 {focal}
- 15–18 · 82
- 18–21 · 76
- 21–24 · 45
> Illustrative normalized workload profile
```
~~~

## Gantt

Um plano no tempo: uma coluna de nomes à esquerda e, à direita, uma barra por tarefa de onde começa até onde termina, as tarefas em fases. O primeiro `#` é o título; cada fase vem depois de um `---`, com o seu `# NOME` (vira a etiqueta mono no canto da zona) e as tarefas em `- Nome · W1..W3` — da segunda-feira da semana 1 à da semana 3, duas semanas de barra, como a referência conta; `W5` sozinho é uma semana. `weeks: 12` fixa o eixo (sem ele, vai até a última tarefa) e a largura de cada semana é a que cabe em 760 px, inteira: 63 para 12 semanas. Com datas, `range: 2025-04-01..2025-06-24` e `- Nome · 2025-04-01..2025-04-15` (ou `2025-04..2025-06`): o eixo fica em dias, as semanas são traços a cada sete e os meses do calendário nomeiam os segmentos. `axis: April | May | June` nomeia segmentos iguais do eixo, com um separador tracejado entre eles; sem `axis:` as semanas se chamam W1…Wn. Uma tarefa é a de destaque (`{focal}`: acento na barra e no nome; uma só); `{label:GATE}` escreve um texto mono no meio da barra, e um segundo campo (`- Nome · responsável · W8..W9`) fica dentro dela. `today: W7` traça a linha tracejada do hoje. A zona de uma fase tem 12 px acima da primeira linha e n × 40 + 4 de altura; `{h:120}` no `#` da fase fixa outra. Até 12 tarefas, 5 por fase. A legenda fecha a figura (`legend: none` tira; `legend: focal=Design review · critical gate, task=Task, phase=Phase` escolhe os rótulos) e a linha `> citação` é a nota em itálico dela.

```@diagram type:gantt
title: Q2 product launch · 12-week plan
weeks: 12
axis: April | May | June
legend: focal=Design review · critical gate, task=Task, phase=Phase
---
# DISCOVERY
- Market research · W1..W3
- User interviews · W2..W4
---
# DESIGN {h:120}
- Wireframes · W4..W6
- Prototype · W5..W8
- Design review · W8..W9 {focal label:GATE}
---
# LAUNCH {h:88}
- Development · W7..W11
- Beta testing · W10..W12
```

~~~text
```@diagram type:gantt
title: Q2 product launch · 12-week plan
weeks: 12
axis: April | May | June
legend: focal=Design review · critical gate, task=Task, phase=Phase
---
# DISCOVERY
- Market research · W1..W3
- User interviews · W2..W4
---
# DESIGN {h:120}
- Wireframes · W4..W6
- Prototype · W5..W8
- Design review · W8..W9 {focal label:GATE}
---
# LAUNCH {h:88}
- Development · W7..W11
- Beta testing · W10..W12
```
~~~

## Sankey

Para onde vai uma quantidade: três colunas de barras, com fitas entre elas cuja espessura é o número — minutos de CI, orçamento, pessoas. Cada linha é um fluxo, `- Origem -> Destino 5200` (`→` também serve; `5,200` e `1200.5` se leem). As colunas saem dos próprios fluxos: quem só origina fica na primeira, quem só recebe na terceira, quem faz os dois no meio — e são exatamente três, como a referência pede. Dentro de uma coluna os nós ficam na ordem em que o texto os cita pela primeira vez (é assim que se desfaz um cruzamento). A escala é uma só para a figura toda: a que faz a coluna mais cheia ter 240 px (`scale: 0.02` fixa outra); a altura de cada fita arredonda ao grid de 4 px (4 no mínimo), e a barra tem a soma das suas fitas, com a quantidade escrita embaixo do nome (`unit: min` acrescenta a unidade). As fitas comuns são cinza; `{accent}` marca as do caminho em destaque, um só, em até duas fitas, pintadas por último. `columns: BUDGET | TEST STAGE | OUTCOME` nomeia as colunas. A legenda fecha a figura (`legend: none` tira; `legend: flow=Flow · stage routing, accent=Flaked path · reruns, node=Node · stage total {x:420}` escolhe os rótulos, e `{x:N}` fixa a posição de uma entrada) e a linha `> citação` é a nota em itálico dela, também com `{x:N}` se quiser.

```@diagram type:sankey
title: CI compute budget · a month of pipeline minutes
columns: BUDGET | TEST STAGE | OUTCOME
unit: min
legend: flow=Flow · stage routing, accent=Flaked path · reruns, node=Node · stage total {x:420}
- CI minutes -> Unit tests 5200
- CI minutes -> E2E 4000
- CI minutes -> Build 2000
- CI minutes -> Lint 800
- Unit tests -> Flaked 800 {accent}
- Unit tests -> Passed 4400
- E2E -> Flaked 200 {accent}
- E2E -> Passed 3800
- Build -> Passed 800
- Build -> Failed 1200
- Lint -> Passed 400
- Lint -> Failed 400
> Two coral ribbons — flaky reruns burn ~8% of the monthly CI budget. {x:600}
```

~~~text
```@diagram type:sankey
title: CI compute budget · a month of pipeline minutes
columns: BUDGET | TEST STAGE | OUTCOME
unit: min
legend: flow=Flow · stage routing, accent=Flaked path · reruns, node=Node · stage total {x:420}
- CI minutes -> Unit tests 5200
- CI minutes -> E2E 4000
- CI minutes -> Build 2000
- CI minutes -> Lint 800
- Unit tests -> Flaked 800 {accent}
- Unit tests -> Passed 4400
- E2E -> Flaked 200 {accent}
- E2E -> Passed 3800
- Build -> Passed 800
- Build -> Failed 1200
- Lint -> Passed 400
- Lint -> Failed 400
> Two coral ribbons — flaky reruns burn ~8% of the monthly CI budget. {x:600}
```
~~~

## Sequência

Quem fala com quem, em que ordem: os atores numa fileira de caixas no alto (144 × 56; a `{focal}`, 160), uma linha de vida tracejada descendo de cada um, e as mensagens como setas horizontais entre as linhas, o tempo correndo para baixo num passo de 56 px. Cada ator é um item da lista, `- Nome · papel {kind:input tag:EXT}`: o `kind` é o tratamento da caixa (`input`, `external`, `store`, `backend`, `optional`, `security`, ou `{focal}` para o ator em destaque, um só), e `tag:` a etiqueta pequena no canto. Cada mensagem é uma linha `A -> B RÓTULO {link|accent}`: `-->` tracejada é um retorno (ponta cheia), `{async}` tracejada com a ponta aberta é disparar e esquecer, `{link}` uma chamada HTTP, `{accent}` a resposta principal (até duas); `A -> A RÓTULO` é uma mensagem para si mesmo, um laço de 36 × 32 à direita da linha de vida. `activate A` depois de uma mensagem abre a barra de ativação (8 px) de A nessa mensagem, `deactivate A` fecha na mensagem acima, ou `{activate}` / `{deactivate}` na própria mensagem; as setas chegam e saem pela borda da barra. `alt [guarda] … else [guarda] … end` (ou `opt`, `loop`) desenha um fragmento combinado: a moldura em volta das linhas de vida que participam, a aba com o operador, a guarda de cada região e o divisor tracejado entre as duas. `note over A: texto` é uma nota numa linha própria. Onde a galeria coloca à mão, a cerca fixa o número: `{x:800}` num ator move a linha de vida, `{y:284}` numa mensagem move a linha (as seguintes continuam dali), `{from:352 to:168}` as pontas, `{mask:100}` ou `{mask:192,96}` a largura e o x da máscara do rótulo, `size: 1000x584` o viewBox e `legend: 56, 188, 308` o x de cada item da legenda. Orçamento: 2 a 5 atores, até 12 mensagens, até 2 acentos, 1 fragmento (2 só se cada um for um `opt` ou `loop` de uma região), 2 regiões num `alt`. Com `motion:step`, cada mensagem é um passo.

```@diagram type:sequence
# Article request, cold cache
size: 1000x584
legend: 56, 188, 308, 476, 652
- Reader · Browser {kind:input tag:EXT}
- Cloudflare · Pages · cache {kind:external tag:EDGE}
- Astro Origin · SSR + MDX {focal tag:ORIG}
- Analytics · Beacon · async {kind:optional tag:ASY x:800}
Reader -> Cloudflare GET /ARTICLES/SLUG {link to:352}
activate Cloudflare
Cloudflare -> Astro Origin CACHE MISS · ORIGIN {from:352 mask:100}
activate Astro Origin
Astro Origin -> Astro Origin RENDER MDX {y:284 mask:72}
Astro Origin --> Cloudflare 200 · HTML + MAX-AGE {y:352 mask:96}
deactivate Astro Origin
Cloudflare -> Reader 200 · EDGE-CACHED {accent mask:192,96}
deactivate Cloudflare
Reader --> Analytics PAGEVIEW BEACON {mask:648,96}
```

~~~text
```@diagram type:sequence
# Article request, cold cache
size: 1000x584
legend: 56, 188, 308, 476, 652
- Reader · Browser {kind:input tag:EXT}
- Cloudflare · Pages · cache {kind:external tag:EDGE}
- Astro Origin · SSR + MDX {focal tag:ORIG}
- Analytics · Beacon · async {kind:optional tag:ASY x:800}
Reader -> Cloudflare GET /ARTICLES/SLUG {link to:352}
activate Cloudflare
Cloudflare -> Astro Origin CACHE MISS · ORIGIN {from:352 mask:100}
activate Astro Origin
Astro Origin -> Astro Origin RENDER MDX {y:284 mask:72}
Astro Origin --> Cloudflare 200 · HTML + MAX-AGE {y:352 mask:96}
deactivate Astro Origin
Cloudflare -> Reader 200 · EDGE-CACHED {accent mask:192,96}
deactivate Cloudflare
Reader --> Analytics PAGEVIEW BEACON {mask:648,96}
```
~~~

A fórmula sozinha reproduz as caixas dos três primeiros atores, as linhas de vida, as duas barras e as seis setas do exemplo da galeria (`example-sequence.html`) na posição e no traço; o que a galeria escolheu à mão sai com as chaves: `{x:800}` no Analytics (a fórmula o põe em 816), `{y:284}` no laço e `{y:352}` no retorno seguinte (a fórmula: 288 e 352), `{to:352}` na primeira chamada e `{from:352}` na segunda (a regra as poria na borda da barra, 348 e 356), as máscaras dos rótulos (`mask:100`, `mask:72`, `mask:96`, `mask:192,96`, `mask:648,96`), `size: 1000x584` e `legend: 56, 188, 308, 476, 652`. Com todas, cada número do SVG é o da galeria. O `example-sequence-oauth.html` (a chamada com bearer e o `alt` de refresh) sai do mesmo jeito: a moldura `x=88 y=208 w=752 h=360`, a aba, as guardas e o divisor em 312 pela fórmula; as linhas, com passos de 40 e 48 px desenhados à mão, com `{y:N}`.

## Raias

Um processo entre times: raias horizontais de 80 px, uma por time, com o nome em maiúsculas pequenas na coluna da esquerda e um fio de 1 px entre elas; os passos como caixas de 120 × 48 dentro da raia de quem os faz, encadeados da esquerda para a direita com 40 px entre um e o próximo, seja qual for a raia; e as setas do fluxo: reta dentro da raia, uma queda vertical para um passo logo abaixo, um cotovelo com uma curva de 8 px para um passo noutra raia mais à frente. `lanes: Author, Reviewer, Editor, CI / CD` nomeia as raias na ordem; cada passo é `- Nome · detalhe {lane:Author}`, na ordem do fluxo, com a raia pelo nome, pelo índice ou por um prefixo (`lane:CI`); sem `lane:`, o passo fica na raia do anterior. `{w:140}` alarga a caixa, `{x:500}` a põe debaixo de outra (a fórmula a poria à direita), `{focal}` marca o resultado em destaque, um só. Sem linhas de seta, cada passo aponta para o seguinte; para escolher, `Open PR -> Review content HANDOFF {accent|dashed|link}`: `accent` é a passagem de bastão crítica (uma, na cor de acento), `dashed` um laço de revisão, `link` uma chamada externa. O que a galeria traça à mão sai com as chaves: `{to:520}` leva a perna vertical de um cotovelo ou de uma queda a esse x, `{from:N}` fixa o y de uma reta, `{mask:60}`, `{mask:528,140,60}` a máscara do rótulo, `size: 1000x480` o viewBox e `legend: 40, 132, 268` o x de cada item da legenda. Orçamento: 2 a 12 passos, até 5 raias. Com `motion:step`, cada passo é um passo.

```@diagram type:swimlane
# Publishing an article
legend: 40, 132, 268, 444, 608
lanes: Author, Reviewer, Editor, CI / CD
- Draft MDX · src/content/… {lane:Author}
- Open PR · gh pr create {lane:Author}
- Review content · fact-check · voice {lane:Reviewer w:140}
- Polish copy · style · line edits {lane:Editor w:140 x:500}
- Approve merge · squash · main {lane:Editor w:140}
- Build · astro build {lane:CI w:80 x:680}
- Deploy · cloudflare pages {lane:CI focal}
Draft MDX -> Open PR
Open PR -> Review content HANDOFF {to:520 mask:528,140,60}
Review content -> Polish copy REVISE {dashed mask:52}
Polish copy -> Approve merge
Approve merge -> Build DEPLOY TRIGGER {accent mask:80}
Build -> Deploy
```

~~~text
```@diagram type:swimlane
# Publishing an article
legend: 40, 132, 268, 444, 608
lanes: Author, Reviewer, Editor, CI / CD
- Draft MDX · src/content/… {lane:Author}
- Open PR · gh pr create {lane:Author}
- Review content · fact-check · voice {lane:Reviewer w:140}
- Polish copy · style · line edits {lane:Editor w:140 x:500}
- Approve merge · squash · main {lane:Editor w:140}
- Build · astro build {lane:CI w:80 x:680}
- Deploy · cloudflare pages {lane:CI focal}
Draft MDX -> Open PR
Open PR -> Review content HANDOFF {to:520 mask:528,140,60}
Review content -> Polish copy REVISE {dashed mask:52}
Polish copy -> Approve merge
Approve merge -> Build DEPLOY TRIGGER {accent mask:80}
Build -> Deploy
```
~~~

Assim escrita, a figura é a do exemplo da galeria (`example-swimlane.html`) nas raias, nas sete caixas, nas seis setas e no viewBox de 1000 × 480; o que falta para cada número bater é o que a galeria escolheu à mão: `{to:520}` no HANDOFF (a fórmula entra pelo centro do passo, 570), as máscaras dos três rótulos (`mask:528,140,60`, `mask:52`, `mask:80`) e `legend: 40, 132, 268, 444, 608`.

## Fluxograma

Lógica de decisão desenhada à mão: um fluxo de cima para baixo em que a forma diz o tipo e a cor nunca diz — oval (`start`, `end`) para começo e fim, retângulo (`step`) para um passo, losango (`decision`) para uma decisão com até três saídas, paralelogramo (`io`) para entrada ou saída, retângulo duplo (`subprocess`) para um subprocesso e um ponto cheio (`merge`) onde ramos se juntam. A gramática é a da [figura](#figura): cada nó numa célula (`- id col,linha tipo "Nome" "detalhe"`, célula de 240 × 128) ou numa caixa em pixels (`- id px:x,y LxA tipo "Nome" "detalhe"`, tudo na grade de 4 px; `size: LxA` fixa o viewBox), `"Uma linha | outra"` quebra o nome em duas linhas, `{focal}` põe o acento num nó só, e cada ligação é `de -> para RÓTULO {accent|dashed}`. Toda saída de um losango leva um rótulo (`YES`, `NO`) — sem ele a página recusa, como a referência manda; as outras ligações podem ficar sem. O losango é entrado e saído pelas quatro pontas, nunca por uma porta distribuída; uma caixa sozinha num lado alinha a porta com a ponta do losango ou com a linha que divide com a outra caixa, e assim um fluxo numa coluna só é uma reta. Duas ligações no mesmo lado se distribuem em L·k/(N+1); as rotas são ortogonais com curvas de 8 px, e `{from:LADO:N to:LADO:N via:N|X,Y}` fixa uma rota como na figura; `{label:X,Y[,L]}` põe a máscara de um rótulo à mão. O rótulo senta numa máscara de papel 8 px fora do traço, centrado na haste (o segmento menos a ponta de 8 px da seta), em acento quando a ligação é o caminho feliz. A legenda é a faixa de baixo da figura — a régua a 60 px da borda, LEGEND · SHAPE CARRIES TYPE, as formas presentes em casas iguais; uma linha `legend: 40, 220, 412, 604, 768` fixa o x de cada item (um por item desenhado, na grade de 4 px). Os pinos (`legend:`, `from:`/`to:`/`via:`, `label:`) são opcionais: sem eles a regra decide — casas iguais na legenda, portas alinhadas e rótulos na haste —, e o fence abaixo os usa para sair número por número. Orçamento: 2 a 9 nós, 12 ligações, 3 saídas por decisão, um nó focal e até duas ligações em acento. O exemplo 04 da galeria, escrito como o SVG dele:

```@diagram type:flowchart
title: Should you write this as a skill?
size: 1000x600
legend: 40, 220, 412, 604, 768
- start px:420,40 160x48 start "New workflow"
- step px:420,120 160x48 step "Do it manually once"
- d1 px:400,192 200x96 decision "Will you repeat | it >3 times?"
- oneoff px:720,216 160x48 end "One-off" "keep manual"
- d2 px:400,328 200x96 decision "Reusable across | projects?"
- note px:720,352 160x48 end "Project note" "project-scoped"
- skill px:420,464 160x56 end "Write a skill" "reusable + assets" {focal}
start -> step
step -> d1
d1 -> oneoff NO
d1 -> d2 YES
d2 -> note NO
d2 -> skill YES {accent}
```

~~~text
```@diagram type:flowchart
title: Should you write this as a skill?
size: 1000x600
legend: 40, 220, 412, 604, 768
- start px:420,40 160x48 start "New workflow"
- step px:420,120 160x48 step "Do it manually once"
- d1 px:400,192 200x96 decision "Will you repeat | it >3 times?"
- oneoff px:720,216 160x48 end "One-off" "keep manual"
- d2 px:400,328 200x96 decision "Reusable across | projects?"
- note px:720,352 160x48 end "Project note" "project-scoped"
- skill px:420,464 160x56 end "Write a skill" "reusable + assets" {focal}
start -> step
step -> d1
d1 -> oneoff NO
d1 -> d2 YES
d2 -> note NO
d2 -> skill YES {accent}
```
~~~

As sete formas, as seis ligações, os quatro rótulos com as máscaras (`NO` em 644,220 e `YES` em 508,298, como o exemplo escreve) e a legenda inteira saem iguais aos do exemplo. A galeria espaçou os cinco itens da legenda a olho (40, 220, 412, 604, 768), e a linha `legend:` repete isso; sem ela ficam em casas iguais de 184 px (40, 224, 408, 592, 776).

Pinos para o que a galeria desenhou à mão: `zone RÓTULO: px:x,y LxA` desenha uma moldura discreta atrás dos nós (rx 8, o rótulo em x+16, y+24), e `{open}` deixa só o rótulo. `{rx:N}` num nó muda o raio do canto, e uma palavra de tratamento (`{input}`, `{store}`…) muda só as cores — a forma continua dizendo o tipo. `{stop:N}` numa ligação faz a seta parar N px antes da borda da caixa. `a -> a RÓTULO` é um laço num nó só, aceito apenas com a rota fixada (`{from:LADO to:LADO via:X,Y}`). `grid: off` tira aquele fence, e só ele, da recusa da grade de 4 px: caixas, portas e x da legenda podem ser qualquer número, decimais inclusive. `look: drawio` desenha aquele fence na mão dos exemplos de importação da galeria (04a, 04b): as curvas como arcos `A 8,8`, a palavra 8 px abaixo do topo da máscara, nome e detalhe em cy−4 e cy+12, e uma legenda de tratamentos (FOCAL, DECISION, STORE, INPUT, SERVICE) a 96 px da borda.

Duas linhas `trace:` fazem do fence um par de avaliações de política (o padrão "por que duas decisões diferem e onde divergem pela primeira vez", exemplo 04c): `trace: Nome | detalhe` para cada uma das duas, `- Regra · detalhe: pass, fail` para cada regra (3 a 6, um status por trace: `pass`, `fail`, `skipped`, `not reached`), `outcome: Permitido, Negado` para o resultado de cada trace e `rules: Política` para o rótulo da coluna. As regras viram linhas numeradas, cada trace um cabeçalho com uma célula por regra e uma linha que desce até onde ele para; a primeira regra em que os dois diferem ganha o colchete FIRST DIVERGENCE, o trace que falhou termina num resultado em acento e o outro num bloco escuro, e a legenda dos status fecha a figura (`legend: 72, 176, 272, 564` fixa o x de cada status). A página recusa um status depois de um `fail` que não seja `not reached`, e `not reached` sem um `fail` antes — um trace negado não roda as regras seguintes.

## Máquina de estados

Lógica finita desenhada à mão — o status de um pedido, o ciclo de um artigo, o estado de uma conexão: estados em retângulos arredondados (`state`, rx 8), um ponto cheio de começo (`initial`, r 6) e um anel de fim (`final`, anel r 8 com ponto r 5), um estado terminal em cinza (`terminal`), um de espera tracejado (`wait`) e um losango de escolha (`choice`). A gramática é a do [fluxograma](#fluxograma), que é a da [figura](#figura): cada nó numa célula (`- id col,linha tipo "Nome" "detalhe" "TAG"`, célula de 224 × 144) ou numa caixa em pixels (`- id px:x,y LxA tipo "Nome" "detalhe" "TAG"`, na grade de 4 px; `size: LxA` fixa o viewBox). Um ponto é uma caixa de 16 × 16: a seta para na borda da caixa, 8 px do centro, como a galeria desenha. A terceira string entre aspas é a etiqueta do canto (`"STATE"`), `"a | b"` no detalhe dá duas linhas, `{focal}` põe o acento no estado que o leitor deve notar. Cada transição é `de -> para EVENTO [GUARDA] / AÇÃO {accent|dashed}` e leva rótulo sempre — sem ele a página recusa, porque o ponto da figura é o que dispara cada passagem. Transições entre lados que se encaram são retas ou ortogonais com curvas de 8 px, fixáveis com `{from:LADO:N to:LADO:N via:N|X,Y}` como na figura; duas portas no mesmo lado (`{from:top to:top}`) fazem uma curva, uma cúbica com os dois pontos de controle 64 px para fora (`via:N` muda a altura); `a -> a` é um laço que sai e entra por cima, 24 px de cada lado do centro. O rótulo senta numa máscara de papel centrada no meio do segmento — 4 px acima de um traço horizontal, em cima de um vertical (a máscara interrompe o traço), 4 px acima do ápice de uma curva — e `{label:X,Y[,L]}` põe a máscara à mão. Os pinos (`from:`/`to:`/`via:`, `label:`) são opcionais: sem eles a regra decide — portas alinhadas, rota reta ou ortogonal, máscara centrada no segmento —, e o fence abaixo os usa para sair número por número. Não há legenda, como no exemplo. Orçamento: 2 a 9 estados, 12 transições e nunca mais que o dobro dos estados (a referência diz que aí são duas máquinas), um estado focal e até duas transições em acento. O exemplo 06 da galeria, escrito como o SVG dele:

```@diagram type:state
title: Article lifecycle
size: 1000x460
- s0 px:52,192 16x16 initial
- draft px:120,160 160x80 state "Draft" "unpublished" "STATE"
- review px:340,160 160x80 state "In Review" "awaiting approval" "STATE"
- published px:560,160 160x80 state "Published" "live on site" "STATE" {focal}
- archived px:560,300 160x100 terminal "Archived" "noindex · hidden | redirect retained" "STATE"
- end px:632,432 16x16 final
s0 -> draft CREATE {label:72,184,48}
draft -> review SUBMIT {label:288,184,48}
review -> published APPROVE {accent label:500,184,60}
published -> archived EXPIRE {label:612,264,56}
archived -> end PURGE {label:620,416,40}
review -> draft REJECT · REVISE {dashed from:top to:top label:276,92,80}
```

~~~text
```@diagram type:state
title: Article lifecycle
size: 1000x460
- s0 px:52,192 16x16 initial
- draft px:120,160 160x80 state "Draft" "unpublished" "STATE"
- review px:340,160 160x80 state "In Review" "awaiting approval" "STATE"
- published px:560,160 160x80 state "Published" "live on site" "STATE" {focal}
- archived px:560,300 160x100 terminal "Archived" "noindex · hidden | redirect retained" "STATE"
- end px:632,432 16x16 final
s0 -> draft CREATE {label:72,184,48}
draft -> review SUBMIT {label:288,184,48}
review -> published APPROVE {accent label:500,184,60}
published -> archived EXPIRE {label:612,264,56}
archived -> end PURGE {label:620,416,40}
review -> draft REJECT · REVISE {dashed from:top to:top label:276,92,80}
```
~~~

O ponto, o anel, os quatro estados com as etiquetas e os textos, as cinco retas e a curva de volta (`M 420,160 C 420,96 200,96 200,160`) saem iguais aos do exemplo. As seis máscaras de rótulo a galeria colocou e dimensionou à mão (dois rótulos de seis letras têm 48 e 56 de largura), e os `{label:X,Y,L}` acima repetem isso — menos `CREATE`, que o exemplo escreve em x 172, dentro da caixa Draft, quando a seta dele corre de 68 a 120: aqui vai em 72, sobre a própria seta. Sem os pinos saem da regra, 6n+12 de largura e centradas no segmento (`CREATE` em 70,184, `EXPIRE` em 616,264 com 48).

O mapa de fases de um ciclo de vida (exemplo 06a) usa os mesmos pinos do fluxograma — `zone RÓTULO: px:x,y LxA {open}` para as faixas (aqui o rótulo em x+16, y+20), `grid: off` para as caixas de 150 de largura — e mais três. `{badge:L}` fixa a largura da etiqueta do canto. `{icon:final}` desenha o anel de fim dentro de um estado (r 7 e 4, em x+24, y+24), o "concluído" do leitor. `look: lifecycle` é a mão desse exemplo: cantos retos, nenhum salto onde duas transições se cruzam, a etiqueta em x+10, y+10, o nome em y+43 e o detalhe em y+58 (sem etiqueta, cy−5 e cy+14) e a palavra 9 px abaixo do topo da máscara. O orçamento conta estados: o ponto de começo e o anel de fim contam só nas transições, como o padrão do ciclo de vida manda.

## Quadrante

Um 2×2: dois eixos que se cruzam no meio e os itens como pontos nos quatro quadrantes — priorização (impacto × esforço), posicionamento, um portfólio. A posição é o sinal: os quadrantes não têm cor, só o item em destaque (`{focal}`, o "faça primeiro") é um ponto maior na cor de acento, e o quadrante dele ganha uma faixa quase invisível e a etiqueta de canto em destaque. Os eixos são obrigatórios: `x: Pouco esforço → Muito esforço` (esquerda → direita) e `y: Pouco impacto → Muito impacto` (baixo → cima); `quadrants: A | B | C | D` nomeia os cantos na ordem superior-esquerdo, superior-direito, inferior-esquerdo, inferior-direito. Cada item é `- Nome · detalhe 0,7,0,8`: `x,y` de 0 a 1 (ou na escala de `scale: 10, 4`), o x pela largura do gráfico (760 px) e o y pela altura (340 px), o rótulo 12 px à direita do ponto; `{anchor:end}` vira o rótulo para a esquerda, `{label:X,Y}` o põe onde quiser, `{px:X,Y}` crava o ponto num pixel do grid de 4 px. `legend: focal=Começa amanhã, item=Candidato` são as palavras da legenda e `legend: 52, 192, 336` o x de cada entrada e da nota; `> nota` vira a nota em itálico no fim da legenda; `arrows: false` tira as setas dos eixos. Os pinos são opcionais: sem eles, a posição vem dos valores pela fórmula e a legenda anda 140 px por entrada — o exemplo da galeria posiciona à mão, então o fence abaixo o reproduz com pinos. Um item em cima de um eixo é recusado (não está em quadrante nenhum), assim como um 2×2 sem nome nos eixos.

```@diagram type:quadrant
title: Content ideas · Impact × Effort
x: Low effort → High effort
y: Low impact → High impact
quadrants: Do first | Major projects | Quick wins | Avoid
legend: focal=Start tomorrow, item=Candidate project
legend: 52, 192, 336
- Schematic skill v4 {px:220,140 focal}
- Update changelog {px:320,200}
- Design v4 refresh {px:620,140}
- New publication {px:760,180}
- Fix footer link {px:260,320}
- Update OG tags {px:360,380}
- Rewrite build pipeline {px:640,380}
- Port to Nuxt {px:780,320}
> Position is the signal. Colour is reserved for the single action item.
```

~~~text
```@diagram type:quadrant
title: Content ideas · Impact × Effort
x: Low effort → High effort
y: Low impact → High impact
quadrants: Do first | Major projects | Quick wins | Avoid
legend: focal=Start tomorrow, item=Candidate project
legend: 52, 192, 336
- Schematic skill v4 {px:220,140 focal}
- Update changelog {px:320,200}
- Design v4 refresh {px:620,140}
- New publication {px:760,180}
- Fix footer link {px:260,320}
- Update OG tags {px:360,380}
- Rewrite build pipeline {px:640,380}
- Port to Nuxt {px:780,320}
> Position is the signal. Colour is reserved for the single action item.
```
~~~

### Matriz de cenários (`quadrant-consultant`)

A variante de consultoria do 2×2: os eixos guardam uma faixa, não uma medida, com setas nas duas pontas, e cada quadrante é uma célula nomeada — quatro futuros, quatro arquétipos, quatro apostas — em vez de pontos posicionados. São exatamente quatro itens, na ordem superior-esquerdo, superior-direito, inferior-esquerdo, inferior-direito, cada um com o nome na linha do item e de uma a três linhas de descrição indentadas embaixo; exatamente um `{focal}` é a aposta principal, na cor de acento. A etiqueta de canto (`01 · REMOTE / HUMAN`) é montada das palavras dos eixos, então nunca discorda deles. Os mesmos `x:`, `y:`, `legend:` e `> nota` do quadrante; aqui a legenda não tem a palavra LEGENDA. Se a posição dentro da célula importa, é o quadrante comum.

```@diagram type:quadrant-consultant
title: Workplace 2030 · Remote × AI automation
x: Human → AI
y: In-person → Remote
legend: focal=Headline bet, item=Candidate future
legend: 40, 160, 304
- Distributed humans
  Async-first, global hiring,
  Slack-heavy. Human-centric
  workflows, low AI leverage.
- Agent teams {focal}
  Humans orchestrate; AI
  handles the routine layer.
  Small, high-leverage teams.
- Office classic
  Return-to-office mandates,
  manual work. Techlash
  prolongs the status quo.
- In-person + AI
  Smart offices, AI-augmented
  staff. Physical presence is
  the moat, AI is the lever.
> Every cell is named. The axes carry the range; the coral quadrant carries the commitment.
```

~~~text
```@diagram type:quadrant-consultant
title: Workplace 2030 · Remote × AI automation
x: Human → AI
y: In-person → Remote
legend: focal=Headline bet, item=Candidate future
legend: 40, 160, 304
- Distributed humans
  Async-first, global hiring,
  Slack-heavy. Human-centric
  workflows, low AI leverage.
- Agent teams {focal}
  Humans orchestrate; AI
  handles the routine layer.
  Small, high-leverage teams.
- Office classic
  Return-to-office mandates,
  manual work. Techlash
  prolongs the status quo.
- In-person + AI
  Smart offices, AI-augmented
  staff. Physical presence is
  the moat, AI is the lever.
> Every cell is named. The axes carry the range; the coral quadrant carries the commitment.
```
~~~

<!-- enum: quadrant-consultant | min: 4 | max: 4 | gallery: 10a -->

## Radar

Três a cinco séries comparadas em três a cinco critérios numa escala só, de 0 a um teto comum — uma matriz de capacidades, a avaliação de produtos ou de backends, o scorecard de times. Onde uma tabela de comparação fica sem largura, o radar mostra a forma de cada opção de uma vez. `axes: Velocidade, Custo, Qualidade` são os eixos, em sentido horário a partir do de cima; cada série é uma linha `- Nome · detalhe · 4,3,5`, um valor por eixo na ordem dos eixos, e `{focal}` destaca uma, no máximo uma, na cor de acento, com um ponto em cada vértice — só ela, para o gráfico continuar legível com cinco séries. As outras vestem a paleta de séries na ordem do fence e são desenhadas da menor área para a maior, a destacada por último. Cinco anéis marcam 20, 40, 60, 80 e 100 % da escala (`rings: 4` muda a contagem), que está escrita uma vez só, no primeiro eixo; `max: 10` fixa o teto (sem ele, o menor de 1, 5, 10 ou 100 que cabe os valores). A grade começa em zero por regra (um anel interno começando em 5 inventa diferenças), e todos os eixos precisam estar na mesma escala normalizada. `legend: 40, 220, 344, 424, 608` é o x de cada entrada da legenda e da nota; `> nota` vira a nota em itálico no fim dela. Os pinos da legenda são opcionais: sem eles cada entrada anda o seu texto mais 40 px — o exemplo da galeria espaça à mão, e o fence abaixo o reproduz com pinos. Duas séries pedem barras ou uma tabela; mais de cinco, dois radares.

```@diagram type:radar
title: Storage backends · Capability radar
axes: Small-file handling, Large-object reads, Write throughput, Operational simplicity, Iceberg integration
max: 10
legend: 40, 220, 344, 424, 608
- MinIO · recommended · 9,8,9,9,9 {focal}
- Amazon S3 · 6,10,9,5,8
- Ceph · 7,7,7,4,6
- Google Cloud Storage · 6,9,8,6,7
> One coral. Position is the signal — color reserved for the recommended option.
```

~~~text
```@diagram type:radar
title: Storage backends · Capability radar
axes: Small-file handling, Large-object reads, Write throughput, Operational simplicity, Iceberg integration
max: 10
legend: 40, 220, 344, 424, 608
- MinIO · recommended · 9,8,9,9,9 {focal}
- Amazon S3 · 6,10,9,5,8
- Ceph · 7,7,7,4,6
- Google Cloud Storage · 6,9,8,6,7
> One coral. Position is the signal — color reserved for the recommended option.
```
~~~

## Modelo de dados (ER)

Entidades e a cardinalidade entre elas — um modelo conceitual ou lógico, os recursos de uma API, um domínio. Cada entidade é uma caixa de duas partes: a faixa de cima com a etiqueta (`ENTITY`, `ENTITY · AGGREGATE ROOT` na focal, `JOIN` numa tabela de junção; `{tag:TEXTO}` troca) e o nome; o corpo com um campo por linha. Uma entidade é uma linha `- Nome px:x,y LxA {focal|join}` — `px:x,y LxA` coloca a caixa onde você quer (múltiplos de 4; a altura é opcional: 40 + 20 por campo + 20); sem `px`, as entidades ficam numa fila a partir de 40,80, 200 de largura e 40 de folga, todas de um jeito ou de outro — e os campos vêm indentados dois espaços abaixo dela, `- nome · tipo {pk}` (vira `# nome`) ou `{fk}` (vira `→ nome`); o tipo é texto livre, `text · unique` inclusive. Uma relação é uma linha na grafia do mermaid, `Author ||--o{ Article WRITES` (`||` um, `|o`/`o|` zero ou um, `}|`/`|{` `1..*`, `}o`/`o{` N; `1`, `N`, `0..1` e `1..*` por extenso também valem; `..` no lugar de `--` tracejada; o rótulo depois da segunda entidade ou após `:`), ou `Author -> Article WRITES`, que é o mesmo que `||--o{`. A página traça a relação em ângulo reto pelos lados que se encaram: uma reta no centro que a outra caixa alcança, senão um Z pelo meio do vão (cantos de 8 px), e põe a cardinalidade de cada ponta numa máscara de papel a 6 px da borda (4 numa linha vertical) e o rótulo numa máscara de 56 × 14, 20 px acima do trecho. Onde a mão do autor decide — a galeria decide —, `{from:320 to:328}` fixa a porta de cada ponta (um lado, `top|bottom|left|right`, uma coordenada em múltiplos de 4, ou `lado:N`), `{via:710}` o corredor do Z (duas portas no mesmo lado fazem um U, `via:` a corrida de fora, 40 px por padrão) e `{label:716}` o centro do rótulo. `size: 1000x480` fixa a moldura (padrão: o conteúdo mais 20 à direita, a legenda 76 abaixo da sua linha). A legenda lista o que o modelo usa, nas seis colunas do exemplo: raiz do agregado, entidade, tabela de junção, `#` chave primária, `→` chave estrangeira, `1 / N` cardinalidade. Orçamento: 2 a 8 entidades, até 12 relações, uma focal. `{step:N}` numa entidade ou relação marca o passo do movimento; uma linha `> nota` vira a frase em itálico da legenda. `{card-from:X,Y card-to:X,Y}` move a máscara da cardinalidade de uma ponta para X,Y (o canto de cima à esquerda, em múltiplos de 2). Todos esses pinos são opcionais: sem eles a regra decide — a porta no centro que a outra caixa alcança, o corredor no meio do vão, o rótulo no meio do trecho, a máscara a 6 px da borda (4 na vertical). O exemplo abaixo é o da galeria (07), reproduzido número por número: os pinos marcam onde a mão do autor saiu da regra (a saída em 320, a chegada no centro de ArticleTag, o rótulo em 716 e três máscaras de cardinalidade).

```@diagram type:er
title: Content platform · data model
- Author px:60,160 200x160
  - id · uuid {pk}
  - handle · text
  - name · text
  - bio · text
  - site_url · text
- Article px:400,120 240x240 {focal}
  - id · uuid {pk}
  - title · text
  - slug · text · unique
  - body_mdx · text
  - published_at · timestamp
  - author_id · uuid {fk}
  - status · enum
  - og_image · text · url
- Tag px:780,120 200x128
  - id · uuid {pk}
  - slug · text · unique
  - name · text
  - description · text
- ArticleTag px:780,280 200x96 {join}
  - article_id · uuid {fk}
  - tag_id · uuid {fk}
Author ||--o{ Article WRITES
Article ||--o{ ArticleTag TAGGED {from:320 to:328 label:716 card-from:646,316 card-to:760,324}
Tag ||--o{ ArticleTag {card-to:872,268}
```

~~~text
```@diagram type:er
title: Content platform · data model
- Author px:60,160 200x160
  - id · uuid {pk}
  - handle · text
  - name · text
  - bio · text
  - site_url · text
- Article px:400,120 240x240 {focal}
  - id · uuid {pk}
  - title · text
  - slug · text · unique
  - body_mdx · text
  - published_at · timestamp
  - author_id · uuid {fk}
  - status · enum
  - og_image · text · url
- Tag px:780,120 200x128
  - id · uuid {pk}
  - slug · text · unique
  - name · text
  - description · text
- ArticleTag px:780,280 200x96 {join}
  - article_id · uuid {fk}
  - tag_id · uuid {fk}
Author ||--o{ Article WRITES
Article ||--o{ ArticleTag TAGGED {from:320 to:328 label:716 card-from:646,316 card-to:760,324}
Tag ||--o{ ArticleTag {card-to:872,268}
```
~~~

## Diagrama de classes (UML)

A estrutura estática de um modelo de objetos: classes, o que cada uma tem, de quem herda e de quem só depende — quando o ponto são as operações e o vocabulário tipado das setas; se a história é entidades e cardinalidade, use o modelo ER. Cada classe é uma caixa de até três compartimentos separados por linhas finas: o nome (centrado; `{interface}` escreve `«interface»` acima dele, `{abstract}` o põe em itálico), os atributos e as operações, cada membro uma linha só, `- + authorize(amount: Money): AuthResult` — o parêntese faz dele uma operação (`{attr}`/`{op}` decidem por cima); um compartimento vazio não aparece; mais de cinco membros mostram quatro e uma linha `…`. Uma classe é uma linha `- Nome px:x,y LxA {interface abstract focal}` — `px:x,y LxA` coloca a caixa (múltiplos de 4; a altura é opcional: 40 + 20 por membro + 20 por compartimento); sem `px`, uma fila a partir de 40,80, 200 de largura — e os membros vêm indentados dois espaços abaixo. A focal é a classe implementada ou estendida (faixa e traço na cor de acento); as heranças e realizações que chegam nela são o segundo acento. Uma relação é uma linha na grafia do mermaid: `Card ..|> PaymentMethod` realização (ou `PaymentMethod <|.. Card`), `Card --|> Base` herança (`<|--`), `Order *-- OrderLine` composição com o dono primeiro (`--*`), `Order o-- Customer` agregação (`--o`), `Order --> Customer` associação com a seta na segunda (`<--`; `--` sem seta), `PaymentService ..> PaymentMethod USES` dependência (`<..`); multiplicidades entre aspas ao lado de cada classe, `Order "1" *-- "1..*" OrderLine`; o rótulo depois da segunda classe ou após `:`. A ponta diz o tipo: triângulo vazado na classe-mãe, losango cheio (composição) ou vazado (agregação) no dono, seta aberta no alvo de uma associação ou dependência; realização tracejada 5,4, dependência 4,3. A página traça cada relação em ângulo reto pelos lados que se encaram — uma reta no centro que a outra caixa alcança, senão um Z pelo meio do vão, cantos de 8 px — e põe as multiplicidades em máscaras de papel a 8 px da borda (28 depois de um losango) e o rótulo 20 px acima do trecho. Onde a mão do autor decide, `{from:bottom to:bottom}` fixa as portas (um lado, uma coordenada em múltiplos de 4, ou `lado:N`; duas portas no mesmo lado fazem um U, 40 px para fora, `via:` muda a corrida), `{via:N}` o corredor do Z e `{label:N}` o centro do rótulo. `size: 980x664` fixa a moldura (padrão: o conteúdo mais 20 à direita, a legenda 60 abaixo da sua linha). A legenda mostra sempre as seis relações — é a referência completa do vocabulário. Orçamento: 2 a 7 classes (4–5 é o tamanho normal), até 8 relações, 5 membros por compartimento, uma focal. `{step:N}` numa classe ou relação marca o passo do movimento; `> nota` vira a frase em itálico da legenda. `{card-from:X,Y card-to:X,Y}` move a máscara da multiplicidade de uma ponta para X,Y (o canto de cima à esquerda, em múltiplos de 2). Todos esses pinos são opcionais: sem eles a regra decide — a porta no centro que a outra caixa alcança, o corredor no meio do vão, o rótulo no meio do trecho, a máscara a 8 px da borda. O exemplo abaixo é o da galeria (42), reproduzido número por número: `size:` fixa a moldura, e os pinos marcam onde a mão do autor saiu da regra (o rótulo USES em 368, a associação dando a volta por baixo, uma máscara de multiplicidade).

```@diagram type:uml-class
title: Payments domain · UML class diagram
size: 980x664
- PaymentMethod px:420,40 360x100 {interface focal}
  - + authorize(amount: Money): AuthResult
  - + capture(ref: String): void
- Card px:380,240 200x120
  - - number: String
  - - expiry: Date
  - - cvv: String
- BankTransfer px:660,240 200x100
  - - iban: String
  - - accountHolder: String
- PaymentService px:40,60 280x80
  - + charge(order: Order): Receipt
- Order px:60,420 200x120
  - - id: String
  - - placedAt: Date
  - - total: Money
- OrderLine px:380,420 200x120
  - - sku: String
  - - qty: Int
  - - price: Money
- Customer px:660,420 200x120
  - - id: String
  - - name: String
  - - email: String
Card ..|> PaymentMethod
BankTransfer ..|> PaymentMethod
PaymentService ..> PaymentMethod USES {label:368}
Order "1" *-- "1..*" OrderLine
Order "0..*" --> "1" Customer {from:bottom to:bottom card-from:164,548}
```

~~~text
```@diagram type:uml-class
title: Payments domain · UML class diagram
size: 980x664
- PaymentMethod px:420,40 360x100 {interface focal}
  - + authorize(amount: Money): AuthResult
  - + capture(ref: String): void
- Card px:380,240 200x120
  - - number: String
  - - expiry: Date
  - - cvv: String
- BankTransfer px:660,240 200x100
  - - iban: String
  - - accountHolder: String
- PaymentService px:40,60 280x80
  - + charge(order: Order): Receipt
- Order px:60,420 200x120
  - - id: String
  - - placedAt: Date
  - - total: Money
- OrderLine px:380,420 200x120
  - - sku: String
  - - qty: Int
  - - price: Money
- Customer px:660,420 200x120
  - - id: String
  - - name: String
  - - email: String
Card ..|> PaymentMethod
BankTransfer ..|> PaymentMethod
PaymentService ..> PaymentMethod USES {label:368}
Order "1" *-- "1..*" OrderLine
Order "0..*" --> "1" Customer {from:bottom to:bottom card-from:164,548}
```
~~~

## Venn

Dois ou três conjuntos que se sobrepõem — onde A encontra B, o "ponto doce" de desejável × viável × factível. Cada conjunto é uma linha `- Nome · subtítulo`, um círculo de raio 140 com um fio de 1 px no seu tom (tinta, apagado, suave, nessa ordem) sobre uma tinta de 4–5 % que se soma onde os círculos se cruzam: com três, um em cima e dois embaixo, um raio mais abaixo e 72 px para cada lado do centro; com dois, lado a lado na linha do meio. O nome fica dentro do lóbulo que é só daquele conjunto, a 0,6 raio do centro, para fora, com o subtítulo em mono maiúsculo 16 px abaixo; `{label:340,386}` fixa a linha de base do nome onde a referência colocou à mão, e `{x:500 y:180 r:140}` fixa o círculo (centro e raio na grade de 4 px). Uma linha `A & B: Nome · subtítulo` (ou `A & B & C:`) rotula a interseção, centrada na lente — o centroide dos membros ou, havendo um terceiro conjunto, o meio da lente na reta que vem dele; `{focal}` em uma região, no máximo uma, pinta a interseção em tinta sólida (dois recortes encadeados, como a referência) e escreve o rótulo em papel. Sem nenhum ajuste a regra desenha a mesma figura da galeria, menos as duas etiquetas de baixo, que a mão da referência afastou um pouco mais. Quatro conjuntos são recusados: uma matriz diz melhor.

```@diagram type:venn
title: Good design · Desirable × Feasible × Viable
- Desirable · People want it
- Feasible · We can build it {label:340,386}
- Viable · Business sustains {label:660,386}
Desirable & Feasible & Viable: Shippable · The sweet spot {focal}
```

~~~text
```@diagram type:venn
title: Good design · Desirable × Feasible × Viable
- Desirable · People want it
- Feasible · We can build it {label:340,386}
- Viable · Business sustains {label:660,386}
Desirable & Feasible & Viable: Shippable · The sweet spot {focal}
```
~~~

## Treemap

Partes de um todo em que o tamanho relativo é a história — uso de disco, orçamento, fatia de mercado, população: a área de cada célula é a sua parte. Cada célula é uma linha `- Nome · valor` (`4.78B`, `2,140`, `0.5k` são lidos como número); `{focal}` destaca uma, no máximo uma, em acento, e as outras seguem uma rampa de tinta do maior para o menor (contraste mais forte é maior, o que sobrevive à impressão em cinza). A área é de 40→956 × 40→420 numa folha de 1000 × 500; as células são "squarificadas" — da maior para a menor, cada fileira encostada no lado mais curto do que sobra, fechada quando a próxima célula pioraria a pior proporção —, com as bordas na grade de 4 px e uma calha de 4 px entre vizinhas, cobrada da maior das duas, para a célula mais fina não perder a área. O nome fica 16 px para dentro, com valor e porcentagem em mono embaixo; uma célula com menos de 48 de largura ou 32 de altura não leva texto, só um disco de informação, e é nomeada na legenda. `total: 8.09B` é o todo quando as partes não somam; `whole: world` é do que a porcentagem é ("59% of world"); `others: Other continents` nomeia a chave das células comuns; `legend: 40, 240, 516` fixa o x de cada chave da legenda; a linha `> fonte` é a fonte, em maiúsculas, à direita de LEGEND. Onde a referência cortou à mão, `{share:59.04 x:40 y:40 w:532 h:380}` (ou `px:940,296,16x124`) fixa a porcentagem e o retângulo da célula — todas ou nenhuma; sem os ajustes a regra decide o corte sozinha, cada célula a poucos por cento da sua parte verdadeira. De 4 a 8 células: além disso, o rabo vira uma célula "Other" com nome.

```@diagram type:treemap
title: World population · six continents
whole: world
others: Other continents
legend: 40, 240, 516
- Asia · 4.78B {focal share:59.04 x:40 y:40 w:532 h:380}
- Africa · 1.48B {share:18.29 x:576 y:40 w:252 h:252}
- Europe · 0.75B {share:9.23 x:832 y:40 w:124 h:252}
- North America · 0.61B {share:7.52 x:576 y:296 w:208 h:124}
- South America · 0.43B {share:5.35 x:788 y:296 w:148 h:124}
- Oceania · 0.05B {share:0.56 x:940 y:296 w:16 h:124}
> Area = population · Our World in Data continents (UN WPP) · mid-2023 · 8.09B total · parts rounded, may not sum
```

~~~text
```@diagram type:treemap
title: World population · six continents
whole: world
others: Other continents
legend: 40, 240, 516
- Asia · 4.78B {focal share:59.04 x:40 y:40 w:532 h:380}
- Africa · 1.48B {share:18.29 x:576 y:40 w:252 h:252}
- Europe · 0.75B {share:9.23 x:832 y:40 w:124 h:252}
- North America · 0.61B {share:7.52 x:576 y:296 w:208 h:124}
- South America · 0.43B {share:5.35 x:788 y:296 w:148 h:124}
- Oceania · 0.05B {share:0.56 x:940 y:296 w:16 h:124}
> Area = population · Our World in Data continents (UN WPP) · mid-2023 · 8.09B total · parts rounded, may not sum
```
~~~

### Marimekko

A variante de duas vias (`layout: marimekko`, ou simplesmente itens aninhados): a largura de cada coluna é a parte da categoria no todo, a altura de cada segmento é a parte da série dentro da coluna, e a área é a parte conjunta — leia na horizontal a mistura de categorias, na vertical a de séries, e pela área quem domina a tabela. Cada coluna é um item (`- web`) e cada série um item recuado dois espaços dentro dela (`  - Linux · 2140`); as colunas dividem 900 px mais quatro calhas de 4 px, a borda direita de cada uma na grade, arredondada para baixo; toda coluna tem os 380 px de altura e os segmentos a preenchem de cima a baixo sem calha, numa só ordem de séries (a do total geral, a maior em cima; `series: Linux, macOS, Windows` escolhe outra), cada divisa no pixel inteiro mais próximo. Uma série ausente de uma coluna é omitida, nunca desenhada com altura zero. O preenchimento é por série (0,16 / 0,10 / 0,05 de tinta para três); `{focal}` num segmento o pinta em acento e acrescenta de quem é a parte ("83% of mobile"); `unit: min` é a unidade dos valores; `{w:280}` numa coluna e `{h:259}` num segmento fixam uma medida onde a mão da referência decidiu; sem ajustes a regra reproduz a galeria. Legendas sob cada coluna (`web · 31%`) dizem a largura em número, e uma coluna com menos de 48 px leva o disco e é nomeada na legenda. De 3 a 8 colunas e de 2 a 5 séries.

```@diagram type:treemap
title: One pipeline on one runner is a fifth of all CI time
layout: marimekko
unit: min
legend: 40, 248, 320, 396, 500
- web
  - Linux · 2140
  - macOS · 380
  - Windows · 620
- api
  - Linux · 2460
  - Windows · 340
- mobile
  - Linux · 420
  - macOS · 1980 {focal}
- infra
  - Linux · 1120
  - Windows · 280
- docs
  - Linux · 260
> Width = pipeline share · Height = runner share within pipeline · Area = share of all CI minutes · 30 days · 10,000 min · Illustrative figures
```

~~~text
```@diagram type:treemap
title: One pipeline on one runner is a fifth of all CI time
layout: marimekko
unit: min
legend: 40, 248, 320, 396, 500
- web
  - Linux · 2140
  - macOS · 380
  - Windows · 620
- api
  - Linux · 2460
  - Windows · 340
- mobile
  - Linux · 420
  - macOS · 1980 {focal}
- infra
  - Linux · 1120
  - Windows · 280
- docs
  - Linux · 260
> Width = pipeline share · Height = runner share within pipeline · Area = share of all CI minutes · 30 days · 10,000 min · Illustrative figures
```
~~~

## Espinha de peixe (Ishikawa)

A análise de causa raiz de um post-mortem: um efeito observado na cabeça, à direita, e as causas investigadas agrupadas por categoria em espinhas a 60° da linha central, alternando acima e abaixo — o leitor vê o que foi investigado, não só a conclusão. `effect: Checkout p99 latency | 4x for 90 minutes` é o efeito (de uma a três linhas separadas por `|`, o que foi visto, nunca o remédio); cada `# Categoria` abre uma espinha, na ordem a partir da cabeça, e cada `- causa` embaixo dela é um traço curto com o rótulo (de uma a três por espinha, dezoito no total); `{focal}` numa causa (ou na categoria) marca a causa raiz confirmada, e só ela e o efeito levam a cor de acento. A geometria é a da referência: espinhas 160 px uma da outra, cada uma até (−96, ∓168) do ponto de encaixe, a etiqueta da categoria numa caixa de 120 × 28 na ponta, as causas a m/6 da espinha (3 para uma; 2 e 4 para duas; 1, 3 e 5 para três). Cinco categorias cabem na tela padrão; a sexta pede `head: 1360` (a referência alarga a cabeça e a tela juntas), e uma categoria sem causa é recusada (uma espinha vazia é um lugar reservado, não um achado). `legend: bone=…, root=…, cause=…, effect=…` são as palavras da legenda e `legend: 40, 260, 480, 700` o x de cada entrada e da nota; `> nota` vira a nota em itálico no fim. Os pinos são opcionais: `{x:N}` numa categoria move o ponto de encaixe e `{m:N}` numa causa escolhe o sexto da espinha — sem eles vale a fórmula, e o exemplo da galeria segue a fórmula número por número, então o fence abaixo não precisa de nenhum.

```@diagram type:fishbone
title: Checkout p99 latency · Root-cause fishbone
effect: Checkout p99 latency | 4x for 90 minutes
# Deploy
- canary skipped
- config drift
# Data
- index missing on orders.created_at {focal}
- table 3x forecast
# Runtime
- connection pool cap 20
- GC pauses
# Observability
- no p99 alert
- dashboard sampled at 5m
# People
- on-call handover mid-incident
```

~~~text
```@diagram type:fishbone
title: Checkout p99 latency · Root-cause fishbone
effect: Checkout p99 latency | 4x for 90 minutes
# Deploy
- canary skipped
- config drift
# Data
- index missing on orders.created_at {focal}
- table 3x forecast
# Runtime
- connection pool cap 20
- GC pauses
# Observability
- no p99 alert
- dashboard sampled at 5m
# People
- on-call handover mid-incident
```
~~~

## Mapa de Wardley

Os componentes de uma cadeia de valor posicionados por quão visíveis são ao usuário (para cima) e quão evoluídos estão (para a direita, nas quatro faixas de gênese a commodity), ligados por quem depende de quem — um artefato de estratégia, não de arquitetura: diz o que construir, o que comprar e o que está prestes a se mover, nada sobre como os componentes conversam. Cada item é `- Nome · detalhe 0,62,0,8`: evolução e visibilidade de 0 a 1, a evolução pela largura do gráfico (800 px) e a visibilidade pela altura (280 px), o nome 12 px acima do ponto; `{anchor:start}` ou `{anchor:end}` põe o nome ao lado do ponto, `{label:X,Y}` onde quiser, `{px:X,Y}` crava o ponto num pixel do grid de 4 px. `A -> B` é uma dependência (A depende de B), uma reta fina sem seta — a posição é o dado, por isso não há cotovelos; `A =>` marca o componente que está evoluindo, com uma seta tracejada na cor de acento até 16 px antes da faixa seguinte (`A => 0,8` até aquela evolução); no máximo dois se movem, e só eles levam a cor de acento. `x: Genesis | Custom-built | Product | Commodity` são as quatro palavras do eixo horizontal e `top: Visible to | the user` / `bottom: Invisible` as do eixo vertical, empilhadas por `|` (todas opcionais, estes são os padrões); `legend: component=…, link=…, moving=…` são as palavras da legenda e `legend: 48, 220, 404, 560` o x de cada entrada e da nota; `> nota` vira a nota em itálico no fim. Os pinos são opcionais: sem eles, a posição vem dos valores pela fórmula e a legenda ocupa as quatro colunas da galeria — o exemplo da galeria posiciona à mão, então o fence abaixo o reproduz com pinos. Um componente sem nenhuma dependência é recusado (não está na cadeia), assim como uma seta para a esquerda (a evolução só anda para commodity).

```@diagram type:wardley
title: AI assistant product · Wardley map
- Answer in the flow of work {px:420,92}
- Chat UI {px:620,124}
- Agent orchestration {px:420,156}
- Eval harness {px:220,188}
- Vector store {px:620,220}
- LLM API {px:680,252}
- GPU compute {px:820,284}
- Object storage {px:820,316 anchor:start}
Answer in the flow of work -> Chat UI
Chat UI -> Agent orchestration
Agent orchestration -> Eval harness
Agent orchestration -> Vector store
Agent orchestration -> LLM API
Vector store -> Object storage
LLM API -> GPU compute
Eval harness -> LLM API
Agent orchestration =>
> One coral. Position along evolution is the signal — the arrow marks what's about to commoditise.
```

~~~text
```@diagram type:wardley
title: AI assistant product · Wardley map
- Answer in the flow of work {px:420,92}
- Chat UI {px:620,124}
- Agent orchestration {px:420,156}
- Eval harness {px:220,188}
- Vector store {px:620,220}
- LLM API {px:680,252}
- GPU compute {px:820,284}
- Object storage {px:820,316 anchor:start}
Answer in the flow of work -> Chat UI
Chat UI -> Agent orchestration
Agent orchestration -> Eval harness
Agent orchestration -> Vector store
Agent orchestration -> LLM API
Vector store -> Object storage
LLM API -> GPU compute
Eval harness -> LLM API
Agent orchestration =>
> One coral. Position along evolution is the signal — the arrow marks what's about to commoditise.
```
~~~

## Kanban

Um censo do trabalho em andamento por estado, sem nenhuma seta: o que está na fila, o que anda, o que travou e onde o limite de WIP estourou (se o fluxo precisa aparecer, use `type:swimlane` ou `type:process`). Até cinco colunas de 240 px com calhas de 32, cada uma com um filete de tinta no fundo, o nome na faixa de cabeçalho e, à direita, a etiqueta de WIP (um retângulo de 40 × 16, nunca uma pílula): `n/limite` numa coluna de processo, `n` só na fila de entrada e na coluna final, que não têm limite; a coluna acima do limite pinta a etiqueta no acento. Os cartões têm 208 × 56 num passo de 68, o título em cima e `TICKET · dono` em mono embaixo, em quatro estados: padrão (branco), `{blocked}` (tinta de acento, traço tracejado `4,4` e uma barra de 4 px na borda esquerda), `{waiting}` (um externo, à espera: tinta a 2 %, traço a 20 % tracejado `4,3`) e `{done}` (tinta a 5 %, traço apagado). O primeiro grupo sem itens é a cabeça (`# Título`, `legend:`); cada `---` começa uma coluna, nomeada pelo seu título com o limite no detalhe, `# In progress · WIP 3` (ou `{wip:3}`; `{count:17}` sobrescreve a contagem quando a fila foi agregada num cartão "+14 more"; `{done}` no título faz os cartões dessa coluna concluídos); cada item é um cartão, `- Postgres 16 upgrade · AVA-118 · sam {blocked tag:BUG}`, com `tag:` uma etiqueta pequena no canto e `{focal}` o único cartão em destaque (tinta e traço do acento). A legenda lista só os estados presentes no quadro, mais "Over WIP limit" quando alguma coluna estourou; `legend: 32, 232` fixa o x de cada item e `legend: none` a dispensa. Os pinos são opcionais e a galeria não precisa de nenhum: sem eles, as colunas têm a altura da mais cheia (`{h:N}` no título fixa a altura, `{y:N}` num cartão fixa a linha dele e os seguintes continuam dali) e a legenda anda 200 px por item. Orçamento: 2 a 5 colunas, até 4 cartões por coluna e 12 no total, um cartão em destaque. Com `motion:step`, os cartões entram um a um, coluna por coluna.

```@diagram type:kanban
# Platform team board
---
# Backlog
- API rate limiting · AVA-201 · priya
- Terraform module cleanup · AVA-205 · leo
- Onboarding docs refresh · AVA-209 · maya
---
# In progress · WIP 3
- Postgres 16 upgrade · AVA-118 · sam {blocked}
- K8s node pool migration · AVA-142 · priya
- Auth token rotation · AVA-150 · leo
- Observability dashboards · AVA-161 · dara
---
# Review · WIP 3
- Feature flag cleanup · AVA-176 · nadia
- Vendor SSO integration · AVA-183 · sam {waiting}
---
# Done {done}
- Log retention policy · AVA-090 · leo
- CI cache warmup · AVA-097 · maya
```

~~~text
```@diagram type:kanban
# Platform team board
---
# Backlog
- API rate limiting · AVA-201 · priya
- Terraform module cleanup · AVA-205 · leo
- Onboarding docs refresh · AVA-209 · maya
---
# In progress · WIP 3
- Postgres 16 upgrade · AVA-118 · sam {blocked}
- K8s node pool migration · AVA-142 · priya
- Auth token rotation · AVA-150 · leo
- Observability dashboards · AVA-161 · dara
---
# Review · WIP 3
- Feature flag cleanup · AVA-176 · nadia
- Vendor SSO integration · AVA-183 · sam {waiting}
---
# Done {done}
- Log retention policy · AVA-090 · leo
- CI cache warmup · AVA-097 · maya
```
~~~

## Jornada do usuário

O que uma pessoa faz ao longo das etapas de uma experiência e como se sente em cada uma: a curva de sentimento é o que sustenta o tipo (se toda etapa se sente igual, é um `type:process` ou `type:timeline`; se o que importa é o palco e os bastidores, um `type:service-blueprint`). Até seis etapas em colunas de 200 px com calhas de 24, cada uma com o `STAGE N` sobre o nome; abaixo, a faixa de sentimento de 160 px com três linhas de referência (HIGH, NEUTRAL, LOW, 80 px entre elas) e a curva, uma polilinha apagada passando por um ponto por etapa, cada ponto no seu nível — cinco níveis ordinais, nunca uma escala numérica no desenho; os dois intermediários ficam entre as linhas — com o ponto do vale e o segmento que chega nele no acento; depois as linhas `ACTIONS` (o que a pessoa faz) e `TOUCHPOINTS` (a superfície: e-mail, app, docs), e uma terceira opcional (uma métrica, um dono) quando alguma etapa tem um terceiro campo; sob a ação do vale, até dois marcadores de dor (184 × 16, acento a 50 % tracejado `3,3`); e a legenda com a curva, o vale e o marcador. O primeiro grupo sem itens é a cabeça: `# Título`, `persona: New trial user` (uma só; entra na descrição acessível), `rows: Ações, Pontos de contato, Dono` (os rótulos das linhas), `legend:`. Cada `---` começa uma etapa, nomeada pelo seu título, com um item `- Ação · ponto de contato · terceiro campo {mood:low}`: o humor é um número de 1 (LOW) a 5 (HIGH) ou um nome (`low`, `med-low`, `neutral`, `med-high`, `high`, também em português); sem ele, neutro. O vale é a etapa de humor mais baixo (a primeira, num empate), ou a etapa marcada `{pain}`, ou a que tem linhas `pain: texto` — e só ela carrega os marcadores. Os pinos são opcionais: `{y:N}` num item fixa o ponto da curva fora da sua linha e `legend: 40, 220, 384` o x de cada item da legenda (sem eles, o ponto fica na linha do seu nível e a legenda anda 180 px por item; `legend: none` a dispensa). Orçamento: 2 a 6 etapas, 3 linhas, 2 marcadores de dor, uma persona por mapa. Com `motion:step`, as etapas entram uma a uma, com o seu ponto, a sua ação e os seus marcadores.

```@diagram type:journey
# Trial to paid: the first week
persona: New trial user
legend: 40, 220, 384
---
# Sign up
- Create workspace · signup form {mood:high}
---
# First run
- Import first dataset · onboarding wizard {mood:neutral}
---
# Invite team
- Add 3 teammates · email invite {mood:high}
---
# Hit the limit
- Export blocked mid-report · in-app modal {mood:low}
pain: No warning at 80%
pain: Pricing page is 3 clicks away
---
# Upgrade
- Pick annual plan · billing page {mood:neutral}
```

~~~text
```@diagram type:journey
# Trial to paid: the first week
persona: New trial user
legend: 40, 220, 384
---
# Sign up
- Create workspace · signup form {mood:high}
---
# First run
- Import first dataset · onboarding wizard {mood:neutral}
---
# Invite team
- Add 3 teammates · email invite {mood:high}
---
# Hit the limit
- Export blocked mid-report · in-app modal {mood:low}
pain: No warning at 80%
pain: Pricing page is 3 clicks away
---
# Upgrade
- Pick annual plan · billing page {mood:neutral}
```
~~~

## Esquema de banco (DB schema)

O esquema físico: tabelas de verdade, tipos SQL, constraints, índices e chaves estrangeiras que ligam uma coluna a outra coluna — o DDL legível, para uma migration, a revisão de um banco, qualquer conversa em que o `ON DELETE` é o assunto (o modelo conceitual, com caixas ligadas a caixas e cardinalidades, é o `type:er`). Cada tabela é uma linha `- schema.tabela px:x,y LxA` — `schema.tabela` põe a tabela no grupo do schema (`public`, ou sem schema, é o padrão e não tem grupo); `px:x,y LxA` coloca a caixa onde você quer (múltiplos de 4; largura e altura opcionais: 240, e 28 + 24 por linha + 20 + 16 por índice); sem `px`, as tabelas ficam numa fila a partir de 40,40, 360 em 360, todas de um jeito ou de outro — e as colunas vêm indentadas dois espaços abaixo dela, `- nome · tipo SQL {pk fk:tabela.coluna unique not-null}`: cada tag vira um chip (`PK`, `FK`, `UQ`, `NN`; `uq` e `nn` também valem), e `fk:tabela.coluna` traça a chave da linha dessa coluna até a linha da coluna referenciada, com `cascade`, `restrict` ou `set-null` como rótulo `ON DELETE …` da chave (sem a ação, a chave sai sem rótulo). Uma linha `- + N more columns` é a linha de transbordo, escrita como o diagrama a mostra; mais de 8 colunas viram 7 e essa linha. Uma linha `index: nome_do_indice` (texto livre, uma por índice) abre o compartimento `INDEXES` da tabela. Uma chave também pode ser uma linha à parte, `orders.customer_id -> customers.id restrict`, que marca a coluna como `FK` e aceita os mesmos pinos. A página traça a chave do lado da tabela que encara a outra (duas tabelas empilhadas saem ambas pela direita, num U 28 px para fora), no centro da linha da coluna; linhas alinhadas fazem uma reta, senão um Z pelo meio do vão (cantos de 8 px); duas chaves na mesma linha de uma tabela abrem ±8 em volta do centro; onde um trecho vertical cruza o horizontal de outra chave, ele salta (meia-volta de 8 px). O rótulo fica numa máscara de papel de 12 px e 4 + 6 por caractere: 10 px acima do trecho de cima num traçado horizontal, ao lado do corredor num vertical. A única chave `cascade` é o par focal — a chave e o rótulo em destaque, e a faixa da tabela que ela apaga (a tabela da própria chave) em tinta de destaque; duas chaves `cascade` não têm foco e são recusadas. Onde a mão do autor decide — a galeria decide —, `{via:716}` fixa o corredor do Z ou do U, `{from:right to:right}` o lado de cada ponta e `{label:X,Y}` ou `{label:X,Y,L}` o canto de cima à esquerda da máscara do rótulo (múltiplos de 2) e a sua largura; `size: 1080x560` fixa a moldura (padrão: o conteúdo mais 40 à direita, a legenda 32 abaixo da tabela mais baixa, 16 abaixo de um grupo, e 60 de rodapé). Todos esses pinos são opcionais: sem eles a regra decide — o corredor no meio do vão, o U a 28, o rótulo centrado sobre o traçado ou ao lado do corredor, a máscara pela conta de caracteres. A legenda lista o que o esquema usa, nas colunas do exemplo: tabela, grupo de schema, chip de constraint, chave estrangeira (coluna a coluna), apagamento destrutivo (CASCADE). Orçamento: 1 a 5 tabelas, 8 linhas por tabela, 6 chaves, uma `cascade`. `{step:N}` numa tabela ou numa chave marca o passo do movimento; uma linha `> nota` vira a frase em itálico da legenda. O exemplo abaixo é o da galeria (44), reproduzido número por número: os pinos marcam onde a mão do autor saiu da regra (os corredores 716 e 692 no vão cujo meio é 700, e três máscaras de rótulo — a do CASCADE com 88 de largura, onde a conta daria 106).

```@diagram type:db-schema
title: Commerce schema · public + billing
size: 1080x560
- public.customers px:40,80
  - id · uuid {pk}
  - email · text {unique not-null}
  - created_at · timestamptz {not-null}
- public.orders px:400,40
  - id · uuid {pk}
  - customer_id · uuid {fk:customers.id restrict not-null}
  - status · text {not-null}
  - total · numeric(12,2) {not-null}
  - placed_at · timestamptz {not-null}
  index: idx_orders_customer_id
  index: idx_orders_status
- public.order_items px:400,320
  - id · uuid {pk}
  - order_id · uuid {fk:orders.id cascade not-null label:572,274,88}
  - product_id · uuid {fk:products.id restrict not-null via:716 label:724,252}
  - qty · integer {not-null}
  - unit_price · numeric(12,2) {not-null}
- public.products px:760,40
  - id · uuid {pk}
  - sku · text {unique not-null}
  - name · text {not-null}
  - price · numeric(12,2) {not-null}
  - + 3 more columns
  index: uq_products_sku
- billing.invoices px:760,368
  - id · uuid {pk}
  - order_id · uuid {fk:orders.id restrict not-null via:692 label:644,440}
  - issued_at · timestamptz {not-null}
```

~~~text
```@diagram type:db-schema
title: Commerce schema · public + billing
size: 1080x560
- public.customers px:40,80
  - id · uuid {pk}
  - email · text {unique not-null}
  - created_at · timestamptz {not-null}
- public.orders px:400,40
  - id · uuid {pk}
  - customer_id · uuid {fk:customers.id restrict not-null}
  - status · text {not-null}
  - total · numeric(12,2) {not-null}
  - placed_at · timestamptz {not-null}
  index: idx_orders_customer_id
  index: idx_orders_status
- public.order_items px:400,320
  - id · uuid {pk}
  - order_id · uuid {fk:orders.id cascade not-null label:572,274,88}
  - product_id · uuid {fk:products.id restrict not-null via:716 label:724,252}
  - qty · integer {not-null}
  - unit_price · numeric(12,2) {not-null}
- public.products px:760,40
  - id · uuid {pk}
  - sku · text {unique not-null}
  - name · text {not-null}
  - price · numeric(12,2) {not-null}
  - + 3 more columns
  index: uq_products_sku
- billing.invoices px:760,368
  - id · uuid {pk}
  - order_id · uuid {fk:orders.id restrict not-null via:692 label:644,440}
  - issued_at · timestamptz {not-null}
```
~~~

## Movimento

`motion:step` faz os itens entrarem um a um, com os botões anterior, tocar, pausar, próximo e repetir, e pelas setas do teclado, Espaço, R, Home e End quando o foco está na figura. `motion:reveal` toca sozinho, uma vez, quando a figura aparece na tela (numa página longa, só quando o leitor chega nela), e termina com a figura completa; os botões repetem. A galeria do diagram-design usa `reveal` nas vistas explodidas e nas plantas animadas, e `step` nos exemplos de passo a passo (o paved road, o policy trace, a fila). A ordem é a da leitura, ou a que `{step:N}` disser. Sem JavaScript, na impressão, ou para quem pediu menos movimento no sistema (no Mac: Ajustes do Sistema → Acessibilidade → Tela → Reduzir movimento), a figura aparece completa e sem os botões.

```@diagram type:layers motion:step
title: Como uma página chega ao leitor
- Edge · Cloudflare, cache {tag:1}
- App web · Rails, a versão da página {tag:2 focal}
- Renderizador · markdown para HTML {tag:3}
- Banco · PostgreSQL {tag:4}
```

~~~text
```@diagram type:layers motion:step
title: Como uma página chega ao leitor
- Edge · Cloudflare, cache {tag:1}
- App web · Rails, a versão da página {tag:2 focal}
- Renderizador · markdown para HTML {tag:3}
- Banco · PostgreSQL {tag:4}
```
~~~

## Argumentos

- `type` — `layers` (o padrão), `pyramid` ou `funnel`.
- `motion` — `none` (o padrão), `step` ou `reveal`.
- `title` — o nome da figura; uma linha `# Título` no corpo faz o mesmo.
- `caption` — a legenda em itálico; uma linha `> citação` no corpo faz o mesmo.
- `desc` — a frase que um leitor de tela recebe no lugar do desenho; sem ela, sai dos itens.
- `top`, `bottom` — a direção na margem esquerda das camadas.
- `left` — o eixo girado na margem da pirâmide ou do funil.

Tags entre chaves no fim de um item: `focal`, `step:N`, `tag:L3`, `side:nota`, `value:240`. Uma linha `---` começa um novo grupo nos tipos que têm grupos.

Limites: camadas aceitam de 2 a 8 itens; pirâmide e funil, de 3 a 6. Acima disso a figura fica ilegível: divida em duas.