flows.md · documentação · Blocos
@chart#
Um gráfico desenhado de um CSV: barras, barras empilhadas, linha, área, pizza, rosca, dispersão (com bolhas), mapa de calor, cascata — ou só a tabela. O leitor aponta um valor para lê-lo e esconde uma série pela legenda.
Barras#
title: Encomendas por mês — Ateliê Exemplo
---
mês,canecas,pratos
Jul,42,18
Ago,51,22
Set,63,30
Out,58,41```@chart type:bar
title: Encomendas por mês — Ateliê Exemplo
---
mês,canecas,pratos
Jul,42,18
Ago,51,22
Set,63,30
Out,58,41
```A primeira linha do CSV dá nome às colunas; a primeira coluna é o eixo. Os argumentos vão antes do ---, um por linha, ou na linha da cerca.
Linha, com um marco#
markers: desenha uma linha tracejada num ponto do eixo, com o nome — e diz o marco em palavras embaixo do gráfico.
title: Visitas por semana
markers: S3=Loja aberta
---
semana,visitas
S1,120
S2,135
S3,310
S4,280
S5,295```@chart type:line
title: Visitas por semana
markers: S3=Loja aberta
---
semana,visitas
S1,120
S2,135
S3,310
S4,280
S5,295
```Um item em destaque#
focal: desenha um item na cor de destaque da página e deixa os outros na paleta das séries — do jeito que o diagram-design marca um elemento por figura. Pode ser uma linha (focal: S5), uma série (focal: pratos) ou, num mapa de calor, uma célula linha,coluna (focal: payments,S4). É um só: dois nomes separados por vírgula, ou um nome que não está nos dados, são recusados com a explicação. A cor nunca fica sozinha: o rótulo e o valor do item saem em negrito na cor de destaque, a legenda e a tabela marcam o item com ★ e dizem, para quem usa leitor de tela, qual está em destaque.
title: Velocidade do time · 8 sprints (pontos de história)
---
sprint,pontos
S1,72
S2,88
S3,95
S4,78
S5,110
S6,102
S7,85
S8,93```@chart type:bar focal:S5
title: Velocidade do time · 8 sprints (pontos de história)
---
sprint,pontos
S1,72
S2,88
S3,95
S4,78
S5,110
S6,102
S7,85
S8,93
```Os dados são o exemplo de barras da galeria do diagram-design (cathrynlavery/diagram-design, MIT): a Sprint 5 é o recorde, e é ela que leva a cor.
Rosca#
pie e donut leem a primeira série, uma fatia por linha.
title: De onde vêm as encomendas
---
canal,encomendas
Site,46
Feira,31
Instagram,23```@chart type:donut
title: De onde vêm as encomendas
---
canal,encomendas
Site,46
Feira,31
Instagram,23
```Dispersão#
scatter lê as duas primeiras colunas numéricas como x e y, um ponto por linha, com o nome da linha ao lado quando cabe (até 12 pontos). Os dois eixos começam em zero e levam o nome das colunas.
title: Frequência de deploy × lead time · 12 times
---
time,deploys por semana,lead time (dias)
Time A,2,20
Time B,4,18
Time C,4,16
Time D,6,14
Time E,8,12
Time F,8,10
Time G,10,8
Time H,12,6
Time I,12,10
Time J,16,4
Platform,18,3
Time L,20,2```@chart type:scatter
title: Frequência de deploy × lead time · 12 times
---
time,deploys por semana,lead time (dias)
Time A,2,20
Time B,4,18
Time C,4,16
Time D,6,14
Time E,8,12
Time F,8,10
Time G,10,8
Time H,12,6
Time I,12,10
Time J,16,4
Platform,18,3
Time L,20,2
```Bolhas#
Uma terceira coluna numérica vira o tamanho de cada bolha — pela área, não pelo raio: um serviço com seis vezes o tráfego tem seis vezes a tinta. As maiores são desenhadas primeiro, para nenhuma pequena ficar enterrada.
title: O maior risco não é o serviço mais lento
---
serviço,p95 (ms),erros (%),req/s
Gateway,85,0.5,900
Payments,260,2.8,760
Auth,140,0.9,620
Catalog,180,0.7,540
Search,320,1.1,480
Media,230,1.4,330
Recommender,420,1.6,210
Notifications,95,2.2,150
Reports,460,0.9,60```@chart type:scatter
title: O maior risco não é o serviço mais lento
---
serviço,p95 (ms),erros (%),req/s
Gateway,85,0.5,900
Payments,260,2.8,760
Auth,140,0.9,620
Catalog,180,0.7,540
Search,320,1.1,480
Media,230,1.4,330
Recommender,420,1.6,210
Notifications,95,2.2,150
Reports,460,0.9,60
```Mapa de calor#
heatmap desenha uma célula por linha e coluna. O valor dá a intensidade do preenchimento e é impresso na célula — ninguém precisa julgar um tom. Uma célula em branco fica vazia, não vira zero.
title: A semana em que payments apagou — falhas de CI (%)
---
serviço,S1,S2,S3,S4,S5,S6
auth,4,5,6,3,2,2
payments,3,4,5,47,6,4
api-gateway,2,3,4,2,1,1
billing,5,7,9,6,4,3
notifications,1,2,2,2,1,1```@chart type:heatmap
title: A semana em que payments apagou — falhas de CI (%)
---
serviço,S1,S2,S3,S4,S5,S6
auth,4,5,6,3,2,2
payments,3,4,5,47,6,4
api-gateway,2,3,4,2,1,1
billing,5,7,9,6,4,3
notifications,1,2,2,2,1,1
```Cascata#
waterfall lê uma coluna: a primeira linha é o total de partida, a última o total de chegada (deixe o valor em branco para calculá-lo) e as do meio são contribuições com sinal. Os totais ficam em tinta a partir do chão; um aumento é uma barra cheia, uma redução a mesma barra vazada; um conector leva o total acumulado de uma barra à seguinte. A legenda nomeia as três formas.
title: Ponte do orçamento de nuvem · FY25 → FY26 ($ mil/mês)
---
item,$ mil/mês
Base FY25,240
Headcount,+64
Instâncias reservadas,-38
Cargas de ML,+22
Camadas de storage,-52
Plano FY26,```@chart type:waterfall
title: Ponte do orçamento de nuvem · FY25 → FY26 ($ mil/mês)
---
item,$ mil/mês
Base FY25,240
Headcount,+64
Instâncias reservadas,-38
Cargas de ML,+22
Camadas de storage,-52
Plano FY26,
```Folha editorial#
look:editorial desenha o gráfico na folha do diagram-design em vez de na largura da página: um viewBox fixo de 1000 × 500, a área de plotagem de x 80 a 960 e de y 40 a 420, a legenda sob um fio em 462 — e a geometria de referência de cada tipo (passo e largura das barras, os conectores da cascata, a polilinha em destaque com 1,8 px e um ponto em cada vértice, os pontos r=5/r=6 da dispersão, as células de 116 × 56 do mapa de calor num só degradê de tinta). As cores e as fontes são as da página, pelos mesmos tokens do bloco @diagram, então a folha segue o tema e o esquema claro ou escuro sem redesenhar; a tabela de dados continua embaixo, e o item em destaque (focal:) leva a cor de destaque e a estrela na legenda e na tabela. Numa tela estreita a folha diminui inteira. O que a galeria coloca à mão, e nenhuma regra da referência deduz, vai em linhas de folha no corpo CSV, # chave: valor — para o look:page são comentários — ou numa etiqueta no rótulo de uma linha, Platform {x:830 y:357}: # unit: (o eixo de valores, em letras pequenas, girado), # desc: (a frase que o leitor de tela recebe), # scale: 120 by 20 (o topo e o passo do eixo; # x-scale:/# y-scale: na dispersão), # legend: A; B {x:220} (os rótulos da legenda em ordem, cada um com um x opcional), # trend: e # guides: (a linha de tendência e as notas de canto de uma dispersão), # layout: scatter|bubble|beeswarm (a forma da dispersão dita por extenso — sem ela, as colunas decidem: uma coluna numérica é um enxame, uma terceira coluna é a área das bolhas), # label-mask: 60 (a largura da máscara de papel sob o rótulo de um ponto; sem ela, 8 px por letra; uma etiqueta qualquer no rótulo da linha, Gateway {label}, dá rótulo a um ponto que não é o destaque), # source: (a nota alinhada à direita na linha da legenda, na dispersão e no mapa de calor), # columns:, # suffix:, # callout: e # note: (o mapa de calor: o título do eixo das colunas, o sufixo dos números, a nota sob a célula em destaque e a nota de rodapé). Num gráfico de linha, # layout: desenha uma das variantes da referência: slopegraph (exatamente duas linhas, os dois estados; uma reta por série entre os eixos em 320 e 680 na mesma escala de # scale: 100-550, nome e valor nas duas pontas), ridgeline (uma linha por faixa, o rótulo o começo dela, e uma coluna por crista; as linhas de base a 56 px uma da outra, e # amplitude: 2.4 diz quantos px vale uma unidade em todas as cristas), streamgraph (uma linha por período e uma coluna por camada, empilhadas na ordem das colunas a partir de baixo, centradas em 230, as bordas suavizadas com os vértices nos valores; markers: W08=Texto marca um período com um fio acima do contorno) e bump (uma linha por momento e o posto de cada série, de 1 a N em cada momento). # x-axis: dá o título do eixo das faixas de uma crista (sem ela, o primeiro cabeçalho do CSV), e um # suffix: com letras (ms, min) entra depois de um espaço. Sem essas linhas, vale a regra. Os sete exemplos abaixo reproduzem os da galeria do diagram-design (cathrynlavery/diagram-design, MIT) número por número, com os dados e os textos originais.
O exemplo 22 da galeria, Sprint velocity · 8-sprint view: oito barras num passo de 110 px, 72 de largura, a Sprint 5 em destaque.
title: Sprint velocity · 8-sprint view
---
# desc: Bar chart showing story points delivered across sprints S1 through S8, with Sprint 5 as the record high.
# legend: Sprint 5 · record high; Other sprints {x:220}
sprint,story points
S1,72
S2,88
S3,95
S4,78
S5,110
S6,102
S7,85
S8,93```@chart type:bar look:editorial focal:S5
title: Sprint velocity · 8-sprint view
---
# desc: Bar chart showing story points delivered across sprints S1 through S8, with Sprint 5 as the record high.
# legend: Sprint 5 · record high; Other sprints {x:220}
sprint,story points
S1,72
S2,88
S3,95
S4,78
S5,110
S6,102
S7,85
S8,93
```O exemplo 23, Cloud budget bridge · FY25 → FY26: seis barras de 96 num passo de 144, os totais a partir do chão, um conector no nível acumulado em cada intervalo, e a maior economia em destaque.
title: Cloud budget bridge · FY25 → FY26
focal: Storage tiering
---
# desc: Waterfall chart bridging the FY25 cloud budget of 240 thousand dollars a month to the FY26 plan of 236, through headcount growth, reserved-instance savings, new ML workloads, and storage tiering — the largest saving.
# legend: Start / end total; Cost added {x:200}; Cost removed {x:340}; Storage tiering · largest saving {x:480}
item,cloud spend · $k / mo
FY25 base,240
Headcount,+64
Reserved inst.,-38
ML workloads,+22
Storage tiering,-52
FY26 plan,```@chart type:waterfall look:editorial
title: Cloud budget bridge · FY25 → FY26
focal: Storage tiering
---
# desc: Waterfall chart bridging the FY25 cloud budget of 240 thousand dollars a month to the FY26 plan of 236, through headcount growth, reserved-instance savings, new ML workloads, and storage tiering — the largest saving.
# legend: Start / end total; Cost added {x:200}; Cost removed {x:340}; Storage tiering · largest saving {x:480}
item,cloud spend · $k / mo
FY25 base,240
Headcount,+64
Reserved inst.,-38
ML workloads,+22
Storage tiering,-52
FY26 plan,
```O exemplo 25, The week payments went dark: trinta células de 116 × 56 num só degradê de tinta, o valor impresso em cada uma, e a célula payments · S4 na cor de destaque com a nota embaixo.
title: The week payments went dark
focal: payments,S4
---
# columns: Sprint
# suffix: %
# callout: Regression
# source: Illustrative CI failure rates · not a measured registry
# legend: payments · S4 · 47% — deploy regression (now fixed)
# note: Non-focal scale: 1–9% · single ink ramp · accent is editorial, not a data range
# desc: Heatmap of CI failure rate by service and sprint; payments service spiked to 47% in sprint 4 due to a deploy regression, recovered to 4% by sprint 6; billing carries the highest baseline failure rate at 9% in sprint 3.
service,S1,S2,S3,S4,S5,S6
auth,4,5,6,3,2,2
payments,3,4,5,47,6,4
api-gateway,2,3,4,2,1,1
billing,5,7,9,6,4,3
notifications,1,2,2,2,1,1```@chart type:heatmap look:editorial
title: The week payments went dark
focal: payments,S4
---
# columns: Sprint
# suffix: %
# callout: Regression
# source: Illustrative CI failure rates · not a measured registry
# legend: payments · S4 · 47% — deploy regression (now fixed)
# note: Non-focal scale: 1–9% · single ink ramp · accent is editorial, not a data range
# desc: Heatmap of CI failure rate by service and sprint; payments service spiked to 47% in sprint 4 due to a deploy regression, recovered to 4% by sprint 6; billing carries the highest baseline failure rate at 9% in sprint 3.
service,S1,S2,S3,S4,S5,S6
auth,4,5,6,3,2,2
payments,3,4,5,47,6,4
api-gateway,2,3,4,2,1,1
billing,5,7,9,6,4,3
notifications,1,2,2,2,1,1
```O exemplo 26, Weekly signups · Organic leads the growth: oito semanas num passo de 120 px, a série Organic em destaque com área até a linha de base e um ponto em cada vértice, as outras duas em 1,2 px.
title: Weekly signups · Organic leads the growth
focal: Organic
---
# unit: Signups / week
# desc: Line chart showing weekly signups from organic, direct, and referral channels across weeks W1 through W8.
# legend: Organic · focal; Direct {x:200}; Referral {x:316}
week,Organic,Direct,Referral
W1,120,80,45
W2,135,82,52
W3,148,88,48
W4,162,90,60
W5,155,86,55
W6,178,92,68
W7,195,95,62
W8,210,98,75```@chart type:line look:editorial
title: Weekly signups · Organic leads the growth
focal: Organic
---
# unit: Signups / week
# desc: Line chart showing weekly signups from organic, direct, and referral channels across weeks W1 through W8.
# legend: Organic · focal; Direct {x:200}; Referral {x:316}
week,Organic,Direct,Referral
W1,120,80,45
W2,135,82,52
W3,148,88,48
W4,162,90,60
W5,155,86,55
W6,178,92,68
W7,195,95,62
W8,210,98,75
```O exemplo 28, Deploy frequency vs. lead time · 12 teams: doze pontos em dois eixos a partir de zero, a linha de tendência tracejada, as notas de canto, e o time Platform em destaque com o nome onde a galeria o pôs.
title: Deploy frequency vs. lead time · 12 teams
focal: Platform
---
# y-scale: 24 by 6
# trend: 168,103 900,388
# guides: High lead time; Low lead time
# legend: Platform team · best performer; Engineering team {x:244}; Trend {x:416}
# desc: Scatter plot showing twelve engineering teams by deploy frequency and lead time, with Platform in the best-performing quadrant.
team,deploys per week,lead time (days)
Team A,2,20
Team B,4,18
Team C,4,16
Team D,6,14
Team E,8,12
Team F,8,10
Team G,10,8
Team H,12,6
Team I,12,10
Team J,16,4
Platform {x:830 y:357},18,3
Team L,20,2```@chart type:scatter look:editorial
title: Deploy frequency vs. lead time · 12 teams
focal: Platform
---
# y-scale: 24 by 6
# trend: 168,103 900,388
# guides: High lead time; Low lead time
# legend: Platform team · best performer; Engineering team {x:244}; Trend {x:416}
# desc: Scatter plot showing twelve engineering teams by deploy frequency and lead time, with Platform in the best-performing quadrant.
team,deploys per week,lead time (days)
Team A,2,20
Team B,4,18
Team C,4,16
Team D,6,14
Team E,8,12
Team F,8,10
Team G,10,8
Team H,12,6
Team I,12,10
Team J,16,4
Platform {x:830 y:357},18,3
Team L,20,2
```O exemplo 28a, The biggest risk is not the slowest service: a dispersão vira bolhas quando há uma terceira coluna numérica — a área de cada bolha é o valor (a maior com 42 px de raio), as maiores desenhadas primeiro, num degradê de tinta mais claro na maior, e o serviço Payments em destaque.
title: The biggest risk is not the slowest service
focal: Payments
---
# y-scale: 4 by 1
# label-mask: 64
# source: P95 vs error rate, bubble area ∝ requests per second · both axes start at zero · illustrative figures, not measured services
# legend: Payments · focal, highest error rate at near-peak traffic; Service · faintest fill is the largest bubble {x:648}
# desc: Bubble chart of nine services by p95 latency and error rate on zero-based axes, bubble area proportional to requests per second; Payments carries near-peak traffic at the highest error rate.
service,"p95 latency, ms","error rate, %",requests per second
Gateway {label},85,0.5,900
Payments {y:108},260,2.8,760
Auth,140,0.9,620
Catalog,180,0.7,540
Search,320,1.1,480
Media,230,1.4,330
Recommender,420,1.6,210
Notifications,95,2.2,150
Reports {y:356},460,0.9,60```@chart type:scatter look:editorial
title: The biggest risk is not the slowest service
focal: Payments
---
# y-scale: 4 by 1
# label-mask: 64
# source: P95 vs error rate, bubble area ∝ requests per second · both axes start at zero · illustrative figures, not measured services
# legend: Payments · focal, highest error rate at near-peak traffic; Service · faintest fill is the largest bubble {x:648}
# desc: Bubble chart of nine services by p95 latency and error rate on zero-based axes, bubble area proportional to requests per second; Payments carries near-peak traffic at the highest error rate.
service,"p95 latency, ms","error rate, %",requests per second
Gateway {label},85,0.5,900
Payments {y:108},260,2.8,760
Auth,140,0.9,620
Catalog,180,0.7,540
Search,320,1.1,480
Media,230,1.4,330
Recommender,420,1.6,210
Notifications,95,2.2,150
Reports {y:356},460,0.9,60
```O exemplo 28b, The median hides the tail: com uma só coluna numérica a dispersão vira um enxame (# layout: beeswarm diz o mesmo por extenso) — um ponto por linha no seu valor, empurrado 10 px para cima ou para baixo da linha do meio até não encostar em nenhum outro, o deslocamento vertical sem valor nenhum; as linhas com nome ganham rótulo com um fio até o ponto, e a mais lenta é o destaque.
title: The median hides the tail
focal: req-4c1f
---
# layout: beeswarm
# x-scale: 440 by 100
# label-mask: 60
# source: One dot = one request · value axis 0–440 ms, linear from zero · vertical spread is packing, not a value · illustrative figures, not measured traffic
# legend: req-4c1f · focal, the slowest request in the window; request · vertical offset is packing only {x:648}
# desc: Beeswarm of 138 per-request latency samples for one checkout endpoint on a shared linear value axis from zero; vertical spread is packing only and carries no value, and three requests past 380 ms form the p99 tail.
request,"per-request latency, ms"
,52
,53
,55
,56
,60
,61
,61
,67
,69
,73
,76
,76
,77
,80
,80
,82
,82
,83
,84
,84
,84
,85
,85
,86
,87
,88
,88
,88
,89
,89
,90
,90
,90
,91
,94
,95
,99
,99
,99
,103
,103
,105
,105
,106
,106
,106
,106
,106
,107
,107
,108
,109
,110
,110
,110
,113
,114
,114
,115
,115
,116
,117
,117
,117
,118
,118
,119
,120
,122
,123
,123
,127
,127
,127
,127
,128
,131
,132
,135
,137
,141
,143
,145
,145
,146
,148
,150
,151
,152
,152
,153
,155
,155
,157
,157
,161
,162
,164
,174
,182
,187
,189
,190
,194
,195
,195
,196
,196
,197
,201
,204
,206
,207
,214
,215
,217
,219
,225
,229
,233
,233
,238
,249
,255
,256
,264
,268
,277
,280
,283
,285
,286
,289
,289
,312
req-77d3,388
req-09aa,402
req-4c1f,431```@chart type:scatter look:editorial
title: The median hides the tail
focal: req-4c1f
---
# layout: beeswarm
# x-scale: 440 by 100
# label-mask: 60
# source: One dot = one request · value axis 0–440 ms, linear from zero · vertical spread is packing, not a value · illustrative figures, not measured traffic
# legend: req-4c1f · focal, the slowest request in the window; request · vertical offset is packing only {x:648}
# desc: Beeswarm of 138 per-request latency samples for one checkout endpoint on a shared linear value axis from zero; vertical spread is packing only and carries no value, and three requests past 380 ms form the p99 tail.
request,"per-request latency, ms"
,52
,53
,55
,56
,60
,61
,61
,67
,69
,73
,76
,76
,77
,80
,80
,82
,82
,83
,84
,84
,84
,85
,85
,86
,87
,88
,88
,88
,89
,89
,90
,90
,90
,91
,94
,95
,99
,99
,99
,103
,103
,105
,105
,106
,106
,106
,106
,106
,107
,107
,108
,109
,110
,110
,110
,113
,114
,114
,115
,115
,116
,117
,117
,117
,118
,118
,119
,120
,122
,123
,123
,127
,127
,127
,127
,128
,131
,132
,135
,137
,141
,143
,145
,145
,146
,148
,150
,151
,152
,152
,153
,155
,155
,157
,157
,161
,162
,164
,174
,182
,187
,189
,190
,194
,195
,195
,196
,196
,197
,201
,204
,206
,207
,214
,215
,217
,219
,225
,229
,233
,233
,238
,249
,255
,256
,264
,268
,277
,280
,283
,285
,286
,289
,289
,312
req-77d3,388
req-09aa,402
req-4c1f,431
```Argumentos#
-
type—bar(o padrão),stacked,line,area,pie,donut,scatter,heatmap,waterfalloutable. -
title— impresso acima do gráfico. -
markers— marcos no eixo,categoria=nomeseparados por ponto e vírgula. -
focal(oufoco) — o item em destaque, na cor de destaque da página: uma linha, uma série ou, no mapa de calor, uma célulalinha,coluna. Um só.
Para um gráfico das linhas de uma coleção, que muda quando elas mudam, um @data.