themelia-ui 3.0.0 → 3.2.0

package/docs/generated/components/base--structure.md

@@ -15,7 +15,6 @@ Passive siblings need consistent spacing, a grid, or a stack — with no semanti
 
 ```tsx fragment — import-only example
 import { AdaptiveGrid } from "themelia-ui/base/structure"
-import "themelia-ui/base/structure.css"
 ```
 
 ## Composition
@@ -31,6 +30,16 @@ outside the package and arrives through the public props, callbacks, slots, or a
 
 Kind: const.
 
+**Use when:** Equal tracks should be added as minimum-width columns fit the available panel.
+
+**Avoid when:** The design requires an explicit column count or a fixed summary rail.
+
+**Compose:** Set minColumnWidth and shared gaps. Column count follows available width; responsive gap and alignment use viewport steps.
+
+**Capabilities:** auto fit columns; minimum column width; responsive panel grid.
+
+**Alternatives:** Grid, Split.
+
 ```text
 React.ForwardRefExoticComponent<Omit<AdaptiveGridProps, "ref"> & React.RefAttributes<HTMLDivElement>>
 ```
@@ -51,7 +60,7 @@ Extends: `React.ComponentProps<"div">`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `minColumnWidth` | no | `AdaptiveGridMinimum` | Minimum column width before another track is added. |
+| `minColumnWidth` | no | `AdaptiveGridMinimum \| CssLength` | Minimum column width before another track is added: `default`, `sm` or a CSS length. |
 | `gap` | no | `ResponsiveValue<StructureGap>` |  |
 | `align` | no | `ResponsiveValue<StructureAlign>` |  |
 
@@ -59,6 +68,16 @@ Extends: `React.ComponentProps<"div">`.
 
 Kind: const.
 
+**Use when:** Intentional media or a rule must escape a known parent inset.
+
+**Avoid when:** Removing duplicate wrapper padding or hiding accidental overflow.
+
+**Compose:** Match amount to the actual inset. Shipped padding and gap pairs match; check custom themes and focus visibility.
+
+**Capabilities:** edge to edge inset escape; inline block negative margins.
+
+**Alternatives:** ContentBlock.
+
 ```text
 React.ForwardRefExoticComponent<Omit<BleedProps, "ref"> & React.RefAttributes<HTMLDivElement>>
 ```
@@ -81,13 +100,33 @@ Extends: `React.ComponentProps<"div">`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `amount` | no | `ResponsiveValue<StructureGap>` | How far to escape, on the spacing scale. Match it to the padding being cancelled — a<br>surface at `--space-md` bleeds `md` — so the two move together under a density change. @default "none" |
-| `axis` | no | `BleedAxis` | Which way to escape; `both` covers every direction. Sideways is the common case: an<br>image bleeds across and keeps its vertical rhythm. |
+| `amount` | no | `ResponsiveValue<StructureGap>` | How far to escape: one of the two gaps, which equal the two paddings. Match it to the<br>padding being cancelled — a surface padded by `--padding-sm` bleeds `sm` — so the two<br>move together under a density change. @default "none" |
+| `axis` | no | `BleedAxis` | Which way to escape; `both` covers every direction. Sideways is the common case: an<br>image bleeds across and keeps its vertical rhythm. @default "inline" |
+
+### `CssLength`
+
+Kind: type.
+
+A CSS length: a number with a unit or a percentage, or a math or `var()` expression.
+
+```text
+`${number}${"px" | "rem" | "em" | "ch" | "%" | "vw" | "vh" | "dvw" | "dvh" | "svw" | "svh" | "lvw" | "lvh"}` | `${"calc" | "min" | "max" | "clamp" | "var"}(${string})`
+```
 
 ### `Grid`
 
 Kind: const.
 
+**Use when:** Passive siblings need an explicit responsive column count.
+
+**Avoid when:** The column count should follow how many minimum-width tracks fit, or a feature already arranges its children.
+
+**Compose:** Grid owns gaps, not child insets. It uses nearest-container thresholds when containment exists, otherwise viewport thresholds.
+
+**Capabilities:** responsive columns; grid row column gaps; nearest container width.
+
+**Alternatives:** AdaptiveGrid, Stack.
+
 ```text
 React.ForwardRefExoticComponent<Omit<GridProps, "ref"> & React.RefAttributes<HTMLDivElement>>
 ```
@@ -96,6 +135,16 @@ React.ForwardRefExoticComponent<Omit<GridProps, "ref"> & React.RefAttributes<HTM
 
 Kind: const.
 
+**Use when:** A direct Grid child needs a numeric span or a full row.
+
+**Avoid when:** The parent is not a Grid, or a span would exceed its current column count.
+
+**Compose:** Coordinate numeric spans with the parent columns. GridCell spans use viewport steps even when Grid uses container steps.
+
+**Capabilities:** responsive cell span; full row span.
+
+**Alternatives:** Stack.
+
 ```text
 React.ForwardRefExoticComponent<Omit<GridCellProps, "ref"> & React.RefAttributes<HTMLDivElement>>
 ```
@@ -108,7 +157,7 @@ Extends: `React.ComponentProps<"div">`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `span` | no | `ResponsiveValue<GridSpan>` | Columns occupied. `full` spans whatever the grid currently has. |
+| `span` | no | `ResponsiveValue<GridSpan>` | Columns occupied. `full` spans whatever the grid currently has, including in a<br>responsive object. Span breakpoints follow the viewport, not Grid's container. |
 
 ### `GridColumns`
 
@@ -126,12 +175,12 @@ Extends: `React.ComponentProps<"div">`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `columns` | no | `ResponsiveValue<GridColumns>` | Defaults to one column, then two from the md breakpoint. |
+| `columns` | no | `ResponsiveValue<GridColumns>` | Defaults to one column, then two from md. Uses the nearest inline-size query<br>container when present (md = 32rem), otherwise the viewport (md = 48rem). |
 | `gap` | no | `ResponsiveValue<StructureGap>` |  |
 | `rowGap` | no | `ResponsiveValue<StructureGap>` |  |
 | `columnGap` | no | `ResponsiveValue<StructureGap>` |  |
 | `align` | no | `ResponsiveValue<StructureAlign>` |  |
-| `maxWidth` | no | `ResponsiveValue<StructureWidth \| (string & {})>` | Caps the grid's width — a content step, or any CSS length. Same scale as `Stack`. |
+| `maxWidth` | no | `ResponsiveValue<StructureWidth \| CssLength>` | Caps the grid's width — a content step, or any CSS length. Same scale as `Stack`. |
 
 ### `GridSpan`
 
@@ -155,6 +204,16 @@ T | Partial<Record<Breakpoint, T>>
 
 Kind: const.
 
+**Use when:** A fluid main region sits beside a constrained rail that collapses at a chosen viewport step.
+
+**Avoid when:** Needing equal tracks or the standard semantic main/aside layout.
+
+**Compose:** Supply main first and side second. side changes visual placement, not DOM order. Width is a rail maximum, with collapseBelow controlling stacking.
+
+**Capabilities:** fluid main fixed rail; responsive two columns; collapse breakpoint.
+
+**Alternatives:** TwoColumnLayout, Grid.
+
 ```text
 React.ForwardRefExoticComponent<Omit<SplitProps, "ref"> & React.RefAttributes<HTMLDivElement>>
 ```
@@ -168,9 +227,9 @@ Extends: `React.ComponentProps<"div">`.
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
 | `side` | no | `SplitSide` | Which visual column is the fixed one. The DOM order never changes with it: the first<br>child is the main content and the second the side on both settings, so a reader<br>tabbing through reaches the content first either way. |
-| `sideWidth` | no | `ResponsiveValue<StructureWidth \| (string & {})>` | The fixed column's width — a step or any CSS length. A maximum rather than an exact<br>size, so a narrow viewport shrinks the rail instead of squeezing the content beside it<br>to nothing. @default "18rem" |
-| `gap` | no | `ResponsiveValue<StructureGap>` | Space between the two columns. @default "md" |
-| `collapseBelow` | no | `"sm" \| "md" \| "lg" \| "xl" \| "never"` | Below this breakpoint the two columns become one. `never` keeps them side by side at<br>every width. |
+| `sideWidth` | no | `ResponsiveValue<StructureWidth \| CssLength>` | The fixed column's width — a step or any CSS length. A maximum rather than an exact<br>size, so a narrow viewport shrinks the rail instead of squeezing the content beside it<br>to nothing. @default "18rem" |
+| `gap` | no | `ResponsiveValue<StructureGap>` | Space between the two columns. @default "default" |
+| `collapseBelow` | no | `"sm" \| "md" \| "lg" \| "xl" \| "never"` | Below this breakpoint the two columns become one. `never` keeps them side by side at<br>every width. @default "md" |
 
 ### `SplitSide`
 
@@ -190,7 +249,7 @@ Kind: const.
 
 **Avoid when:** An existing component already owns the layout.
 
-**Compose:** Use shared gap and inset props; do not pin local pixel spacing.
+**Compose:** Use gap, direction and alignment props; Stack adds no inset. Let child surfaces own padding.
 
 **Capabilities:** vertical horizontal gap spacing; responsive arrangement.
 
@@ -209,11 +268,11 @@ Extends: `Omit<React.ComponentProps<"div">, "dir">`.
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
 | `direction` | no | `ResponsiveValue<StructureDirection>` | Main axis. @default "vertical" |
-| `gap` | no | `ResponsiveValue<StructureGap>` | Space between children, on the semantic spacing scale. @default "md" |
+| `gap` | no | `ResponsiveValue<StructureGap>` | Space between children: `default` between groups, `sm` inside one. @default "default" |
 | `align` | no | `ResponsiveValue<StructureAlign>` | Cross-axis alignment. @default "stretch" |
 | `justify` | no | `ResponsiveValue<StructureJustify>` | Main-axis distribution. @default "start" |
 | `wrap` | no | `ResponsiveValue<boolean>` | Allows children to flow onto more than one line. @default false |
-| `maxWidth` | no | `ResponsiveValue<StructureWidth \| (string & {})>` | Caps the box's width — a content step (`sm` to `2xl`, `full`, `none`) or any CSS<br>length, such as a form's `26rem`. A field measure is a control decision rather than a<br>content one, which is why a raw length is allowed beside the scale. |
+| `maxWidth` | no | `ResponsiveValue<StructureWidth \| CssLength>` | Caps the box's width — a content width (`default`, `sm`, `full`, `none`) or any CSS<br>length, such as a form's `26rem`. A field measure is a control decision rather than a<br>content one, which is why a raw length is allowed beside the scale. |
 
 ### `StructureAlign`
 
@@ -243,8 +302,11 @@ Kind: type.
 
 Kind: type.
 
+The two gaps: `default` between groups (fields, cards, sections), `sm` inside a group
+(icon and label, title and description, a toolbar's controls). Unset is `default`.
+
 ```text
-"none" | "2xs" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl"
+"none" | "sm" | "default"
 ```
 
 ### `StructureJustify`
@@ -259,16 +321,178 @@ Kind: type.
 
 Kind: type.
 
-A content-width step (`--content-width-*`), or any CSS length for a control measure such
-as a field's ~26rem.
+The content width (`default`), a narrow reading or form measure (`sm`), or any CSS length
+for a control measure such as a field's ~26rem.
 
 ```text
-"sm" | "md" | "lg" | "xl" | "2xl" | "full" | "none"
+"default" | "sm" | "full" | "none"
 ```
 
 ## Preview recipes
 
-Preview route: Form field — `/form-field`
+Preview route: Analytics — `/analytics`
+
+### Compose your own
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+import { ArrowUpIcon, CreditCardIcon } from "lucide-react"
+
+import { Badge } from "themelia-ui/base/badge"
+import { Card } from "themelia-ui/base/cards"
+import { Sparkline } from "themelia-ui/base/chart"
+import { IconBadge } from "themelia-ui/base/display"
+import { Stack } from "themelia-ui/base/structure"
+import { DisplayLabel, Text } from "themelia-ui/base/typography"
+import { Money } from "themelia-ui/primitives"
+
+export default function AnalyticsBlueprint() {
+	return (
+		<Card style={{ maxWidth: "20rem" }}>
+			<Stack gap="sm">
+				<Stack direction="horizontal" align="center" gap="sm">
+					<IconBadge icon={CreditCardIcon} tone="primary" />
+					<DisplayLabel>Revenue</DisplayLabel>
+				</Stack>
+				<Stack direction="horizontal" align="center" justify="between" gap="sm">
+					<Money amount={48200} currency="EUR" size="xl" weight="semibold" />
+					<Badge tone="success">
+						<ArrowUpIcon />
+						12.4%
+					</Badge>
+				</Stack>
+				<Sparkline data={[18, 22, 19, 27, 24, 31, 29, 38]} tone="success" label="Revenue rising over eight weeks" />
+				<Text size="xs" type="secondary">
+					Net of refunds, this quarter
+				</Text>
+			</Stack>
+		</Card>
+	)
+}
+```
+
+### Compose your own timeline
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+import { RocketIcon, WrenchIcon } from "lucide-react"
+
+import { Badge } from "themelia-ui/base/badge"
+import { Stack } from "themelia-ui/base/structure"
+import { Timeline, type TimelineItem } from "themelia-ui/base/timeline"
+import { MonoValue } from "themelia-ui/primitives"
+
+const RELEASES: TimelineItem[] = [
+	{
+		id: "3.1.0",
+		title: "Saved views",
+		timestamp: <MonoValue size="xs" type="secondary">v3.1.0</MonoValue>,
+		icon: RocketIcon,
+		status: "success",
+		description: "Filters and columns can be saved and shared with the team.",
+		children: (
+			<Stack direction="horizontal" gap="sm">
+				<Badge tone="success">Added</Badge>
+				<Badge tone="neutral">Tables</Badge>
+			</Stack>
+		),
+	},
+	{
+		id: "3.0.2",
+		title: "Faster exports",
+		timestamp: <MonoValue size="xs" type="secondary">v3.0.2</MonoValue>,
+		icon: WrenchIcon,
+		status: "neutral",
+		description: "Large exports stream instead of waiting for the whole file.",
+	},
+]
+
+export default function ChangelogBlueprint() {
+	return (
+		<Timeline items={RELEASES} />
+	)
+}
+```
+
+### Compose your own checklist
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+import { CheckIcon, CircleIcon } from "lucide-react"
+
+import { Accordion } from "themelia-ui/base/accordion"
+import { Button } from "themelia-ui/base/buttons"
+import { IconBadge } from "themelia-ui/base/display"
+import { Progress } from "themelia-ui/base/feedback"
+import { Stack } from "themelia-ui/base/structure"
+import { Text } from "themelia-ui/base/typography"
+
+export default function ChecklistBlueprint() {
+	return (
+		<Stack style={{ maxWidth: "34rem", width: "100%" }}>
+			<Progress value={1} max={3} label="1 of 3 steps complete" />
+			<Accordion
+				media="medallion"
+				defaultValue={["invite"]}
+				items={[
+					{
+						value: "profile",
+						title: "Complete your profile",
+						icon: <IconBadge icon={CheckIcon} tone="success" shape="circle" />,
+						content: <Text type="secondary">Name, avatar and time zone are set.</Text>,
+					},
+					{
+						value: "invite",
+						title: "Invite your team",
+						icon: <IconBadge icon={CircleIcon} shape="circle" />,
+						content: (
+							<Stack gap="sm" align="start">
+								<Text type="secondary">Teammates see the same projects and saved views.</Text>
+								<Button>Send invites</Button>
+							</Stack>
+						),
+					},
+					{
+						value: "connect",
+						title: "Connect a data source",
+						icon: <IconBadge icon={CircleIcon} shape="circle" />,
+						content: <Text type="secondary">Postgres, a CSV upload or the REST API.</Text>,
+					},
+				]}
+			/>
+		</Stack>
+	)
+}
+```
+
+### Compose your own
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+import { Button } from "themelia-ui/base/buttons"
+import { Card } from "themelia-ui/base/cards"
+import { MetadataList } from "themelia-ui/base/display"
+import { Stack } from "themelia-ui/base/structure"
+import { toast } from "themelia-ui/base/toaster"
+import { Money } from "themelia-ui/primitives"
+
+export default function CartSummaryBlueprint() {
+	return (
+		<Card title="Order summary" description="3 items" style={{ maxWidth: "24rem" }}>
+			<Stack>
+				<MetadataList
+					layout="rows"
+					items={[
+						{ label: "Subtotal", value: <Money amount={258} currency="EUR" /> },
+						{ label: "Shipping", value: <Money amount={4.8} currency="EUR" /> },
+						{ label: "Tax", value: <Money amount={51.6} currency="EUR" /> },
+						{ label: "Total", value: <Money amount={314.4} currency="EUR" weight="semibold" /> },
+					]}
+				/>
+				<Button onClick={() => toast("Checkout requested", { description: "Preview callback — connect this action to your application." })}>
+					Check out
+				</Button>
+			</Stack>
+		</Card>
+	)
+}
+```
 
 ### Scale
 
@@ -276,29 +500,29 @@ Preview route: Form field — `/form-field`
 import { Stack } from "themelia-ui/base/structure"
 import { Input, NativeSelect } from "themelia-ui/base/text-inputs"
 import { MonoValue } from "themelia-ui/primitives"
-import { Scope } from "themelia-ui/ui-provider"
+import { UIScope } from "themelia-ui/ui-provider"
 
 export default function FormsScale() {
 	return (
-		<Stack gap="lg" style={{ width: "100%" }}>
-			{[1, 0.875, 1.125].map((scale) => (
-				<Scope key={scale} vars={{ "--density-scale": scale }}>
-					<Stack direction="horizontal" gap="md" align="center" justify="start">
+		<Stack style={{ width: "100%" }}>
+			{(["compact", "default", "comfortable"] as const).map((density) => (
+				<UIScope key={density} config={{ density }}>
+					<Stack direction="horizontal" gap="sm" align="center" justify="start">
 						{/* Widths on the wrappers: Input's style lands on the inner control, not its frame. */}
-						<MonoValue size="xs" style={{ width: "3.5rem", flexShrink: 0, fontSize: "0.75rem" }}>
-							{scale}
+						<MonoValue size="xs" style={{ width: "6rem", flexShrink: 0 }}>
+							{density}
 						</MonoValue>
 						{/* Named even in a geometry demo: a placeholder is not a label. */}
 						<div style={{ width: "12rem", flexShrink: 0 }}>
-							<Input placeholder="Field" aria-label={`Example field at density ${scale}`} />
+							<Input placeholder="Field" aria-label={`Example field at ${density} density`} />
 						</div>
 						<div style={{ width: "9rem", flexShrink: 0 }}>
-							<NativeSelect defaultValue="a" aria-label={`Example select at density ${scale}`}>
+							<NativeSelect defaultValue="a" aria-label={`Example select at ${density} density`}>
 								<option value="a">Option</option>
 							</NativeSelect>
 						</div>
 					</Stack>
-				</Scope>
+				</UIScope>
 			))}
 		</Stack>
 	)
@@ -315,7 +539,7 @@ import { Demo } from "./_shared"
 
 export default function OverlayPlacementExample() {
 	return (
-		<Stack direction="horizontal" gap="md" wrap>
+		<Stack direction="horizontal" gap="sm" wrap>
 			{(
 				["center", "inline-start", "inline-end", "block-start", "block-end"] as OverlayPlacement[]
 			).map((placement) => (
@@ -335,7 +559,7 @@ import { Demo } from "./_shared"
 
 export default function OverlayDismissal() {
 	return (
-		<Stack direction="horizontal" gap="md" wrap>
+		<Stack direction="horizontal" gap="sm" wrap>
 			<Demo label="no backdrop dismiss" dismissal={{ backdrop: false }} />
 			<Demo label="no escape" dismissal={{ escape: false }} />
 		</Stack>
@@ -347,6 +571,7 @@ export default function OverlayDismissal() {
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
 import { Stack } from "themelia-ui/base/structure"
+import { Text } from "themelia-ui/base/typography"
 import { UIProvider } from "themelia-ui/ui-provider"
 
 import { ControlRow } from "./_shared"
@@ -358,8 +583,8 @@ export default function TheFactor() {
 		<>
 			{FACTORS.map((scale) => (
 				<UIProvider key={scale} config={{ scale }}>
-					<Stack direction="horizontal" gap="lg" align="center">
-						<code style={{ width: "4rem", fontSize: "var(--text-xs)" }}>{scale}</code>
+					<Stack direction="horizontal" align="center">
+						<Text tag="span" size="xs" mono style={{ width: "4rem", flex: "none" }}>{scale}</Text>
 						<ControlRow />
 					</Stack>
 				</UIProvider>
@@ -369,7 +594,7 @@ export default function TheFactor() {
 }
 ```
 
-### Type can override the master factor
+### Type has its own factor
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
 import { Button } from "themelia-ui/base/buttons"
@@ -380,11 +605,11 @@ import { UIProvider } from "themelia-ui/ui-provider"
 
 export default function TypeFactor() {
 	return (
-		<Stack gap="lg">
+		<Stack>
 			<Stack gap="sm">
 				<Text type="secondary" size="xs">typography.scale 0.875 — type shrinks, control geometry holds</Text>
 				<UIProvider config={{ typography: { scale: 0.875 } }}>
-					<Stack direction="horizontal" gap="md" align="center" wrap>
+					<Stack direction="horizontal" gap="sm" align="center" wrap>
 						<Text>Body copy at this factor.</Text>
 						<Button>Save</Button>
 						<Checkbox label="Check" defaultChecked />
@@ -394,7 +619,7 @@ export default function TypeFactor() {
 			<Stack gap="sm">
 				<Text type="secondary" size="xs">scale 0.875 + typography.scale 1 — geometry shrinks, type holds</Text>
 				<UIProvider config={{ scale: 0.875, typography: { scale: 1 } }}>
-					<Stack direction="horizontal" gap="md" align="center" wrap>
+					<Stack direction="horizontal" gap="sm" align="center" wrap>
 						<Text>Body copy at this factor.</Text>
 						<Button>Save</Button>
 						<Checkbox label="Check" defaultChecked />
@@ -406,37 +631,37 @@ export default function TypeFactor() {
 }
 ```
 
-### Two levels of control
+### A factor, or one variable
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
 import { Stack } from "themelia-ui/base/structure"
 import { Text } from "themelia-ui/base/typography"
-import { Scope } from "themelia-ui/ui-provider"
+import { Scope, UIProvider } from "themelia-ui/ui-provider"
 
 import { ControlRow } from "./_shared"
 
 export default function FactorChain() {
 	return (
-		<Stack gap="lg">
+		<Stack>
 			<Stack gap="sm">
 				<Text type="secondary" size="xs">default</Text>
 				<ControlRow />
 			</Stack>
 			<Stack gap="sm">
-				<Text type="secondary" size="xs">--density-scale: 0.8 — heights and rows tighten, gaps hold</Text>
-				<Scope vars={{ "--density-scale": 0.8 }}>
+				<Text type="secondary" size="xs">scale: 0.875 — every length and type step</Text>
+				<UIProvider config={{ scale: 0.875 }}>
 					<ControlRow />
-				</Scope>
+				</UIProvider>
 			</Stack>
 			<Stack gap="sm">
-				<Text type="secondary" size="xs">--density-scale: 1.4 — gaps open, control heights hold</Text>
-				<Scope vars={{ "--density-scale": 1.4 }}>
+				<Text type="secondary" size="xs">--control-height: 2.5rem — every control, nothing else</Text>
+				<Scope vars={{ "--control-height": "2.5rem" }}>
 					<ControlRow />
 				</Scope>
 			</Stack>
 			<Stack gap="sm">
-				<Text type="secondary" size="xs">--button-h: 2.75rem — one measurement</Text>
-				<Scope vars={{ "--button-h": "2.75rem" }}>
+				<Text type="secondary" size="xs">--radius-sm: 0 — every item corner</Text>
+				<Scope vars={{ "--radius-sm": "0" }}>
 					<ControlRow />
 				</Scope>
 			</Stack>
@@ -457,13 +682,13 @@ import { ControlRow } from "./_shared"
 export default function Nesting() {
 	return (
 		<UIProvider config={{ scale: 1.125 }}>
-			<Stack gap="lg">
+			<Stack>
 				<Text type="secondary" size="sm">
 					Outer scope — 1.125
 				</Text>
 				<ControlRow />
 				<UIProvider config={{ scale: 0.8 }}>
-					<Stack gap="md">
+					<Stack gap="sm">
 						<Text type="secondary" size="sm">
 							Nested scope — 0.8
 						</Text>
@@ -480,6 +705,7 @@ export default function Nesting() {
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
 import { Stack } from "themelia-ui/base/structure"
+import { Text } from "themelia-ui/base/typography"
 import { UIProvider } from "themelia-ui/ui-provider"
 
 import { ControlRow } from "./_shared"
@@ -489,8 +715,8 @@ export default function Density() {
 		<>
 			{(["compact", "default", "comfortable"] as const).map((density) => (
 				<UIProvider key={density} config={{ density }}>
-					<Stack direction="horizontal" gap="lg" align="center">
-						<code style={{ width: "7rem", fontSize: "var(--text-xs)" }}>{density}</code>
+					<Stack direction="horizontal" align="center">
+						<Text tag="span" size="xs" mono style={{ width: "7rem", flex: "none" }}>{density}</Text>
 						<ControlRow />
 					</Stack>
 				</UIProvider>
@@ -509,7 +735,7 @@ import { Panel } from "./_shared"
 
 export default function SidebarVariantExample() {
 	return (
-		<Stack gap="xl">
+		<Stack>
 			<Panel variant="floating" />
 			<Panel variant="inset" />
 		</Stack>
@@ -531,7 +757,7 @@ export default function StackExample() {
 				<Box>vertical, gap sm</Box>
 				<Box>second</Box>
 			</Stack>
-			<Stack direction="horizontal" gap="md" justify="between" align="center">
+			<Stack direction="horizontal" gap="sm" justify="between" align="center">
 				<Box>horizontal</Box>
 				<Box>justify between</Box>
 				<Box>align center</Box>
@@ -550,7 +776,7 @@ import { Box } from "./_shared"
 
 export default function ResponsiveProps() {
 	return (
-		<Stack direction={{ base: "vertical", md: "horizontal" }} gap={{ base: "xs", md: "xl" }}>
+		<Stack direction={{ base: "vertical", md: "horizontal" }} gap={{ base: "sm", md: "default" }}>
 			<Box>stacks on small</Box>
 			<Box>row from md</Box>
 			<Box>gap grows too</Box>
@@ -568,13 +794,14 @@ import { Box } from "./_shared"
 
 export default function GridExample() {
 	return (
-		<Grid columns={{ base: 1, md: 3 }} gap="md">
+		<Grid columns={{ base: 1, md: 3 }} gap="sm">
 			<GridCell span="full"><Box>span full</Box></GridCell>
 			<GridCell><Box>one</Box></GridCell>
 			<GridCell><Box>two</Box></GridCell>
 			<GridCell><Box>three</Box></GridCell>
 			<GridCell span={{ base: 1, md: 2 }}><Box>span 2 from md</Box></GridCell>
 			<GridCell><Box>four</Box></GridCell>
+			<GridCell span={{ base: 1, md: "full", xl: 2 }}><Box>responsive full row</Box></GridCell>
 		</Grid>
 	)
 }
@@ -589,7 +816,7 @@ import { Box } from "./_shared"
 
 export default function AdaptiveGridExample() {
 	return (
-		<AdaptiveGrid minColumnWidth="sm" gap="md">
+		<AdaptiveGrid minColumnWidth="sm" gap="sm">
 			{Array.from({ length: 6 }, (_, i) => (
 				<Box key={i}>card {i + 1}</Box>
 			))}
@@ -607,12 +834,12 @@ import { Box } from "./_shared"
 
 export default function SplitExample() {
 	return (
-		<Stack gap="lg" style={{ width: "100%" }}>
-			<Split sideWidth="14rem" gap="md">
+		<Stack style={{ width: "100%" }}>
+			<Split sideWidth="14rem" gap="sm">
 				<Box>main content, takes the rest</Box>
 				<Box>side, 14rem</Box>
 			</Split>
-			<Split side="start" sideWidth="14rem" gap="md">
+			<Split side="start" sideWidth="14rem" gap="sm">
 				<Box>main content — still first in the DOM</Box>
 				<Box>side, drawn on the left</Box>
 			</Split>
@@ -629,10 +856,10 @@ import { Text } from "themelia-ui/base/typography"
 
 export default function BleedExample() {
 	return (
-		<div style={{ width: "100%", padding: "var(--space-md)", border: "1px solid var(--border)", borderRadius: "var(--radius-sm)" }}>
-			<Text size="xs" type="secondary">A surface padded by --space-md.</Text>
-			<Bleed amount="md">
-				<div style={{ background: "var(--muted)", padding: "var(--space-sm) var(--space-md)", marginBlock: "var(--space-sm)" }}>
+		<div style={{ width: "100%", padding: "var(--padding-sm)", border: "var(--border-width) solid var(--border)", borderRadius: "var(--radius-sm)" }}>
+			<Text size="xs" type="secondary">A surface padded by --padding-sm.</Text>
+			<Bleed amount="sm">
+				<div style={{ background: "var(--muted)", padding: "calc(var(--padding-sm) / 2) var(--padding-sm)", marginBlock: "calc(var(--gap-sm) / 2)" }}>
 					<Text size="xs">This band bleeds to both edges.</Text>
 				</div>
 			</Bleed>
@@ -647,7 +874,7 @@ export default function BleedExample() {
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
 import { Stack } from "themelia-ui/base/structure"
 import { Text } from "themelia-ui/base/typography"
-import { Scope } from "themelia-ui/ui-provider"
+import { UIScope } from "themelia-ui/ui-provider"
 
 import { InvoiceTable } from "./_shared"
 
@@ -657,18 +884,41 @@ export default function TableScale() {
 		 * Both, captioned. On its own the scoped table just looked like a table —
 		 * the section asserted a difference the page gave the reader no way to see.
 		 */
-		<Stack gap="lg" style={{ width: "100%" }}>
-			<Stack gap="xs" style={{ width: "100%" }}>
-				<Text size="xs" type="secondary">--density-scale: 1</Text>
+		<Stack style={{ width: "100%" }}>
+			<Stack gap="sm" style={{ width: "100%" }}>
+				<Text size="xs" type="secondary">density: default</Text>
 				<InvoiceTable />
 			</Stack>
-			<Stack gap="xs" style={{ width: "100%" }}>
-				<Text size="xs" type="secondary">--density-scale: 0.85</Text>
-				<Scope vars={{ "--density-scale": 0.85 }} style={{ width: "100%" }}>
+			<Stack gap="sm" style={{ width: "100%" }}>
+				<Text size="xs" type="secondary">density: compact</Text>
+				<UIScope config={{ density: "compact" }} style={{ width: "100%" }}>
 					<InvoiceTable />
-				</Scope>
+				</UIScope>
 			</Stack>
 		</Stack>
 	)
 }
 ```
+
+### Colour islands
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+import { Button } from "themelia-ui/base/buttons"
+import { Card } from "themelia-ui/base/cards"
+import { Grid } from "themelia-ui/base/structure"
+import { UIProvider } from "themelia-ui/ui-provider"
+
+export default function ColourIsland() {
+	return (
+		<Grid columns={{ base: 1, sm: 2 }}>
+			{(["light", "dark"] as const).map((colorScheme) => (
+				<UIProvider key={colorScheme} config={{ colorScheme }}>
+					<Card title={`A ${colorScheme} region`} description="Every colour inside resolves to this half.">
+						<Button>Continue</Button>
+					</Card>
+				</UIProvider>
+			))}
+		</Grid>
+	)
+}
+```