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 77 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 }

gantt — schedule bars

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

chart — a data chart (bar / line / area / donut / 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 }

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.

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.

pyramid — stacked hierarchy (top → bottom widening)

quadrant — 2×2 matrix

x / y are 0..1.

journey — user journey map with optional emotion curve