themelia-ui 3.0.0 → 3.2.0

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

@@ -15,7 +15,6 @@ A region reports its own state — informational alert, empty, loading, error, o
 
 ```tsx fragment — import-only example
 import { Alert } from "themelia-ui/base/feedback"
-import "themelia-ui/base/feedback.css"
 ```
 
 ## Composition
@@ -113,8 +112,10 @@ The alert's heading. It inherits the alert's ink.
 
 Kind: type.
 
+Semantic colour: the kit's one tone union.
+
 ```text
-"neutral" | "primary" | "secondary" | "destructive" | "warning" | "success" | "info"
+SemanticTone
 ```
 
 ### `AlertVariant`
@@ -207,8 +208,8 @@ How the `media` slot is dressed.
 
 Kind: type.
 
-Breathing room: `sm` for panels and cells, `lg` for a whole page. Not derived from
-provider density, which already reaches these tokens via `--density-scale`.
+Breathing room: `sm` for panels and cells, `default` for a card body or a page. Not
+derived from provider density, which already reaches the paddings through the presets.
 
 ```text
 ComponentScale
@@ -229,7 +230,7 @@ Extends: `Omit<React.ComponentProps<"div">, "title">`.
 | `description` | no | `React.ReactNode \| false` | Why it is empty, or what will fill it. `false` hides it, for a title that already tells<br>the whole story. |
 | `action` | no | `React.ReactNode` | Buttons or links offering the next step. An empty state that only explains is a dead<br>end. |
 | `footer` | no | `React.ReactNode` | Quiet copy under the action — a hint, a learn-more, a shortcut. |
-| `padding` | no | `EmptyPadding` | Breathing room, on both axes: `sm` for panels and cells, `lg` for a whole page. The<br>inline padding is what keeps copy off a dashed edge. |
+| `padding` | no | `EmptyPadding` | Breathing room, on both axes: `sm` for panels and cells, `default` for a card body or a<br>page. The inline padding is what keeps copy off a dashed edge. @default "default" |
 | `border` | no | `boolean` | The dashed outline. Off by default; use it when the empty state stands in for a card's<br>body and the edge says "something goes here". |
 | `strings` | no | `Partial<EmptyStrings>` | Overrides this state's own copy: `title`, `description`, and `ariaLabel`. The region<br>announces through `role="status"`, so a list that empties out while the reader is on the<br>page says so. |
 
@@ -336,7 +337,7 @@ attributes are then dropped rather than reporting 0%.
 Kind: callable.
 
 A determinate ring with the reading inside it, for tiles, scores and grids of small
-measures. Its size comes from `--progress-circle`; there is no size prop.
+measures. It has one size, big enough for a percentage in the hole; there is no size prop.
 
 ```text
 ({ value, max, tone, label, children, className, style, ...props }: ProgressCircleProps) => React.JSX.Element
@@ -373,8 +374,10 @@ Extends: `Omit<React.ComponentProps<"div">, "children">`.
 
 Kind: type.
 
+The tones a measure takes: the kit's tone union, without neutral and secondary.
+
 ```text
-"primary" | "success" | "warning" | "destructive" | "info"
+Extract<SemanticTone, "primary" | "success" | "warning" | "destructive" | "info">
 ```
 
 ### `SearchGlassIllustration`
@@ -458,7 +461,7 @@ export default function AlertLayout() {
 				<AlertTitle>With an action</AlertTitle>
 				<AlertDescription>Inline space is reserved on the trailing edge.</AlertDescription>
 				<AlertAction>
-					<Button tone="neutral" buttonStyle="ghost">
+					<Button tone="neutral" appearance="ghost">
 						Undo
 					</Button>
 				</AlertAction>
@@ -472,6 +475,56 @@ export default function AlertLayout() {
 }
 ```
 
+### 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>
+	)
+}
+```
+
 ### Empty
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
@@ -490,7 +543,7 @@ export default function EmptyExample() {
 			action={
 				<>
 					<Button>Create invoice</Button>
-					<Button tone="neutral" buttonStyle="outline">
+					<Button tone="neutral" appearance="outline">
 						Import
 					</Button>
 				</>
@@ -511,7 +564,7 @@ import { Grid } from "themelia-ui/base/structure"
 
 export default function EmptyMedia() {
 	return (
-		<Grid columns={{ base: 1, md: 3 }} gap="xl">
+		<Grid columns={{ base: 1, md: 3 }}>
 			<Empty
 				padding="sm"
 				border
@@ -564,9 +617,9 @@ const ILLUSTRATIONS = [
 
 export default function EmptyIllustrations() {
 	return (
-		<Grid columns={{ base: 1, sm: 2, lg: 3 }} gap="2xl">
+		<Grid columns={{ base: 1, sm: 2, lg: 3 }}>
 			{ILLUSTRATIONS.map(({ name, Component, use }) => (
-				<Stack key={name} gap="md" align="center">
+				<Stack key={name} gap="sm" align="center">
 					<Component />
 					<Stack gap="none" align="center">
 						<Text size="sm" weight="medium">{name}</Text>
@@ -589,9 +642,9 @@ import { Stack } from "themelia-ui/base/structure"
 
 export default function EmptyBorder() {
 	return (
-		<Stack gap="xl">
+		<Stack>
 			<Empty padding="sm" border media={<InboxIcon />} mediaVariant="icon" title="padding=&quot;sm&quot;" description="A side panel, a table cell, a card body." />
-			<Empty padding="lg" media={<InboxIcon />} mediaVariant="icon" title="padding=&quot;lg&quot;" description="A whole page, with no border." />
+			<Empty media={<InboxIcon />} mediaVariant="icon" title="padding=&quot;default&quot;" description="A whole page, with no border." />
 		</Stack>
 	)
 }
@@ -606,7 +659,7 @@ import { Stack } from "themelia-ui/base/structure"
 
 export default function FormStates() {
 	return (
-		<Stack gap="lg">
+		<Stack>
 			<Card>
 				<CardContent>
 					<LoadingState />
@@ -640,7 +693,7 @@ import { Text } from "themelia-ui/base/typography"
 export default function ProgressExample() {
 	return (
 		// Captioned: `label` is the accessible name and renders nothing.
-		<Stack gap="lg" style={{ width: "100%" }}>
+		<Stack style={{ width: "100%" }}>
 			{[
 				{ value: 24, tone: undefined, caption: "value={24}" },
 				{ value: 64, tone: "info" as const, caption: 'value={64} tone="info"' },
@@ -648,7 +701,7 @@ export default function ProgressExample() {
 				{ value: 92, tone: "warning" as const, caption: 'value={92} tone="warning"' },
 				{ value: undefined, tone: undefined, caption: "no value — indeterminate" },
 			].map((row) => (
-				<Stack key={row.caption} gap="2xs">
+				<Stack key={row.caption} gap="sm">
 					<Text size="xs" type="secondary">{row.caption}</Text>
 					<Progress value={row.value} tone={row.tone} label={row.caption} />
 				</Stack>
@@ -667,7 +720,7 @@ import { Text } from "themelia-ui/base/typography"
 
 export default function ProgressCircleExample() {
 	return (
-		<Stack direction="horizontal" gap="lg" wrap>
+		<Stack direction="horizontal" wrap>
 			{[
 				{ value: 24, tone: undefined },
 				{ value: 60, tone: "info" as const },

package/docs/generated/components/base--forms-numeric.md

@@ -15,12 +15,11 @@ A numeric field carries a unit, currency or precision the input itself must enfo
 
 ```tsx fragment — import-only example
 import { CoordinatesInput } from "themelia-ui/base/forms-numeric"
-import "themelia-ui/base/forms-numeric.css"
 ```
 
 ## Composition
 
-This module composes `base/choice-inputs`, `base/text-inputs`.
+This module composes `base/choice-inputs`, `base/text-inputs`, `base/typography`.
 
 Application policy—routing, fetching, persistence, permissions, and translation—stays
 outside the package and arrives through the public props, callbacks, slots, or accessors below.
@@ -456,7 +455,7 @@ export default function Currency() {
 	const [currency, setCurrency] = useState("EUR")
 
 	return (
-		<Stack gap="xl" style={{ maxWidth: "26rem", width: "100%" }}>
+		<Stack style={{ maxWidth: "26rem", width: "100%" }}>
 			<FormField label="Invoice total">
 				<CurrencyInput
 					value={amount}
@@ -484,7 +483,7 @@ import { Stack } from "themelia-ui/base/structure"
 
 export default function Decimal() {
 	return (
-		<Stack gap="xl" style={{ maxWidth: "26rem", width: "100%" }}>
+		<Stack style={{ maxWidth: "26rem", width: "100%" }}>
 			<FormField label="Plain" helperText="Commas become dots; extra decimals are refused.">
 				<DecimalInput defaultValue="12.5" decimalPlaces={2} />
 			</FormField>
@@ -516,7 +515,7 @@ export default function RoundingModeExample() {
 	const [mode, setMode] = useState<RoundingMode>("half-even")
 
 	return (
-		<Stack gap="xl" style={{ maxWidth: "26rem", width: "100%" }}>
+		<Stack style={{ maxWidth: "26rem", width: "100%" }}>
 			<FormField label="Rounding" helperText="Applies to the field below.">
 				<RoundingModeSelect
 					value={mode}
@@ -542,7 +541,7 @@ import { Stack } from "themelia-ui/base/structure"
 
 export default function Percentage() {
 	return (
-		<Stack gap="xl" style={{ maxWidth: "26rem", width: "100%" }}>
+		<Stack style={{ maxWidth: "26rem", width: "100%" }}>
 			<FormField label="VAT rate">
 				<PercentageInput defaultValue="21" />
 			</FormField>
@@ -576,7 +575,7 @@ export default function Units() {
 	const [coordinates, setCoordinates] = useState<CoordinatesValue>({ latitude: "52.370216", longitude: "4.895168" })
 
 	return (
-		<Stack gap="xl" style={{ maxWidth: "34rem", width: "100%" }}>
+		<Stack style={{ maxWidth: "34rem", width: "100%" }}>
 			<FormField label="Shipping weight">
 				<WeightInput
 					value={weight}

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

@@ -14,8 +14,7 @@ Assembling a form's visible structure — label, control, support text, sections
 ## Import
 
 ```tsx fragment — import-only example
-import { DirtyStateBanner } from "themelia-ui/base/forms"
-import "themelia-ui/base/forms.css"
+import { FormField, FormSection } from "themelia-ui/base/forms"
 ```
 
 ## Composition
@@ -136,6 +135,16 @@ Several fields sharing one label and one supporting line — a date range, a nam
 two. A real `<fieldset>` and `<legend>`, so the legend is announced when focus enters the
 group.
 
+**Use when:** Related controls sharing an announced fieldset legend.
+
+**Avoid when:** A whole independently titled subject surface.
+
+**Compose:** Use one legend for the group and distinct FormField labels for its controls.
+
+**Capabilities:** semantic fieldset legend; related editable controls.
+
+**Alternatives:** FormSection.
+
 ```text
 ({ legend, description, className, children, ...props }: FieldGroupProps) => React.JSX.Element
 ```
@@ -231,6 +240,16 @@ Kind: callable.
 
 A titled group of fields, on a card's surface.
 
+**Use when:** Editable form sections, including groups inside an existing Card.
+
+**Avoid when:** Read-only facts or a semantic fieldset with one shared legend.
+
+**Compose:** Use flat inside a surface; flat retains Card region insets. Let its title name the section and FormField name each field.
+
+**Capabilities:** editable form sections; existing surface grouping.
+
+**Alternatives:** ContentBlock, FieldGroup.
+
 ```text
 ({ title, description, actions, children, footer, surface, className, }: FormSectionProps) => import("react").JSX.Element
 ```
@@ -304,7 +323,7 @@ import { Input } from "themelia-ui/base/text-inputs"
 
 export default function FormFieldExample() {
 	return (
-		<Stack gap="xl" style={{ maxWidth: "26rem", width: "100%" }}>
+		<Stack style={{ maxWidth: "26rem", width: "100%" }}>
 			<FormField label="Email" required hint="We only use this for receipts.">
 				<Input type="email" placeholder="you@example.com" />
 			</FormField>
@@ -354,7 +373,7 @@ import { Input } from "themelia-ui/base/text-inputs"
 
 export default function HorizontalFields() {
 	return (
-		<Stack gap="lg" style={{ width: "100%" }}>
+		<Stack style={{ width: "100%" }}>
 			<FormField orientation="horizontal" label="Display name" hint="Shown on invoices.">
 				<Input defaultValue="Acme Corporation" />
 			</FormField>
@@ -378,7 +397,7 @@ export default function FieldGroupExample() {
 	return (
 		<div style={{ maxWidth: "34rem", width: "100%" }}>
 			<FieldGroup legend="Reporting period" description="Both ends are inclusive.">
-				<Stack direction="horizontal" gap="md">
+				<Stack direction="horizontal" gap="sm">
 					<FormField label="From">
 						<Input type="date" defaultValue="2026-03-01" />
 					</FormField>
@@ -392,6 +411,57 @@ export default function FieldGroupExample() {
 }
 ```
 
+### Multi-section form reference
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+import { useRef, useState } from "react"
+import { Card } from "themelia-ui/base/cards"
+import { ContentBlock } from "themelia-ui/base/display"
+import { FieldGroup, FormField, FormSection, FormActionsBar, SubmitStateButton } from "themelia-ui/base/forms"
+import { Stack } from "themelia-ui/base/structure"
+import { Input } from "themelia-ui/base/text-inputs"
+import { Text } from "themelia-ui/base/typography"
+import { useFormFieldBinding, useStateFormControl, type FormControl } from "themelia-ui/forms"
+
+type Draft = { firstName: string; lastName: string; company: string }
+function BoundField({ control, name, label, error }: { control: FormControl<Draft>; name: keyof Draft; label: string; error?: string }) {
+	const field = useFormFieldBinding<string, Draft>({ control, name })
+	return <FormField label={label} error={error} hint={name === "company" ? "The name shown on invoices." : undefined}><Input required value={field.value ?? ""} onChange={event => field.onValueChange(event.target.value)} onBlur={field.onBlur} /></FormField>
+}
+
+export default function MultiSectionReference() {
+	const control = useStateFormControl<Draft>({ firstName: "Alex", lastName: "Example", company: "Example team" })
+	const [pending, setPending] = useState(false)
+	const [error, setError] = useState<string>()
+	const [rootError, setRootError] = useState<string>()
+	const [saved, setSaved] = useState(0)
+	const running = useRef(false)
+	return <Stack>
+		<Card title="Account details" description="One outer surface, editable sections with retained region insets.">
+			<form onSubmit={async event => {
+				event.preventDefault(); if (running.current) return
+				running.current = true; setPending(true); setError(undefined); setRootError(undefined)
+				try {
+					await new Promise(resolve => setTimeout(resolve, 250))
+					if (control.values.company === "offline") throw new Error("Request failed. Your values remain here.")
+					if (control.values.company.length < 3) { setError("Company must have at least three characters."); return }
+					setSaved(count => count + 1)
+				} catch (failure) { setRootError((failure as Error).message) }
+				finally { running.current = false; setPending(false) }
+			}}>
+				<Stack gap="none">
+					{rootError && <Text role="alert" type="error">{rootError}</Text>}
+					<FormSection surface="flat" title="Contact"><FieldGroup legend="Legal name" disabled={pending}><BoundField control={control} name="firstName" label="First name" /><BoundField control={control} name="lastName" label="Last name" /></FieldGroup></FormSection>
+					<FormSection surface="flat" title="Billing"><fieldset disabled={pending} style={{ border: 0, padding: 0, margin: 0 }}><BoundField control={control} name="company" label="Company" error={error} /></fieldset></FormSection>
+					<FormActionsBar leading={<Text role="status">Successful submissions {saved}</Text>}><SubmitStateButton type="submit" state={pending ? "submitting" : "idle"} strings={{ idle: "Save account" }} /></FormActionsBar>
+				</Stack>
+			</form>
+		</Card>
+		<Card title="Preferences" description="A sibling subject owns its own surface."><ContentBlock surface="plain" title="Delivery instructions"><Text>Use ContentBlock for supporting prose; FieldGroup supplies fieldset semantics for related controls.</Text></ContentBlock></Card>
+	</Stack>
+}
+```
+
 ### FormSection
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
@@ -403,12 +473,12 @@ import { Text } from "themelia-ui/base/typography"
 
 export default function FormSectionExample() {
 	return (
-		<Stack gap="xl" style={{ maxWidth: "34rem" }}>
+		<Stack style={{ maxWidth: "34rem" }}>
 			<FormSection
 				title="Billing"
 				description="Where invoices go. Changing it does not change the shipping address."
 				actions={
-					<Button tone="neutral" buttonStyle="ghost">
+					<Button tone="neutral" appearance="ghost">
 						Edit
 					</Button>
 				}
@@ -446,7 +516,7 @@ export default function FormActions() {
 						</Text>
 					}
 				>
-					<Button tone="neutral" buttonStyle="outline">
+					<Button tone="neutral" appearance="outline">
 						Discard
 					</Button>
 					<Button>Save</Button>
@@ -466,7 +536,7 @@ import { Stack } from "themelia-ui/base/structure"
 
 export default function FormErrorSummary() {
 	return (
-		<Stack style={{ maxWidth: "34rem" }}>
+		<Stack gap="sm" style={{ maxWidth: "34rem" }}>
 			<ErrorSummary
 				errors={[
 					"Name is required.",
@@ -474,7 +544,7 @@ export default function FormErrorSummary() {
 					"VAT number does not match the selected country.",
 				]}
 				action={
-					<Button tone="neutral" buttonStyle="outline">
+					<Button tone="neutral" appearance="outline">
 						Review the first problem
 					</Button>
 				}
@@ -493,14 +563,14 @@ import { Stack } from "themelia-ui/base/structure"
 
 export default function FormDirty() {
 	return (
-		<Stack gap="lg" style={{ maxWidth: "34rem" }}>
+		<Stack style={{ maxWidth: "34rem" }}>
 			{(["neutral", "info", "warning"] as const).map((tone) => (
 				<DirtyStateBanner
 					key={tone}
 					tone={tone}
 					actions={
 						<>
-							<Button tone="neutral" buttonStyle="outline">
+							<Button tone="neutral" appearance="outline">
 								Discard
 							</Button>
 							<Button>Save</Button>
@@ -526,13 +596,13 @@ export default function FormSubmitState() {
 	const [state, setState] = useState<SubmitState>("idle")
 
 	return (
-		<Stack direction="horizontal" gap="lg" wrap align="center">
+		<Stack direction="horizontal" wrap align="center">
 			{(["idle", "submitting", "succeeded"] as SubmitState[]).map((s) => (
 				<SubmitStateButton key={s} state={s} />
 			))}
 			<Button
 				tone="neutral"
-				buttonStyle="outline"
+				appearance="outline"
 				onClick={() => {
 					setState("submitting")
 					setTimeout(() => setState("succeeded"), 1200)

package/docs/generated/components/base--hover-card.md

@@ -15,12 +15,11 @@ Hovering a reference reveals a preview the reader does not have to act on.
 
 ```tsx fragment — import-only example
 import { HoverCard } from "themelia-ui/base/hover-card"
-import "themelia-ui/base/hover-card.css"
 ```
 
 ## Composition
 
-This module depends on no other module.
+This module composes `base/typography`.
 
 Application policy—routing, fetching, persistence, permissions, and translation—stays
 outside the package and arrives through the public props, callbacks, slots, or accessors below.
@@ -111,11 +110,11 @@ export default function HoverCardExample() {
 					@jane
 				</HoverCardTrigger>
 				<HoverCardContent>
-					<Stack direction="horizontal" gap="md" align="start">
+					<Stack direction="horizontal" gap="sm" align="start">
 						<Avatar>
 							<AvatarFallback>JM</AvatarFallback>
 						</Avatar>
-						<Stack gap="2xs">
+						<Stack gap="sm">
 							<Text weight="medium">Jane McDonald</Text>
 							<Text size="xs" type="secondary">Billing · joined March 2024</Text>
 						</Stack>

package/docs/generated/components/base--input-group.md

@@ -15,7 +15,6 @@ A control needs an affix inside its border — an icon, unit, prefix button or c
 
 ```tsx fragment — import-only example
 import { InputGroup } from "themelia-ui/base/input-group"
-import "themelia-ui/base/input-group.css"
 ```
 
 ## Composition
@@ -66,18 +65,20 @@ Kind: callable.
 A quiet Button sized to sit inside the field rather than beside it.
 
 ```text
-({ className, type, tone, buttonStyle, size, ...props }: InputGroupButtonProps) => React.JSX.Element
+({ className, type, tone, appearance, iconOnly, ...props }: InputGroupButtonProps) => React.JSX.Element
 ```
 
 ### `InputGroupButtonProps`
 
 Kind: interface.
 
-Extends: `Omit<React.ComponentProps<typeof Button>, "size" | "type">`.
+One size, inset inside the field: a full-height Button would set the field's height rather
+than fit in it. `iconOnly` makes it square.
+
+Extends: `Omit<React.ComponentProps<typeof Button>, "type">`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `size` | no | `"xs" \| "sm" \| "icon-xs" \| "icon-sm"` | The sizes that fit inside a field: two text sizes and their icon-only twins. A<br>full-height Button would set the field's height rather than fit in it, which is why<br>this is the one place the kit keeps a size prop on a control. |
 | `type` | no | `"button" \| "submit" \| "reset"` | The native button type: `button` unless set, so pressing it never submits the form around the field. |
 
 ### `InputGroupInput`
@@ -111,8 +112,8 @@ React.ComponentProps<"div">
 
 Kind: callable.
 
-Secondary text at the group's own size — a unit, a domain suffix, a counter. It inherits
-the size, so it cannot drift from the input beside it.
+Secondary text at the field's size — a unit, a domain suffix, a counter. Text's `sm`, the
+step every field control's value uses, so it cannot drift from the input beside it.
 
 ```text
 ({ className, ...props }: React.ComponentProps<"span">) => React.JSX.Element
@@ -161,7 +162,7 @@ import { Stack } from "themelia-ui/base/structure"
 
 export default function InputGroupInline() {
 	return (
-		<Stack gap="lg" style={{ maxWidth: "26rem" }}>
+		<Stack style={{ maxWidth: "26rem" }}>
 			<InputGroup>
 				<InputGroupAddon>
 					<SearchIcon aria-hidden="true" />
@@ -182,7 +183,7 @@ export default function InputGroupInline() {
 			<InputGroup>
 				<InputGroupInput placeholder="Add a label" aria-label="Label" />
 				<InputGroupAddon align="inline-end">
-					<InputGroupButton size="icon-xs" aria-label="Add">
+					<InputGroupButton iconOnly aria-label="Add">
 						<ArrowRightIcon aria-hidden="true" />
 					</InputGroupButton>
 				</InputGroupAddon>
@@ -204,10 +205,10 @@ import { Stack } from "themelia-ui/base/structure"
 
 export default function InputGroupBlock() {
 	return (
-		<Stack gap="lg" style={{ maxWidth: "26rem" }}>
+		<Stack style={{ maxWidth: "26rem" }}>
 			<InputGroup>
 				<InputGroupAddon align="block-start">
-					<InputGroupButton size="icon-xs" aria-label="Favourite">
+					<InputGroupButton iconOnly aria-label="Favourite">
 						<StarIcon aria-hidden="true" />
 					</InputGroupButton>
 					<InputGroupText>Internal note</InputGroupText>
@@ -222,7 +223,7 @@ export default function InputGroupBlock() {
 }
 ```
 
-### Button sizes inside the shell
+### A button inside the shell
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
 import { ArrowRightIcon } from "lucide-react"
@@ -234,25 +235,21 @@ import { Stack } from "themelia-ui/base/structure"
 
 export default function InputGroupButtons() {
 	return (
-		<Stack gap="lg" style={{ maxWidth: "26rem" }}>
-			{(["xs", "sm"] as const).map((size) => (
-				<InputGroup key={size}>
-					<InputGroupInput placeholder={`size="${size}"`} aria-label={size} />
-					<InputGroupAddon align="inline-end">
-						<InputGroupButton size={size}>Apply</InputGroupButton>
-					</InputGroupAddon>
-				</InputGroup>
-			))}
-			{(["icon-xs", "icon-sm"] as const).map((size) => (
-				<InputGroup key={size}>
-					<InputGroupInput placeholder={`size="${size}"`} aria-label={size} />
-					<InputGroupAddon align="inline-end">
-						<InputGroupButton size={size} aria-label="Go">
-							<ArrowRightIcon aria-hidden="true" />
-						</InputGroupButton>
-					</InputGroupAddon>
-				</InputGroup>
-			))}
+		<Stack style={{ maxWidth: "26rem" }}>
+			<InputGroup>
+				<InputGroupInput placeholder="A labelled button" aria-label="Coupon code" />
+				<InputGroupAddon align="inline-end">
+					<InputGroupButton>Apply</InputGroupButton>
+				</InputGroupAddon>
+			</InputGroup>
+			<InputGroup>
+				<InputGroupInput placeholder="An icon-only button" aria-label="Search" />
+				<InputGroupAddon align="inline-end">
+					<InputGroupButton iconOnly aria-label="Go">
+						<ArrowRightIcon aria-hidden="true" />
+					</InputGroupButton>
+				</InputGroupAddon>
+			</InputGroup>
 		</Stack>
 	)
 }

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

@@ -15,7 +15,6 @@ A row carries identity — media, title, description and trailing actions — in
 
 ```tsx fragment — import-only example
 import { Item } from "themelia-ui/base/item"
-import "themelia-ui/base/item.css"
 ```
 
 ## Composition
@@ -31,8 +30,8 @@ outside the package and arrives through the public props, callbacks, slots, or a
 
 Kind: callable.
 
-A row — a list row, a menu row, a table row. No size prop: row height follows
-`--density-scale`, so use a denser scope for a denser list.
+A row — a list row, a menu row, a table row. No size prop: row height follows the
+density, so use a denser scope for a denser list.
 
 **Use when:** An identity row with a title, description, media and actions.
 
@@ -205,14 +204,14 @@ export default function ItemExample() {
 import { Card } from "themelia-ui/base/cards"
 import { Item, ItemContent, ItemDescription, ItemGroup, ItemTitle } from "themelia-ui/base/item"
 import { Stack } from "themelia-ui/base/structure"
-import { Scope } from "themelia-ui/ui-provider"
+import { UIScope } from "themelia-ui/ui-provider"
 
 export default function CardsScale() {
 	return (
-		<Stack gap="lg" style={{ width: "100%" }}>
-			{[1, 0.85].map((scale) => (
-				<Scope key={scale} vars={{ "--density-scale": scale }}>
-					<Card surface="bordered" title={`--density-scale ${scale}`}>
+		<Stack style={{ width: "100%" }}>
+			{(["default", "compact"] as const).map((density) => (
+				<UIScope key={density} config={{ density }}>
+					<Card surface="bordered" title={`density="${density}"`}>
 						<ItemGroup>
 							<Item surface="bordered">
 								<ItemContent>
@@ -228,7 +227,7 @@ export default function CardsScale() {
 							</Item>
 						</ItemGroup>
 					</Card>
-				</Scope>
+				</UIScope>
 			))}
 		</Stack>
 	)