Charts & overviews

Field contracts and worked examples for the charts & overviews blocks — converted at build time from the repo's authoring-skill reference. Every example body is YAML; in a real doc the fence language is the block type (for example sequence … ). Schemas are strict — unknown fields are rejected. See the field contract for the at-a-glance shape of all 87 blocks, or the block catalog for live previews.

Charts & overviews

graph — node-link graph

group: <n> cycles through the chart palette. Edge dir is directed (default) or undirected. Weightless edges can use the terse a -> b: label form (--> dashed, -x-> error); use the object form when an edge carries weight or dir. For algorithm walkthroughs (BFS / DFS / Dijkstra visit order) set node state — visited · current · frontier · target — which overrides the group colour; edge weight (a number) renders on the edge pill, combined with a label as "label · w".

tree — indented hierarchy (HTML, not SVG)

variant: issue draws the same nodes as a MECE issue tree — one problem split into mutually-exclusive branches (left-to-right SVG, depth-coloured stripes, DFS layout). The old mece type is its permanent alias:

variant: issue
title: Why are conversions down?
nodes:
  - { id: root, label: Lower conversion }
  - { id: traffic, parent: root, label: Traffic quality }
  - { id: friction, parent: root, label: Funnel friction }
  - { id: f1, parent: friction, label: Slow checkout, note: p95 > 4s }

Give the nodes a value and it becomes a driver tree. The hierarchy stops being an outline and starts being arithmetic: each node shows its number and its share of its parent, so the row that owns the total is obvious.

unit: ms
nodes:
  - { id: p95, label: Checkout p95, value: 2400 }
  - { id: cap, parent: p95, label: Payment capture, value: 1780 }
  - { id: psp, parent: cap, label: PSP round trip, value: 1520 }
  - { id: db, parent: p95, label: Order write, value: 380 }

p95 = capture (74%) + order write (16%) + the rest — the same move works for revenue = price × volume, or cost by component.

gantt — schedule bars

Task kind is done | active | current | milestone (drives bar colour).

chart — a data chart (bar / stacked / line / area / scatter / donut / gauge / radar / waterfall / funnel)

labels + series drive bar / line / area (one or more series, coloured by accent or an automatic cycle); donut uses items instead:

title: Traffic by client
kind: donut
unit: "%"
items:
  - { label: Web, value: 62, accent: navy }
  - { label: iOS, value: 23, accent: teal }
  - { label: Android, value: 15, accent: amber }

kind: stacked sums each column instead of standing the series side by side — for when the total matters as much as the split; the y-axis scales to the totals and each column is labelled with its own. kind: scatter plots the same labels + series as unjoined points, for when the x order carries no meaning and the question is where things cluster.

kind: gauge — radial progress against a ceiling. A donut says how a whole splits up; a gauge says how far along one number is, which is the shape an SLO, a quota, a migration or a rollout actually has. max is the full sweep (default 100, the percentage case):

title: Migration progress
kind: gauge
unit: "%"
items:
  - { label: Services migrated, value: 68, desc: of 42 services }

One item draws a single dial with the value in the middle and desc under it; several become concentric rings, outermost first, with a legend — good for three or four related percentages, not for a breakdown that should sum to a whole (that is donut).

radar draws a polygon web — labels become the axes (3+ required) and each series is a stroked polygon over concentric rings:

title: Vendor comparison
kind: radar
labels: [Throughput, Latency, Cost, Ops burden, Ecosystem]
series:
  - { label: Kafka, accent: navy, values: [5, 4, 2, 2, 5] }
  - { label: SQS, accent: amber, values: [3, 3, 5, 5, 3] }

Optional max caps the y-axis (radar: the outer ring) instead of auto-scaling to the data. Values are plain numbers — negatives clamp to 0. Use chart for real numeric series; use stats for a handful of headline KPIs and gantt for schedules.

kind: waterfall — a budget cascade. Driven by items (each may carry a desc), with an optional budget cap. The old waterfall type is its permanent alias:

kind: waterfall
title: API latency budget
unit: ms                 # default ms
budget: 250              # optional dashed cap line
items:
  - { label: DNS + TLS, value: 35 }
  - { label: Gateway, value: 20, desc: auth + routing }
  - { label: Service, value: 90 }
  - { label: Database, value: 70 }

Horizontal cascading bars — each starts where the previous total ended, and a navy TOTAL bar closes the run. With budget set, a dashed line marks the cap: any segment past it tints red and the total row gets a green "under" / red "over" chip. Use it for latency budgets and cost breakdowns — how parts add up against a cap; use a plain chart kind for series over categories and kind: funnel for stage-to-stage drop-off.

kind: funnel — a conversion funnel, also driven by items (stages is accepted as a legacy synonym from the funnel-type era, which is now a permanent alias):

kind: funnel
title: Signup → paid conversion
unit: users
items:
  - { label: Visited landing page, value: 48000 }
  - { label: Started signup, value: 9600, desc: email + password }
  - { label: Activated, value: 4300, desc: created a first doc }
  - { label: Upgraded to paid, value: 860 }

Stacked centered bands, each width proportional to value (with a floor so labels fit); a mono ↓ NN% chip between bands shows stage-to-stage conversion. value is a plain number (no separators — the renderer formats it); unit suffixes the value. Use kind: funnel when the story is drop-off between ordered stages; use journey for the qualitative experience across stages.

sankey — how much moves between stages

flow and dfd show that a path exists; sankey shows how heavy it is. Node height and ribbon thickness are the same scale, so the widest ribbon leaving a stage IS where the volume goes — cloud spend, traffic by route, a funnel with its drop-off.

Nodes are inferred from the links, so a bare link list is a complete block. Declare nodes only to give one a nicer label, an accent, or a fixed column:

title: Signup funnel with drop-off
unit: k
nodes:
  - { id: visits, label: Visits, accent: navy }
  - { id: bounced, label: Bounced, accent: red }
links:
  - { from: visits, to: signup, value: 32 }
  - { from: visits, to: bounced, value: 68 }

A node's column is the longest chain of links reaching it, so a stage always sits right of everything feeding it; col (1-indexed) pins one when the derived depth reads wrong. Use sankey for volumes, funnel (a chart kind) for a single ordered drop-off, and flow when only the path matters.

treemap — proportional composition

Where a donut gives up. Six slices is a donut; thirty services by spend, or a bundle by module, is a treemap — area is the value, so the big tiles are the answer and the small ones still have a place to sit.

Tiles are laid out squarified — near-square and biggest-first — which is what makes their areas comparable by eye. Each shows its value and share of the total; the label, value and desc appear only where the tile can hold them, and the tooltip always carries all three.

venn — two or three overlapping sets

For scope, ownership and responsibility, where the interesting part is what two groups share:

Positions are fixed (two circles, or three on a triangle) because a Venn names regions rather than measuring them. shared.sets matches set labels: two names put the label in that lens, all three put it in the middle.

heatmap — a numeric grid with an intensity ramp

Row labels left, column labels on top; each cell tints on a single-hue ramp from light (low) to deep blue (high), normalized between the data min and max (override with explicit min / max). A slim min → max legend sits beneath. Short rows pad missing cells as blank tiles. Use heatmap for a dense value grid (latency × hour, load × region); use matrix for categorical capability cells and table when the reader needs exact rows.

Give the nodes a value and the hierarchy stops being an outline and starts being arithmetic: each node shows its number and its share of its parent, so the row that owns the total is obvious.

unit: ms
nodes:
  - { id: p95, label: Checkout p95, value: 2400 }
  - { id: cap, parent: p95, label: Payment capture, value: 1780 }
  - { id: psp, parent: cap, label: PSP round trip, value: 1520 }
  - { id: db, parent: p95, label: Order write, value: 380 }

p95 = capture (74%) + order write (16%) + the rest — the same move works for revenue = price × volume, or cost by component.

pyramid — stacked hierarchy (top → bottom widening)

quadrant — 2×2 matrix

x / y are 0..1.

journey — user journey map with optional emotion curve