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 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: 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