Referência da API

Os símbolos públicos do tempest_core, gerados a partir das docstrings.

tempest-core — the renderer-agnostic core shared across the tempest stack.

The engine behind both tempestroid (native renderers) and tempestweb (DOM): the IR, reconciler, state model, style model, widgets, components and the cross-cutting helpers (animation, i18n, navigation, theme, validators). It carries no platform-coupled code (no Qt, no JNI, no Android, no DOM) so it imports cleanly under CPython, Pyodide and a headless server.

This is the single source of truth — consumers depend on the published package and import from here (from tempest_core import App, Column, build, diff) rather than vendoring a copy.

AnimationController

Drives a normalized value on the app's frame clock.

A controller is renderer-agnostic: it owns only its progress (value, 0.0..1.0), the direction it is moving (forward toward 1.0, reverse toward 0.0), and how to advance — either an eased ramp over duration_s or a :class:Spring integration. The app's clock calls :meth:_advance once per frame with the elapsed dt and removes the controller when it reports completion.

The controller binds to an app lazily: it stores no App reference until :meth:forward/:meth:reverse is called after the app has registered it (via :meth:bind), so a controller can be constructed in a view without a circular import.

Attributes:

Name	Type	Description
value	float	The current progress, 0.0..1.0 — read by the view.

Methods:

Name	Description
bind	Attach the controller to an app's frame clock.
forward	Animate value toward 1.0 and (re)register on the app clock.
reverse	Animate value toward 0.0 and (re)register on the app clock.
stop	Halt the animation and unregister from the app clock.

__init__(duration_s, curve=Curve.EASE_IN_OUT, spring=None, *, time_source=None)

Initialize the controller.

Parameters:

Name	Type	Description	Default
duration_s	float	The ramp duration in seconds (ignored when spring is given). Must be positive for a fixed-duration ramp.	required
curve	Curve	The easing curve applied to the linear ramp.	EASE_IN_OUT
spring	Spring | None	Optional spring parameters; when set, the controller integrates a damped oscillator instead of easing over a fixed duration.	None
time_source	Callable[[], float] | None	Optional injectable monotonic clock (seconds). Tests pass a deterministic source; in production the app supplies its own loop clock, so this is normally left unset.	None

bind(app)

Attach the controller to an app's frame clock.

Called by :meth:~tempestroid.core.state.App.register_animation so a later :meth:stop can unregister, and so :meth:forward/:meth:reverse can (re)register even if invoked after construction.

Parameters:

Name	Type	Description	Default
app	_AppClock	The app driving this controller's frames.	required

forward()

Animate value toward 1.0 and (re)register on the app clock.

reverse()

Animate value toward 0.0 and (re)register on the app clock.

stop()

Halt the animation and unregister from the app clock.

Alert

Bases: Component

A block-level status callout: optional icon glyph, title, body and dismiss.

The richer sibling of :class:Banner, lowered through the same :func:~tempest_core.variants.resolve_alert_variant resolver: a row with an optional leading glyph and an optional trailing dismiss widget around a column that stacks the title (bold) over the body text. Use variant=LEFT_ACCENT for the classic accented-edge callout.

Attributes:

Name	Type	Description
title	str	The alert's headline (bold).
body	str | None	An optional secondary line of detail.
glyph	str | None	An optional leading text glyph (no icon font needed).
color_scheme	str	The Material 3 status family to tint with (default "info").
variant	AlertVariant	The alert treatment (subtle / solid / left_accent / top_accent).
dismiss	Widget | None	An optional trailing dismiss widget (e.g. a close Button).
theme	Theme	The design-system theme whose tokens resolve the treatment.

render()

Lower the alert into a themed primitive row.

Returns:

Type	Description
Widget	A themed Row of an optional glyph, the title/body column and an
Widget	optional dismiss widget.

Badge

Bases: Component

A small inline status pill (count or short label).

Themed (Trilho H4): the pill treatment comes from :func:~tempest_core.variants.resolve_badge_variant against the theme (a Material 3 solid/subtle/outline badge) rather than a hard-coded hex. The legacy tone prop is mapped onto a color_scheme, so Badge(tone="error") keeps working; pass color_scheme / variant / size for the full API.

Attributes:

Name	Type	Description
label	str	The badge text (e.g. a count like "3" or "NEW").
tone	str	The legacy status tone, mapped onto color_scheme when unset.
color_scheme	str | None	The Material 3 status family to tint with; derived from tone when None.
variant	BadgeVariant	The badge treatment (solid / subtle / outline).
size	ResponsiveSize	The density size of the pill.
theme	Theme	The design-system theme whose tokens resolve the treatment.
media	MediaQueryData | None	Optional viewport snapshot for a responsive size.

render()

Lower the badge into a primitive pill.

Returns:

Type	Description
Widget	A small rounded Text pill in the resolved badge style.

Banner

Bases: Component

An inline status bar with a message and an optional trailing action.

Themed (Trilho H4): the background/content come from the :func:~tempest_core.variants.resolve_alert_variant resolver against the theme (a Material 3 subtle alert by default) rather than a hard-coded hex. The legacy tone prop is mapped onto a color_scheme, so Banner(tone="success") keeps working; pass color_scheme / variant directly for the full H4 API.

Attributes:

Name	Type	Description
message	str	The banner text.
tone	str	The legacy status tone ("info" / "success" / "warning" / "error"); mapped onto color_scheme when the latter is unset.
color_scheme	str | None	The Material 3 status family to tint with; None derives it from tone.
variant	AlertVariant	The alert treatment (subtle / solid / left_accent / top_accent).
action	Widget | None	An optional trailing widget (e.g. a dismiss Button).
theme	Theme	The design-system theme whose tokens resolve the treatment.

render()

Lower the banner into a primitive row.

Returns:

Type	Description
Widget	A themed Row with the growing message and the optional action.

BarChart

Bases: _ChartBase

A bar chart drawn over a :class:~tempest_core.widgets.Canvas.

Accepts either a list of :class:ChartSeries (the first series' points become the bars) or, for the trivial single-series case, a plain values list (+ optional labels). Each bar is a :class:~tempest_core.widgets.DrawRect + a :class:~tempest_core.widgets.FillCmd over the shared framed plot rect; the command list is deterministic, so the conformance suite pins it. No new draw command is introduced.

Attributes:

Name	Type	Description
series	list[ChartSeries]	The data series (the first series is plotted as bars). Optional when values is given.
values	list[float]	A convenience single-series value list (used when series is empty).
labels	list[str]	Optional x-axis labels for the bars.

render()

Lower the bar chart into a Canvas of axis + bar commands.

Returns:

Name	Type	Description
A	Widget	class:~tempest_core.widgets.Canvas carrying the deterministic
	Widget	draw-command list.

ChartSeries

Bases: BaseModel

A single named, optionally-colored data series for a chart.

A chart takes a list of these rather than bare list[float] so it can plot several series at once, each with its own label and (optionally) its own color_scheme; an unset color_scheme lets the chart pick from its rotating themed palette by series index.

Attributes:

Name	Type	Description
points	list[float]	The series' y-values, in plot order (one per x position).
label	str	An optional series label (e.g. for a legend; not drawn by the minimal v1 charts but carried for the renderers/legend to read).
color_scheme	str | None	An optional Material 3 role family to color this series with; None falls back to the chart's rotating palette.

Chip

Bases: Component

A small rounded label, optionally selectable, themed via the badge resolver.

Themed (Trilho H4): the pill treatment comes from :func:~tempest_core.variants.resolve_badge_variant against the theme — a solid badge when selected, a subtle badge otherwise. A tappable chip (on_click set) lowers to a Button carrying the resolved badge style; a presentational chip lowers to a Text pill.

Attributes:

Name	Type	Description
label	str	The chip text.
selected	bool	Whether the chip reads as active (a solid badge vs a subtle one).
on_click	Callable[[], Any] | None	Optional tap handler; when None the chip is presentational.
color_scheme	str	The Material 3 role family the chip tints with.
size	ResponsiveSize	The density size of the pill.
theme	Theme	The design-system theme resolving the chip treatment.
media	MediaQueryData | None	Optional viewport snapshot for a responsive size.

render()

Lower the chip into a primitive button or a static pill.

Returns:

Type	Description
Widget	A Button when on_click is set, otherwise a Text pill.

ConfidenceBadge

Bases: Component

A status pill showing a model's confidence, colored by threshold.

Composes the H4 :class:~tempest_core.components.Badge, picking its color_scheme from :func:confidence_scheme (success / warning / error) and labelling it as a rounded percentage ("92%"). Optionally prefixes a class name ("cat 92%").

Attributes:

Name	Type	Description
confidence	float	The model confidence in [0, 1].
label	str	An optional prefix (e.g. the predicted class) shown before the percentage.
high	float	The success threshold passed to :func:confidence_scheme.
mid	float	The warning threshold passed to :func:confidence_scheme.
theme	Theme	The design-system theme whose tokens resolve the pill.

render()

Lower the confidence badge into a themed status pill.

Returns:

Name	Type	Description
A	Widget	class:~tempest_core.components.Badge whose color_scheme and
	Widget	label encode the confidence.

DetectionBox

Bases: BaseModel

A normalized object-detection bounding box (xyxy in [0, 1]).

Coordinates are fractions of the canvas width/height (0 = left/top, 1 = right/bottom), so a box is resolution-independent and multiplied by the canvas pixel size at draw time. This mirrors the common normalized-xyxy convention without depending on ort-vision-sdk — an adapter from a Detection result lives on the tempestroid side.

Attributes:

Name	Type	Description
x1	float	The left edge as a fraction of the canvas width ([0, 1]).
y1	float	The top edge as a fraction of the canvas height ([0, 1]).
x2	float	The right edge as a fraction of the canvas width ([0, 1]).
y2	float	The bottom edge as a fraction of the canvas height ([0, 1]).
name	str	An optional class label drawn beside the box.
conf	float	The detection confidence in [0, 1] (drives the box color and the label percentage).

DetectionOverlay

Bases: Component

An image with object-detection boxes drawn on top of it.

Lowers to a :class:~tempest_core.widgets.Stack of a base :class:~tempest_core.widgets.Image (fit=COVER) and a :class:~tempest_core.widgets.Canvas overlay. Each :class:DetectionBox (normalized xyxy) is multiplied by the canvas size and drawn as a stroked rectangle (:class:~tempest_core.widgets.DrawRect + :class:~tempest_core.widgets.StrokeCmd) colored by :func:confidence_scheme, with a small filled label background (:class:~tempest_core.widgets.DrawRect + :class:~tempest_core.widgets.FillCmd) and a "{name} {conf:.0%}" caption (:class:~tempest_core.widgets.DrawText). No new draw command is introduced.

Attributes:

Name	Type	Description
image_src	str	The image source (URL or asset path) to box over.
boxes	list[DetectionBox]	The normalized detection boxes to draw.
width	float	The canvas/image width, in logical pixels.
height	float	The canvas/image height, in logical pixels.
high	float	The success threshold passed to :func:confidence_scheme.
mid	float	The warning threshold passed to :func:confidence_scheme.
theme	Theme	The design-system theme whose tokens supply the label color.

render()

Lower the overlay into a stack of an image and a box canvas.

Returns:

Name	Type	Description
A	Widget	class:~tempest_core.widgets.Stack of the base image and the
	Widget	detection-box canvas, sized to width × height.

EmptyState

Bases: Component

A centered placeholder for empty screens: glyph, title, subtitle, action.

Themed (Trilho H4): the glyph/subtitle read the muted ON_SURFACE_VARIANT role, the title reads ON_SURFACE, and the gaps/padding come from the theme's spacing scale rather than fixed pixels.

Attributes:

Name	Type	Description
title	str	The primary message.
subtitle	str | None	An optional secondary line.
glyph	str	A large text glyph shown above the title (no icon font needed).
action	Widget | None	An optional call-to-action widget (e.g. a Button).
theme	Theme	The design-system theme whose tokens supply colors and spacing.

render()

Lower the empty state into a centered primitive column.

Returns:

Type	Description
Widget	A Column stacking the glyph, title, optional subtitle and action.

HStack

Bases: Component

A horizontal stack: children laid left-to-right with a token-step gap.

A thin, SwiftUI-style ergonomic wrapper over the primitive :class:~tempest_core.widgets.Row. The gap is a token-step name ("md" / "lg") resolved against the theme's spacing scale, or a raw float for backward-compatibility; align (cross-axis) and justify (main-axis) are surfaced directly so the common layout is one call. An explicit style is merged on top of the resolved defaults.

Attributes:

Name	Type	Description
children	list[Widget]	The ordered child widgets, laid left-to-right.
gap	float | str	The spacing between children — a token-step name ("md") or a float in logical pixels.
align	AlignItems | None	The cross-axis (vertical) alignment of the children.
justify	JustifyContent | None	The main-axis (horizontal) distribution of the children.
theme	Theme	The design-system theme whose spacing scale resolves the gap.

render()

Lower the horizontal stack into a primitive Row.

Returns:

Type	Description
Widget	A Row carrying the resolved gap/align/justify, with any explicit
Widget	style merged on top.

LineChart

Bases: _ChartBase

A multi-series line chart drawn over a :class:~tempest_core.widgets.Canvas.

Each :class:ChartSeries becomes a connected polyline (:class:~tempest_core.widgets.MoveTo + a run of :class:~tempest_core.widgets.LineTo + one :class:~tempest_core.widgets.StrokeCmd) over a shared, framed plot rect with y-axis gridlines and right-aligned tick labels. The command list is deterministic for fixed input, so the conformance suite pins it. No new draw command is introduced.

Attributes:

Name	Type	Description
series	list[ChartSeries]	The data series to plot (each its own polyline + color).

render()

Lower the line chart into a Canvas of axis + polyline commands.

Returns:

Name	Type	Description
A	Widget	class:~tempest_core.widgets.Canvas carrying the deterministic
	Widget	draw-command list.

MetricCard

Bases: Component

A dashboard metric inside a themed card: label, value and optional trend.

Composes the H3 :class:~tempest_core.components.Card (the surface) around the H4 :class:~tempest_core.components.Stat (the label/value/delta block), with an optional trailing slot (e.g. a sparkline :class:LineChart or an icon). No new primitive is introduced — it is Card + Stat.

Attributes:

Name	Type	Description
label	str	The metric's caption (muted).
value	str	The metric's value (large, prominent).
delta	str | None	An optional trend line (e.g. "+12%"); None hides it.
delta_up	bool	Whether the delta is positive (success-tinted) or negative (error-tinted).
color_scheme	str	The Material 3 role family the card surface tints with.
variant	CardVariant	The card surface treatment (elevated / filled / outlined).
trailing	Widget | None	An optional widget shown to the right of the stat block.
theme	Theme	The design-system theme whose tokens resolve the surface and stat.
media	MediaQueryData | None	Optional viewport snapshot (accepted for parity; unused).

render()

Lower the metric card into a themed card wrapping a stat.

Returns:

Name	Type	Description
A	Widget	class:~tempest_core.components.Card containing the stat block and,
	Widget	when set, a trailing widget laid out in a centered Row-like column.

ProgressStepper

Bases: Component

A horizontal wizard / progress stepper showing labelled, numbered steps.

Lays out the steps in a row: each step is a small numbered circle (a filled accent disc for done/active steps, a muted outline for pending ones) above its label, joined by connector rules. The colors are theme-driven: done/active steps read the color_scheme role; pending steps read the muted ON_SURFACE_VARIANT role. Named ProgressStepper to avoid colliding with the numeric :class:~tempest_core.components.Stepper (a +/- number spinner).

Attributes:

Name	Type	Description
steps	list[str]	The step labels, in order.
current	int	The index of the active step (steps before it read as done).
color_scheme	str	The Material 3 role family the done/active steps paint with.
theme	Theme	The design-system theme resolving the step colors and spacing.

render()

Lower the stepper into a primitive row of step cells.

Returns:

Type	Description
Widget	A Row of step cells joined by flexible connector spaces.

ResultView

Bases: Component

The image-picker → result flow: pick an image, then show its result.

Stacks an :class:~tempest_core.components.ImagePicker over an optional result slot — the widget the app builds from the model output (e.g. a :class:DetectionOverlay, a :class:MetricCard, a :class:ConfidenceBadge or a chart). The app owns the inference + builds the result; this component only arranges the picker and the result.

Attributes:

Name	Type	Description
value	str	The picked image URI (forwarded to the picker; "" until one is chosen).
label	str	An optional heading shown above the picker.
on_pick	Callable[[str], Any]	Called with the picked image URI on selection.
result	Widget | None	The optional result widget shown below the picker; None shows only the picker.
theme	Theme	The design-system theme whose tokens supply the spacing.

render()

Lower the result view into a column of the picker and the result.

Returns:

Name	Type	Description
A	Widget	class:~tempest_core.widgets.Column of the
	Widget	class:~tempest_core.components.ImagePicker and, when set, the result
	Widget	widget.

Stat

Bases: Component

A labelled metric with a value and an optional trend delta.

A compact dashboard stat: a muted label over a large value, with an optional delta line tinted by the H4 success (up) or error (down) status role depending on delta_up — the canonical "▲ +12%" / "▼ -3%" trend cue.

Attributes:

Name	Type	Description
label	str	The metric's caption (muted).
value	str	The metric's value (large, prominent).
delta	str | None	An optional trend line (e.g. "+12%"); None hides it.
delta_up	bool	Whether the delta is positive (success-tinted) or negative (error-tinted).
theme	Theme	The design-system theme whose tokens supply colors and spacing.

render()

Lower the stat into a primitive column.

Returns:

Type	Description
Widget	A Column of the muted label, the prominent value and an optional
Widget	status-tinted delta.

StatCard

Bases: MetricCard

A compact preset of :class:MetricCard (a filled, tighter card).

Exactly a :class:MetricCard with a denser default surface (filled, smaller padding) — handy for a tight grid of stats. Every MetricCard prop still applies; override variant / padding via style to retune.

Attributes:

Name	Type	Description
variant	CardVariant	Defaults to filled for the compact look (overridable).

StyledContainer

Bases: Component

A themed single-child box with token-step padding over the IR Container.

The thin, additive wrapper that gives the primitive :class:~tempest_core.widgets.Container design-system ergonomics — a token-step padding ("md" / "lg" / a raw float) resolved against the theme's spacing scale — without mutating the IR primitive, which stays pure. A bare padding float keeps backward-compatibility; a step name resolves via :meth:~tempest_core.theme.Theme.space. An explicit style is merged on top.

Attributes:

Name	Type	Description
child	Widget | None	The optional wrapped widget.
padding	float | str	The inner padding — a token-step name ("md") or a raw float in logical pixels.
theme	Theme	The design-system theme whose spacing scale resolves a step name.

render()

Lower the styled container into a primitive padded container.

Returns:

Type	Description
Widget	A Container whose style.padding is the resolved token-step (or
Widget	float) padding, with any explicit style merged on top.

Surface

Bases: Component

A themed, un-padded single-child box — the surface primitive cards build on.

Resolves its :class:~tempest_core.style.Style from variant / color_scheme / elevation against the design-system theme via :func:~tempest_core.variants.resolve_surface_variant, then merges the caller's explicit style on top (its set fields win, so hand-styling still works and stays backward-compatible). Unlike :class:~tempest_core.components.Card it adds no inner padding or gap — it is the bare surface, leaving content layout to whatever it wraps. Card is exactly Surface + padding + a Column.

Attributes:

Name	Type	Description
child	Widget | None	The optional wrapped widget.
variant	CardVariant	The surface treatment (elevated / filled / outlined).
color_scheme	str	The Material 3 role family to tint with ("neutral" uses the plain surface roles; a role family uses the tonal container roles).
elevation	int | None	An explicit Material 3 elevation level (0-5) overriding the variant default; None uses the per-variant default.
radius_step	str	The shape-scale step name for the corner radius.
theme	Theme	The design-system theme whose tokens resolve the surface.
media	MediaQueryData | None	Optional viewport snapshot (accepted for parity; unused here).

render()

Lower the surface into a themed single-child container.

Returns:

Type	Description
Widget	A Container carrying the resolved surface style (no inner padding
Widget	of its own beyond the resolver's), wrapping the child.

Tabs

Bases: Component

A tab strip whose active tab carries an underline indicator.

Themed (Trilho H5): the strip is a :func:~tempest_core.variants.resolve_surface_variant surface; each tab is a :func:~tempest_core.variants.resolve_variant (GHOST, neutral) text; the active tab takes the color_scheme role color plus a thin underline indicator — a one-pixel-tall bottom :class:~tempest_core.style.SideBorder in the accent role (existing Border / SideBorder fields, no new style field). Mirrors :class:NavBar's lowering and the same zero-argument select handler. Tabs is presentational selection: the active index lives in app state, toggled from on_select.

Attributes:

Name	Type	Description
tabs	list[str]	The visible tab labels, in order.
active	int	The index of the currently selected tab.
on_select	Callable[[int], Any]	Called with the tapped tab's index when a tab is pressed.
color_scheme	str	The Material 3 role family the active tab + underline use.
size	ResponsiveSize	The density size — a single :class:~tempest_core.style.Size or a per-breakpoint map.
theme	Theme	The design-system theme whose tokens resolve the strip and tabs.
media	MediaQueryData | None	Optional viewport snapshot used to resolve a responsive size.

render()

Lower the tab strip into a primitive row of tab buttons.

Returns:

Type	Description
Widget	A Row of GHOST tab buttons with the active one underlined,
Widget	carrying the resolved surface strip style.

Tag

Bases: Chip

A closed, non-selectable label — a thin preset of :class:Chip.

A Tag is exactly a :class:Chip fixed to its presentational, low-emphasis form: never selectable and never tappable (selected and on_click are not exposed), so it always lowers to a static subtle badge Text pill. It carries the same theming props (color_scheme / size / theme) as Chip and reuses :func:~tempest_core.variants.resolve_badge_variant. Use it for read-only category/status labels where a Chip's interactivity is wrong.

VStack

Bases: Component

A vertical stack: children laid top-to-bottom with a token-step gap.

The vertical sibling of :class:HStack over the primitive :class:~tempest_core.widgets.Column. The gap is a token-step name resolved against the theme's spacing scale (or a raw float); align (cross-axis, horizontal) and justify (main-axis, vertical) are surfaced directly. An explicit style is merged on top.

Attributes:

Name	Type	Description
children	list[Widget]	The ordered child widgets, laid top-to-bottom.
gap	float | str	The spacing between children — a token-step name ("md") or a float in logical pixels.
align	AlignItems | None	The cross-axis (horizontal) alignment of the children.
justify	JustifyContent | None	The main-axis (vertical) distribution of the children.
theme	Theme	The design-system theme whose spacing scale resolves the gap.

render()

Lower the vertical stack into a primitive Column.

Returns:

Type	Description
Widget	A Column carrying the resolved gap/align/justify, with any
Widget	explicit style merged on top.

App

Bases: Generic[S]

Owns app state and drives coalesced rebuilds.

The view receives the app itself, so it can read app.state and wire handlers that call :meth:set_state (sync or from inside an async handler). This avoids any circular dependency between the view and the app.

The app also owns a :class:~tempestroid.navigation.NavStack (self.nav), independent of the generic state S. The view reads app.nav.top to decide which screen to build; :meth:push/:meth:pop/:meth:replace/ :meth:reset mutate the stack and schedule the same coalesced rebuild as a state change, so navigation flows through the existing diff with no new patch kind.

The type parameter S is the application state type.

Methods:

Name	Description
start	Build the initial scene and record it as the current tree.
set_state	Mutate state (optionally) and request a coalesced rebuild.
swap_view	Swap the view function and rebuild against live state.
request_rebuild	Schedule a single coalesced rebuild on the event loop.
push / pop / replace / reset	Navigation-stack mutations (each rebuilds).
show_dialog / show_sheet / show_menu / toast	Push an overlay layer entry.
dismiss	Remove an overlay by id and request a rebuild.
set_theme / set_locale	Swap the active theme/locale and rebuild.
slide_window / slide_section_window	Set a virtualized list's visible window.
register_animation / unregister_animation	Manage the frame-clock controllers.

Properties

current_tree: The most recently built scene (None before start). has_animations: Whether any animation controller is active on the clock.

has_animations property

Whether at least one animation controller is active on the frame clock.

The device bridge reads this when serializing a mount/patch so the Compose host knows whether to run its withFrameNanos loop (and emit the reserved __frame__ token). It flips True as soon as a controller is registered (:meth:register_animation) and back to False once the last controller settles and is dropped by :meth:_tick/:meth:_tick_from_device.

Returns:

Type	Description
bool	True when one or more controllers are active, False otherwise.

current_tree property

The most recently built scene (None before :meth:start).

Returns:

Type	Description
Scene | None	The current scene, or None.

__init__(state, view, apply_patches, nav=None, *, time_source=None, theme=None, media=None, locale=None)

Initialize the app.

Parameters:

Name	Type	Description	Default
state	S	The initial application state.	required
view	Callable[[App[S]], Widget]	Builds the widget tree from the app (reads app.state and app.nav.top).	required
apply_patches	Callable[[list[Patch]], None]	Renderer callback that applies a patch list.	required
nav	NavStack | None	The initial navigation stack. Defaults to a fresh :class:~tempestroid.navigation.NavStack with the root route.	None
time_source	Callable[[], float] | None	Optional monotonic clock (seconds) used by the animation frame loop to compute the per-frame dt. Tests inject a deterministic source; the Qt runner passes loop.time. Defaults to the event loop's clock.	None
theme	Theme | None	The initial theme context the view reads. Defaults to a fresh :class:~tempestroid.theme.Theme (SYSTEM mode).	None
media	MediaQueryData | None	The initial media-query context the view reads. Defaults to a fresh :class:~tempestroid.theme.MediaQueryData.	None
locale	Locale | None	The initial locale context the view reads. Defaults to a fresh :class:~tempestroid.i18n.Locale (pt, LTR).	None

start()

Build the initial scene and record it as the current tree.

Returns:

Name	Type	Description
The	Scene	class:Scene (root tree + overlay layer), ready to hand to a
	Scene	renderer's mount.

swap_view(view)

Swap the view function and rebuild against the live state.

This is stateful hot reload: unlike a hot restart (which throws the state away and remounts), it keeps the current state object and diffs the tree built by the new view against the current tree, so on-screen state survives a code edit. The new tree is built eagerly (synchronously) so an incompatible view — e.g. one reading a state attribute the preserved state lacks — raises here and the old view stays installed, letting the caller fall back to a clean restart.

Parameters:

Name	Type	Description	Default
view	Callable[[App[S]], Widget]	The new view function (typically from a reloaded module).	required

Returns:

Type	Description
list[Patch]	The patches applied to reconcile the new tree ([] if unchanged).

Raises:

Type	Description
RuntimeError	If called before :meth:start.
Exception	Whatever the new view/build raises — the swap is rolled back (the old view stays installed) before re-raising.

set_state(mutate=None)

Mutate state (optionally) and request a coalesced rebuild.

Parameters:

Name	Type	Description	Default
mutate	Callable[[S], None] | None	Optional callback that mutates self.state in place.	None

set_theme(theme)

Swap the active theme and request a coalesced rebuild.

The view reads app.theme on the next build, so toggling dark/light (or a palette) flows through the existing diff with no new patch kind.

Parameters:

Name	Type	Description	Default
theme	Theme	The new theme context.	required

set_locale(locale)

Swap the active locale and request a coalesced rebuild.

The view reads app.locale (language for string lookup, locale.rtl for layout direction) on the next build.

Parameters:

Name	Type	Description	Default
locale	Locale	The new locale context.	required

slide_window(key, start, end)

Set the visible window of a virtualized list and request a rebuild.

A renderer (or the device bridge) calls this from a list's scroll handler: the new [start, end) window is recorded by the list's key and injected into the next build, so :class:LazyColumn/:class:LazyRow/ :class:LazyGrid materialize the slid window. Through the keyed diff this becomes a minimal remove/reorder/insert patch sequence.

Parameters:

Name	Type	Description	Default
key	str	The key of the target list widget.	required
start	int	The first visible index (inclusive).	required
end	int	The one-past-last visible index (exclusive).	required

slide_section_window(key, section_title, start, end)

Set the visible window of one section of a :class:SectionList.

Parameters:

Name	Type	Description	Default
key	str	The key of the target :class:SectionList widget.	required
section_title	str	The title of the section to slide.	required
start	int	The first visible index (inclusive) within that section.	required
end	int	The one-past-last visible index (exclusive) within that section.	required

push(route)

Push a route onto the navigation stack and request a rebuild.

Parameters:

Name	Type	Description	Default
route	Route	The destination route to navigate to.	required

pop()

Pop the top route, returning to the previous screen.

At the root (a single route on the stack) this is a no-op: the stack is left untouched so the host can take its default back action (e.g. close the app on Android).

Returns:

Type	Description
bool	True if a route was popped, False if already at the root.

replace(route)

Replace the top route in place (no stack-depth change).

Parameters:

Name	Type	Description	Default
route	Route	The route to put on top, replacing the current screen.	required

reset(stack)

Replace the entire navigation stack and request a rebuild.

Parameters:

Name	Type	Description	Default
stack	list[Route]	The new, non-empty route stack (e.g. for a deep link).	required

Raises:

Type	Description
ValueError	If stack is empty — an app must always have a screen.

show_dialog(widget, *, barrier=True)

Push a modal dialog onto the overlay layer.

Parameters:

Name	Type	Description	Default
widget	Widget	The dialog widget (typically a :class:~tempestroid.Dialog).	required
barrier	bool	Whether a touch-blocking scrim sits behind the dialog.	True

Returns:

Type	Description
str	The stable overlay id, for a later :meth:dismiss.

show_sheet(widget, *, barrier=True)

Push a bottom sheet onto the overlay layer.

Parameters:

Name	Type	Description	Default
widget	Widget	The sheet widget (typically a :class:~tempestroid.BottomSheet).	required
barrier	bool	Whether a touch-blocking scrim sits behind the sheet.	True

Returns:

Type	Description
str	The stable overlay id, for a later :meth:dismiss.

show_menu(widget, *, anchor=None, barrier=False)

Push a menu or popover onto the overlay layer.

Parameters:

Name	Type	Description	Default
widget	Widget	The menu widget (typically a :class:~tempestroid.Menu or :class:~tempestroid.Popover). When it exposes an anchor field and anchor is given, the anchor is applied to the widget so the renderer can position the menu.	required
anchor	str | None	Optional key of the widget to anchor the menu to.	None
barrier	bool	Whether a touch-blocking scrim sits behind the menu (menus are usually anchored and barrier-free).	False

Returns:

Type	Description
str	The stable overlay id, for a later :meth:dismiss.

toast(widget, *, duration_s=2.5)

Push a transient toast that auto-dismisses after duration_s.

The auto-dismiss is scheduled on the event loop via call_later; the app remains authoritative over the toast's lifetime even if a renderer also runs its own visual timer.

Parameters:

Name	Type	Description	Default
widget	Widget	The toast widget (typically a :class:~tempestroid.Toast).	required
duration_s	float	How long the toast stays visible, in seconds.	2.5

Returns:

Type	Description
str	The stable overlay id (also dismissable early via :meth:dismiss).

dismiss(overlay_id)

Remove an overlay by id and request a rebuild.

A no-op when the id is unknown (e.g. a toast already auto-dismissed, or a double dismiss), so renderer-driven and timer-driven dismissals are safe to race.

Parameters:

Name	Type	Description	Default
overlay_id	str	The id returned by a show_*/toast call.	required

register_animation(ctrl)

Register an active animation controller on the frame clock.

Binds the controller to this app (so it can later unregister itself) and starts the frame clock if it was idle. Registering an already-tracked controller is a no-op beyond (re)binding, so repeated :meth:~tempestroid.animation.AnimationController.forward calls are safe.

Parameters:

Name	Type	Description	Default
ctrl	AnimationController	The controller to drive on each frame.	required

unregister_animation(ctrl)

Remove a controller from the frame clock.

A no-op when the controller is not tracked (e.g. a double :meth:~tempestroid.animation.AnimationController.stop). The clock stops re-arming once the set drains.

Parameters:

Name	Type	Description	Default
ctrl	AnimationController	The controller to remove.	required

request_rebuild()

Schedule a single rebuild on the event loop.

Repeated calls before the loop next runs are coalesced into one rebuild.

Insert

Bases: _IRModel

Insert node as a new child at index under path.

Attributes:

Name	Type	Description
path	Path	Address of the parent node.
index	int	Position among the parent's children for the new node.
node	Node	The subtree to insert.

Node

Bases: _IRModel

A normalized, renderer-agnostic UI node.

Attributes:

Name	Type	Description
type	str	The widget type tag (e.g. "Text", "Column").
key	str | None	Optional stable identity used to match nodes across rebuilds.
props	dict[str, Any]	Renderable properties (style, text, label, handlers, ...), excluding children. Values are compared by equality during diffing.
children	list[Node]	Ordered child nodes.

OverlayEntry dataclass

One slot in the app's floating overlay layer.

Attributes:

Name	Type	Description
id	str	Stable overlay id (a UUID), used as the overlay node's key.
widget	Widget	The overlay's widget tree.
barrier	bool	Whether a touch-blocking scrim sits behind the overlay.
is_toast	bool	Whether this overlay auto-dismisses on a timer (a toast).

Remove

Bases: _IRModel

Remove the child at index under path.

Attributes:

Name	Type	Description
path	Path	Address of the parent node.
index	int	Position of the child to remove.

Reorder

Bases: _IRModel

Reorder the children under path according to order.

Attributes:

Name	Type	Description
path	Path	Address of the parent node.
order	list[int]	A permutation where order[i] is the old index of the child that must end up at new index i. The renderer rebuilds the child list as [old_children[order[i]] for i in ...].

Replace

Bases: _IRModel

Replace the whole subtree at path with node.

Emitted when the node type or key changes — the old subtree cannot be updated in place, so the renderer rebuilds it from scratch.

Attributes:

Name	Type	Description
path	Path	Address of the node to replace.
node	Node	The new subtree.

Scene

Bases: _IRModel

A full UI document: the root tree plus a z-ordered overlay layer.

A scene is the unit the runtime builds and diffs once overlays exist. The root is the ordinary screen tree; overlays is the floating layer (dialogs, sheets, toasts, menus) rendered above it in ascending z-order. Each overlay node carries its stable overlay id as its key so the keyed diff can match overlays across rebuilds. An empty overlays list reduces a scene to its root tree, so the no-overlay path is unchanged.

Attributes:

Name	Type	Description
root	Node	The root screen node.
overlays	list[Node]	The floating overlay nodes, in ascending z-order. Each node's key is its stable overlay id.

Update

Bases: _IRModel

Update the props of the node at path in place.

Attributes:

Name	Type	Description
path	Path	Address of the node to update.
set_props	dict[str, Any]	Props to add or overwrite.
unset_props	list[str]	Prop names to remove (reset to the renderer default).

Locale

Bases: BaseModel

An immutable locale: language, optional region, and layout direction.

Attributes:

Name	Type	Description
language	str	The BCP-47 language tag (e.g. "pt", "en", "ar").
region	str | None	The optional region/country subtag (e.g. "BR", "US").
rtl	bool	Whether the locale lays out right-to-left (e.g. Arabic, Hebrew).

Properties

tag: The locale as a BCP-47 tag (language or language-REGION).

tag property

Render the locale as a BCP-47 tag (language or language-REGION).

Returns:

Type	Description
str	The composed tag, e.g. "pt-BR" or "pt".

NavStack

Bases: BaseModel

The ordered stack of routes, from root to the visible screen.

Unlike :class:Route, the stack is mutable: :class:~tempestroid.App pushes, pops, replaces and resets it in place and schedules a rebuild. The bottom of the stack is the root route; the top is the screen currently shown.

Attributes:

Name	Type	Description
stack	list[Route]	The route stack. Defaults to a single root route "/" so an app always has a screen to render.

Properties

top: The route on top of the stack (the visible screen). can_pop: Whether the stack can be popped without emptying it.

top property

The route on top of the stack (the visible screen).

Returns:

Type	Description
Route	The top-most route.

can_pop property

Whether the stack can be popped without emptying it.

Returns:

Type	Description
bool	True when more than one route is on the stack (a back navigation
bool	is possible), False at the root.

Route

Bases: BaseModel

A single navigation destination.

A route is an immutable value (frozen, like :class:~tempestroid.style.Style and :class:~tempestroid.widgets.Event) so the navigation stack can be compared and diffed by value.

Attributes:

Name	Type	Description
name	str	The route name (a path-like identifier, e.g. "/" or "/details").
params	dict[str, Any]	Typed parameters passed to the destination screen.

AlertVariant

Bases: StrEnum

The visual variant of an alert / banner (Chakra-style variant).

Picks the treatment a block-level status surface (alert, banner) renders with, mapped to a Material 3 treatment by the H4 alert resolver (:func:~tempest_core.variants.resolve_alert_variant). The color_scheme then chooses which status family the alert tints with. An alert is non-interactive (no state layer), like a surface.

Attributes:

Name	Type	Description
SUBTLE		A low-emphasis tonal fill — the *_container role as the background with its on_*_container content (WCAG-AA safe, the default alert).
SOLID		A filled treatment — the role color as the background with its legible on_* content (a high-emphasis alert).
LEFT_ACCENT		A subtle tonal fill with a thick directional border on the leading (start) edge in the saturated role color.
TOP_ACCENT		A subtle tonal fill with a thick directional border on the top edge in the saturated role color.

BadgeVariant

Bases: StrEnum

The visual variant of a badge / tag / chip (Chakra-style variant).

Picks the treatment a small inline status pill (badge, tag, chip) renders with, mapped to a Material 3 treatment by the H4 badge resolver (:func:~tempest_core.variants.resolve_badge_variant). The color_scheme then chooses which color family the badge tints with. Distinct from :class:Variant (the button treatment): a badge is a compact, pill-shaped label, not a tappable action surface.

Attributes:

Name	Type	Description
SOLID		A filled treatment — the role color as the background with its legible on_* content (a high-emphasis status pill).
SUBTLE		A low-emphasis tonal fill — the *_container role as the background with its on_*_container content (WCAG-AA safe, the default subtle badge).
OUTLINE		A transparent background with the role color as both the content and a same-color border (the lowest-emphasis badge).

CardVariant

Bases: StrEnum

The visual variant of a surface/card (Chakra-style variant).

Picks the treatment a non-interactive surface (card, panel, container) renders with, mapped to a Material 3 surface appearance by the H3 surface resolver (:func:~tempest_core.variants.resolve_surface_variant). Distinct from :class:Variant (the button treatment) and :class:FieldVariant (the text-field treatment): a surface is non-interactive, so it has no state layer — it simply chooses how the box is filled and whether it casts an elevation shadow or carries an outline. The color_scheme then chooses which color family the surface tints with ("neutral" uses the plain surface roles; a role family uses the tonal *_container roles).

Attributes:

Name	Type	Description
ELEVATED		A surface background that casts a Material 3 elevation shadow and carries no border — the default raised card.
FILLED		A low-emphasis surface_variant tonal fill with no shadow and no border (the M3 filled card).
OUTLINED		A surface background with a hairline outline border and no shadow (the M3 outlined card).

ComponentState

Bases: StrEnum

The interaction state a component is resolved for (M3 state layers).

The H1 variant resolver (:func:~tempest_core.variants.resolve_variant) layers a Material 3 state layer over the base style for the non-default states: HOVER and PRESSED overlay the content color at the M3 state opacities, FOCUS adds a focus indicator, and DISABLED drops content to the M3 disabled opacity. The renderers apply the per-state styles in response to real pointer/focus events.

Attributes:

Name	Type	Description
DEFAULT		The resting state, with no state layer applied.
HOVER		The pointer-hover state (M3 hover state layer, ~8% overlay).
PRESSED		The pressed/active state (M3 pressed state layer, ~12% overlay).
DISABLED		The disabled state (M3 disabled content/container opacities).
FOCUS		The keyboard/accessibility focus state (focus indicator + the M3 focus state layer).

FieldVariant

Bases: StrEnum

The visual variant of a text-input field (Chakra-style field_variant).

Picks the treatment a value-bearing field (text input, select, masked input, autocomplete, …) renders with, mapped to a Material 3 text-field appearance by the H2 field resolver (:func:~tempest_core.variants.resolve_field_variant). Distinct from :class:Variant (which is the button treatment) because fields have their own affordances: a field is never "solid" or "link", and the color_scheme only tints the focus/caret/label, never the resting fill.

Attributes:

Name	Type	Description
OUTLINE		A transparent fill with a full same-color outline border and a small radius — the M3 outlined text field (the default).
FILLED		A low-emphasis tonal fill (surface_variant) with no resting border and a small radius — the M3 filled text field.
FLUSHED		A transparent fill with only a bottom border and no radius — a minimal, underline-only field (Chakra flushed).

Size

Bases: StrEnum

The density size of a styled component (Chakra-style size).

Picks the padding/typography density the H1 variant resolver (:func:~tempest_core.variants.resolve_variant) applies. The hit target is always kept at or above the Material 3 minimum (48dp) regardless of size — a smaller size reduces visual density (padding, font) but never the accessible touch area.

Attributes:

Name	Type	Description
XS		The most compact density.
SM		A compact density.
MD		The default, comfortable density.
LG		A spacious, high-emphasis density.

Style

Bases: BaseModel

An inline, typed style object.

Every field is optional: None means "unset", letting the leaf renderer fall back to its own default. Styles are frozen; combine them with :meth:merge to layer overrides without mutation.

Methods:

Name	Description
merge	Layer another style on top of this one (returns a new Style).

merge(other)

Layer another style on top of this one.

Fields explicitly set on other (i.e. not None) win; everything else is inherited from self.

Parameters:

Name	Type	Description	Default
other	Style	The overriding style.	required

Returns:

Type	Description
Style	A new, merged style.

Variant

Bases: StrEnum

The visual variant of a styled component (Chakra-style variant).

Picks the emphasis/treatment a component renders with, mapped to a Material 3 container/outline/text treatment by the H1 variant resolver (:func:~tempest_core.variants.resolve_variant). The color_scheme then chooses which color family the treatment paints with.

Attributes:

Name	Type	Description
SOLID		A filled treatment — the role color as the background with its legible on_* content (M3 filled button).
OUTLINE		A transparent background with the role color as both the content and a same-color border (M3 outlined button).
GHOST		A transparent background with the role color as the content and no border — the lowest-emphasis tappable treatment (M3 text button without underline).
LINK		A transparent, inline text treatment — the role color as the content with an underline, no padding-heavy hit area styling beyond the enforced touch target.

MediaQueryData

Bases: BaseModel

An immutable snapshot of the viewport / environment context.

Read by the view to build responsively (e.g. switch a column to a row above a width breakpoint, scale text by the user's accessibility setting). The renderer keeps it current via App._update_media on resize / config change; it is never serialized as tree data — it is context, not a node.

Attributes:

Name	Type	Description
width	float	The viewport width in logical pixels.
height	float	The viewport height in logical pixels.
device_pixel_ratio	float	The display density (physical / logical pixels).
text_scale_factor	float	The user's font-scale accessibility multiplier.
platform_dark_mode	bool	Whether the OS is currently in dark mode.
orientation	str	"portrait" or "landscape".

Theme

Bases: BaseModel

An immutable theme: the active mode plus a small color palette.

The palette mirrors a subset of Material's color roles. Every legacy color is optional: None lets the renderer fall back to its own default scheme. The view reads :attr:mode (resolving SYSTEM against the media query) to decide which colors to apply to the tree it builds.

Beyond the legacy flat colors, a theme carries a full Material 3 :class:~tempest_core.tokens.TokenSet (color schemes + spacing/shape/ typography/elevation/motion scales). A researcher seeds a brand color with :meth:from_seed to get a complete M3 palette, then components (or the view) read tokens via :meth:color/:meth:space/:meth:radius/… or resolve a :class:~tempest_core.tokens.TokenRef carried in a Style via :meth:resolve_ref. The legacy flat colors remain so existing apps keep working unchanged — tokens are additive.

Attributes:

Name	Type	Description
mode	ThemeMode	The active color-scheme mode.
tokens	TokenSet	The Material 3 token set (color schemes + scales). Defaults to the baseline M3 token set.
primary	Color | None	The legacy primary brand color (optional override).
secondary	Color | None	The legacy secondary brand color (optional override).
background	Color | None	The legacy screen background color (optional override).
surface	Color | None	The legacy raised-surface color (optional override).
on_primary	Color | None	The legacy color of content drawn on primary.
on_background	Color | None	The legacy color of content drawn on background.
error	Color | None	The legacy error color (optional override).

Methods:

Name	Description
from_seed	Build a theme from a brand seed color (classmethod).
is_dark	Resolve whether the theme renders dark, given the platform setting (resolves SYSTEM against the media query).
scheme	Resolve the active :class:~tempest_core.tokens.ColorScheme.
color	Resolve a color role to a concrete color.
space	Resolve a spacing step to its pixel value.
radius	Resolve a radius step to its pixel value.
typography	Resolve a typography role to its token.
elevation	Resolve an elevation level to its dp value.
resolve_ref	Resolve a :class:~tempest_core.tokens.TokenRef to a concrete value.

from_seed(seed, *, mode=ThemeMode.SYSTEM, secondary_seed=None, tertiary_seed=None, error_seed=None, success_seed=None, warning_seed=None, info_seed=None) classmethod

Build a theme whose tokens are derived from a brand seed color.

This is the researcher-facing entry point: seed a single brand color and get a complete Material 3 token set (light + dark schemes + the default scales). Override the secondary/tertiary/error key colors to hand-pick brand accents, or the H4 success/warning/info status seeds to retune the semantic status colors.

Parameters:

Name	Type	Description	Default
seed	Color	The primary brand/key color.	required
mode	ThemeMode	The initial color-scheme mode.	SYSTEM
secondary_seed	Color | None	Override key color for the secondary palette.	None
tertiary_seed	Color | None	Override key color for the tertiary palette.	None
error_seed	Color | None	Override key color for the error palette.	None
success_seed	Color | None	Override key color for the success status palette (H4).	None
warning_seed	Color | None	Override key color for the warning status palette (H4).	None
info_seed	Color | None	Override key color for the info status palette (H4).	None

Returns:

Type	Description
Theme	A theme carrying the seeded token set.

is_dark(*, platform_dark_mode=False)

Resolve whether the theme renders dark, given the platform setting.

LIGHT / DARK are absolute; SYSTEM defers to the platform.

Parameters:

Name	Type	Description	Default
platform_dark_mode	bool	The OS dark-mode flag (typically :attr:MediaQueryData.platform_dark_mode).	False

Returns:

Type	Description
bool	True when the resolved scheme is dark.

scheme(*, platform_dark_mode=False)

Resolve the active color scheme for the current mode.

Parameters:

Name	Type	Description	Default
platform_dark_mode	bool	The OS dark-mode flag, used to resolve SYSTEM mode.	False

Returns:

Type	Description
ColorScheme	The light or dark color scheme matching the resolved mode.

color(role, *, platform_dark_mode=False)

Resolve a Material 3 color role to a concrete color.

Parameters:

Name	Type	Description	Default
role	ColorRole | str	The color role (a :class:~tempest_core.tokens.ColorRole or its string value).	required
platform_dark_mode	bool	The OS dark-mode flag, used to resolve SYSTEM mode.	False

Returns:

Type	Description
Color	The concrete color for that role in the active scheme.

space(name)

Resolve a named spacing step to its pixel value.

Parameters:

Name	Type	Description	Default
name	str	The spacing step name ("md", …).	required

Returns:

Type	Description
float	The spacing in logical pixels.

radius(name)

Resolve a named radius step to its pixel value.

Parameters:

Name	Type	Description	Default
name	str	The radius step name ("lg", …).	required

Returns:

Type	Description
float	The radius in logical pixels.

typography(name)

Resolve a typography role to its token.

Parameters:

Name	Type	Description	Default
name	str	The type role name ("body_medium", …).	required

Returns:

Type	Description
TypographyToken	The typography token for that role.

elevation(level)

Resolve an elevation level to its dp value.

Parameters:

Name	Type	Description	Default
level	int	The elevation level, 0-5.	required

Returns:

Type	Description
float	The elevation in dp.

resolve_ref(ref, *, platform_dark_mode=False)

Resolve a token reference to its concrete value.

This is the seam that lets a Style field carry a :class:~tempest_core.tokens.TokenRef instead of a raw value: the renderer (or the variant resolver in H1) calls this to turn the reference into the concrete color/spacing/radius/type/elevation/motion value before the diff.

Parameters:

Name	Type	Description	Default
ref	TokenRef	The token reference to resolve.	required
platform_dark_mode	bool	The OS dark-mode flag, used to resolve a color reference against the active scheme.	False

Returns:

Type	Description
Color | float | TypographyToken | Curve | int	The concrete value: a :class:~tempest_core.style.Color for
Color | float | TypographyToken | Curve | int	"color"; a float for "space"/"radius"/
Color | float | TypographyToken | Curve | int	"elevation"; a :class:~tempest_core.tokens.TypographyToken for
Color | float | TypographyToken | Curve | int	"type"; a :class:~tempest_core.style.Curve or int for
Color | float | TypographyToken | Curve | int	"motion" (easing curve vs. duration in ms).

Raises:

Type	Description
ValueError	If ref.category is not a known token category.
KeyError	If ref.name is not a defined token in its category.

resolve_style(refs, *, base=None, platform_dark_mode=False)

Build a concrete Style by resolving token references per field.

This is the Style ⟷ token seam: a component (or the H1 variant resolver) maps style fields to token references — e.g. {"background": TokenRef.color("primary"), "radius": TokenRef.radius("lg")} — and the theme resolves them against its tokens, producing a plain frozen Style the renderers consume unchanged. A "type" reference expands into the matching font_size/line_height/font_weight/letter_spacing fields. Raw Style values keep working — this is purely an additive way to source values from the theme.

Parameters:

Name	Type	Description	Default
refs	dict[str, TokenRef]	Mapping of Style field name to the token reference that supplies its value.	required
base	Style | None	An optional base style the resolved fields are layered on top of (via :meth:Style.merge); None starts from an empty style.	None
platform_dark_mode	bool	The OS dark-mode flag, used to resolve color references against the active scheme.	False

Returns:

Type	Description
Style	A concrete, frozen Style with every referenced field resolved.

Raises:

Type	Description
ValueError	If a reference category is unknown.
KeyError	If a referenced token name is not defined.

ThemeMode

Bases: StrEnum

The active color-scheme mode of the application.

SYSTEM defers to the platform's current setting (read from :attr:MediaQueryData.platform_dark_mode); LIGHT / DARK force the respective scheme regardless of the OS.

Attributes:

Name	Type	Description
LIGHT		Force the light color scheme always, ignoring the OS setting.
DARK		Force the dark color scheme always, ignoring the OS setting.
SYSTEM		Follow the platform's current scheme, resolving against :attr:MediaQueryData.platform_dark_mode at build time.

Breakpoints

Bases: BaseModel

Responsive width breakpoints in logical pixels (Chakra-style).

Used by H1's responsive token resolution against the E9 :class:~tempest_core.theme.MediaQueryData (e.g. size={"base": "sm", "md": "lg"}). Frozen so it diffs by value.

Attributes:

Name	Type	Description
sm	float	The small breakpoint (compact phones).
md	float	The medium breakpoint (large phones / small tablets).
lg	float	The large breakpoint (tablets).
xl	float	The extra-large breakpoint (desktop).

ColorRole

Bases: StrEnum

The Material 3 color roles a :class:ColorScheme exposes.

These are the semantic slots components paint against — never raw tones. Each on_* role is the legible foreground for its base role and is generated to meet WCAG-AA contrast against it.

Attributes:

Name	Type	Description
PRIMARY		The highest-emphasis brand color (key actions, active state).
ON_PRIMARY		Legible content drawn on top of PRIMARY.
PRIMARY_CONTAINER		A tonal, lower-emphasis fill derived from primary.
ON_PRIMARY_CONTAINER		Content drawn on PRIMARY_CONTAINER.
SECONDARY		A complementary, lower-emphasis accent.
ON_SECONDARY		Content drawn on SECONDARY.
SECONDARY_CONTAINER		A tonal fill derived from secondary.
ON_SECONDARY_CONTAINER		Content drawn on SECONDARY_CONTAINER.
TERTIARY		A contrasting accent used to balance primary/secondary.
ON_TERTIARY		Content drawn on TERTIARY.
TERTIARY_CONTAINER		A tonal fill derived from tertiary.
ON_TERTIARY_CONTAINER		Content drawn on TERTIARY_CONTAINER.
ERROR		The role signalling errors and destructive actions.
ON_ERROR		Content drawn on ERROR.
ERROR_CONTAINER		A tonal error fill.
ON_ERROR_CONTAINER		Content drawn on ERROR_CONTAINER.
SUCCESS		The role signalling success / positive confirmation (H4).
ON_SUCCESS		Content drawn on SUCCESS.
SUCCESS_CONTAINER		A tonal success fill.
ON_SUCCESS_CONTAINER		Content drawn on SUCCESS_CONTAINER.
WARNING		The role signalling caution / a non-blocking problem (H4).
ON_WARNING		Content drawn on WARNING.
WARNING_CONTAINER		A tonal warning fill.
ON_WARNING_CONTAINER		Content drawn on WARNING_CONTAINER.
INFO		The role signalling neutral information (H4).
ON_INFO		Content drawn on INFO.
INFO_CONTAINER		A tonal info fill.
ON_INFO_CONTAINER		Content drawn on INFO_CONTAINER.
BACKGROUND		The screen background.
ON_BACKGROUND		Content drawn on BACKGROUND.
SURFACE		The base surface of cards, sheets and menus.
ON_SURFACE		Content drawn on SURFACE.
SURFACE_VARIANT		A subtly differentiated surface for dividers/fills.
ON_SURFACE_VARIANT		Lower-emphasis content on a surface.
OUTLINE		The color of borders and dividers.
OUTLINE_VARIANT		A lower-emphasis outline.
INVERSE_SURFACE		A surface inverted relative to the scheme (snackbars).
INVERSE_ON_SURFACE		Content drawn on INVERSE_SURFACE.
INVERSE_PRIMARY		The primary color as it appears on an inverse surface.

ColorScheme

Bases: BaseModel

A resolved Material 3 color scheme — every role as a concrete color.

One scheme is the full set of M3 roles for a single mode (light or dark). Built from tonal palettes via :func:color_schemes_from_seed, or supplied directly to fully hand-author a brand scheme. Frozen so it diffs by value.

Attributes:

Name	Type	Description
primary	Color	The PRIMARY role color.
on_primary	Color	The ON_PRIMARY role color.
primary_container	Color	The PRIMARY_CONTAINER role color.
on_primary_container	Color	The ON_PRIMARY_CONTAINER role color.
secondary	Color	The SECONDARY role color.
on_secondary	Color	The ON_SECONDARY role color.
secondary_container	Color	The SECONDARY_CONTAINER role color.
on_secondary_container	Color	The ON_SECONDARY_CONTAINER role color.
tertiary	Color	The TERTIARY role color.
on_tertiary	Color	The ON_TERTIARY role color.
tertiary_container	Color	The TERTIARY_CONTAINER role color.
on_tertiary_container	Color	The ON_TERTIARY_CONTAINER role color.
error	Color	The ERROR role color.
on_error	Color	The ON_ERROR role color.
error_container	Color	The ERROR_CONTAINER role color.
on_error_container	Color	The ON_ERROR_CONTAINER role color.
success	Color | None	The SUCCESS role color (H4 status family).
on_success	Color | None	The ON_SUCCESS role color.
success_container	Color | None	The SUCCESS_CONTAINER role color.
on_success_container	Color | None	The ON_SUCCESS_CONTAINER role color.
warning	Color | None	The WARNING role color (H4 status family).
on_warning	Color | None	The ON_WARNING role color.
warning_container	Color | None	The WARNING_CONTAINER role color.
on_warning_container	Color | None	The ON_WARNING_CONTAINER role color.
info	Color | None	The INFO role color (H4 status family).
on_info	Color | None	The ON_INFO role color.
info_container	Color | None	The INFO_CONTAINER role color.
on_info_container	Color | None	The ON_INFO_CONTAINER role color.
background	Color	The BACKGROUND role color.
on_background	Color	The ON_BACKGROUND role color.
surface	Color	The SURFACE role color.
on_surface	Color	The ON_SURFACE role color.
surface_variant	Color	The SURFACE_VARIANT role color.
on_surface_variant	Color	The ON_SURFACE_VARIANT role color.
outline	Color	The OUTLINE role color.
outline_variant	Color	The OUTLINE_VARIANT role color.
inverse_surface	Color	The INVERSE_SURFACE role color.
inverse_on_surface	Color	The INVERSE_ON_SURFACE role color.
inverse_primary	Color	The INVERSE_PRIMARY role color.

Methods:

Name	Description
role	Read the color for a :class:ColorRole.

role(role)

Read the color for a given Material 3 color role.

Parameters:

Name	Type	Description	Default
role	ColorRole	The semantic role to resolve.	required

Returns:

Type	Description
Color	The concrete color for that role in this scheme.

ColorSchemes

Bases: BaseModel

The light and dark :class:ColorScheme pair of a theme.

Attributes:

Name	Type	Description
light	ColorScheme	The color scheme used when the theme renders light.
dark	ColorScheme	The color scheme used when the theme renders dark.

Methods:

Name	Description
for_mode	Pick the scheme for a resolved dark/light flag.

for_mode(*, is_dark)

Pick the scheme matching a resolved dark/light flag.

Parameters:

Name	Type	Description	Default
is_dark	bool	True to select the dark scheme, False for light.	required

Returns:

Type	Description
ColorScheme	The matching color scheme.

ElevationScale

Bases: BaseModel

The Material 3 elevation scale (levels 0-5 → dp).

Maps the six M3 elevation levels to their dp values; renderers turn the dp into a tonal-surface tint (Compose) or a drop shadow (Qt). Frozen so it diffs by value.

Attributes:

Name	Type	Description
level0	float	0 dp — flush with the background.
level1	float	1 dp.
level2	float	3 dp.
level3	float	6 dp.
level4	float	8 dp.
level5	float	12 dp.

Methods:

Name	Description
get	Resolve an elevation level (0-5) to its dp value.

get(level)

Resolve an elevation level to its dp value.

Parameters:

Name	Type	Description	Default
level	int	The elevation level, 0-5.	required

Returns:

Type	Description
float	The elevation in dp.

Raises:

Type	Description
KeyError	If level is outside 0-5.

MotionScale

Bases: BaseModel

The Material 3 motion scale (standard durations + easing curves).

Durations are in milliseconds (M3's short/medium/long buckets); easing reuses the framework's :class:~tempest_core.style.Curve. Frozen so it diffs by value.

Attributes:

Name	Type	Description
duration_short	int	A short transition (150 ms) — small UI changes.
duration_medium	int	A medium transition (300 ms) — the default.
duration_long	int	A long transition (500 ms) — large/expressive motion.
easing_standard	Curve	The default easing for most transitions.
easing_emphasized	Curve	A more expressive easing for prominent motion.

ShapeScale

Bases: BaseModel

The Material 3 shape (corner-radius) scale in logical pixels.

full uses the framework's pill sentinel (999) so the renderer clamps it to a fully-rounded shape. Frozen so it diffs by value.

Attributes:

Name	Type	Description
none	float	0 dp — square corners.
xs	float	4 dp.
sm	float	8 dp.
md	float	12 dp (the M3 default for cards/buttons).
lg	float	16 dp.
xl	float	28 dp (large containers, sheets).
full	float	999 dp — the pill/circle sentinel.

Methods:

Name	Description
get	Resolve a named radius step to its pixel value.

get(name)

Resolve a named radius step to its pixel value.

Parameters:

Name	Type	Description	Default
name	str	The step name ("none", "xs", …, "full").	required

Returns:

Type	Description
float	The radius in logical pixels.

Raises:

Type	Description
KeyError	If name is not a defined radius step.

SpacingScale

Bases: BaseModel

The 4dp-grid spacing scale (named steps → logical pixels).

Named t-shirt steps mapping to a 4dp grid, matching Chakra's spacing ergonomics over Material's raw dp. Components ask for space("md") rather than a literal 16.0. Frozen so it diffs by value.

Attributes:

Name	Type	Description
none	float	0 dp.
xs	float	4 dp (one grid unit).
sm	float	8 dp.
md	float	16 dp (the default content gutter).
lg	float	24 dp.
xl	float	32 dp.
xxl	float	48 dp.

Methods:

Name	Description
get	Resolve a named step to its pixel value.

get(name)

Resolve a named spacing step to its pixel value.

Parameters:

Name	Type	Description	Default
name	str	The step name ("none", "xs", …, "xxl").	required

Returns:

Type	Description
float	The spacing in logical pixels.

Raises:

Type	Description
KeyError	If name is not a defined spacing step.

TokenRef

Bases: BaseModel

A reference to a design token, resolved by the theme at build time.

This is the seam that lets a :class:~tempest_core.style.Style field carry a token reference instead of a raw value: a component (or app) writes Style(background=TokenRef.color("primary")) and the theme resolves it to a concrete value before the diff. Raw values keep working unchanged — a TokenRef is purely an additional, opt-in source.

The reference names a category and a token name; the theme's :meth:~tempest_core.theme.Theme.resolve_ref reads the right scale. Frozen so it diffs by value and can sit inside a frozen Style.

Attributes:

Name	Type	Description
category	str	Which token scale to read — "color", "space", "radius", "type", "elevation" or "motion".
name	str	The token name within the category (e.g. "primary", "md", "body_medium", "level2", "duration_short").

Methods:

Name	Description
color	Build a color-role reference (classmethod).
space	Build a spacing-step reference (classmethod).
radius	Build a radius-step reference (classmethod).
type_	Build a typography-role reference (classmethod).
elevation	Build an elevation-level reference (classmethod).
motion	Build a motion-token reference (classmethod).

color(role) classmethod

Build a reference to a color role.

Parameters:

Name	Type	Description	Default
role	ColorRole | str	The color role (a :class:ColorRole or its string value).	required

Returns:

Type	Description
TokenRef	The token reference.

space(name) classmethod

Build a reference to a spacing step.

Parameters:

Name	Type	Description	Default
name	str	The spacing step name ("md", …).	required

Returns:

Type	Description
TokenRef	The token reference.

radius(name) classmethod

Build a reference to a radius step.

Parameters:

Name	Type	Description	Default
name	str	The radius step name ("lg", …).	required

Returns:

Type	Description
TokenRef	The token reference.

type_(name) classmethod

Build a reference to a typography role.

Parameters:

Name	Type	Description	Default
name	str	The type role name ("body_medium", …).	required

Returns:

Type	Description
TokenRef	The token reference.

elevation(level) classmethod

Build a reference to an elevation level.

Parameters:

Name	Type	Description	Default
level	int	The elevation level, 0-5.	required

Returns:

Type	Description
TokenRef	The token reference.

motion(name) classmethod

Build a reference to a motion token.

Parameters:

Name	Type	Description	Default
name	str	The motion token name ("duration_short", "easing_standard", …).	required

Returns:

Type	Description
TokenRef	The token reference.

TokenSet

Bases: BaseModel

The full set of design tokens a theme resolves against.

Bundles the color schemes with every systematic scale (spacing, shape, typography, elevation, motion, breakpoints). Build one from a seed via :meth:from_seed, or hand-author any scale. Frozen so the runtime can hold it as an immutable snapshot and swap it wholesale.

Attributes:

Name	Type	Description
schemes	ColorSchemes	The light/dark color schemes.
spacing	SpacingScale	The 4dp spacing scale.
shape	ShapeScale	The corner-radius scale.
typography	TypographyScale	The type scale.
elevation	ElevationScale	The elevation scale.
motion	MotionScale	The motion (duration/easing) scale.
breakpoints	Breakpoints	The responsive width breakpoints.

Methods:

Name	Description
from_seed	Build a token set from a brand seed color (classmethod).
scheme	Resolve the color scheme for a dark/light flag.

from_seed(seed, *, secondary_seed=None, tertiary_seed=None, error_seed=None, success_seed=None, warning_seed=None, info_seed=None) classmethod

Build a token set from a brand seed color with M3 default scales.

Parameters:

Name	Type	Description	Default
seed	Color	The primary brand/key color.	required
secondary_seed	Color | None	Override key color for the secondary palette.	None
tertiary_seed	Color | None	Override key color for the tertiary palette.	None
error_seed	Color | None	Override key color for the error palette.	None
success_seed	Color | None	Override key color for the success status palette (H4).	None
warning_seed	Color | None	Override key color for the warning status palette (H4).	None
info_seed	Color | None	Override key color for the info status palette (H4).	None

Returns:

Type	Description
TokenSet	A token set with schemes derived from the seed and default M3
TokenSet	spacing/shape/typography/elevation/motion scales.

scheme(*, is_dark)

Resolve the color scheme for a dark/light flag.

Parameters:

Name	Type	Description	Default
is_dark	bool	True for the dark scheme, False for light.	required

Returns:

Type	Description
ColorScheme	The matching color scheme.

TonalPalette

Bases: BaseModel

A Material 3 tonal palette: one hue sampled at the standard tones.

Generated from a single key color via :func:tonal_palette_from_seed; the color schemes read specific tones from it (light primary = tone 40, dark primary = tone 80, etc.). Frozen so it diffs by value.

Attributes:

Name	Type	Description
tones	dict[int, Color]	Mapping of each standard M3 tone (0-100) to its color.

Methods:

Name	Description
tone	Read the color at a given tone (nearest standard tone).

tone(value)

Read the palette color at a tone, snapping to the nearest standard tone.

Parameters:

Name	Type	Description	Default
value	int	The desired tone, 0-100.	required

Returns:

Type	Description
Color	The color at the nearest available standard tone.

TypographyScale

Bases: BaseModel

The Material 3 type scale (display/headline/title/body/label × sizes).

Each role is a :class:TypographyToken carrying size, line-height and weight, matching the M3 baseline values. Frozen so it diffs by value.

Attributes:

Name	Type	Description
display_large	TypographyToken	Largest display role (57/64).
display_medium	TypographyToken	Medium display role (45/52).
display_small	TypographyToken	Small display role (36/44).
headline_large	TypographyToken	Large headline (32/40).
headline_medium	TypographyToken	Medium headline (28/36).
headline_small	TypographyToken	Small headline (24/32).
title_large	TypographyToken	Large title (22/28).
title_medium	TypographyToken	Medium title (16/24, medium weight).
title_small	TypographyToken	Small title (14/20, medium weight).
body_large	TypographyToken	Large body (16/24).
body_medium	TypographyToken	Medium body (14/20).
body_small	TypographyToken	Small body (12/16).
label_large	TypographyToken	Large label (14/20, medium weight).
label_medium	TypographyToken	Medium label (12/16, medium weight).
label_small	TypographyToken	Small label (11/16, medium weight).

Methods:

Name	Description
get	Resolve a named type role to its :class:TypographyToken.

get(name)

Resolve a named type role to its token.

Parameters:

Name	Type	Description	Default
name	str	The role name ("body_medium", "title_large", …).	required

Returns:

Type	Description
TypographyToken	The typography token for that role.

Raises:

Type	Description
KeyError	If name is not a defined type role.

TypographyToken

Bases: BaseModel

One role of the Material 3 type scale (size + line-height + weight).

Attributes:

Name	Type	Description
font_size	float	The font size in logical pixels.
line_height	float	The line height in logical pixels.
font_weight	FontWeight	The font weight.
letter_spacing	float	The tracking in logical pixels (M3 uses small values).

Button

Bases: Widget

A tappable button, styled via the Chakra-ergonomics variant API.

The button resolves its base :class:~tempest_core.style.Style from its variant / size / color_scheme against the design-system theme (Material 3 tokens), via :func:~tempest_core.variants.resolve_variant. An explicit style is merged on top of the resolved base (its set fields win), so hand-styling still works and stays backward-compatible: Button(label=...) with no variant produces a solid/primary/md button, and Button(label=..., style=…) layers the override over it. The resolved style is baked into :attr:~tempest_core.widgets.base.Widget.style so the renderers consume a plain Style unchanged.

The per-state styles (default/hover/pressed/disabled/focus) are exposed via :meth:state_styles so a renderer can apply the matching Material 3 state layer on real pointer/focus events — the resolution stays pure and in the engine; only the event→state mapping lives in the renderers.

The accessibility surface (semantics / focusable / focus_order) is preserved unchanged from :class:~tempest_core.widgets.base.Widget.

Attributes:

Name	Type	Description
label	str	The text shown on the button.
on_click	EventHandler | None	Optional handler invoked on tap. May be sync or async; the runtime schedules awaitables on the event loop.
variant	Variant	The visual treatment (solid/outline/ghost/link).
size	ResponsiveSize	The density size — a single :class:~tempest_core.style.Size or a per-breakpoint map ({"base": Size.SM, "md": Size.LG}).
color_scheme	str	The Material 3 role family to paint with ("primary", "secondary", "tertiary", "error" or "neutral").
theme	Theme	The design-system theme whose tokens resolve the variant; defaults to the baseline Material 3 theme.
media	MediaQueryData | None	Optional viewport snapshot used to resolve a responsive size.

Methods:

Name	Description
state_styles	Resolve the per-interaction-state style table for the renderers (default/hover/pressed/disabled/focus).

state_styles()

Resolve the per-interaction-state style table for the renderers.

Returns the resolved :class:~tempest_core.style.Style for every :class:~tempest_core.style.ComponentState (default/hover/pressed/ disabled/focus), each with any explicit style override merged on top — the same merge applied to the baked default style. A renderer applies the matching style on the corresponding pointer/focus event.

Returns:

Type	Description
dict[ComponentState, Style]	A mapping of each ComponentState to its resolved, override-merged
dict[ComponentState, Style]	Style.

Column

Bases: Widget

A vertical flex container (main axis = top-to-bottom).

Attributes:

Name	Type	Description
children	list[Widget]	The ordered child widgets.

child_nodes()

Return the column's children.

Returns:

Type	Description
list[Widget]	The ordered child widgets.

Component

Bases: Widget

A composite widget that lowers to a primitive widget tree.

A component is not part of the serialized IR. The reconciler expands it via :meth:render into primitive widgets (Text / Row / Column / Container / inputs / …) before diffing, so neither leaf renderer (Qt or Compose) ever sees a component — only the tree it produces. This keeps higher-level, reusable building blocks (app bars, scaffolds, navigation bars) fully renderer-agnostic and device-ready: they work anywhere a primitive works, with zero renderer changes.

Subclasses declare their inputs as Pydantic fields and implement :meth:render; they may read self.style / self.key and fold them into the returned tree. render runs on the same thread as build (desktop and device), so it may close over plain Python callables (e.g. a navigation item's on_select) and wire them into the primitives it emits.

render()

Lower this component into a primitive widget tree.

Returns:

Type	Description
Widget	The widget tree this component expands to (may itself contain further
Widget	components, which are expanded recursively).

Raises:

Type	Description
NotImplementedError	If a subclass does not implement it.

Container

Bases: Widget

A single-child box used for padding, background, borders and sizing.

Attributes:

Name	Type	Description
child	Widget | None	The optional wrapped widget.

child_nodes()

Return the wrapped child, if any.

Returns:

Type	Description
list[Widget]	A one-element list with the child, or an empty list.

IconButton

Bases: Widget

A square/circular icon-only button, styled via the Chakra-style variant API.

An icon button is button-shaped, so it reuses :func:~tempest_core.variants.resolve_variant exactly like :class:Button — then pins its width and height to the resolved min_height (a square hit area at least the 48dp touch target) and sets a circular radius, using only existing :class:~tempest_core.style.Style fields (no new field). It defaults to the GHOST variant (the lowest-emphasis, icon-forward treatment). An explicit style is merged on top of the resolved base.

The label carries the accessible name (contentDescription / accessible label) since the button has no visible text; renderers route it into the node's accessibility surface.

Attributes:

Name	Type	Description
icon	Icons | str	The icon to show — a curated :class:~tempest_core.icons.Icons value (or its string) or an arbitrary platform icon name.
on_click	EventHandler | None	Optional handler invoked on tap. May be sync or async.
variant	Variant	The visual treatment (solid/outline/ghost/link); defaults to GHOST.
size	ResponsiveSize	The density size — a single :class:~tempest_core.style.Size or a per-breakpoint map.
color_scheme	str	The Material 3 role family to paint with.
label	str	The accessible label for the icon-only button (a11y / Semantics).
theme	Theme	The design-system theme whose tokens resolve the variant.
media	MediaQueryData | None	Optional viewport snapshot used to resolve a responsive size.

Methods:

Name	Description
state_styles	Resolve the per-interaction-state style table for the renderers (default/hover/pressed/disabled/focus), each pinned to the square/circular icon-button geometry.

state_styles()

Resolve the per-interaction-state style table for the renderers.

Returns:

Type	Description
dict[ComponentState, Style]	A mapping of each :class:~tempest_core.style.ComponentState to its
dict[ComponentState, Style]	resolved, squared, override-merged Style.

Row

Bases: Widget

A horizontal flex container (main axis = left-to-right).

Attributes:

Name	Type	Description
children	list[Widget]	The ordered child widgets.

child_nodes()

Return the row's children.

Returns:

Type	Description
list[Widget]	The ordered child widgets.

Spacer

Bases: Widget

A flexible empty box that consumes free space along its parent's main axis.

The layout primitive for pushing siblings apart: dropped between two children of a :class:Row/:class:Column (or an :class:HStack/:class:VStack), it expands to fill the remaining space so the children are pushed to the ends. It is a leaf with no children and renders nothing visible — only its :attr:~tempest_core.widgets.base.Widget.style grow matters. When the caller leaves grow unset, the spacer defaults to grow == 1.0 (its whole purpose); an explicit style with a different grow wins, so a weighted spacer (Style(grow=2.0)) still works. The renderers realize it as a stretchable empty box (Qt addStretch / a growing QWidget; Compose Modifier.weight), using only the existing grow style field — no new field is added.

Attributes:

Name	Type	Description
flex	float	The flex weight the spacer grows by (defaults to 1.0); baked into the node's style.grow unless an explicit style.grow is already set.

Text

Bases: Widget

A run of text.

Attributes:

Name	Type	Description
content	str	The string to display.

Widget

Bases: BaseModel

Base class for every node in the declarative UI tree.

Attributes:

Name	Type	Description
key	str | None	Optional stable identity used by the reconciler to match nodes across rebuilds (analogous to a React key).
style	Style | None	Optional inline style for this node.
semantics	Semantics | None	Optional accessibility metadata for this node, propagated to both renderers and to :func:~tempestroid.introspect.
focusable	bool | None	Whether this node accepts focus. None keeps the widget's natural focusability (e.g. a button is focusable, a label is not).
focus_order	int | None	The node's explicit focus/tab order; None uses the natural traversal order.

widget_type property

The node's type tag, used by renderers and diffing.

Returns:

Type	Description
str	The concrete class name (e.g. "Text", "Column").

child_nodes()

Return this node's children in order.

Leaf widgets return an empty list. Container/layout widgets override this to expose their children, giving the reconciler a uniform way to walk any tree regardless of how children are stored.

Returns:

Type	Description
list[Widget]	The ordered child widgets (empty for leaf nodes).

confidence_scheme(conf, *, high=0.8, mid=0.5)

Map a confidence score to a status color_scheme.

The canonical traffic-light cue for a model's confidence: at or above high is "success" (green), at or above mid is "warning" (amber), and below mid is "error" (red). Pure and deterministic, so every confidence-driven component (badge, detection box) colors consistently.

Parameters:

Name	Type	Description	Default
conf	float	The confidence score, typically in [0, 1].	required
high	float	The inclusive threshold at or above which the score reads as high confidence ("success").	0.8
mid	float	The inclusive threshold at or above which the score reads as medium confidence ("warning"); below it reads as low ("error").	0.5

Returns:

Type	Description
str	One of "success" / "warning" / "error".

build(widget)

Normalize a widget tree into an IR node tree.

A :class:Component is expanded first — replaced by the primitive tree its :meth:Component.render returns — so the IR (and therefore both renderers) only ever contains primitive widgets. Children come from :meth:Widget.child_nodes; everything else on the widget (except key and the declared child slots) becomes a prop.

Parameters:

Name	Type	Description	Default
widget	Widget	The root widget to normalize.	required

Returns:

Type	Description
Node	The root IR node.

build_scene(widget, overlays)

Build a full :class:Scene from a root widget plus an overlay layer.

Each overlay is given as a (id, widget, barrier) tuple: the id becomes the overlay node's stable key (so the keyed diff matches it across rebuilds), and barrier is recorded as a barrier prop on the overlay node so a renderer knows whether to draw a touch-blocking scrim.

Parameters:

Name	Type	Description	Default
widget	Widget	The root screen widget.	required
overlays	list[tuple[str, Widget, bool]]	The overlay layer, in ascending z-order, as (overlay_id, widget, barrier) tuples.	required

Returns:

Type	Description
Scene	The built scene (root node + overlay nodes).

diff(old, new)

Diff two IR node trees into an ordered list of patches.

Patches are ordered so a renderer can apply them sequentially: a node's own update/reorder precedes its descendants' patches, and within a child list removals run tail-first before insertions.

Parameters:

Name	Type	Description	Default
old	Node	The previously rendered tree.	required
new	Node	The freshly built tree.	required

Returns:

Type	Description
list[Patch]	The patches that transform old into new (empty if identical).

diff_scene(old, new)

Diff two scenes into an ordered patch list.

The root tree is diffed exactly as :func:diff does (paths unchanged, so every existing renderer consumer is unaffected). The overlay layer is diffed as a fully-keyed child list (each overlay's key is its stable id) under the reserved ("overlay",) path prefix, so overlay add/remove/reorder reuse the existing :class:Insert/:class:Remove/:class:Reorder/ :class:Update/:class:Replace patch kinds — no new patch kind is needed.

Parameters:

Name	Type	Description	Default
old	Scene	The previously rendered scene.	required
new	Scene	The freshly built scene.	required

Returns:

Type	Description
list[Patch]	The patches transforming old into new (empty if identical).

event_catalog()

Describe every event payload schema.

Returns:

Type	Description
dict[str, Any]	A mapping of event name to its JSON schema.

introspect()

Produce the full, JSON-serializable framework contract.

Returns:

Type	Description
dict[str, Any]	{"widgets": <widget catalog>, "events": <event catalog>}.

widget_catalog()

Describe every widget: its prop schema and the events it emits.

Returns:

Type	Description
dict[str, Any]	A mapping of widget name to ``{"schema": , "events":
dict[str, Any]	{handler_prop: event_type_name}}``.

translate(key, locale, translations, **kwargs)

Look up and interpolate a localized string.

Resolution order, by the locale's language: a translation table keyed by language ({"pt": {"hello": "Olá, {name}"}, "en": {...}}) is searched for locale.language; the matched string is then interpolated with kwargs via :meth:str.format. When the language or key is missing, key itself is returned (still interpolated when possible) so a missing translation degrades to the developer-facing key rather than raising.

Parameters:

Name	Type	Description	Default
key	str	The translation key to resolve.	required
locale	Locale	The active locale (its :attr:Locale.language selects the table).	required
translations	dict[str, dict[str, str]]	A {language: {key: template}} mapping.	required
**kwargs	str	Interpolation values applied to the resolved template.	{}

Returns:

Type	Description
str	The interpolated, localized string (or the interpolated key on miss).

routes_from_path(path)

Resolve a deep-link path into an initial navigation stack.

A deep link arrives as an intent extra on the device (or a launch argument in the simulator) and is resolved to the stack the app should open on. This is the device-independent half of the deep-link path: the entry point passes the resulting stack to :meth:~tempestroid.App.reset so the app opens directly on the linked screen with its back stack already built.

The path is split on "/" into cumulative segments, so "/a/b" opens the stack ["/", "/a", "/a/b"] — the user can pop back through the intermediate screens. The root "/" (or an empty path) yields the single root route, matching :class:NavStack's default.

Parameters:

Name	Type	Description	Default
path	str	The deep-link path (e.g. "/details" or "/shop/item").	required

Returns:

Type	Description
list[Route]	A non-empty list of routes from the root to the linked screen.

color_schemes_from_seed(seed, *, secondary_seed=None, tertiary_seed=None, error_seed=None, success_seed=None, warning_seed=None, info_seed=None)

Generate the light + dark Material 3 schemes from a brand seed color.

By default the secondary and tertiary key colors are derived by rotating the seed hue (M3 derives related palettes from one seed); a researcher can override any of them to hand-pick a brand accent. The neutral palette is the desaturated seed so surfaces carry a hint of the brand tint, as M3 does. The H4 status families (success / warning / info) use fixed semantic seeds (green / amber / blue) so a "success" surface reads green regardless of the brand hue, and are overridable like the error seed.

Parameters:

Name	Type	Description	Default
seed	Color	The primary brand/key color.	required
secondary_seed	Color | None	Override key color for the secondary palette; defaults to the seed hue rotated -60°.	None
tertiary_seed	Color | None	Override key color for the tertiary palette; defaults to the seed hue rotated +60°.	None
error_seed	Color | None	Override key color for the error palette; defaults to the Material 3 baseline red.	None
success_seed	Color | None	Override key color for the success palette (H4); defaults to :data:_DEFAULT_SUCCESS_SEED (green).	None
warning_seed	Color | None	Override key color for the warning palette (H4); defaults to :data:_DEFAULT_WARNING_SEED (amber).	None
info_seed	Color | None	Override key color for the info palette (H4); defaults to :data:_DEFAULT_INFO_SEED (blue).	None

Returns:

Type	Description
ColorSchemes	The light/dark scheme pair derived from the seed.

default_tokens()

Build the default Material 3 token set (the baseline M3 theme).

Seeded with the Material 3 reference purple so an app that sets no brand color still gets a complete, M3-faithful token set.

Returns:

Type	Description
TokenSet	The default token set.

tonal_palette_from_seed(seed)

Generate a Material 3 tonal palette from a seed/brand color.

The seed's hue and saturation are preserved while lightness is swept across the thirteen standard M3 tones; chroma is attenuated at the extremes. The result is deterministic for a given seed.

Parameters:

Name	Type	Description	Default
seed	Color	The key/brand color to derive the palette from.	required

Returns:

Type	Description
TonalPalette	The tonal palette sampling the seed's hue at every standard tone.

resolve_alert_variant(*, variant, color_scheme='info', theme, padding_step='md', radius_step='sm', platform_dark_mode=False, media=None)

Resolve an alert / banner's props into a Material 3 Style.

The H4 sibling of :func:resolve_surface_variant for the alert family (alert, banner). An alert is a non-interactive block-level status surface — there is no state parameter and no per-state table (like a surface):

• subtle fills with the tonal *_container role and its on_*_container content — the WCAG-AA-safe default;
• solid fills with the saturated role color and its on_* content;
• left_accent / top_accent are a subtle fill plus a thick directional :class:~tempest_core.style.SideBorder (4px) in the saturated role on the leading / top edge respectively. The renderers mirror the start/end side under RTL via their existing rtl flag (the same idiom as the field flushed bottom border).

Padding and radius come from the spacing / shape scales via the padding_step / radius_step token-step names. Pure and deterministic.

Parameters:

Name	Type	Description	Default
variant	AlertVariant	The alert treatment (subtle / solid / left_accent / top_accent).	required
color_scheme	str	The Material 3 role family to tint with — one of :data:VALID_COLOR_SCHEMES (default "info"; the H4 status families "success" / "warning" / "info" are the typical choices).	'info'
theme	Theme	The theme whose tokens supply colors, spacing and shape.	required
padding_step	str	The spacing-scale step name for the alert padding (default "md").	'md'
radius_step	str	The shape-scale step name for the corner radius (default "sm").	'sm'
platform_dark_mode	bool	The OS dark-mode flag, used to resolve the scheme.	False
media	MediaQueryData | None	The current viewport snapshot (accepted for signature parity; an alert has no responsive size).	None

Returns:

Type	Description
Style	The resolved, frozen Style for the requested alert combination.

Raises:

Type	Description
ValueError	If color_scheme is unknown.

resolve_badge_variant(*, variant, size, color_scheme, theme, state=ComponentState.DEFAULT, platform_dark_mode=False, media=None)

Resolve a badge / tag / chip's props into a Material 3 Style.

The H4 sibling of :func:resolve_variant for the badge family (badge, tag, chip). A badge is a compact, pill-shaped status label:

• solid fills with the role color and its legible on_* content;
• subtle fills with the tonal *_container role and its on_*_container content — the WCAG-AA-safe subtle look (a saturated status role on white can fail AA, see :func:_status_container_pair);
• outline is a transparent background with the role color as both content and a same-color border.

Padding is compact (:data:BADGE_DENSITY), the radius is the M3 full pill sentinel, and the font comes from a label-scale typography role. An optional interaction state layers a Material 3 state layer (for a tappable chip); a presentational badge resolves at DEFAULT. Pure and deterministic, like every resolver.

Parameters:

Name	Type	Description	Default
variant	BadgeVariant	The badge treatment (solid / subtle / outline).	required
size	ResponsiveSize	The density size — a single :class:~tempest_core.style.Size or a per-breakpoint map resolved against the theme + media.	required
color_scheme	str	The Material 3 role family to paint with — one of :data:VALID_COLOR_SCHEMES (incl. the H4 status families "success" / "warning" / "info").	required
theme	Theme	The theme whose tokens supply colors, spacing, shape and type.	required
state	ComponentState	The interaction state to resolve for (default :attr:~tempest_core.style.ComponentState.DEFAULT).	DEFAULT
platform_dark_mode	bool	The OS dark-mode flag, used to resolve the scheme.	False
media	MediaQueryData | None	The current viewport snapshot for a responsive size.	None

Returns:

Type	Description
Style	The resolved, frozen Style for the requested badge combination.

Raises:

Type	Description
ValueError	If color_scheme is unknown or the size map is malformed.

resolve_badge_variant_states(*, variant, size, color_scheme, theme, platform_dark_mode=False, media=None)

Resolve the full per-state style table for a badge variant + size + scheme.

The H4 badge-family counterpart of :func:resolve_variant_states — the seam a tappable chip's renderer consumes to apply the matching state layer on real pointer/focus events.

Parameters:

Name	Type	Description	Default
variant	BadgeVariant	The badge treatment (solid / subtle / outline).	required
size	ResponsiveSize	The density size (single or responsive map).	required
color_scheme	str	The Material 3 role family — one of :data:VALID_COLOR_SCHEMES.	required
theme	Theme	The theme whose tokens supply the values.	required
platform_dark_mode	bool	The OS dark-mode flag.	False
media	MediaQueryData | None	The current viewport snapshot for a responsive size.	None

Returns:

Type	Description
dict[ComponentState, Style]	A mapping of every :class:~tempest_core.style.ComponentState to its
dict[ComponentState, Style]	resolved Style.

Raises:

Type	Description
ValueError	If color_scheme is unknown or the size map is malformed.

resolve_field_variant(*, variant, size, color_scheme, theme, state=ComponentState.DEFAULT, invalid=False, platform_dark_mode=False, media=None)

Resolve a text-field's Chakra-style props into a Material 3 Style.

The H2 sibling of :func:resolve_variant for the field family (text input, text area, select/dropdown, masked input, autocomplete, pin). A field is focus-led: the resting treatment is low-emphasis (outline / filled / flushed) and the color_scheme role only tints the focus border/caret/label. An invalid field forces the border + label to the error role in every state (it coexists with the field's separate error-message text, which the field widget renders elsewhere). Pure and deterministic, like every resolver.

Parameters:

Name	Type	Description	Default
variant	FieldVariant	The field treatment (outline / filled / flushed).	required
size	ResponsiveSize	The density size — a single :class:~tempest_core.style.Size or a per-breakpoint map resolved against the theme + media.	required
color_scheme	str	The Material 3 role family the focus tint paints with — one of :data:VALID_COLOR_SCHEMES.	required
theme	Theme	The theme whose tokens supply colors, spacing, shape and type.	required
state	ComponentState	The interaction state to resolve for (default :attr:~tempest_core.style.ComponentState.DEFAULT).	DEFAULT
invalid	bool	Whether the field is in an invalid (error) state — forces the border/label to the error role.	False
platform_dark_mode	bool	The OS dark-mode flag, used to resolve the scheme.	False
media	MediaQueryData | None	The current viewport snapshot for a responsive size.	None

Returns:

Type	Description
Style	The resolved, frozen Style for the requested field combination.

Raises:

Type	Description
ValueError	If color_scheme is unknown or the size map is malformed.

resolve_field_variant_states(*, variant, size, color_scheme, theme, invalid=False, platform_dark_mode=False, media=None)

Resolve the full per-state style table for a field variant + size + scheme.

The H2 field-family counterpart of :func:resolve_variant_states — the seam the renderers consume to apply the matching style on real focus/hover events.

Parameters:

Name	Type	Description	Default
variant	FieldVariant	The field treatment (outline / filled / flushed).	required
size	ResponsiveSize	The density size (single or responsive map).	required
color_scheme	str	The Material 3 role family — one of :data:VALID_COLOR_SCHEMES.	required
theme	Theme	The theme whose tokens supply the values.	required
invalid	bool	Whether the field is in an invalid (error) state.	False
platform_dark_mode	bool	The OS dark-mode flag.	False
media	MediaQueryData | None	The current viewport snapshot for a responsive size.	None

Returns:

Type	Description
dict[ComponentState, Style]	A mapping of every :class:~tempest_core.style.ComponentState to its
dict[ComponentState, Style]	resolved Style.

Raises:

Type	Description
ValueError	If color_scheme is unknown or the size map is malformed.

resolve_selection_variant(*, size, color_scheme, theme, state=ComponentState.DEFAULT, checked=False, platform_dark_mode=False, media=None)

Resolve a selection control's props into a Material 3 Style.

The H2 sibling of :func:resolve_variant for the selection family (checkbox, switch, radio row). Material 3 gives selection controls a single affordance each, so there is no variant param. The resolved style carries: the accent (color_scheme role) as color (the tick / on-track); background = the accent when checked else transparent (no fill); the outline role as the empty-ring border when unchecked; and the control box dimension (width == height) from :data:SELECTION_SIZE. The 48dp touch target is the parent row's job, never the box.

Parameters:

Name	Type	Description	Default
size	ResponsiveSize	The density size — a single :class:~tempest_core.style.Size or a per-breakpoint map resolved against the theme + media.	required
color_scheme	str	The Material 3 role family the accent paints with — one of :data:VALID_COLOR_SCHEMES.	required
theme	Theme	The theme whose tokens supply colors and the dimension.	required
state	ComponentState	The interaction state to resolve for.	DEFAULT
checked	bool	Whether the control is currently selected/on.	False
platform_dark_mode	bool	The OS dark-mode flag, used to resolve the scheme.	False
media	MediaQueryData | None	The current viewport snapshot for a responsive size.	None

Returns:

Type	Description
Style	The resolved, frozen Style for the requested selection combination.

Raises:

Type	Description
ValueError	If color_scheme is unknown or the size map is malformed.

resolve_selection_variant_states(*, size, color_scheme, theme, checked=False, platform_dark_mode=False, media=None)

Resolve the full per-state style table for a selection control.

The H2 selection-family counterpart of :func:resolve_variant_states.

Parameters:

Name	Type	Description	Default
size	ResponsiveSize	The density size (single or responsive map).	required
color_scheme	str	The Material 3 role family — one of :data:VALID_COLOR_SCHEMES.	required
theme	Theme	The theme whose tokens supply the values.	required
checked	bool	Whether the control is currently selected/on.	False
platform_dark_mode	bool	The OS dark-mode flag.	False
media	MediaQueryData | None	The current viewport snapshot for a responsive size.	None

Returns:

Type	Description
dict[ComponentState, Style]	A mapping of every :class:~tempest_core.style.ComponentState to its
dict[ComponentState, Style]	resolved Style.

Raises:

Type	Description
ValueError	If color_scheme is unknown or the size map is malformed.

resolve_size(size, theme, *, media=None)

Resolve a (possibly responsive) size prop to a concrete Size.

A bare :class:~tempest_core.style.Size resolves to itself. A per-breakpoint map is resolved mobile-first against the theme's :class:~tempest_core.tokens.Breakpoints and the optional viewport width from media: the entry for the widest breakpoint whose min-width the viewport meets wins, falling back to "base" (or the smallest provided entry) when no width context is available.

Parameters:

Name	Type	Description	Default
size	ResponsiveSize	The size prop — a single Size or a {"base": …, "md": …} map.	required
theme	Theme	The theme whose breakpoints resolve the map.	required
media	MediaQueryData | None	The current viewport snapshot; when None (or width 0) the "base" entry is used.	None

Returns:

Type	Description
Size	The concrete Size for the current viewport.

Raises:

Type	Description
ValueError	If size is an empty map or names an unknown breakpoint.

resolve_slider_variant(*, size, color_scheme, theme, state=ComponentState.DEFAULT, platform_dark_mode=False, media=None)

Resolve a slider's props into a Material 3 Style.

The H2 sibling of :func:resolve_variant for the slider family (slider, range slider). Material 3 gives a slider a single affordance, so there is no variant param. The resolved style carries: the accent (color_scheme role) as color (the active track + thumb); the surface_variant role as background (the inactive track); the track thickness as height from :data:SLIDER_SIZE; and a thumb radius hint as radius (the M3 full pill). The thumb halo + 48dp touch target are the renderer's job, never the track height.

Parameters:

Name	Type	Description	Default
size	ResponsiveSize	The density size — a single :class:~tempest_core.style.Size or a per-breakpoint map resolved against the theme + media.	required
color_scheme	str	The Material 3 role family the accent paints with — one of :data:VALID_COLOR_SCHEMES.	required
theme	Theme	The theme whose tokens supply colors and the track thickness.	required
state	ComponentState	The interaction state to resolve for.	DEFAULT
platform_dark_mode	bool	The OS dark-mode flag, used to resolve the scheme.	False
media	MediaQueryData | None	The current viewport snapshot for a responsive size.	None

Returns:

Type	Description
Style	The resolved, frozen Style for the requested slider combination.

Raises:

Type	Description
ValueError	If color_scheme is unknown or the size map is malformed.

resolve_slider_variant_states(*, size, color_scheme, theme, platform_dark_mode=False, media=None)

Resolve the full per-state style table for a slider.

The H2 slider-family counterpart of :func:resolve_variant_states.

Parameters:

Name	Type	Description	Default
size	ResponsiveSize	The density size (single or responsive map).	required
color_scheme	str	The Material 3 role family — one of :data:VALID_COLOR_SCHEMES.	required
theme	Theme	The theme whose tokens supply the values.	required
platform_dark_mode	bool	The OS dark-mode flag.	False
media	MediaQueryData | None	The current viewport snapshot for a responsive size.	None

Returns:

Type	Description
dict[ComponentState, Style]	A mapping of every :class:~tempest_core.style.ComponentState to its
dict[ComponentState, Style]	resolved Style.

Raises:

Type	Description
ValueError	If color_scheme is unknown or the size map is malformed.

resolve_surface_variant(*, variant, color_scheme='neutral', theme, elevation=None, padding_step='md', radius_step='md', platform_dark_mode=False, media=None)

Resolve a surface/card's Chakra-style props into a Material 3 Style.

The H3 sibling of :func:resolve_variant for the surface family (card, surface, panel, accordion header). A surface is non-interactive — there is no state parameter and no per-state table (D5): it simply chooses how the box is filled and whether it carries an elevation shadow (elevated), a tonal fill (filled) or a hairline outline (outlined). Every treatment paints onto existing :class:~tempest_core.style.Style fields, so no new field is introduced (D1): elevation is realized as a :class:~tempest_core.style.Shadow mapped from the M3 level, never an elevation style field.

The color_scheme tints the surface (D2): "neutral" uses the plain SURFACE / ON_SURFACE roles; a role family ("primary", …) uses the tonal *_container role as the background and its on_*_container role as the content. Padding and radius come from the spacing/shape scales via the padding_step / radius_step token-step names (D6). Pure and deterministic, like every resolver.

Parameters:

Name	Type	Description	Default
variant	CardVariant	The surface treatment (elevated / filled / outlined).	required
color_scheme	str	The Material 3 role family to tint with — one of :data:VALID_COLOR_SCHEMES (default "neutral").	'neutral'
theme	Theme	The theme whose tokens supply colors, spacing, shape and elevation.	required
elevation	int | None	An explicit Material 3 elevation level (0-5) overriding the variant default; None uses the per-variant default (elevated → level 1, filled/outlined → level 0).	None
padding_step	str	The spacing-scale step name for the surface padding (default "md").	'md'
radius_step	str	The shape-scale step name for the surface corner radius (default "md").	'md'
platform_dark_mode	bool	The OS dark-mode flag, used to resolve the scheme.	False
media	MediaQueryData | None	The current viewport snapshot (accepted for signature parity with the other resolvers; unused here as a surface has no responsive size).	None

Returns:

Type	Description
Style	The resolved, frozen Style for the requested surface combination.

Raises:

Type	Description
ValueError	If color_scheme is unknown or elevation is outside the 0-5 range.

resolve_variant(*, variant, size, color_scheme, theme, state=ComponentState.DEFAULT, platform_dark_mode=False, media=None)

Resolve Chakra-style variant props into a concrete Material 3 Style.

This is the heart of H1: a pure function that maps variant / size / color_scheme (+ an interaction state) onto a frozen :class:~tempest_core.style.Style, resolved against the theme's M3 tokens. It is renderer-agnostic and deterministic, so it is unit-tested exhaustively and pinned by the conformance suite. See the module docstring for the full variant→treatment, size→density and state→state-layer mapping.

Parameters:

Name	Type	Description	Default
variant	Variant	The visual treatment (solid/outline/ghost/link).	required
size	ResponsiveSize	The density size — a single :class:~tempest_core.style.Size or a per-breakpoint map resolved against the theme + media.	required
color_scheme	str	The Material 3 role family to paint with — one of :data:VALID_COLOR_SCHEMES.	required
theme	Theme	The theme whose tokens supply colors, spacing, shape and type.	required
state	ComponentState	The interaction state to resolve for (default :attr:~tempest_core.style.ComponentState.DEFAULT).	DEFAULT
platform_dark_mode	bool	The OS dark-mode flag, used to resolve SYSTEM theme mode to the right color scheme.	False
media	MediaQueryData | None	The current viewport snapshot, used to resolve a responsive size map; None resolves to the "base" entry.	None

Returns:

Type	Description
Style	The resolved, frozen Style for the requested combination.

Raises:

Type	Description
ValueError	If color_scheme is not one of :data:VALID_COLOR_SCHEMES, or the responsive size map is malformed.

resolve_variant_states(*, variant, size, color_scheme, theme, platform_dark_mode=False, media=None)

Resolve the full per-state style table for a variant + size + scheme.

This is the seam the renderers consume: a styled component asks for every interaction state up front (default/hover/pressed/disabled/ focus) and hands the table to the renderer, which applies the matching style on real pointer/focus events (Qt QSS pseudo-states; Compose InteractionSource / Material3 state layers). The resolution stays pure and in the engine; only the event→state mapping lives in the renderers.

Parameters:

Name	Type	Description	Default
variant	Variant	The visual treatment.	required
size	ResponsiveSize	The density size (single or responsive map).	required
color_scheme	str	The Material 3 role family — one of :data:VALID_COLOR_SCHEMES.	required
theme	Theme	The theme whose tokens supply the values.	required
platform_dark_mode	bool	The OS dark-mode flag.	False
media	MediaQueryData | None	The current viewport snapshot for a responsive size.	None

Returns:

Type	Description
dict[ComponentState, Style]	A mapping of every :class:~tempest_core.style.ComponentState to its
dict[ComponentState, Style]	resolved Style.

Raises:

Type	Description
ValueError	If color_scheme is unknown or the size map is malformed.