Raxol.Style.Colors.Accessibility (Raxol v0.4.0)
View SourceProvides utilities for color accessibility, focusing on WCAG contrast.
Summary
Functions
Finds an accessible color pair (foreground/background) based on a base color and WCAG level.
Adjusts a color palette to ensure all colors are accessible against a background.
Checks if two colors have sufficient contrast according to WCAG guidelines.
Calculates the contrast ratio between two colors according to WCAG guidelines.
Checks if a foreground color is readable on a background color.
Calculates the relative luminance of a color according to WCAG guidelines.
Suggests a color with good contrast (at least AA) to the base color.
Suggests an appropriate text color (black or white) for a given background.
Functions
Finds an accessible color pair (foreground/background) based on a base color and WCAG level.
Tries to find a contrasting color (black or white first) that meets the desired level.
Parameters:
base_color
: The Color struct or hex string to find a contrasting pair for.level
: The minimum WCAG contrast ratio level (:aa or :aaa, defaults to :aa).
Returns:
A tuple {foreground_color, background_color}
where one is the base_color
and the other is a contrasting color (typically black or white) that meets the
specified level
. Returns nil
if no suitable pair is found immediately
(further logic might be needed for complex cases).
@spec adjust_palette(map(), Raxol.Style.Colors.Color.t() | String.t()) :: map()
Adjusts a color palette to ensure all colors are accessible against a background.
Parameters
colors
- Map of colors to adjustbackground
- Background color to check against
Returns
- Map of adjusted colors
Checks if two colors have sufficient contrast according to WCAG guidelines.
Parameters
color1
- First colorcolor2
- Second colorlevel
- WCAG level (:aa or :aaa)size
- Text size (:normal or :large)
Returns
{:ok, ratio}
if contrast is sufficient{:error, {:contrast_too_low, ratio, min_ratio}}
if contrast is insufficient
Calculates the contrast ratio between two colors according to WCAG guidelines.
Parameters
color1
- The first color (hex string or Color struct)color2
- The second color (hex string or Color struct)
Returns
- A float representing the contrast ratio (1:1 to 21:1)
Examples
iex> Raxol.Style.Colors.Accessibility.contrast_ratio("#000000", "#FFFFFF")
21.0
iex> Raxol.Style.Colors.Accessibility.contrast_ratio("#777777", "#999999")
1.3
@spec darken_until_contrast( Raxol.Style.Colors.Color.t(), Raxol.Style.Colors.Color.t(), number() ) :: Raxol.Style.Colors.Color.t() | nil
@spec generate_accessible_palette( Raxol.Style.Colors.Color.t() | String.t(), Raxol.Style.Colors.Color.t() | String.t() | Keyword.t() ) :: map()
@spec get_optimal_text_color(Raxol.Style.Colors.Color.t() | String.t()) :: String.t()
@spec is_suitable_for_text?( Raxol.Style.Colors.Color.t() | String.t(), Raxol.Style.Colors.Color.t() | String.t() ) :: boolean()
@spec lighten_until_contrast( Raxol.Style.Colors.Color.t(), Raxol.Style.Colors.Color.t(), number() ) :: Raxol.Style.Colors.Color.t() | nil
@spec readable?( Raxol.Style.Colors.Color.t() | String.t(), Raxol.Style.Colors.Color.t() | String.t(), :aa | :aaa | :aa_large | :aaa_large ) :: boolean()
Checks if a foreground color is readable on a background color.
Parameters
background
- Background colorforeground
- Text colorlevel
- Accessibility level (:aa
,:aaa
,:aa_large
,:aaa_large
)
Examples
iex> bg = Raxol.Style.Colors.Color.from_hex("#333333")
iex> fg = Raxol.Style.Colors.Color.from_hex("#FFFFFF")
iex> Raxol.Style.Colors.Accessibility.readable?(bg, fg)
true
iex> bg = Raxol.Style.Colors.Color.from_hex("#CCCCCC")
iex> fg = Raxol.Style.Colors.Color.from_hex("#999999")
iex> Raxol.Style.Colors.Accessibility.readable?(bg, fg, :aaa)
false
Calculates the relative luminance of a color according to WCAG guidelines.
Parameters
color
- The color to calculate luminance for (hex string or Color struct)
Returns
- A float between 0 and 1 representing the relative luminance
Examples
iex> Raxol.Style.Colors.Accessibility.relative_luminance("#000000")
0.0
iex> Raxol.Style.Colors.Accessibility.relative_luminance("#FFFFFF")
1.0
@spec suggest_accessible_color( Raxol.Style.Colors.Color.t() | String.t(), Raxol.Style.Colors.Color.t() | String.t() | Keyword.t() ) :: String.t()
Suggests a color with good contrast (at least AA) to the base color.
Prioritizes complementary color, then black/white.
Parameters
color
- The base color (hex string or Color struct)
Examples
iex> color = Raxol.Style.Colors.Color.from_hex("#3366CC")
iex> contrast_color = Raxol.Style.Colors.Accessibility.suggest_contrast_color(color)
iex> Raxol.Style.Colors.Accessibility.readable?(color, contrast_color)
true
Suggests an appropriate text color (black or white) for a given background.
Ensures minimum AA contrast.
Parameters
background
- The background color (hex string or Color struct)
Examples
iex> Raxol.Style.Colors.Accessibility.suggest_text_color("#333333").hex
"#FFFFFF"
iex> Raxol.Style.Colors.Accessibility.suggest_text_color("#EEEEEE").hex
"#000000"