color_tools.naming

Color naming utilities for generating descriptive names from RGB values.

This module provides intelligent color naming that: - Matches exact CSS colors when possible - Identifies near matches to CSS colors - Generates descriptive names based on HSL properties - Avoids collisions with existing color names

color_tools.naming.get_lightness_modifier(l)

Get lightness modifier based on LAB L* value.

Parameters:

l (float) – LAB L* value (0-100)

Returns:

“very light”, “light”, “medium”, “dark”, “very dark”, or “”

Return type:

Lightness modifier

color_tools.naming.get_saturation_modifier(s, l)

Get saturation modifier based on HSL saturation and lightness.

Parameters:

• s (float) – HSL saturation (0-100)

• l (float) – LAB L* value (0-100) for context

Returns:

“pale”, “muted”, “dull”, “bright”, “deep”, “vivid”, or “”

Return type:

Saturation modifier

color_tools.naming.get_hue_with_ish(h, s)

Get “-ish” hue variant if near a boundary, otherwise None.

When a hue is within ±8° of a major hue boundary, we can describe it with an “-ish” modifier for more variety and precision.

Parameters:

• h (float) – HSL hue (0-360)

• s (float) – HSL saturation (0-100) - only apply -ish to saturated colors

Return type:

str | None

Returns:

“-ish” hue variant (e.g., “reddish orange”) or None if not near boundary

color_tools.naming.determine_base_hue(h, s, l)

Determine base hue name including special cases and “-ish” variants.

Special cases like brown, pink, gold, etc. are determined by combinations of hue, saturation, and lightness.

When near hue boundaries (±8°), returns “-ish” variants for more descriptive names (e.g., “yellowish orange”, “reddish brown”).

Parameters:

• h (float) – HSL hue (0-360)

• s (float) – HSL saturation (0-100)

• l (float) – LAB L* value (0-100)

Return type:

str

Returns:

Base hue name (e.g., “red”, “brown”, “teal”, “yellowish orange”)

color_tools.naming.get_generic_hue(h)

Get generic hue name from hue angle (fallback for collision avoidance).

This uses simple hue ranges without special cases like brown, teal, etc.

Parameters:

h (float) – HSL hue (0-360)

Return type:

str

Returns:

Generic hue name

color_tools.naming.is_unique_near_claim(rgb, css_name, palette_colors=None, threshold=5.0)

Check if this RGB is the uniquely closest color to claim “near [css_name]”.

A color can only be named “near X” if no other color in the palette would also be within threshold distance to X.

Parameters:

• rgb (tuple[int, int, int]) – RGB tuple to check

• css_name (str) – CSS color name being claimed

• palette_colors (list[tuple[int, int, int]] | None) – List of all RGB colors in the palette (optional)

• threshold (float) – Delta E threshold for “near” match

Return type:

bool

Returns:

True if this is the unique closest color to css_name

color_tools.naming.generate_color_name(rgb, palette_colors=None, near_threshold=5.0)

Generate a descriptive name for an RGB color.

This function follows a priority-based naming strategy: 1. Exact match with CSS colors 2. Near match with CSS colors (within threshold, uniquely) 3. Generated descriptive name based on HSL properties

Generated names avoid collisions with CSS color names by falling back to generic hue names when necessary.

Parameters:

• rgb (tuple[int, int, int]) – RGB tuple (0-255 for each component)

• palette_colors (list[tuple[int, int, int]] | None) – Optional list of all RGB colors in palette (for near match uniqueness)

• near_threshold (float) – Delta E threshold for “near” matches (default 5.0)

Returns:

• name: Color name string

• match_type: “exact”, “near”, or “generated”

Return type:

Tuple of (name, match_type) where

Examples

>>> generate_color_name((255, 0, 0))
('red', 'exact')

>>> generate_color_name((255, 10, 10))
('near red', 'near')

>>> generate_color_name((128, 128, 255))
('medium bright blue', 'generated')