Charting

Chart type selection

Start from the question the chart must answer, not from the data shape. The same dataset can be visualised in multiple ways — only one will answer the actual question directly.

Chart anatomy

Every Cartesian chart is built from the same set of elements. Keep them consistent — users should not have to re-learn where to look for the title, scale, or legend across different charts in your product.

Sankey diagrams

A Sankey diagram shows the quantity of flow between named nodes arranged in columns. Link widths are proportional to the flow value — the wider the band, the larger the quantity moving from source to target. The total volume entering any node equals the total volume leaving it.

Anatomy

When to use

Implementation

import { sankey, sankeyLinkHorizontal, SankeyNode, SankeyLink } from "d3-sankey";

interface RawNode { id: string; label: string; }
interface RawLink { source: string; target: string; value: number; }

export function SankeyChart({ nodes, links, width, height }: {
  nodes: RawNode[];
  links: RawLink[];
  width: number;
  height: number;
}) {
  const { nodes: laidOut, links: laidOutLinks } = sankey<RawNode, RawLink>()
    .nodeId((d) => d.id)
    .nodeWidth(16)
    .nodePadding(8)
    .extent([[0, 0], [width, height]])({ nodes, links });

  return (
    <svg width={width} height={height}>
      {laidOutLinks.map((link, i) => (
        <path
          key={i}
          d={sankeyLinkHorizontal()(link) ?? ""}
          fill="none"
          stroke={colorForSource(link.source)}
          strokeWidth={Math.max(1, link.width ?? 0)}
          strokeOpacity={0.35}
        />
      ))}
      {laidOut.map((node) => (
        <rect
          key={node.id}
          x={node.x0} y={node.y0}
          width={(node.x1 ?? 0) - (node.x0 ?? 0)}
          height={(node.y1 ?? 0) - (node.y0 ?? 0)}
          fill={colorForNode(node.id)}
        />
      ))}
    </svg>
  );
}

Alluvial diagrams

An Alluvial diagram is a specialisation of Sankey where each column represents a point in time and each row of bands represents the same category persisting across periods. The vertical position and height of a band shows the category's share; the drift between columns reveals movement — in JobFlo, applications advancing through the pipeline, stalling in a stage, or reaching terminal outcomes like Rejected or Accepted.

Reading an Alluvial

Design rules

• →Sort categories by size at the first column, largest to smallest. Maintain that order across all columns — do not re-sort between periods. Users track bands by position, not colour alone.
• →Normalise totals to 100% unless the absolute population size is the point. Percentage alluvials are easier to read because all columns have the same height.
• →Use 4 categories or fewer. Beyond that, thin bands become illegible and the diagram loses its glanceability advantage over a stacked bar chart.
• →Annotate bands that cross. A crossing is the most significant event in an alluvial — it deserves a callout note explaining what drove the change.
• →Show at most 5 time periods (columns). More columns compress the bands and make individual change unreadable. Use a stacked area chart for long time series.
• →Band opacity at 25–35% allows the overlap zone to be read as a blend. Lower opacity loses the band; higher opacity obscures the space between columns.

Implementation

import { linkHorizontal } from "d3-shape";

// Each band connects the same category across two adjacent columns.
// left / right describe the vertical span in the column.
interface Band {
  category: string;
  color: string;
  left:  { y0: number; y1: number };  // top and bottom y in left column
  right: { y0: number; y1: number };  // top and bottom y in right column
}

function ribbonPath(
  lx: number, ly0: number, ly1: number,
  rx: number, ry0: number, ry1: number,
): string {
  const cx = (lx + rx) / 2;
  return [
    `M ${lx} ${ly0}`,
    `C ${cx} ${ly0} ${cx} ${ry0} ${rx} ${ry0}`,
    `L ${rx} ${ry1}`,
    `C ${cx} ${ry1} ${cx} ${ly1} ${lx} ${ly1}`,
    "Z",
  ].join(" ");
}

export function AlluvialChart({ bands, lx, rx }: {
  bands: Band[];
  lx: number;  // right edge of left column
  rx: number;  // left edge of right column
}) {
  return (
    <>
      {bands.map((band) => (
        <path
          key={band.category}
          d={ribbonPath(lx, band.left.y0, band.left.y1, rx, band.right.y0, band.right.y1)}
          fill={band.color}
          fillOpacity={0.3}
        />
      ))}
    </>
  );
}

Pipeline flow alluvial

A source alluvial extends the standard alluvial by splitting each stage column into coloured source strands — one per acquisition channel or origin. Instead of showing how a single population shifts over time, it answers: which sources contribute most at each stage, and where do they fall off? The chart reads left-to-right; strand thickness at each column is proportional to the volume from that channel at that stage.

Anatomy

Design rules

• →Assign each source a distinct hue from the product's extended palette. Do not reuse stage colours for sources — stage colour encodes position in the pipeline; source colour encodes origin.
• →Stack sources consistently by volume at the first stage (largest to smallest, top to bottom). Never reorder strands between columns — users track strands by position across the diagram.
• →Use opacity 0.75–0.85 for strand fills. Full opacity occludes overlapping strands and removes the sense of depth. Too-low opacity makes thin strands disappear.
• →Keep the crosshair subtle (1px white, 80% opacity). It should be readable against the dark background but not compete with the strands for visual weight.
• →Show 5–7 sources maximum. Beyond that, thin strands at late stages become indistinguishable. Group small sources into an 'Other' strand.
• →Always pair the chart with a text summary of the key finding — e.g. 'Referral drives 22% of inbound but converts at 3× the rate of Paid.' The chart alone is not accessible.

Implementation

// Each source defines one StreamPt per stage column.
// top/bot are SVG y-coordinates; the strand fills between them.
type StreamPt = { x: number; bot: number; top: number };

// Generates a closed bezier path for a single source strand.
// Uses midpoint control points for smooth organic curves.
function streamPath(pts: StreamPt[]): string {
  let d = `M ${pts[0].x} ${pts[0].top}`;
  for (let i = 1; i < pts.length; i++) {
    const cx = (pts[i - 1].x + pts[i].x) / 2;
    d += ` C ${cx} ${pts[i-1].top} ${cx} ${pts[i].top} ${pts[i].x} ${pts[i].top}`;
  }
  d += ` L ${pts[pts.length-1].x} ${pts[pts.length-1].bot}`;
  for (let i = pts.length - 2; i >= 0; i--) {
    const cx = (pts[i].x + pts[i+1].x) / 2;
    d += ` C ${cx} ${pts[i+1].bot} ${cx} ${pts[i].bot} ${pts[i].x} ${pts[i].bot}`;
  }
  return d + " Z";
}

// Render the chart
{sources.map((src) => (
  <path
    key={src.name}
    d={streamPath(src.points)}
    fill={src.color}
    fillOpacity={0.78}
  />
))}

// Crosshair + intersection dots
<line x1={crosshairX} y1={TOP} x2={crosshairX} y2={BOTTOM}
  stroke="white" strokeWidth={1} strokeOpacity={0.8} />
{sources.map((src) => {
  const pt = src.points[activeStageIndex];
  return pt.bot - pt.top >= 3 ? (
    <circle cx={crosshairX} cy={(pt.top + pt.bot) / 2}
      r={2.5} fill="white" fillOpacity={0.9} />
  ) : null;
})}

Sankey vs Alluvial

They look similar — both use curved bands between vertical bars — but they answer fundamentally different questions.

Tooltip patterns

Tooltips are the primary interaction surface for charts. They surface precise values that would clutter the chart if always visible.

Responsive behaviour

Burn Trajectory

A Burn Trajectory chart overlays four time series on a single axes: historical actuals, a forward forecast, a planned baseline, and a budget ceiling. It is the primary chart type for budget-vs-actual tracking in Warren's project finance views.