Module primitives 

The design system’s primitives (docs/design-language.md, “Primitives”): the only way to build these things. Each owns its padding, radius, colour and motion; callers pass content, never geometry or colour.

Primitive	Is
Surface / paint_surface	one of the five surface levels with its edge and shadow
paint_document_sheet	a document that brings its own colours, on a sheet with an edge
paint_see_through	the see-through material for chrome over pixels being chosen
FloatingPanel / FloatingPanelFace	a floating surface with header, body and footer slots
TextStack / TextStackFace	title, secondary and tertiary lines
TextLineFace	one line of words in a role, measured and centred or started
TextBlockFace	wrapped running text in one style, at a width
paint_control_row	a Control’s fill, edge and focus ring, the list language
Facts / FactsFace	separate facts with space between, never a joined string
KeyHintsFace	drawn keycaps and what they do
BarControlFace	a top bar or window bar control
ActivityCardFace	an activity’s card on the floating layer
BarChip / BarChipFace	a bar control holding a face stack, a label and a press
IconButton	a square icon button whose name is required
DisclosureRow	a row whose body opens in place
DensityRegion	a region laid out at compact (or comfortable) density
QuickTileFace / paint_level_gauge	a Quick Settings tile’s ground, ink and chevron rule; a charge gauge
StatusCluster / StatusClusterFace	the bar’s status cluster: slots, a count and the critical-battery wash

The rest of the set is the existing shared widgets, restyled on the tokens: crate::widget::Button (primary, secondary, quiet = crate::widget::ButtonRole::Plain, destructive), crate::widget::Chip (people, tags, filters only), crate::widget::Toggle, crate::widget::Checkbox, crate::widget::ToggleGroup (segmented), crate::widget::Slider, crate::widget::ListRow, crate::widget::Section, crate::widget::PropertyList, crate::widget::Breadcrumb, crate::widget::EmptyState, crate::widget::Banner and the toast.

Structs

ActivityCardFace

An activity’s card, ready to paint: what it says, what its own controls are called out loud, and what the person is doing to it.

BarChip

A bar chip as a retained widget: the BarChipFace’s content with its own press.

BarChipFace

One bar chip’s content and state, borrowed. Built by the caller each frame; Self::paint draws it and hands back where its parts landed.

BarChipLayout

Where a BarChipFace painted its parts.

BarChipProps

One bar control that stands for people: their faces, a label and a press. A chip with faces opens who is here, an invite opens the host’s own invite flow; a press reaches the view’s press event, which is the same action the palette, scripts and agents invoke.

BarControlFace

A bar control’s content and state, borrowed.

DeclaredModal

A modal driven from a view: its answers and its dismissal reach the view’s events.

DeclaredPanel

A floating panel whose body, header and footer may change by key.

DeclaredPopover

A popover whose content may change by key.

DeclaredPopoverButton

A popover button whose content may change by key.

DensityRegion

A region of a window laid out and drawn at another density (crate::tokens::Density): a data-heavy sidebar or list at compact while the rest of the window stays comfortable. Rows, rhythm and tables inside it take the region’s density; controls and text keep their size.

DisclosureGroup

Rows that keep one open at a time. Clone it into every row of the group; a view that rebuilds its rows keeps the group and keys the rows (DisclosureRow::keyed).

DisclosureRow

A row that opens its body in place.

DisclosureRowProps

A row whose body opens in place under it: a device’s details, a run’s log, a setting’s options. Its chevron turns as it opens, and what follows moves down with it. A press on the row, Enter or Space opens and closes it.

DisclosureState

Whether a disclosure row is open, its reveal and its body’s open height: what outlives the row when the view that owns it rebuilds it. Clones share one state.

Fact

One fact: an optional icon from the icon set and its text.

FactProps

One fact of a row of facts: its text, and a glyph before it.

Facts

A retained FactsFace.

FactsFace

A row of facts, borrowed.

FactsProps

Separate facts in one row, each an optional glyph and its text, with space between them and no separator glyph: “12 files”, “3 MB”, “Edited today” are three facts. Where the row is too narrow, the facts that matter least give way first.

FloatingPanel

A retained floating panel: a header slot, a body and a footer slot.

FloatingPanelFace

A floating panel’s shape: how tall its header and footer are and whether its body holds anything.

FloatingPanelLayout

Where a floating panel’s parts stand, from FloatingPanelFace::layout.

FloatingPanelProps

A floating panel a view places itself: a header slot, a body and a footer slot, on the floating material.

IconButton

The square icon button. Each constructor requires the accessible name, which is also the tooltip; there is no way to make an unnamed one.

KeyHint

One hint: the keys of a chord, as printed on the keyboard, and what pressing them does.

KeyHintProps

One hint of a strip: the keys of a chord and what pressing them does.

KeyHints

A retained strip of key hints: a chord’s drawn keycaps on a row’s trailing edge (a shortcut that cannot be changed), or several chords side by side, a sibling gap apart. Never a joined string.

KeyHintsFace

A strip of key hints, borrowed.

KeyHintsProps

Shortcuts and what they do, side by side: each hint the drawn keycaps of a chord and its label (“Enter Save”, “Esc Cancel”), in the person’s own keyboard legends. Never a sentence with a separator glyph.

LinkStatus

The machine’s link, as a surface draws it: what it is, what it is called, and how strong its signal is.

ModalProps

A question over the window: a dimmed page, a sheet with a title, the view’s content, and up to three answers. Escape or a click on the scrim closes it; Enter fires the main answer, except in a destructive question, where Enter is the safe one.

NotificationListLayout

Where a painted notification list put its parts.

NotificationListView

What the list paints and hit-tests: its rows, its paging, its empty state and the host’s cursor.

NotificationRowControls

A row’s trailing controls, where they stand.

PopoverButtonProps

A button that opens a popover anchored to itself: a filter’s options, a share sheet, a picker of values. A press opens it, and it closes by a second press, Escape, or a press outside it.

PopoverProps

A menu or a small form beside its control: the one anchored floating panel. The view’s content is inside it.

QuickTileFace

A Quick Settings tile’s ground: its switch half (main) and, when it has a section, its chevron half (expand).

StatusCluster

The cluster’s one control: its slots, the state they share and how it tells the degrees that matter.

StatusClusterFace

One slot’s drawing, as a bar control’s glyph.

StatusClusterLayout

Where a painted cluster put its parts, for hit-testing and for the accessibility tree.

Surface

A retained surface of one level around one child, padded by the level’s rhythm. A Surface inside a surface of the same level paints no ground of its own.

TextBlockFace

A block of wrapped text in one style, starting at its rect’s leading top corner and wrapping to the rect’s width: a reader’s body, a page’s paragraph, a note’s prose. The shared way to paint running text on a surface a host owns; the host never draws it run by run.

TextLineFace

One line of words in a role, measured and centred on a point or aligned in a box: the bar’s clock reading, a live activity’s headline, an overlay’s timer. It is the shared way to put a single string on a surface; a host never draws a bare text run of its own.

TextStack

A retained TextStackFace.

TextStackFace

A text stack’s lines, borrowed, and how to paint them.

TextStackProps

A title over a secondary line, with an optional third line under it, in fixed roles and at fixed gaps: a file’s name over its folder, a person over their role. Each line is one line, cut short with an ellipsis; two facts never share a line.

Enums

LinkKind

What kind of connection the machine’s link is.

NotificationListControl

What the person asked of the list.

NotificationListRow

One row of the list.

StackSize

How prominent a stack’s title is.

StatusSlot

What one slot of the cluster shows.

SurfaceLevel

TextLineAlign

Where a TextLineFace stands in the rect it is given.

Functions

badge_label

The bell’s count as it reads: 9+ once it needs a second digit, since two digits would crowd the bar.

badge_size

A count badge’s size: s1 of padding above and below the line, s1 either side, never shorter than s4 nor narrower than it is tall.

control_fill

A Control’s fill: the shared hover tier when hovered, otherwise a quiet floor on the same ramp, so a row reads as a surface rather than bare text on the panel. Both states sit on one ordered ramp, so hover is always the more prominent.

control_radius

The Control radius for rect (radii.control).

paint_control_row

Paint one Control: its fill with the derived rest edge at the Control radius, and the toolkit’s 2 px focus ring when focused. The one painter for every tile, card, power row, edit row and list row a host draws, so they cannot drift apart.

paint_document_sheet

A document set on a reader: a page that brings its own colours (an HTML mail on its light sheet, a web page), drawn by content and clipped to the raised level’s radius, with the hairline derived from the window content it stands on just inside its edge, so a sheet as light as that content still has one.

paint_level_gauge

A charge gauge at rect: a rounded rim in the secondary ink, filled to level (0 to 1) in the primary ink.

paint_see_through

Paint the see-through material over rect at radius: half the panel ground over the blurred backdrop, its floating shadow outside it only (a shadow under the body would darken what shows through) and the floating hairline. Only for chrome over pixels the person is choosing (docs/design-language.md, “Material and transparency”). Returns the theme a child standing on it paints with.

paint_severity_rail

The rail a warning or a failure keeps beside its text, so a row’s status is scannable without taking another line; plain information carries no colour, so the rail means something wherever it appears.

paint_surface

Paint level over rect: its shadow, its fill and its edge. Returns the theme a child standing on it paints with (Theme::on_ground): ink, lifts and the raised well re-measured against the level’s fill.

paint_unread_badge

The unread count on a running application’s own icon: the badge a sidebar’s unread count wears, filled in the person’s colour.