Raxol.Style.Colors.Accessibility (Raxol v0.2.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.

Calculates the contrast ratio between two colors according to WCAG guidelines.

Darkens a color until it meets the specified contrast ratio with a background color.

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

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)

Darkens a color until it meets the specified contrast ratio with a background color.

Requires HSL module for darken function.

Parameters

  • color - The color to darken (Color struct)
  • background - The background color (Color struct)
  • target_ratio - The target contrast ratio to achieve

Returns

  • A Color struct representing the darkened color

lighten_until_contrast(color, background, target_ratio)

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_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"