diff --git a/R/pal-.R b/R/pal-.R
index 66d1f27f..d465595b 100644
--- a/R/pal-.R
+++ b/R/pal-.R
@@ -1,3 +1,89 @@
+#' @name palette-recommendations
+#' @title Recommendations for colour palettes
+#' @description
+#' For the purposes of these recommendations, we define a palette as a function
+#' that either takes an `n` argument for the number of desired output colours or
+#' a `value` argument between 0-1 representing how far along a gradient output
+#' colours should be. The palette then returns a number of colours equal to `n`
+#' or `length(x)`.
+#'
+#' The convention in the scales package is to name functions that generate
+#' palettes (palette factories) with the `pal_`-prefix. The benefit of
+#' factories is that you can easily parameterise palettes, for example giving
+#' options for how a palette should be constructed.
+#'
+#' In the example below `pal_aurora()` is a palette factory parameterised by
+#' a `direction` argument.
+#'
+#' ```r
+#' pal_aurora <- function(direction = 1) {
+#' colours <- c("palegreen", "deepskyblue", "magenta")
+#' if (sign(direction) == -1) {
+#' colours <- rev(colours)
+#' }
+#' pal_manual(colours, type = "colour")
+#' }
+#'
+#' class(pal_aurora())
+#' #> [1] "pal_discrete" "scales_pal" "function"
+#' ```
+#'
+#' It is recommended that a palette factory returns a function with either the
+#' `pal_discrete` or `pal_continuous` class. If your factory constructs a
+#' plain vector of colours, then `pal_manual(type = "colour")` or
+#' `pal_gradient_n()` are useful to return a classed palette for this common
+#' use case.
+#'
+#' When your inner palette function does not return a defined vector of colours,
+#' it is recommended to use `new_discrete_palette` and `new_continuous_palette`
+#' instead and supplement the additional `type` and `na_safe`/`nlevels`
+#' properties. This should allow easy translation between discrete and
+#' continuous palettes.
+#'
+#' ```r
+#' pal_random <- function() {
+#' fun <- function(n) {
+#' sample(colours(distinct = TRUE), size = n)
+#' }
+#' new_discrete_palette(fun, type = "colour", nlevels = length(colours()))
+#' }
+#' ```
+#'
+#' If you don't have parameterised palettes, but also if you have palette
+#' factories, it is encouraged to export an (inner) palette function or
+#' plain colour vector. This is in addition to exporting the palette factory.
+#' Exporting this makes it easy for users to specify for example
+#' `as_continuous_pal(mypackage::aurora)`.
+#'
+#' ```
+#' #' @export
+#' aurora <- pal_aurora()
+#'
+#' # or:
+#'
+#' #' @export
+#' aurora <- c("palegreen", "deepskyblue", "magenta")
+#' ```
+#'
+#' Lastly, for testing purposes we encourage that your palettes can be
+#' interpreted both as discrete palette, but also a continuous palette.
+#' To test for this, you can test the output of `as_discrete_pal()` and
+#' `as_continuous_pal()`.
+#'
+#' ```r
+#' test_that("pal_aurora can be discrete or continuous", {
+#'
+#' my_pal <- pal_aurora()
+#' colours <- c("palegreen", "deepskyblue", "magenta")
+#'
+#' expect_equal(as_discrete_pal(my_pal)(3), colours)
+#' expect_equal(as_continuous_pal(my_pal)(c(0, 0.5, 1)), alpha(colours, NA))
+#'
+#' })
+#' ```
+#' @seealso [palette utilities][new_continuous_palette]
+NULL
+
# Constructors ------------------------------------------------------------
#' Constructors for palettes
@@ -28,6 +114,7 @@
#' For `palette_nlevels()` a single integer. For `palette_na_safe()` a boolean.
#' For `palette_type()` a string.
#' @export
+#' @seealso [palette recommendations][palette-recommendations]
#'
#' @examples
#' # Creating a new discrete palette
diff --git a/man/new_continuous_palette.Rd b/man/new_continuous_palette.Rd
index 49860805..cf0b1585 100644
--- a/man/new_continuous_palette.Rd
+++ b/man/new_continuous_palette.Rd
@@ -106,3 +106,6 @@ show_col(pal(c(0, 0.1, 0.2, 0.4, 1)))
pal <- as_discrete_pal(pal_div_gradient())
show_col(pal(9))
}
+\seealso{
+\link[=palette-recommendations]{palette recommendations}
+}
diff --git a/man/palette-recommendations.Rd b/man/palette-recommendations.Rd
new file mode 100644
index 00000000..0f0be9de
--- /dev/null
+++ b/man/palette-recommendations.Rd
@@ -0,0 +1,86 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/pal-.R
+\name{palette-recommendations}
+\alias{palette-recommendations}
+\title{Recommendations for colour palettes}
+\description{
+For the purposes of these recommendations, we define a palette as a function
+that either takes an \code{n} argument for the number of desired output colours or
+a \code{value} argument between 0-1 representing how far along a gradient output
+colours should be. The palette then returns a number of colours equal to \code{n}
+or \code{length(x)}.
+
+The convention in the scales package is to name functions that generate
+palettes (palette factories) with the \code{pal_}-prefix. The benefit of
+factories is that you can easily parameterise palettes, for example giving
+options for how a palette should be constructed.
+
+In the example below \code{pal_aurora()} is a palette factory parameterised by
+a \code{direction} argument.
+
+\if{html}{\out{}}\preformatted{pal_aurora <- function(direction = 1) \{
+ colours <- c("palegreen", "deepskyblue", "magenta")
+ if (sign(direction) == -1) \{
+ colours <- rev(colours)
+ \}
+ pal_manual(colours, type = "colour")
+\}
+
+class(pal_aurora())
+#> [1] "pal_discrete" "scales_pal" "function"
+}\if{html}{\out{
}}
+
+It is recommended that a palette factory returns a function with either the
+\code{pal_discrete} or \code{pal_continuous} class. If your factory constructs a
+plain vector of colours, then \code{pal_manual(type = "colour")} or
+\code{pal_gradient_n()} are useful to return a classed palette for this common
+use case.
+
+When your inner palette function does not return a defined vector of colours,
+it is recommended to use \code{new_discrete_palette} and \code{new_continuous_palette}
+instead and supplement the additional \code{type} and \code{na_safe}/\code{nlevels}
+properties. This should allow easy translation between discrete and
+continuous palettes.
+
+\if{html}{\out{}}\preformatted{pal_random <- function() \{
+ fun <- function(n) \{
+ sample(colours(distinct = TRUE), size = n)
+ \}
+ new_discrete_palette(fun, type = "colour", nlevels = length(colours()))
+\}
+}\if{html}{\out{
}}
+
+If you don't have parameterised palettes, but also if you have palette
+factories, it is encouraged to export an (inner) palette function or
+plain colour vector. This is in addition to exporting the palette factory.
+Exporting this makes it easy for users to specify for example
+\code{as_continuous_pal(mypackage::aurora)}.
+
+\if{html}{\out{}}\preformatted{#' @export
+aurora <- pal_aurora()
+
+# or:
+
+#' @export
+aurora <- c("palegreen", "deepskyblue", "magenta")
+}\if{html}{\out{
}}
+
+Lastly, for testing purposes we encourage that your palettes can be
+interpreted both as discrete palette, but also a continuous palette.
+To test for this, you can test the output of \code{as_discrete_pal()} and
+\code{as_continuous_pal()}.
+
+\if{html}{\out{}}\preformatted{test_that("pal_aurora can be discrete or continuous", \{
+
+ my_pal <- pal_aurora()
+ colours <- c("palegreen", "deepskyblue", "magenta")
+
+ expect_equal(as_discrete_pal(my_pal)(3), colours)
+ expect_equal(as_continuous_pal(my_pal)(c(0, 0.5, 1)), alpha(colours, NA))
+
+\})
+}\if{html}{\out{
}}
+}
+\seealso{
+\link[=new_continuous_palette]{palette utilities}
+}