Heatmap Color Scales: Sequential vs Diverging

A heatmap colour scale is an argument about the data. A light-to-dark ramp suggests increasing amount; two opposing arms suggest direction around a meaningful centre. Choosing the wrong structure can imply a threshold or polarity that does not exist, even when every individual colour looks attractive.

Decide whether the data has a meaningful centre

Use a sequential scale for values that move from less to more: counts, duration, concentration, or other ordered magnitudes. Use a diverging scale when deviation on either side of a meaningful reference matters, such as temperature anomaly around zero or performance relative to a target.

Preview candidate ramps in the gradient generator. Start with the data relationship, not a fashionable gradient. Set two endpoints for a sequential experiment; add a deliberate centre and two arms for a diverging experiment. Keep the numerical domain beside the preview while making colour decisions.

A median is not automatically a meaningful neutral point. Splitting a sequential count distribution at its median creates an artificial “two sides” story. Conversely, a scale for profit and loss may need a zero centre even if the values are distributed very unevenly.

The MDN gradient guide explains how CSS previews are constructed. Treat those previews as design aids rather than complete chart scales: your visualization library still needs an explicit mapping from values to colour positions.

Make sequential lightness move consistently

For a sequential scale, higher values should usually appear consistently stronger. A pale-to-dark family is a common solution because its order can remain understandable even when hue differences are reduced. Avoid ramps that become dark, then light, then dark again unless that structure has a specific data meaning.

Monotonic lightness reduces false boundaries. If a midrange yellow is much brighter than its neighbours, it can create an apparent band in a continuous field. Viewers may interpret that band as a threshold even when it is just an artefact of the colour path.

Try five or seven discrete samples before testing a fully continuous ramp. Ask whether their order is obvious without labels, then restore the numerical legend. If two middle samples are nearly indistinguishable while the last step is dramatic, redistribute the perceptual changes.

Do not assume that equal RGB interpolation steps produce equal visual differences. Perceptual models can help, but the final scale still requires contextual review. The CSS Color specification provides useful background on the distinction between colour coordinates and perceived relationships.

Balance both arms of a diverging scale

A diverging scale needs two distinguishable directions and an intentionally chosen centre. The midpoint might be near-white or another quiet neutral. Both arms should gain comparable visual weight as they move away from the reference, so one direction does not appear more extreme purely because it is darker.

.scale--sequential {
background: linear-gradient(
  to right, #f1f6fb, #8bb6d6, #24587f
);
}

.scale--diverging {
background: linear-gradient(
  to right, #9c3f22, #f7f4ee 50%, #24587f
);
}

These gradients illustrate scale structure, not a validated data palette. Review sampled colours at equal data intervals. For a diverging domain from -10 to 30, placing zero at the visual middle requires an intentional normalization strategy; a naive linear mapping puts it one quarter of the way across.

Choose symmetric limits when equal distances from the centre should receive equal visual treatment. If asymmetric limits are necessary, explain them clearly in the legend. The choice is analytical as well as visual, and should not be hidden inside a colour-generation setting.

Define missing values and exceptional ranges separately

Missing data is not the same as zero. Assigning both the palest colour can mislead viewers into interpreting unknown regions as low values. Use a distinct neutral, a pattern, or an explicit marker depending on the chart form and available space.

Also decide how outliers behave. Clamping maps values beyond the displayed domain to the endpoint colour; expanding the domain preserves them but may compress most of the remaining variation. Either approach can be valid if the legend and notes make the choice clear.

Use the colour converter to record exact sampled values when handing a scale to another implementation. If one version uses a different interpolation path, the same endpoints may still produce a noticeably different middle. Export stops or a shared interpolation method rather than only two HEX codes.

Check label colours against the cells where they appear using the contrast checker. A single label colour often cannot remain readable across an entire dark-to-light ramp. Consider external labels, conditional foregrounds, or another presentation that avoids weak pairings.

Verify the scale against realistic distributions

Test uniform data, clustered data, a few extreme values, and a mostly missing field. A palette can look balanced in a smooth legend while collapsing when most observations occupy a narrow interval. Decide whether transformation or discrete bins are appropriate before making cosmetic adjustments.

The W3C guidance on use of colour is relevant because the data cannot depend on colour alone for precise interpretation. Provide values through labels, interaction, a table, or another suitable alternative rather than expecting viewers to decode exact numbers from shades.

Inspect the map or matrix at its real size. Spatial context changes perception: a medium cell surrounded by dark neighbours may appear lighter than the same cell elsewhere. Avoid claims of precise visual measurement and provide a clear legend with meaningful tick labels.

Finally, record the domain, centre, interpolation method, missing-value treatment, and outlier policy. Those decisions are part of the colour scale. Without them, a future palette refresh can accidentally change the analytical story while appearing to be a harmless visual update.

Key takeaways

• Use sequential scales for magnitude and diverging scales for meaningful two-sided deviation.
• Keep sequential lightness ordered and diverging arms visually balanced.
• Specify the domain and midpoint explicitly.
• Distinguish missing values from zero and document outlier treatment.
• Test real distributions and provide access to values beyond colour estimation.