Skip to content

Armonia

ἁρμονία
Ancient Greek; noun
The principle of order and beauty through balanced relationships.
A joining, joint; harmony, agreement, concord.

Armonia is a Python library for elegant theme management with dynamic computed colors, font definitions, and powerful transformation functions.

Built on top of polychromos, it offers:

  • Centralized Theme Management: Define all your colors, fonts, spacing, and shapes in one place.
  • Dynamic Computed Colors: Colors that automatically update when base colors change.
  • Dynamic Computed Fonts: Fonts derived from other fonts (varying size, weight, italic style, and letter spacing).
  • Color Functions: Comprehensive color transformation library (lighter, darker, mix, contrast, etc.).
  • Font Functions: Font transformation library (scale_size, bolder, lighter, italic, roman, etc.).
  • Spacing & Shape Tokens: Manage consistent spacing and corner radii throughout your application.
  • Palette System: Organize colors into named collections.
  • Logotype Management: Store and manage logo URIs alongside your theme.
  • CSS Export: Generate CSS custom properties and classes directly from the theme.
  • Serialization Support: Save and load themes from JSON/YAML or DESIGN.md files.

Installation

pip install armonia

Or using uv:

uv add armonia

Quick Start

from armonia import Theme
from armonia import colorfunctions as cf
from polychromos.color import HSLColor

# Create a theme
theme = Theme()

# Set base colors
theme.set_color("primary", HSLColor.from_hex("#2563eb"))
theme.set_color("background", HSLColor.from_hex("#ffffff"))

# Create computed colors that automatically derive from base colors
theme.set_computed_color("primary_light", cf.lighter("primary", 0.2))
theme.set_computed_color("on_primary", cf.contrast("primary"))

# Get colors - they resolve automatically
print(theme.get_color("primary_light").to_css_hex())  # #6b95f1

# Change the base color - computed colors update automatically!
theme.set_color("primary", HSLColor.from_hex("#7c3aed"))
print(theme.get_color("primary_light").to_css_hex())  # Now reflects new primary color