Box

Box is the foundational layout container: padding, margin, gap, display modes, alignment, borders, backgrounds, state washes, sizing, and positioning hooks. It carries no semantic meaning on its own—it organizes content. The mental model is “styled rectangle,” not “interactive control.” Box is configured by props rather than named visual variants. Common combinations: Box renders a container around children. Nesting Boxes is normal; keep depth readable. FlexBox is Box with flex display preset—choose it to reduce boilerplate, not to change semantics. Prefer item={FlexItem.*} on Box or FlexBox instead of CSS-module flex shorthand. Recipes bundle grow, shrink, basis, and (for scroll hosts) minHeight, minWidth, and overflow. Use alignSelf when one child breaks out of the parent cross-axis alignment. For ratio columns (2:1, 3:1, ten equal tracks, queue metric widths), use Grid template={GridTemplate.*} instead of flex basis tricks on Box. BlockSize.ExtraLargeControl sets a 40px block size (--space-40), aligned with ButtonSize.ExtraLarge and InputSize.ExtraLarge. Use it on height or minHeight for bordered FlexBox pills (for example Call Dock number and timer rows) instead of padding on a shorter box. InlineSize.ControlColumn sets a 56px inline size (--space-56) on width, minWidth or maxWidth for a column that stacks an Extra Large control over its caption without shifting when the label toggles. Give the outer column a definite block size (height={BlockSize.Full} inside a sized parent, or a viewport step). On the row that should absorb leftover space and scroll, set item={FlexItem.FillScroll} (or explicit grow, shrink, minHeight={BlockSize.Zero}, and overflow={Overflow.Auto}). shrink alone only clears the inline-axis minimum; block-axis flex scrolling needs minHeight={BlockSize.Zero}. Do Don’t gradient={GradientPaint.*} applies Chroma's paint_wash_<id> recipe: a diagonal wash over --color-wash-ground, paired light text through --color-fg-on-wash-*, mirrored under right-to-left layout, and dropped under prefers-contrast: more and forced colors. Only blocks inside @prepared911/ui set this prop from their own state enum. Shells and remotes pass state into the block; they do not choose a wash on Box or FlexBox directly. Text and Icon inside a wash use the default foreground tokens; do not add a color prop to force dark ink on the wash. Pair the wash with a label or icon so state is never conveyed by color alone. When a Light wash needs a stroke, use border-transient. Do not set background on the same node as gradient. For wall and board layouts that measure a cell at runtime, map the measured scale with toZoomStep and pass the result on zoom. The helper rounds down so content never overflows the cell. Do not use 0.4 on desktop UI; zoom shrinks text with the layout.