Skip to content

Color Management

Armonia provides a sophisticated yet simple system for managing color themes in Python applications.

Dynamic Color Computation

Computed colors are functions that derive their values from other colors in the theme. When you change a base color, all computed colors update automatically:

# Define once
theme.set_color("brand", HSLColor.from_hex("#ff6b6b"))
theme.set_computed_color("brand_hover", cf.darker("brand", 0.1))
theme.set_computed_color("brand_subtle", cf.alpha("brand", 0.3))

# Update anywhere - computed colors follow
theme.set_color("brand", HSLColor.from_hex("#4ecdc4"))
# brand_hover and brand_subtle automatically reflect the new brand color

Comprehensive Color Functions

Armonia includes over 40 built-in transformation functions organized by purpose.

Lightness & Darkness

  • cf.lighter("color", 0.2): Increase lightness.
  • cf.darker("color", 0.2): Decrease lightness.
  • cf.brighten("color", 0.3): Significantly lighter.
  • cf.dim("color", 0.3): Significantly darker.

Saturation

  • cf.saturate("color", 0.2): More vivid.
  • cf.desaturate("color", 0.2): More gray.
  • cf.muted("color", 0.4): Significantly less saturated.
  • cf.grayscale("color"): Complete desaturation.

Mixing & Blending

  • cf.mix("color1", "color2", 0.5): Blend two colors.
  • cf.tint("color", 0.2): Mix with white.
  • cf.shade("color", 0.2): Mix with black.
  • cf.tone("color", 0.2): Mix with gray.
  • cf.softer("color", "background", 0.3): Shift toward background.

Opacity

  • cf.alpha("color", 0.5): Set opacity.
  • cf.fade("color", 0.3): Alias for alpha.

Advanced Transformations

  • cf.rotate_hue("color", 180): Rotate hue by degrees.
  • cf.complementary("color"): Opposite on color wheel.
  • cf.invert("color"): Invert lightness.
  • cf.contrast("color"): Choose black or white for optimal contrast.
  • cf.alias("color"): Reference another color by name.

Color Palettes

Organize related colors into named palettes:

# Define a palette
theme.set_palette("primary_scale", [
    "primary_dark",
    "primary",
    "primary_light",
    "primary_bright"
])

# Get all colors in the palette
colors = theme.get_palette("primary_scale")  # Returns List[HSLColor]

Flexible Resolution

The get_color() method resolves colors with a smart fallback chain:

  1. Theme colors: Explicitly set with set_color.
  2. Computed colors: Set with set_computed_color.
  3. Web colors: CSS/HTML standard color names (e.g., "tomato", "skyblue").
  4. Hex colors: Direct hex parsing (e.g., "#3498db").

Listing Colors

Retrieve and sort all theme colors:

# Sort by name, hue, saturation, or lightness
colors = theme.get_all_colors(sort_by="hue")

for entry in colors:
    print(f"{entry.name}: {entry.color.to_css_hex()} ({entry.source})")