Visualization Catalog — sample renders

When to use: Use for a 0–100 composite that must stay decomposable: a headline score, ~3 weighted components, and the measures + data under each. Reading: each component is a dot on a shared 0–100 axis vs the headline marker; the measures open beneath it.

When not to use: Do not use a gauge/speedometer or a full-width single-value bar for an index (retired — they exaggerate and don't decompose). For a single value vs a target use `viz.bullet-bar`; for an estimate with uncertainty use `viz.forest-plot`.

Renderer: src/lib/visualizations/templates/IndexMeter.tsx

When to use: Use to scan many measures across many segments for WHERE the problem concentrates: pay-below-market by department, attrition risk by level × tenure, compliance gaps by jurisdiction. Reading: color = severity (darker/redder = worse), rows sorted worst-first, redacted cells = below min-N. Color is the only encoded signal — pair with the value read-out and a legend.

When not to use: Do not use when you have one measure vs a target (use viz.bullet-bar) or an estimate with uncertainty (use viz.forest-plot). Do not use rainbow / categorical hues for severity, and never read an exact value from a shade — the cell carries its own number.

Renderer: src/lib/visualizations/templates/SeverityHeatTable.tsx

When to use: Use when the answer is an ESTIMATE WITH UNCERTAINTY across groups or against a reference: pay-equity gaps centered on zero, engagement/manager scores with CIs, ranking-with-uncertainty. Reading: dot = estimate, line = 95% CI, vertical rule = no-effect/reference; judge each interval against the rule.

When not to use: Do not use mirrored/butterfly bars or two-bar comparisons when the output is a gap estimate — they force mental subtraction and hide uncertainty. Do not use for a single value vs a target (use `viz.bullet-bar`). Do not infer significance from two overlapping group CIs; this chart shows the difference's own interval.

Renderer: src/lib/visualizations/templates/ForestPlot.tsx

When to use: Use when the question is how a net total is built from additive/subtractive contributors over an ordered sequence. Reading: totals anchor at zero; each rise/fall is a signed delta off the running level.

When not to use: Do not use for simple stage-count comparison (use ranked bars) or for pure part-to-whole at one point in time (use a 100% stacked bar). Do not use a stacked bar to fake a bridge — same-category segments can't be compared.

Renderer: src/lib/visualizations/templates/Waterfall.tsx

When to use: Use for before/after change or rank change across exactly two ordered points (then vs now, pre/post program), especially across many items where a full line chart would be empty between endpoints.

When not to use: Do not use for a full time trajectory (use a line chart) or for start-vs-end magnitude where absolute bars are the point (use `viz.slope-comparison`). Keep item count modest or lines overlap.

Renderer: src/lib/visualizations/templates/Slopegraph.tsx

When to use: Use when showing a single metric trending over time AND you have pointwise CIs (e.g., Wilson CIs for a proportion). Reading: the band's width tells the reader how much noise vs signal sits in any one period.

When not to use: Do not use without CIs — `viz.sparkline-grid` is a better fit for bare lines, or just use a plain line chart. Do not use for cohort-by-cohort trends — use `viz.small-multiples-by-segment` (one trend per cohort, shared y-axis).

Renderer: src/lib/visualizations/templates/TrendWithCiBands.tsx

When to use: Use when comparing the SHAPE of a trend across many segments (5+ panels). Shared y-axis range matters: a segment that looks like it's dropping fast might just have a different baseline.

When not to use: Do not use for 1-2 segments — `viz.comparison-pair` or two overlaid trend lines read better. Do not use when you want to compare ONE segment's absolute level to a baseline — use `viz.percentile-callout`.

Renderer: src/lib/visualizations/templates/SmallMultiplesBySegment.tsx

When to use: Use when answering 'how long do people last' across two or more cohorts (tenure bands, hire years, manager type, comp percentile). The step-function shape reads as serious survival analysis.

When not to use: Do not use for non-survival metrics. Do not use for a single cohort with no comparison group — `viz.trend-with-ci-bands` is cleaner. Do not use for very short period grids (<4 points) — the steps will look noisy.

Renderer: src/lib/visualizations/templates/CohortSurvivalCurve.tsx

When to use: Use for any sequential-stage conversion analysis: hiring funnel, performance-review participation, training completion, exit-process steps. Prior-stage % is the diagnostic; absolute counts give scale.

When not to use: Do not use for non-sequential category breakdowns — use a bar chart. Do not use when stages aren't strictly nested (every stage-N person must have been a stage-N-1 person).

Renderer: src/lib/visualizations/templates/FunnelStageConversion.tsx

When to use: Use when showing comp-band positioning per level: where employees sit relative to the band's p50, and how wide each level's spread actually is. The median tick + IQR markers make the diagnostic explicit.

When not to use: Do not use for a single level — `viz.distribution-histogram` is the simpler choice. Do not use for non-compensation distributions — the methodology framing (medians/IQR vs means/SD) is specifically a comp pattern.

Renderer: src/lib/visualizations/templates/CompaRatioDistribution.tsx

When to use: Use for the 'monitor everything' surface: an executive scorecard, a metric-explorer index, a daily ops digest. Cells are intentionally small so density doesn't drop with row count.

When not to use: Do not use as a primary chart — sparklines aren't meant for inspection. Do not use when you need axes (no axis labels per cell). Do not use for single-metric deep dives — promote to `viz.trend-with-ci-bands`.

Renderer: src/lib/visualizations/templates/SparklineGrid.tsx

When to use: Use for any explicit Kepner-Tregoe-style decision: vendor evaluation, comp-strategy choice, intervention selection. The weighted-sum row makes the tradeoff explicit instead of hand-wavy.

When not to use: Do not use for non-decision contexts. Do not use when criteria aren't independent (entangled criteria need a different scoring frame). Do not use with >10 options or >12 criteria — the matrix becomes unreadable.

Renderer: src/lib/visualizations/templates/KepnerTregoeGrid.tsx

When to use: Use for any one-dimensional continuous distribution: tenure, salary, engagement scores, time-to-fill. Mean + median together flag skew at a glance (large gap = skewed).

When not to use: Do not use for split distributions — promote to `viz.compa-ratio-distribution` (per-level panels). Do not use for categorical breakdowns — use a bar chart. Do not use with n<30 — the bins will be noise.

Renderer: src/lib/visualizations/templates/DistributionHistogram.tsx

When to use: Use for binary-cohort comparisons: control vs treatment, manager-tenured vs manager-new, before vs after. CIs and the sig flag prevent the 'two bars look different but aren't actually different' failure mode.

When not to use: Do not use for >3 groups — bars get cluttered and the pairwise sig flag stops being useful. Use a small-multiples or distribution view instead. Do not use without n — the sig flag depends on sample-size-aware CIs.

Renderer: src/lib/visualizations/templates/ComparisonPair.tsx

When to use: Use for an 'answer-first' summary card: 'your value is X, that's pNN of the comparison cohort, baseline is Y'. The percentile band gives shape context without a full distribution chart.

When not to use: Do not use for a trend over time — promote to `viz.trend-with-ci-bands`. Do not use when there's no baseline cohort — a plain metric tile is cleaner. Do not use when percentile is unknown — drop to a simple delta tile.

Renderer: src/lib/visualizations/templates/PercentileCallout.tsx

When to use: Use for pay-structure visualization: where a band actually sits on a shared dollar scale, level-over-level overlap, market positioning. The shared step-sized boxes (e.g., $10K each) keep cross-row comparison honest in a way that bar widths can't.

When not to use: Do not use for continuous distributions — use `viz.compa-ratio-distribution`. Do not use when ranges aren't on the same numeric scale (e.g., one row is salary, another is bonus pct). Do not use with >12 rows — the strip table loses readability.

Renderer: src/lib/visualizations/render/templates/range-strip.tsx

When to use: Use for metric forecasting with explicit uncertainty: attrition forecast, headcount projection, comp-cost forward look. Inner band typically represents 1-sigma, outer band 2-sigma — the wider band signals the methodologically honest answer.

When not to use: Do not use without bands — degrade to a plain trend line or `viz.trend-with-ci-bands` (period-string axis + single CI band). Do not use for historical-only series — the band framing implies a forecast.

Renderer: src/lib/visualizations/render/templates/confidence-band.tsx

When to use: Use when comparing distribution shape across 2–12 groups (departments, levels, hire cohorts): the box's IQR shows spread, the whiskers show range, the median tick shows skew. Pre-aggregate to the five-number summary before plotting — this template doesn't compute quartiles.

When not to use: Do not use for raw points — use `viz.distribution-histogram` (single group) or `viz.compa-ratio-distribution` (per-level histograms). Do not use with n<10 per group — the quartiles are noise. Do not use without the 5-number summary computed upstream.

Renderer: src/lib/visualizations/render/templates/box-whisker.tsx

When to use: Use for KPI scorecards where each metric has a target + qualitative bands (e.g., poor/satisfactory/good). The marker (target) and value-bar render side by side so 'are we hitting it' reads at a glance. Stephen Few's bullet-chart shape; replaces gauge dials.

When not to use: Do not use without a target — degrade to a plain bar chart. Do not use when ranges don't share a unit. Do not use for time-series — promote to `viz.trend-with-ci-bands`.

Renderer: src/lib/visualizations/render/templates/bullet-bar.tsx

When to use: Use for compact dashboard summaries and watchlists: 5–20 metrics, each with its own trend. Reads more like a 'list' than a 'chart'; sibling of `viz.sparkline-grid` but optimized for narrower frames (one trend per row, formatted value as text).

When not to use: Do not use for single-metric deep dives — promote to `viz.trend-with-ci-bands`. Do not use for very dense scoreboards (30+ rows) — use `viz.sparkline-grid` with table layout. Do not use when values aren't pre-formatted strings.

Renderer: src/lib/visualizations/render/templates/sparkline-rows.tsx

When to use: Use to turn a key-driver / relative-importance analysis into an action list: which sub-measures are both important AND underperforming (fix first) vs important-and-strong (maintain). Reading: top-right quadrant = act now; bubble size = n; dashed ring = importance from a prior, not enough client data yet.

When not to use: Do not use for a plain two-variable scatter without a priority interpretation (use `viz.bubble-scatter`), or for an estimate-with-uncertainty across groups (use `viz.forest-plot`). Do not read importance as causal — it is correlation strength.

Renderer: src/lib/visualizations/templates/DriverQuadrant.tsx

When to use: Use to answer 'why does this number matter?' — connecting measures to the strategy they serve for an exec audience (the comp/PA explanation-and-reporting layer, PAT-171; the metric↔strategy mapping, PAT-176). Reading: top-down objective → drivers → measures; status hue + value-vs-benchmark flag the measures threatening the objective.

When not to use: Do not use for a quantitative relationship or trend (use a data chart). Do not use to triage drivers by importance × performance (use `viz.driver-quadrant`), or to decompose a single composite score (use `viz.index-meter`). It argues a hierarchy; it does not plot data.

Renderer: src/lib/visualizations/templates/StrategyMap.tsx

When to use: Use to tell a remediation / change story to an exec: the current state, the target, the gap, and the contributing moves that bridge it. Reading: left = today, right = target; the dashed deck connects the steps; the right-edge bracket calls out the gap.

When not to use: Do not use for a full account-level variance decomposition (use `viz.waterfall`), a time series (use a trend), or a single value vs target (use `viz.bullet-bar`). It argues a two-anchor journey, not a continuous trend.

Renderer: src/lib/visualizations/templates/BridgeGap.tsx

When to use: Use to position items in a named 2×2 for a prioritization / portfolio argument with arbitrary axes. Reading: each point sits in a named quadrant; emphasis = the item the argument is about; bubble size = n.

When not to use: Do not use for the specific Importance × Performance key-driver triage (use `viz.driver-quadrant`), or for a plain two-variable scatter (use `viz.bubble-scatter`).

Renderer: src/lib/visualizations/templates/Strategy2x2.tsx

When to use: Use to argue the structure of a problem's causes for a diagnosis / root-cause discussion (~2–6 categories, a few causes each). Reading: spine points into the effect; bones = categories; twigs = causes.

When not to use: Do not use to quantify how much each driver contributes (use `viz.driver-quadrant` or `viz.waterfall`), or to cascade a strategy down to measures (use `viz.strategy-map`). It is qualitative structure, not magnitude.

Renderer: src/lib/visualizations/templates/CauseEffect.tsx

When to use: Use for a phased plan or a self-correction / dissipation horizon on a shared time axis. Reading: each row is a phase bar from start to end; hue = status; the dashed line marks now.

When not to use: Do not use for a measured time series (use a trend / `viz.multi-line`) or discrete dated events without duration (use `viz.timeline-milestone`). It shows spans, not points or values.

Renderer: src/lib/visualizations/templates/Roadmap.tsx

When to use: Use to argue the structure of a recommendation under uncertainty — choices, chance events, and the outcomes each path reaches. Reading: squares = decisions, circles = chance, pills = outcomes; branch labels sit on the connectors.

When not to use: Do not use to cascade a strategy to measures (use `viz.strategy-map`) or to decompose causes (use `viz.cause-effect`). It is a forward branch structure, not a hierarchy of contributions.

Renderer: src/lib/visualizations/templates/DecisionTree.tsx

When to use: Use to argue that a visible number is a fraction of a larger hidden total (hidden comp waste, stored vs activated value, true vs reported cost). Reading: the tip = visible, the submerged mass = hidden; tip height ∝ visible share when values are given.

When not to use: Do not use for a precise part-to-whole breakdown (use `viz.waterfall` or a composition chart) or more than two layers. It is a two-layer visible/hidden metaphor, not a quantitative decomposition.

Renderer: src/lib/visualizations/templates/IcebergLayers.tsx

When to use: Use to show aggregated flow/affinity between a small set of GROUPS (departments, locations, job families) without exposing individuals. Reading: groups on the ring; a thicker ribbon = more aggregated volume between that pair.

When not to use: Do not use to show individual-level ties (privacy) or to answer 'is the network healthy?' — boil the graph down to summary measures + benchmarks instead (viz.bullet-bar / viz.forest-plot / viz.severity-heat-table; network-analysis spoke). Do not use for >~10 groups (the ring gets unreadable).

Renderer: src/lib/visualizations/templates/ChordDiagram.tsx

When to use: Use only when a node-link picture is genuinely warranted (small, sparse network; an exploratory or illustrative view). Reading: bigger node = more central (by AREA); same color = same community; thicker edge = stronger tie. Always pass a fixed seed.

When not to use: Do not use as the default ONA deliverable — boil the network down to summary measures + benchmarks (network-analysis spoke; viz.bullet-bar / viz.forest-plot / viz.severity-heat-table). Do not use on a dense network (hairball) — fall back to viz.chord-diagram or an adjacency matrix. Layout position carries no meaning unless attribute-anchored.

Renderer: src/lib/visualizations/templates/NodeLinkNetwork.tsx

When to use: Use to show where people actually sit inside their pay bands across levels/families — the single most-requested comp picture (PAT-171 dashboard deliverable). Reading: each dot = a person's pay; the box = the policy band (dashed line = midpoint); dots above/below the box = out-of-band placement; spread = dispersion.

When not to use: Do not use for a single value vs a target (use `viz.bullet-bar`), an estimate-with-uncertainty across groups (use `viz.forest-plot`), or a smoothed shape of one distribution (use `viz.distribution-histogram` / `viz.compa-ratio-distribution`). Never plot individual-pay dots for a group below the min-N floor — the template suppresses them; do not work around it.

Renderer: src/lib/visualizations/templates/SalaryJitterplot.tsx

When to use: Use to compare two groups' headcount across levels — the workforce-structure / representation picture (PAT-171 dashboard). Reading: rows = levels (base at the bottom); left/right bar length = each group's count; symmetry = parity, skew = imbalance.

When not to use: Do not use for more than two groups (use a grouped bar or small multiples), for a part-to-whole composition (use `viz.waffle-bar`), or for a flow between states (use `viz.alluvial`). Never expose a below-min-N cell count — the template suppresses it per-cell.

Renderer: src/lib/visualizations/templates/PopulationPyramid.tsx

When to use: Show where an employee or cohort lands inside an explicit dollar floor/target/ceiling trio on one scale per row.

When not to use: When you lack explicit numeric band edges — degrade to percentile callout instead.

Renderer: src/lib/visualizations/templates/RangeTargetBullet.tsx

When to use: Compare employee placement inside multiple pay bands simultaneously while keeping outliers visible.

When not to use: When you only have aggregates — reuse `viz.box-whisker` histogram instead.

Renderer: src/lib/visualizations/templates/RangeDotPlot.tsx

When to use: Structural compensation comparisons emphasizing midpoint alignment versus absolute dollar spread.

When not to use: Situations needing shared absolute min/max anchors — reuse `viz.range-strip`.

Renderer: src/lib/visualizations/templates/RangeStripAligned.tsx

When to use: Operator desktops where hovered employee detail complements static range charts.

When not to use: SSR-only thumbnails without hydration — PNG render path unsupported today.

Renderer: src/lib/visualizations/templates/InteractiveRangeStrip.tsx

When to use: When two or more related metrics evolve over identical calendar periods.

When not to use: When envelopes include CI overlays — reuse `viz.trend-with-ci-bands` or `viz.confidence-band`.

Renderer: src/lib/visualizations/templates/MultiLine.tsx

When to use: Headline comparisons of KPI directionality between two audited periods.

When not to use: Fine-grained chronological noise — reuse line trends instead.

Renderer: src/lib/visualizations/templates/SlopeComparison.tsx

When to use: Demonstrate leaderboard churn for a handful of named entities.

When not to use: When raw magnitudes matter more than ordinal ordering.

Renderer: src/lib/visualizations/templates/Bump.tsx

When to use: Correlation storytelling with tertiary emphasis via diameter (e.g., headcount-adjusted outliers).

When not to use: When z-dimension unreliable — degrade to planar scatter equivalents.

Renderer: src/lib/visualizations/templates/BubbleScatter.tsx

When to use: Intersectional breakdowns across two nominal dimensions.

When not to use: Temporal ordering priorities — transpose to longitudinal strip instead.

Renderer: src/lib/visualizations/templates/VizHeatmap.tsx

When to use: Showing raw observations per metric where density matters more than quartiles.

When not to use: When strict statistical jitter is mandated — escalate to analytic pipeline.

Renderer: src/lib/visualizations/templates/StripDot.tsx

When to use: Demonstrate mixes (cost components, HC mix) accumulating over FY slices.

When not to use: Additive constraint violated (negative contributors) unless pre-normalized upstream.

Renderer: src/lib/visualizations/templates/StackedArea.tsx

When to use: Audience-friendly composition tiles when donut charts feel too sugary.

When not to use: >8 buckets — degrade to stacked bar percentages.

Renderer: src/lib/visualizations/templates/WaffleBar.tsx

When to use: Executive tiles that must telegraph attainment vs nominal 100 baseline.

When not to use: Fractional composites — use waffle-bar buckets instead.

Renderer: src/lib/visualizations/templates/WafflePercent.tsx

When to use: Transitions such as leveling mix before/after restructuring.

When not to use: Ultra-dense pairwise exchanges — escalate to analytic tables.

Renderer: src/lib/visualizations/templates/AlluvialFlow.tsx

When to use: Executive drill-down previews of hierarchies.

When not to use: Large balanced trees (>50 nodes interactive) needing force layout fidelity.

Renderer: src/lib/visualizations/templates/DendrogramTree.tsx

When to use: Circular scoreboards with ≤8 spokes.

When not to use: Temporal analysis — radial layout loses chronology fidelity.

Renderer: src/lib/visualizations/templates/RadialBarViz.tsx

When to use: Rough geographic variance without projecting GeoJSON payloads.

When not to use: District-level precision mandates — escalate to Vega/D3 choropleths.

Renderer: src/lib/visualizations/templates/TileCartogram.tsx

When to use: Compliance or launch programs tracking ordered gate reviews.

When not to use: When timelines need duration-length segments — escalate to gantts.

Renderer: src/lib/visualizations/templates/TimelineMilestone.tsx

When to use: Operational metrics where breaches beyond control rails matter.

When not to use: Insufficient samples for meaningful control limits (<20 obs).

Renderer: src/lib/visualizations/templates/ControlChart.tsx