Custom colour palette functionality/documentation

[nickhenden]

Update (05/02/2026): Agreed with R package subgroup to go with Option 2 (documentation), at least for now. See comments for more info.

Consider adding functionality and/or documentation on how to use non-Analysis Function colour palettes.

We want to encourage users to use the Analysis Function colour palettes where possible. However, we acknowledge that there are times when custom colour palettes are required. We need to decide whether to provide specific functionality to help users create custom palettes, or if we show users how to do it via the documentation.

Option 1: Added functionality

The abandoned PR #20 includes two functions that may be useful:

• create_colormap_from_stops takes a list of gradient colour stops and turns it into a colormap object
• sample_colors_from_cmap extracts a specified number of colours from a colourmap

Example use case: to generate a sequential colour palette with more than three colours (the AF palette only has 3).

Option 2: Documentation

Instead we could include example code for how to change colour palettes in the cookbook. We could include a warning that users should use custom colour palettes with caution.

[nickhenden]

Having spoken to the R package group, the current steer is Option 2 (documentation only). The R group decided not to implement functionality that encourages people to use their own palettes because, ideally, departments should be using the AF colours for charts. Using departmental colours elsewhere is fine, but one of the aims of the AF guidance is that charts across gov are consistent and accessible. That's not possible if each department uses different palettes that aren't guaranteed to comply with accessibility legislation.

We can visit this decision if we get significant demand for custom colour palette functionality. But for now let's remain consistent with the R package and handle it through documentation. The R group are planning to add an explanation to their cookbook for why they don't encourage custom palettes. We can do the same so we're consistent.