Raxol.Core.ColorSystem (Raxol v0.3.0)

View Source

Core color system for Raxol.

This module provides a unified interface for managing colors and themes throughout the application. It integrates with the Style.Colors modules to provide a consistent color experience.

Features

  • Theme management with semantic color naming
  • Color format conversion and validation
  • Accessibility checks and adjustments

Summary

Functions

Adjusts a color to meet contrast requirements with another color.

Creates a new theme with the given name and colors.

Gets the effective color value for a given semantic color name.

Gets a color value and ensures it's returned in a specific format (e.g., RGB tuple). Useful when a specific color representation is required for rendering.

Gets a color from the theme by its semantic name.

Checks if two colors meet WCAG contrast requirements.

Converts a color to its ANSI representation.

Functions

adjust_for_contrast(theme, foreground, background, level, size)

Adjusts a color to meet contrast requirements with another color.

Examples

iex> theme = create_theme("dark", %{
...>   text: "#808080",
...>   background: "#000000"
...> })
iex> adjusted = adjust_for_contrast(theme, :text, :background, :AA, :normal)
iex> meets_contrast_requirements?(adjusted, :text, :background, :AA, :normal)
true

create_theme(name, colors)

Creates a new theme with the given name and colors.

Examples

iex> theme = create_theme("dark", %{
...>   primary: "#FF0000",
...>   background: "#000000",
...>   text: "#FFFFFF"
...> })
iex> theme.name
"dark"

get(theme_id, color_name)

@spec get(atom(), atom()) :: Raxol.Style.Colors.color_value() | nil

Gets the effective color value for a given semantic color name.

It retrieves the color from the specified theme (by ID), automatically considering whether a high contrast variant is active based on accessibility settings.

Args:

  • theme_id: The atom ID of the theme to use (e.g., :default, :dark).
  • color_name: The semantic name of the color (e.g., :primary, :background).

Returns the color value (e.g., :red, {:rgb, r, g, b}) or nil if not found.

get_as(theme_id, color_name, format \\ :term)

@spec get_as(atom(), atom(), atom()) :: any() | nil

Gets a color value and ensures it's returned in a specific format (e.g., RGB tuple). Useful when a specific color representation is required for rendering.

Args:

  • theme_id: The atom ID of the theme to use.
  • color_name: The semantic name of the color.
  • format: The desired output format (:rgb_tuple, :hex_string, :term).

Supported formats: :rgb_tuple, :hex_string, :term

get_color(theme, name)

Gets a color from the theme by its semantic name.

Examples

iex> theme = create_theme("dark", %{primary: "#FF0000"})
iex> get_color(theme, :primary)
%Color{r: 255, g: 0, b: 0, hex: "#FF0000"}

meets_contrast_requirements?(theme, foreground, background, level, size)

Checks if two colors meet WCAG contrast requirements.

Examples

iex> theme = create_theme("dark", %{
...>   text: "#FFFFFF",
...>   background: "#000000"
...> })
iex> meets_contrast_requirements?(theme, :text, :background, :AA, :normal)
true

to_ansi(theme, color_name, type)

Converts a color to its ANSI representation.

Examples

iex> theme = create_theme("dark", %{primary: "#FF0000"})
iex> to_ansi(theme, :primary, :foreground)
196