Module shell 

The shared vocabulary the OS’s own chrome is drawn from.

Shell chrome does not invent appearance (crates/sdk/ui-core/HIG.md §9): it selects a role, which resolves to tokens in crate::tokens. Colors::lift and Colors::hairline_on measure their move against the ground by relative luminance, so they behave on dark, light and high-contrast without a per-theme branch.

Structs

RowJoin

Which neighbours of a selected row are selected too. A run of selected rows reads as one lift: the corners where two lifted rows meet are square, so the run has no notch between its rows.

SelectionState

The three inputs that decide how a chosen-from control looks.

SelectionTier

How one control paints for one frame.

StripRail

A map of the windows along one strip, and where on it the user is standing — the counterpart of StripRibbon for the axis a strip can overflow. Three facts in order of importance: how many windows the strip holds (one segment each — the fact that makes travel worth attempting), which has focus (the long, bright segment), and which are on screen right now (the middle weight, sliding as the strip pans).

StripRibbon

Geometry and appearance for the strip ribbon — the indicator for which strip of the current workspace has focus, and how many there are (HIG §9.10, §9.11). Every strip renders at once sharing the content height, so this means the strip with focus (where a new window joins, where the keyboard is aimed), not “the strip you can see”.

Enums

ChromeRole

What a chrome surface is. Picking the role fixes radius, surface and border together, so two surfaces of the same role are consistent without their authors having to coordinate.

Constants

FLOOR_HOVER_T

Where its hovered face sits.

FLOOR_IDLE_T

Where the rest face of a control with its own floor sits on the ramp selection_floor_ramp walks from the ground.

GLASS_ACTIVE_ALPHA

Film alpha of an active or pressed selector. Well short of opaque — the ground has to keep coming through, or the material stops being glass.

GLASS_EDGE_ACTIVE_ALPHA

Edge alpha of an active selector at the lit end; runs down to GLASS_EDGE_SEAT_SCALE of itself at the seated end, making the edge a light rather than a halo.

GLASS_EDGE_HOVER_ALPHA

Edge alpha of a hovered selector. Below HAIRLINE_ALPHA — a hover is pointed at, not chosen, and a full hairline reads as a second active tab. Carries more of the state than it looks like: the light preset’s translucent body only lands ~3 levels off its ground (bar sits ~19 below white) versus ~12 on a graphite ground, but Colors::hairline_on picks whichever polarity moves the ground it’s actually drawn on.

GLASS_EDGE_SEAT_SCALE

How much of its lit-end strength a selector’s edge keeps at the seated end.

GLASS_GLOW_SPAN

Fraction of a selector’s height over which its inner glow survives. A lit rim, not a ring — stroked at constant alpha all the way round it becomes the milky halo that made the active pill look cheap.

GLASS_HOVER_ALPHA

Film alpha of a hovered selector.

GLASS_LIT_GAIN

Film density at the lit end of a selector, relative to its own alpha.

GLASS_LIT_SPAN

How far down a selector the lit end’s extra density decays to the body’s own value. Spread over half the pill this would read as “a lighter grey”; concentrated near the edge it reads as light landing on a surface.

GLASS_SEAT_FALLOFF

Film density at the seated end, relative to its own alpha.

GLOW_ALPHA

Alpha of the inset stroke that gives an active control its inner glow.

HAIRLINE_ALPHA

Alpha of the hairline that gives a lifted control a defined edge.

HOVER_LIFT_T

Fraction of the full active lift a hovered control reaches.

PANEL_BORDER_ALPHA

Alpha of the edge around a floating ChromeRole::Panel. Heavier than a control’s hairline because a panel must separate itself from whatever content it floats over, not just a surface already in view — on high-contrast it’s the only thing that does (see panel_ground).

PRESS_SCALE

Uniform scale a pressed control takes, about its own centre.

RAIL_GAP

RAIL_HIT_H

Minimum pointer target (HIG §9.6) across the rail’s short axis.

RAIL_MARGIN

RAIL_SEG_H

Matches RIBBON_SEG_W on its own axis, so the two controls read as the same object turned ninety degrees.

RAIL_SEG_W

RAIL_SEG_W_FOCUSED

RIBBON_GAP

Sized so segment height plus gap equals RIBBON_HIT_W: adjacent hit rects tile without overlapping, so a click near a boundary belongs to exactly one strip.

RIBBON_HIT_W

Minimum pointer target (HIG §9.6) — the segment itself is 6 px wide.

RIBBON_MARGIN

RIBBON_SEG_H

RIBBON_SEG_H_FOCUSED

Longer than RIBBON_SEG_H, so the ribbon reads at a glance without needing colour to carry the signal — what keeps it legible on high-contrast.

RIBBON_SEG_W

SCRIM_LEVEL_SHARE

Share of a scrim’s strength that the flat level stage takes; the tone stage takes the whole of it. See fill_scrim.

SELECTION_MIN_STEP

Smallest OKLCH lightness step between a selected row and the ground it stands on for the selection to read. Lightness, not relative luminance: luminance compresses at the dark end, where a perfectly visible step measures under a light-theme threshold.

Functions

chrome_hairline

A separator or edge drawn on a chrome surface. Derived against the ground it sits on rather than a declared border_standard, which doesn’t track what’s under a translucent panel and either vanishes on one theme or glares on another.

column_gutter

The content edge of a window’s overview or content column, from the column’s leading edge: where the shell starts the column’s header title, and so where the column’s rows, headings and fields start their text. A list painted edge to edge in a column puts its rows’ outer rects at column_gutter - row_bleed.

fill_scrim

Paint a scrim over rect at strength, in the theme’s own scrim hue.

glass_selector

Same three states and ordering as selection_tier — not a second opinion about what “active” means — but the bodies are films rather than washes, carrying the light direction the tier table has no field for. Kept separate rather than replacing it: a translucent fill handed to a caller that fills it flat is weaker than an opaque wash, so the swap must happen per surface, together with its painter.

lightness_step

OKLCH lightness distance between two colours.

paint_glass_body

Paint one selector’s body in the glass material: film, edge, and — for a lifted one — a lit inner rim.

paint_panel

Paint a floating ChromeRole::Panel body: its shadow at shadow_intensity, the panel_ground fill and the 1 px panel_border, all at the Panel radius. Returns the body’s outline for callers that clip their content to it.

paint_row_selection

Paint the selection of one row of a list: the hover or active lift of ground (selection_tier_on) on rect with the item radius (radii.item), and nothing for an idle row. A row is a lift with primary ink and nothing else: no hue, no border, no leading bar.

paint_row_selection_joined

paint_row_selection for a row inside a run of selected rows: the corners shared with a lifted neighbour are square, so adjacent selected rows join into one lift (a multi-selection in a mail list).

panel_border

The edge around a floating ChromeRole::Panel. See PANEL_BORDER_ALPHA.

panel_ground

The opaque colour a chrome surface is built from, guaranteed to register against both the desktop and the window card (Bar/Panel share one material, and a Panel floats over app content).

panel_shadow

Lay down a floating panel’s elevation, clipped to the ring outside its own silhouette. The shadow is crate::surface::shadow, a blur of the panel’s own rounded rect (so it stays even around a corner instead of showing a flat-edged ghost of a square one). The ring clip stays even though chrome is opaque: a blurred rect is solid in the middle, and a half-faded panel (intensity) must not darken its own interior on the way in.

row_bleed

How far a row’s hover and selection lift, and a zebra stripe, bleed past the column’s content edge on each side (s2).

scrim_channel

What fill_scrim does to one 8-bit channel behind it, given that channel of the scrim hue: the same tone and level stages, for a host that composites a scrim on the CPU (a cached frame) instead of through the shader.

scrim_maps

What fill_scrim does to one 8-bit grey behind it, as a pure function so the property the two fills are for can be asserted without a GPU. Must mirror the shader: soft light against black is Cb² (W3C compositing) composited lerp(Cb, Cb², αs), then an ordinary source-over of the theme’s scrim hue for the level stage.

selection_floor_ramp

The face of a control that has its own floor (a filled rest face rather than a transparent one), for state, standing on ground: one ordered ramp from the ground, so rest, hover and active are each further from the ground than the last on every material, and no state mixes a floor with the transparent tier.

selection_tier

Resolve one control’s appearance. This is the only way the shell expresses “which one is chosen” — active tab, active workspace, active strip, selected row, chosen scope chip, current power profile.

selection_tier_on

selection_tier for a control that sits on ground rather than on surfaces.base: a list row on a sidebar, a menu row on panel_ground, a card on a sheet. The active fill is one surface step of that ground (Colors::lift_on) and hover is half a step, so a selection is the same lift on every ground, including a raised or white one where a lift of the desktop would vanish into it.