contrast_ratio {colorspace} | R Documentation |
W3C Contrast Ratio
Description
Compute (and visualize) the contrast ratio of pairs of colors, as defined by the World Wide Web Consortium (W3C).
Usage
contrast_ratio(
col,
col2 = "white",
algorithm = c("WCAG", "APCA"),
plot = FALSE,
border = FALSE,
cex = 2,
off = 0.05,
mar = rep(0.5, 4),
digits = 2L,
...
)
Arguments
col , col2 |
vectors of any of the three kind of R colors, i.e., either a color
name (an element of |
algorithm |
character specifying whether the established standard |
plot |
logical indicating whether the contrast ratios should also be visualized by simple color swatches. Can also be a vector of length 2, indicating whether the foreground color should be visualized on the background color and/or the background color on the foreground color. |
border |
logical or color specification for the borders around the color swatches (only
used if |
cex |
numeric. Size of the text in the color color swatches (only if |
off |
numeric. Vertical offset between the different color swatches (only if |
mar |
numeric. Size of the margins around the color swatches (only if |
digits |
numeric. Number of digits for the contrast ratios displayed in the color swatches
(only if |
... |
further arguments passed to the plot of the color swatches (only if |
Details
The W3C Content Accessibility Guidelines (WCAG) recommend a contrast ratio of at least 4.5 for the color of regular text on the background color, and a ratio of at least 3 for large text. See https://www.w3.org/TR/WCAG21/#contrast-minimum.
The contrast ratio is defined in https://www.w3.org/TR/WCAG21/#dfn-contrast-ratio
as (L1 + 0.05) / (L2 + 0.05)
where L1
and L2
are the relative luminances
(see https://www.w3.org/TR/WCAG21/#dfn-relative-luminance) of the lighter and darker
colors, respectively. The relative luminances are weighted sums of scaled sRGB coordinates:
0.2126 * R + 0.7152 * G + 0.0722 * B
where each of R
, G
, and B
is defined as ifelse(RGB <= 0.03928, RGB/12.92, ((RGB + 0.055)/1.055)^2.4)
based on
the RGB
coordinates between 0 and 1.
For use in the next major revision of the WCAG a new advanced perceptual contrast algorithm (APCA) has been proposed by Somers (2022), see also Muth (2022) for more background and details. APCA is still under development, here version 0.98G-4g is implemented. Unlike the standard WCAG algorithm, APCA takes into account which color is the text and which is the background. Hence for the APCA algorithm a matrix with normal and reverse polarity is returned. An absolute value of 45 is "sort of" like a WCAG ratio of 3, 60 is "sort of" like 4.5.
Value
A numeric vector with the contrast ratios is returned (invisibly, if plot
is TRUE
).
References
W3C (2018). “Web Content Accessibility Guidelines (WCAG) 2.1.” https://www.w3.org/TR/WCAG21/
Somers A (2022). “Advanced Perceptual Contrast Algorithm.” https://github.com/Myndex/SAPC-APCA
Muth LC (2022). “It's Time for a More Sophisticated Color Contrast Check for Data Visualizations.” Datawrapper Blog. https://blog.datawrapper.de/color-contrast-check-data-vis-wcag-apca/
See Also
Examples
# check contrast ratio of default palette on white background
contrast_ratio(palette(), "white")
# visualize contrast ratio of default palette on white and black background
contrast_ratio(palette(), "white", plot = TRUE)
contrast_ratio(palette()[-1], "black", plot = TRUE)
# APCA algorithm
contrast_ratio(palette(), "white", algorithm = "APCA")
contrast_ratio(palette(), "white", algorithm = "APCA", plot = TRUE, digits = 0)