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

PaintedPanel

A painted floating Panel: its outline, for callers that clip their content to it, and the theme to draw that content with.

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.

DisplayEdge

What a display’s edge says (paint_display_edge).

Constants

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, in surface steps: under the stock hover lift, the calmest a floor goes while the theme’s hover stays at the stock half step.

FLOOR_REST_SHARE

Share of the theme’s hover lift a floored control’s rest face sits at. A theme whose hover is quieter than the stock half step (crate::tokens::ResponseStep::LIFT_ADMITTED admits 0.25) takes the rest face down with it, so a hovered control never reads quieter than an idle one on any theme.

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: the stock theme’s hover response (crate::tokens::ResponseStep::HOVER_LIFT).

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: the stock theme’s press response.

RAIL_GAP

RAIL_HIT_H

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

RAIL_MARGIN

How far the rail keeps inside the content’s bottom edge, within the strip’s bottom gutter: flush with the screen’s edge, six pixels of mark on the last rows read as a pager the screen had cropped, and further up it floated over the windows’ own bottom edge.

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

Flush with the screen’s right edge: the segments are an edge mark, and a gap between them and the edge read as a stray, misplaced control.

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.

desktop_ground

The desktop’s own ground: what shell chrome drawn over the whole desktop (the overview’s pictured windows and their captions) stands on.

disclosure_gutter

The gutter a disclosure chevron hangs in, left of the content it opens (icon_sm and the gap to what follows it): the one step a list indents a nested row by, so a row’s chevron stands in the gutter of its own depth and the rows’ content keeps one column.

fill_scrim

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

lightness_step

OKLCH lightness distance between two colours.

on_panel

The theme a floating Panel’s contents are drawn with: theme as seen from the panel_ground (Theme::on_ground). paint_panel returns it; a surface that paints its panel in one pass and its contents in another derives it here.

paint_alignment_guide

An alignment guide: the line a dragged object lines up with while it is near enough to snap (a display on the arrangement canvas, a shape on a slide), from from to to. The accent as a mark on a surface, one chrome rule wide; drawn only while the drag is snapped to that line.

paint_display_edge

Paint edge along the inside of display’s rectangle.

paint_hairline_outline

A derived hairline round shape on ground: a whole-row target that should read as one without a body of its own.

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 and the theme the panel’s contents are drawn with.

paint_panel_edge

A Panel’s derived edge: panel_border, stroked half a pixel inside its outline so the 1 px edge is crisp and stays the panel’s own outermost pixel row.

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 of a floating ChromeRole::Panel, stroked on its outermost pixel row: the design language’s inner hairline (white at 7 % on a dark material, black at 8 % on a light one, crate::tokens::Elevation::floating_edge). High contrast draws the full-strength edge (PANEL_BORDER_ALPHA), where it is the only thing separating a panel.

panel_ground

The opaque colour a chrome surface is built from: the floating level, surfaces.overlay, verbatim (docs/design-language.md, “Surfaces”). A floating surface separates by its level, its two-layer shadow and its inner hairline together, never by drifting off its level.

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

The rest face of a control with its own floor on ground: the idle rung of selection_floor_ramp, for the painters that keep the floor under every state themselves.

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.