Finds an accessible color pair (foreground/background) based on a base color and WCAG level.

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

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

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

See Raxol.Style.Colors.Accessibility.Suggester.darken_until_contrast/3.

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

See Raxol.Style.Colors.Accessibility.PaletteGenerator.generate_accessible_palette/2.

See Raxol.Style.Colors.Accessibility.Suggester.get_optimal_text_color/1.

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

See Raxol.Style.Colors.Accessibility.Suggester.lighten_until_contrast/3.

@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

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

See Raxol.Style.Colors.Accessibility.Suggester.suggest_accessible_color/2.

Suggests a color with good contrast (at least AA) to the base color.

Prioritizes complementary color, then black/white.

Suggests an appropriate text color (black or white) for a given background.

Ensures minimum AA contrast.

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

See Raxol.Style.Colors.Accessibility.PaletteGenerator.suitable_for_text?/2.

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

See Raxol.Style.Colors.Accessibility.PaletteGenerator.validate_colors/2.