Theming

Theme wraps an armonia Theme and exposes colors and fonts to chart strategies.

Colors

from orama.theme import Theme
from polychromos.color import HSLColor

theme = Theme(colors={
    # Required for all charts
    "background":              HSLColor.from_hex("#1e293b"),
    "primary_color_normal":    HSLColor.from_hex("#3b82f6"),
    # Optional — used by strategies and computed color variants
    "secondary_color_normal":  HSLColor.from_hex("#8c9aa3"),
    "accent_color_normal":     HSLColor.from_hex("#f59e0b"),
    # Optional — semantic sentiment colors
    "positive_color_normal":   HSLColor.from_hex("#22c55e"),
    "neutral_color_normal":    HSLColor.from_hex("#94a3b8"),
    "negative_color_normal":   HSLColor.from_hex("#ef4444"),
})

Computed color variants

When "background" is provided, the following computed colors are automatically registered:

• background_inverted, background_inverted_mild, background_inverted_milder, background_inverted_faint
• {prefix}_color_softer, {prefix}_color_stronger for each of primary, secondary, accent, positive, neutral, negative

When "primary_color_normal" is provided, the Plotly template's sequential and sequentialminus color scales and the figure colorway are automatically derived from the primary palette via cylindrical interpolation.

When "positive_color_normal", "neutral_color_normal", and "negative_color_normal" are all provided, a diverging color scale is also generated automatically.

Use theme.get_color(name) to retrieve any named or computed color as an HSLColor. Use theme.get_all_colors() to list all registered colors.

Fonts

Theme manages a set of named fonts via armonia's font system. The following fonts are registered automatically on every theme:

Name	Kind	Description
title	manual	Figure title — base font (default: Open Sans 17px weight 600)
subtitle	computed	70% the size of title
axis_tick	computed	60% the size of title — applied to x/y tick labels
legend	computed	60% the size of title — applied to the legend
annotation	computed	title scaled −4px, italic — for callout text

Override any of these by passing a fonts dict to the constructor:

from orama.theme import Font, Theme

theme = Theme(
    colors={"background": HSLColor.from_hex("#ffffff"), ...},
    fonts={
        "title": Font('"Open Sans", verdana, arial, sans-serif', 20.0, 700, False),
    },
)

Computed fonts (subtitle, axis_tick, legend, annotation) are re-derived from whatever title resolves to, so overriding title automatically scales all derived fonts.

Use theme.get_font(name) to retrieve any font as an armonia.typography.Font. Use theme.get_all_fonts() to list all registered fonts.

Plotly template customization hook

Theme exposes a _plotly_template_customization(template) method that is called at the end of template construction. Subclass Theme and override it to apply additional Plotly layout or trace defaults without reimplementing the full template build:

import plotly.graph_objects as go
from orama.theme import Theme

class MyTheme(Theme):
    def _plotly_template_customization(self, template: go.layout.Template) -> None:
        template.layout.colorway = ["#3b82f6", "#f59e0b", "#10b981"]

The method receives the fully built (mutable) go.layout.Template object and may modify any layout property or trace default in-place. It is called once per plot() / build() invocation and its return value is ignored.