CMColors Utility Class

CMColors Utility Class#

The CMColors class provides a high-level utility interface for color contrast tuning and analysis.

Note

Recommendation: For object-oriented color manipulation, consider using the ColorPair Class and Color Class classes. The CMColors class is maintained for backward compatibility and for users who prefer a functional utility approach.

class cm_colors.CMColors[source]#

Bases: object

CMColors provides a comprehensive API for color accessibility and manipulation.

All core functionalities are exposed as methods of this class.

The main utility class for CM-Colors operations.

__init__()[source]#

Initializes the CMColors instance.

Currently, no specific parameters are needed for initialization.

Color Tuning#

CMColors.tune_colors(text, bg, large_text: bool = False, details: bool = False)[source]#

Adjusts the text color to meet WCAG contrast requirements against a background.

Parameters:

  • text (str | tuple) – Text color in any supported format (hex string, rgb(a) string, named color, or RGB tuple).

  • bg (str | tuple) – Background color in any supported format (hex string, rgb(a) string, named color, or RGB tuple).

  • large_text (bool) – True when text is considered large (18pt+ or 14pt+ bold); affects required WCAG level.

  • details (bool) – If True, return a detailed report instead of the simple result tuple.

Returns:

If details is False:
tuple: (tuned_text_rgb_str, is_accessible)

tuned_text_rgb_str (str): Adjusted text color as an ‘rgb(…)’ string. is_accessible (bool): True if the adjusted pair meets at least WCAG AA, False otherwise.

If details is True:
dict: Detailed report with keys:

  • text: original text color input

  • tuned_text: adjusted text color as an ‘rgb(…)’ string

  • bg: background color input

  • large: value of the large_text parameter

  • wcag_level: resulting WCAG compliance level (‘AAA’, ‘AA’, or ‘FAIL’)

  • improvement_percentage: percentage improvement in contrast

  • status: True if wcag_level != ‘FAIL’, False otherwise

  • message: human-readable status message

Return type:

tuple | dict

Adjusts a foreground color to meet WCAG contrast requirements against a background color.

Examples:

cm = CMColors()

# Simple tuning
tuned_text, is_accessible = cm.tune_colors("gray", "white")
print(f"Tuned: {tuned_text}")

# Detailed report
result = cm.tune_colors("gray", "white", details=True)
print(f"WCAG Level: {result['wcag_level']}")

Contrast Analysis#

CMColors.contrast_ratio(text_color, bg_color) → float[source]#

Compute the WCAG contrast ratio between two colors.

Parameters:

  • text_color – Text color in any supported format (hex, “rgb(…)”, “rgba(…)”, 3-tuple, named color, etc.).

  • bg_color – Background color in any supported format.

Returns:

The computed contrast ratio between the text and background colors.

Return type:

float

Raises:

ValueError – If either color cannot be parsed or the color pair is invalid.

Calculates the contrast ratio between two colors.

Returns:

float: The contrast ratio (1.0 to 21.0).

Example:

ratio = cm.contrast_ratio("#000000", "#FFFFFF")
# Returns 21.0
CMColors.wcag_level(text_color, bg_color, large_text: bool = False) → str[source]#

Determine the WCAG contrast compliance level for a text/background color pair, considering large-text rules.

Parameters:

  • text_color – Text color in any supported format (hex, rgb/rgba string, (r,g,b) tuple, named color, etc.). RGBA colors will be composited as needed.

  • bg_color – Background color in any supported format.

  • large_text (bool) – True when text is considered large (18pt+ or 14pt+ bold), False otherwise.

Returns:

‘AAA’, ‘AA’, or ‘FAIL’ indicating the WCAG compliance level.

Return type:

str

Raises:

ValueError – If one or both colors cannot be parsed or are otherwise invalid.

Determines the WCAG compliance level for a color pair.

Returns:

str: “AAA”, “AA”, or “FAIL”.

Example:

level = cm.wcag_level("#767676", "#FFFFFF")
# Returns "AA"
CMColors.delta_e(color1, color2) → float[source]#

Compute the Delta E 2000 color difference between two colors.

Accepts color inputs in any supported format (hex, rgb/rgba strings, tuples, named colors, etc.). RGBA inputs will be composited as needed before comparison.

Parameters:

  • color1 – First color (text or sample) in any supported format.

  • color2 – Second color (background or reference) in any supported format.

Returns:

The Delta E 2000 distance. Values below about 2.3 are typically imperceptible to the average observer.

Return type:

float

Calculates the Delta E (CIE 2000) distance between two colors.

Returns:

float: The perceptual difference between the colors.

Color Conversion#

CMColors.parse_to_rgb(color: str) → Tuple[int, int, int][source]#

Convert a color string in common formats to an RGB triple.

Accepts hex (#RRGGBB, #RGB), functional rgb()/rgba() (alpha composited over white), and CSS color names. Parsing is case-insensitive and will composite RGBA into an opaque RGB when an alpha channel is provided.

Parameters:

color (str) – Color value in hex, rgb(a) function notation, or named color.

Returns:

(R, G, B) with each component as an integer in the range 0–255.

Return type:

tuple

Parses a color string into an RGB tuple.

CMColors.rgb_to_oklch(rgb: Tuple[int, int, int]) → Tuple[float, float, float][source]#

Converts an RGB color to the OKLCH color space.

OKLCH is a perceptually uniform color space, making it ideal for color manipulation.

Parameters:

rgb (Tuple[int, int, int]) – The RGB tuple (R, G, B).

Returns:

The OKLCH tuple (Lightness, Chroma, Hue).

Lightness is 0-1, Chroma is 0-~0.4, Hue is 0-360.

Return type:

Tuple[float, float, float]

Converts an RGB tuple to OKLCH color space.

CMColors.oklch_to_rgb(oklch: Tuple[float, float, float]) → Tuple[int, int, int][source]#

Converts an OKLCH color back to the RGB color space.

Parameters:

oklch (Tuple[float, float, float]) – The OKLCH tuple (Lightness, Chroma, Hue).

Returns:

The RGB tuple (R, G, B).

Return type:

Tuple[int, int, int]

Converts an OKLCH tuple to RGB color space.

CMColors.rgb_to_lab(rgb: Tuple[int, int, int]) → Tuple[float, float, float][source]#

Converts an RGB color to the CIELAB (LAB) color space.

Parameters:

rgb (Tuple[int, int, int]) – RGB components (R, G, B) with values 0–255.

Returns:

LAB tuple (L, a, b) where L is perceptual lightness.

Return type:

Tuple[float, float, float]

Converts an RGB tuple to LAB color space.

Contents