Raxol.Style.Colors.Accessibility (Raxol v0.5.0)

View Source

Provides 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

accessible_color_pair(base_color, level \\ :aa)

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).

adjust_palette(colors, background)

@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 adjust
  • background - Background color to check against

Returns

  • Map of adjusted colors

check_contrast(color1, color2, level \\ :aa, size \\ :normal)

Checks if two colors have sufficient contrast according to WCAG guidelines.

Parameters

  • color1 - First color
  • color2 - Second color
  • level - 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

contrast_ratio(color1, color2)

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

darken_until_contrast(color, background, target_ratio)

generate_accessible_palette(base_color, opts)

@spec generate_accessible_palette(
  Raxol.Style.Colors.Color.t() | String.t(),
  Raxol.Style.Colors.Color.t() | String.t() | Keyword.t()
) :: map()

get_optimal_text_color(background)

@spec get_optimal_text_color(Raxol.Style.Colors.Color.t() | String.t()) :: String.t()

lighten_until_contrast(color, background, target_ratio)

@spec lighten_until_contrast(
  Raxol.Style.Colors.Color.t(),
  Raxol.Style.Colors.Color.t(),
  number()
) ::
  Raxol.Style.Colors.Color.t() | nil

readable?(background, foreground, level \\ :aa)

@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 color
  • foreground - Text color
  • level - 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

relative_luminance(color)

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

suggest_accessible_color(color, background)

@spec suggest_accessible_color(
  Raxol.Style.Colors.Color.t() | String.t(),
  Raxol.Style.Colors.Color.t() | String.t() | Keyword.t()
) :: String.t()

suggest_contrast_color(color)

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

suggest_text_color(background)

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"

suitable_for_text?(color, background)

@spec suitable_for_text?(
  Raxol.Style.Colors.Color.t() | String.t(),
  Raxol.Style.Colors.Color.t() | String.t()
) :: boolean()

validate_colors(colors, opts)

@spec validate_colors(map(), Raxol.Style.Colors.Color.t() | String.t() | Keyword.t()) ::
  {:ok, map()} | {:error, Keyword.t()}