Raxol.UI.Theming.Colors (Raxol v0.2.0)

View Source

Color management utilities for theme handling.

This module provides functions for:

  • Converting between color formats
  • Color manipulation (lighten, darken, alpha blend)
  • Calculating color contrast
  • Validating color accessibility

Summary

Functions

Checks if the contrast ratio between two colors meets accessibility standards.

Blends two colors together with the specified alpha value.

Calculates the contrast ratio between two colors.

Converts a color or theme map to use a specific palette (e.g., 256 colors). Finds the closest color in the palette for each color in the theme. Currently only supports named palettes like :xterm256

Darkens a color by the specified percentage.

Finds the closest ANSI 256-color index (0-255) to the given RGB color.

Finds the closest ANSI basic color index (0-15) to the given RGB color.

Lightens a color by the specified percentage.

Converts RGB values to a hex color string.

Converts a color from one format to RGB values.

Types

color_hex()

@type color_hex() :: String.t()

color_hsl()

@type color_hsl() :: {hue :: 0..360, saturation :: 0..100, lightness :: 0..100}

color_name()

@type color_name() :: atom()

color_rgb()

@type color_rgb() :: {red :: 0..255, green :: 0..255, blue :: 0..255}

color_rgba()

@type color_rgba() ::
  {red :: 0..255, green :: 0..255, blue :: 0..255, alpha :: 0..255}

Functions

accessible?(color1, color2, level \\ :aa, type \\ :normal)

@spec accessible?(
  color_hex() | color_name(),
  color_hex() | color_name(),
  level :: :aa | :aaa,
  type :: :normal | :large
) :: boolean()

Checks if the contrast ratio between two colors meets accessibility standards.

Parameters

  • color1 - The first color
  • color2 - The second color
  • level - The WCAG accessibility level to check for (:aa or :aaa)
  • type - The text type (:normal or :large)

Examples

iex> Colors.accessible?("#FFFFFF", "#000000", :aa, :normal)
true

blend(color1, color2, alpha)

@spec blend(color_hex() | color_name(), color_hex() | color_name(), alpha :: 0..1) ::
  color_hex()

Blends two colors together with the specified alpha value.

Examples

iex> Colors.blend("#FF0000", "#0000FF", 0.5)
"#800080"

contrast_ratio(color1, color2)

@spec contrast_ratio(color_hex() | color_name(), color_hex() | color_name()) ::
  float()

Calculates the contrast ratio between two colors.

Returns a value between 1 and 21, with 21 being the highest contrast.

Examples

iex> Colors.contrast_ratio("#FFFFFF", "#000000")
21.0

convert_to_basic(color)

convert_to_palette(value, palette_name \\ :xterm256)

Converts a color or theme map to use a specific palette (e.g., 256 colors). Finds the closest color in the palette for each color in the theme. Currently only supports named palettes like :xterm256

darken(color, percentage)

@spec darken(color_hex() | color_name(), percentage :: 0..100) :: color_hex()

Darkens a color by the specified percentage.

Examples

iex> Colors.darken("#FF0000", 20)
"#CC0000"

find_closest_256_color(rgb)

@spec find_closest_256_color(color_rgb()) :: 0..255

Finds the closest ANSI 256-color index (0-255) to the given RGB color.

find_closest_basic_color(rgb)

@spec find_closest_basic_color(color_rgb()) :: 0..15

Finds the closest ANSI basic color index (0-15) to the given RGB color.

lighten(color, percentage)

@spec lighten(color_hex() | color_name(), percentage :: 0..100) :: color_hex()

Lightens a color by the specified percentage.

Examples

iex> Colors.lighten("#FF0000", 20)
"#FF6666"

to_hex(arg)

@spec to_hex(color_rgb() | color_rgba()) :: color_hex()

Converts RGB values to a hex color string.

Examples

iex> Colors.to_hex({255, 0, 0})
"#FF0000"

to_rgb(color)

@spec to_rgb(color_hex() | color_name()) :: color_rgb()

Converts a color from one format to RGB values.

Examples

iex> Colors.to_rgb("#FF0000")
{255, 0, 0}

iex> Colors.to_rgb(:blue)
{0, 0, 255}