Theme

Enabling the theme

import attaviz
attaviz.enable()                  # medium size (default)
attaviz.enable(size="small")      # charts under ~400px wide
attaviz.enable(size="large")      # charts wider than ~700px

enable() registers and activates a theme variant globally. Every subsequent Altair chart in the session picks up WBG typography, colors, grids, and mark styling.

What the theme applies

Element	WBG specification
Font	Open Sans, sans-serif
Title	18px, bold, #111111
Subtitle	15px, regular, #666666
Axis labels	13px, semibold, #111111
Tick labels	13px, regular, #666666
Grid lines	#CED4DE, 1px, dashed (4 2)
Legend	14×14px symbol dots, semibold labels
Categorical colors	9-color WBG palette
Sequential colors	WBG blue ramp (default)
Diverging colors	WBG default diverging scale
Line marks	4px stroke, round caps/joins
Point marks	1px white stroke outline
Geo shapes	0.3px grey stroke, round joins

The values above are the medium defaults. small and large scale typography and spacing proportionally.

Size system

Size	Typical width	Typography / spacing
small	under 400px	compact
medium	400–700px	default
large	over 700px	expanded

Registered names: wbg (the default medium size), wbg-small, wbg-medium, and wbg-large.

Per-chart sizing

chart = attaviz.configure_size(chart, width=600, aspect_ratio="16:9")

• width — target pixel width; the size variant is inferred automatically.
• aspect_ratio — one of "1:1", "4:3", "16:9", "21:9", or a (w, h) tuple.

Calculating dimensions

w, h = attaviz.calculate_dimensions(800, "16:9")  # → (800, 450)

Useful when you need the height up front (e.g. for a faceted chart whose rows must add up to a known total).

Size context managers

To override the active theme for a single chart (or a block of charts) without changing the global setting, use alt.theme.enable as a context manager against the registered variants:

import altair as alt

theme_registry = alt.theme if hasattr(alt, "theme") else alt.themes

with theme_registry.enable("wbg-small"):
    small_chart = make_chart().properties(width=300, height=150)

with theme_registry.enable("wbg-large"):
    large_chart = make_chart().properties(width=600, height=300)

alt.theme is the current Altair interface; the fallback keeps this example compatible with older supported Altair 5 releases. When the block exits, the previously active theme is restored.

Theme configuration

wbg_theme() returns the raw theme dictionary. Use size, width, height, and aspect_ratio to inspect or register a configuration for a specific output medium:

import altair as alt
import attaviz

@alt.theme.register("wbg-widescreen", enable=True)
def wbg_widescreen():
    return alt.theme.ThemeConfig(
        attaviz.wbg_theme(width=1200, aspect_ratio="16:9")
    )

Typography and spacing scale off the supplied width using the size breakpoints above (so a 1200px theme inherits large tokens).

The registration example uses Altair 6. With Altair 5, register the same function through the legacy alt.themes registry.

Sizing constants

For custom theming or introspection, these constants are re-exported:

• attaviz.SIZE_BREAKPOINTS — {"small": 400, "medium": 700}
• attaviz.TYPOGRAPHY — per-size font-size dicts
• attaviz.SPACING — per-size spacing tokens (xs, s, m, l, xl)
• attaviz.ASPECT_RATIOS — named ratio lookup
• attaviz.DEFAULT_DIMENSIONS — default (w, h) per size