themelia-ui 3.0.0 → 3.2.0

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

@@ -15,7 +15,6 @@ Any activation control — including one that carries a loading state, a tooltip
 
 ```tsx fragment — import-only example
 import { Button } from "themelia-ui/base/buttons"
-import "themelia-ui/base/buttons.css"
 ```
 
 ## Composition
@@ -31,11 +30,21 @@ outside the package and arrives through the public props, callbacks, slots, or a
 
 Kind: callable.
 
-The kit's action primitive. No `size` prop by design: geometry follows the scale factors,
-so a denser region is a scope (styles/FACTORS.md).
+The kit's action primitive. No `size` prop by design: geometry follows the provider's density
+and scale, so a denser region is a scope.
 
 ```text
-({ tone, buttonStyle, iconOnly, fullWidth, loading, render, className, disabled, children, onClick, ...props }: ButtonProps) => React.JSX.Element
+({ tone, appearance, iconOnly, fullWidth, loading, render, className, disabled, children, onClick, ...props }: ButtonProps) => React.JSX.Element
+```
+
+### `ButtonAppearance`
+
+Kind: type.
+
+Fill treatment. Structural, independent of the tone's colour.
+
+```text
+"solid" | "outline" | "ghost"
 ```
 
 ### `ButtonGroup`
@@ -115,23 +124,13 @@ Extends: `Omit<React.ComponentProps<"button">, "children">`.
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
 | `tone` | no | `ButtonTone` | Semantic colour intent. Resolves through the provider when omitted, so `UIProvider`<br>defaults can change it. @default "primary" |
-| `buttonStyle` | no | `ButtonStyle` | Fill treatment, independent of `tone`. `UIProvider` defaults can change it. @default "solid" |
+| `appearance` | no | `ButtonAppearance` | Fill treatment, independent of `tone`. `UIProvider` defaults can change it. @default "solid" |
 | `iconOnly` | no | `boolean` | Square button sized to its height. The label becomes the accessible name. |
 | `fullWidth` | no | `boolean` | Stretches the button to its container's width. |
 | `loading` | no | `boolean` | Shows a spinner and blocks interaction. The label keeps its space so the button does<br>not resize mid-action. |
 | `render` | no | `React.ReactElement` | The element this button becomes — an anchor, a router link, a label. `children` stay<br>the content and keep the button's label wrapper, so a link still sizes like a button.<br>`render` is how every kit component changes its element, the contract Base UI's parts<br>already take.<br><br>  <Button render={<a href="/settings" />}>Settings</Button> |
 | `children` | no | `React.ReactNode` |  |
 
-### `ButtonStyle`
-
-Kind: type.
-
-Fill treatment. Structural, independent of the tone's colour.
-
-```text
-"solid" | "outline" | "ghost"
-```
-
 ### `ButtonTone`
 
 Kind: type.
@@ -182,7 +181,7 @@ React.ForwardRefExoticComponent<Omit<TextButtonProps, "ref"> & React.RefAttribut
 Kind: type.
 
 ```text
-Omit<ButtonProps, "tone" | "buttonStyle" | "iconOnly" | "fullWidth"> & { tone?: ButtonTone; }
+Omit<ButtonProps, "tone" | "appearance" | "iconOnly" | "fullWidth"> & { tone?: ButtonTone; }
 ```
 
 ### `TooltipButton`
@@ -206,26 +205,108 @@ Extends: `ButtonProps`.
 
 ## Preview recipes
 
-Preview route: Button — `/button`
+Preview route: Timelines, onboarding & admin — `/blocks-admin`
+
+### 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>
+	)
+}
+```
 
 ### Tone × style
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-import { Button, type ButtonStyle, type ButtonTone } from "themelia-ui/base/buttons"
+import { Button, type ButtonAppearance, type ButtonTone } from "themelia-ui/base/buttons"
 
 const TONES: ButtonTone[] = [
 	"neutral", "primary", "secondary", "info", "success", "warning", "destructive",
 ]
 
-const STYLES: ButtonStyle[] = ["solid", "outline", "ghost"]
+const STYLES: ButtonAppearance[] = ["solid", "outline", "ghost"]
 
 export default function ToneStyle() {
 	return (
 		<>
-			{STYLES.map((buttonStyle) => (
-				<div key={buttonStyle} style={{ display: "flex", gap: ".5rem", flexWrap: "wrap" }}>
+			{STYLES.map((appearance) => (
+				<div key={appearance} style={{ display: "flex", gap: ".5rem", flexWrap: "wrap" }}>
 					{TONES.map((tone) => (
-						<Button key={tone} tone={tone} buttonStyle={buttonStyle}>
+						<Button key={tone} tone={tone} appearance={appearance}>
 							{tone}
 						</Button>
 					))}
@@ -260,7 +341,7 @@ export default function Scale() {
 							scale {scale}
 						</MonoValue>
 						<Button>Save</Button>
-						<Button tone="neutral" buttonStyle="outline">Cancel</Button>
+						<Button tone="neutral" appearance="outline">Cancel</Button>
 						<Button iconOnly aria-label="Add"><PlusIcon /></Button>
 						<Checkbox label="Also this" defaultChecked />
 					</div>
@@ -279,11 +360,11 @@ import { Stack } from "themelia-ui/base/structure"
 
 export default function State() {
 	return (
-		<Stack direction="horizontal" gap="lg" wrap align="center">
+		<Stack direction="horizontal" wrap align="center">
 			<Button>Save changes</Button>
 			<Button loading>Save changes</Button>
 			<Button disabled>Disabled</Button>
-			<Button tone="neutral" buttonStyle="outline" loading>
+			<Button tone="neutral" appearance="outline" loading>
 				Loading
 			</Button>
 		</Stack>
@@ -301,10 +382,10 @@ import { Stack } from "themelia-ui/base/structure"
 
 export default function IconOnly() {
 	return (
-		<Stack direction="horizontal" gap="lg" wrap align="center">
+		<Stack direction="horizontal" wrap align="center">
 			<Button iconOnly aria-label="Add"><PlusIcon /></Button>
-			<Button tone="neutral" buttonStyle="outline" iconOnly aria-label="Edit">✎</Button>
-			<Button tone="destructive" buttonStyle="ghost" iconOnly aria-label="Delete">🗑</Button>
+			<Button tone="neutral" appearance="outline" iconOnly aria-label="Edit">✎</Button>
+			<Button tone="destructive" appearance="ghost" iconOnly aria-label="Delete">🗑</Button>
 		</Stack>
 	)
 }
@@ -318,15 +399,15 @@ import { Stack } from "themelia-ui/base/structure"
 
 export default function Group() {
 	return (
-		<Stack direction="horizontal" gap="lg" wrap align="center">
+		<Stack direction="horizontal" wrap align="center">
 			<ButtonGroup>
-				<Button tone="neutral" buttonStyle="outline">Day</Button>
-				<Button tone="neutral" buttonStyle="outline">Week</Button>
-				<Button tone="neutral" buttonStyle="outline">Month</Button>
+				<Button tone="neutral" appearance="outline">Day</Button>
+				<Button tone="neutral" appearance="outline">Week</Button>
+				<Button tone="neutral" appearance="outline">Month</Button>
 			</ButtonGroup>
 			<ButtonGroup orientation="vertical">
-				<Button tone="neutral" buttonStyle="outline">Top</Button>
-				<Button tone="neutral" buttonStyle="outline">Bottom</Button>
+				<Button tone="neutral" appearance="outline">Top</Button>
+				<Button tone="neutral" appearance="outline">Bottom</Button>
 			</ButtonGroup>
 		</Stack>
 	)
@@ -342,18 +423,18 @@ import { Text } from "themelia-ui/base/typography"
 
 export default function ButtonVariants() {
 	return (
-		<Stack direction="horizontal" gap="xl" wrap align="center">
+		<Stack direction="horizontal" wrap align="center">
 			<Text size="xs" type="secondary">
 				Changed your mind? <TextButton>Undo the import</TextButton>
 			</Text>
 			<LoaderButton
 				tone="neutral"
-				buttonStyle="outline"
+				appearance="outline"
 				onClick={() => new Promise((resolve) => setTimeout(resolve, 1200))}
 			>
 				Save and wait
 			</LoaderButton>
-			<TooltipButton tooltip="Archive this order" tone="neutral" buttonStyle="outline">
+			<TooltipButton tooltip="Archive this order" tone="neutral" appearance="outline">
 				Archive
 			</TooltipButton>
 		</Stack>
@@ -371,25 +452,25 @@ import { Stack } from "themelia-ui/base/structure"
 
 export default function ButtonGroupParts() {
 	return (
-		<Stack direction="horizontal" gap="xl" wrap align="center">
+		<Stack direction="horizontal" wrap align="center">
 			<ButtonGroup>
-				<Button tone="neutral" buttonStyle="outline">Day</Button>
+				<Button tone="neutral" appearance="outline">Day</Button>
 				<ButtonGroupSeparator />
-				<Button tone="neutral" buttonStyle="outline">Week</Button>
+				<Button tone="neutral" appearance="outline">Week</Button>
 				<ButtonGroupSeparator />
-				<Button tone="neutral" buttonStyle="outline">Month</Button>
+				<Button tone="neutral" appearance="outline">Month</Button>
 			</ButtonGroup>
 			<ButtonGroup>
 				<ButtonGroupText>Show</ButtonGroupText>
-				<Button tone="neutral" buttonStyle="outline">All</Button>
-				<Button tone="neutral" buttonStyle="outline">Open</Button>
+				<Button tone="neutral" appearance="outline">All</Button>
+				<Button tone="neutral" appearance="outline">Open</Button>
 			</ButtonGroup>
 		</Stack>
 	)
 }
 ```
 
-### 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"
@@ -400,11 +481,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 />
@@ -414,7 +495,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 />
@@ -426,6 +507,29 @@ export default function TypeFactor() {
 }
 ```
 
+### 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>
+	)
+}
+```
+
 ### Scoped theming
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application

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

@@ -15,7 +15,6 @@ A surface needs visible chrome — border, padding, header and footer regions.
 
 ```tsx fragment — import-only example
 import { Card } from "themelia-ui/base/cards"
-import "themelia-ui/base/cards.css"
 ```
 
 ## Composition
@@ -46,7 +45,7 @@ composing.
 **Alternatives:** ContentBlock, Overlay.
 
 ```text
-({ icon, title, titleSuffix, tooltip, description, surface, titleLevel, media, headerStart, headerEnd, headerAction, actions, alert, alertTone, contentTop, contentBottom, footerText, footerSlot, headerDivider, footerDivider, expandable, expanded, defaultExpanded, onExpandedChange, strings, className, children, ...props }: CardProps) => React.JSX.Element
+({ icon, title, titleSuffix, tooltip, description, surface, titleLevel, titleSize, media, headerStart, headerEnd, headerAction, actions, alert, alertTone, contentTop, contentBottom, footerText, footerSlot, headerDivider, footerDivider, expandable, expanded, defaultExpanded, onExpandedChange, strings, className, children, ...props }: CardProps) => React.JSX.Element
 ```
 
 ### `CardAction`
@@ -76,7 +75,7 @@ Extends: `Omit<ComponentProps<"div">, "children">`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `actions` | yes | `ActionDefinition[]` | The commands, as the overflow menu takes them. The first is the primary action; the rest<br>follow in outline unless an entry sets its own `buttonStyle`. |
+| `actions` | yes | `ActionDefinition[]` | The commands, as the overflow menu takes them. The first is the primary action; the rest<br>follow in outline unless an entry sets its own `appearance`. |
 | `separator` | no | `boolean` | A rule above the strip, ruling it off from content that runs right into it. |
 | `align` | no | `"start" \| "end" \| "between"` | Where the buttons sit along the strip. |
 | `fullWidthPrimary` | no | `boolean` | Stretches the first action, for a card whose action is the point, or a narrow card where<br>two buttons will not fit. |
@@ -116,7 +115,7 @@ The header region: a title row with trailing controls, plus an optional full-wid
 above. The title truncates rather than pushing the controls off the row.
 
 ```text
-({ icon, title, titleSuffix, tooltip, tooltipLabel, description, headerStart, headerEnd, headerAction, divider, titleLevel, className, ...props }: Omit<React.ComponentProps<"div">, "title"> & { icon?: React.ReactNode; title?: React.ReactNode; titleSuffix?: React.ReactNode; tooltip?: React.ReactNode; tooltipLabel?: string; description?: React.ReactNode; headerStart?: React.ReactNode; headerEnd?: React.ReactNode; headerAction?: React.ReactNode; divider?: boolean; titleLevel?: 1 | 2 | 3 | 4 | 5 | 6; }) => React.JSX.Element
+({ icon, title, titleSuffix, tooltip, tooltipLabel, description, headerStart, headerEnd, headerAction, divider, titleLevel, titleSize, className, ...props }: Omit<React.ComponentProps<"div">, "title"> & { icon?: React.ReactNode; title?: React.ReactNode; titleSuffix?: React.ReactNode; tooltip?: React.ReactNode; tooltipLabel?: string; description?: React.ReactNode; headerStart?: React.ReactNode; headerEnd?: React.ReactNode; headerAction?: React.ReactNode; divider?: boolean; titleLevel?: 1 | 2 | 3 | 4 | 5 | 6; titleSize?: "base" | "xl"; }) => React.JSX.Element
 ```
 
 ### `CardPrimaryAction`
@@ -160,6 +159,7 @@ Extends: `Omit<React.ComponentProps<"div">, "title">`.
 | `headerAction` | no | `React.ReactNode` | A single control at the end of the header. Use `actions` for a list of commands. |
 | `actions` | no | `CardAction[]` | Overflow commands, collapsed into one menu trigger and rendered by the shared<br>`ActionMenu`: a destructive entry moves last and is separated. |
 | `titleLevel` | no | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | Renders the title as a heading of this level, for a card that heads a page or a region.<br>Unset, the title is a span that heading navigation can't find. |
+| `titleSize` | no | `"base" \| "xl"` | Title type size. `xl` is for a Card that heads a page, such as an auth form. |
 | `media` | no | `React.ReactNode` | A full-bleed strip above the header — a cover image, a map, a brand band — clipped to<br>the card's top corners. |
 | `alert` | no | `React.ReactNode` | Banner between header and content. A plain string is wrapped in an `Alert`. |
 | `alertTone` | no | `CardAlertTone` | Tone of the alert band. |
@@ -301,6 +301,76 @@ export default function MenusInContext() {
 }
 ```
 
+### 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
+
+```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>
+	)
+}
+```
+
 ### Surfaces
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
@@ -313,7 +383,7 @@ const SURFACES: CardSurface[] = ["card", "framed", "flat", "bordered"]
 export default function CardSurfaces() {
 	return (
 		/* Two columns for four surfaces, so none sits alone on a row. */
-		<Grid columns={{ base: 1, sm: 2 }} gap="lg" style={{ width: "100%" }}>
+		<Grid columns={{ base: 1, sm: 2 }} style={{ width: "100%" }}>
 			{SURFACES.map((surface) => (
 				<Card key={surface} surface={surface} title={surface} description="Supporting sentence.">
 					<Text type="secondary" size="sm">
@@ -340,7 +410,7 @@ import { Text } from "themelia-ui/base/typography"
 
 export default function CardSlots() {
 	return (
-		<Stack gap="lg" style={{ maxWidth: "34rem", width: "100%" }}>
+		<Stack style={{ maxWidth: "34rem", width: "100%" }}>
 			<Card
 				icon={<CreditCardIcon />}
 				title="Primary payment method"
@@ -353,7 +423,7 @@ export default function CardSlots() {
 					{ label: "Remove", icon: <TrashIcon />, onClick: () => {}, tone: "destructive" },
 				]}
 				footerText="Updated 3 days ago"
-				footerSlot={<Button tone="neutral" buttonStyle="outline">Manage</Button>}
+				footerSlot={<Button tone="neutral" appearance="outline">Manage</Button>}
 				footerDivider
 			>
 				<Text type="secondary" size="sm">
@@ -387,7 +457,7 @@ import { Text } from "themelia-ui/base/typography"
 export default function CardExpandable() {
 	return (
 		<Card expandable title="Terms of service" style={{ maxWidth: "34rem", width: "100%" }}>
-			<Stack gap="md">
+			<Stack gap="sm">
 				{Array.from({ length: 10 }, (_, i) => (
 					<Text key={i} type="secondary" size="sm">
 						Clause {i + 1}. Content that runs past the collapsed height, so the fade has
@@ -414,21 +484,21 @@ import { Text } from "themelia-ui/base/typography"
 
 export default function CardHeaderSlots() {
 	return (
-		<Stack gap="lg" style={{ maxWidth: "34rem", width: "100%" }}>
+		<Stack style={{ maxWidth: "34rem", width: "100%" }}>
 			<Card
 				icon={<CreditCardIcon />}
 				title="Payment method"
 				titleSuffix={<Badge tone="success">Verified</Badge>}
 				tooltip="We store only the last four digits. The full number never reaches our servers."
 				headerAction={
-					<Button buttonStyle="ghost" tone="neutral">
+					<Button appearance="ghost" tone="neutral">
 						Change
 					</Button>
 				}
 				description="Charged on the first of the month."
 				headerDivider
 				footerText="Next charge 1 April"
-				footerSlot={<Button buttonStyle="outline" tone="neutral">Invoices</Button>}
+				footerSlot={<Button appearance="outline" tone="neutral">Invoices</Button>}
 				footerDivider
 			>
 				<Text size="sm" type="secondary">
@@ -450,7 +520,7 @@ import { Text } from "themelia-ui/base/typography"
 
 export default function CardAlert() {
 	return (
-		<Stack gap="lg" style={{ maxWidth: "34rem", width: "100%" }}>
+		<Stack style={{ maxWidth: "34rem", width: "100%" }}>
 			<Card title="Domain" alert="Verification expires in 3 days." alertTone="warning">
 				<Text size="sm" type="secondary">
 					acme.com
@@ -475,7 +545,7 @@ import { TextLink } from "themelia-ui/base/typography"
 
 export default function CardActions() {
 	return (
-		<Stack direction="horizontal" gap="lg" wrap align="start">
+		<Stack direction="horizontal" wrap align="start">
 			<Card style={{ width: "18rem" }} title="Northwind Traders" description="Invoice #4417">
 				<CardFooter>
 					<CardActionStrip
@@ -506,7 +576,7 @@ import { Stack } from "themelia-ui/base/structure"
 
 export default function CardSkeletonExample() {
 	return (
-		<Stack direction="horizontal" gap="lg" wrap align="start">
+		<Stack direction="horizontal" wrap align="start">
 			<div style={{ width: "18rem" }}>
 				<CardSkeleton showHeader lines={3} label="Loading invoice" />
 			</div>
@@ -517,3 +587,26 @@ export default function CardSkeletonExample() {
 	)
 }
 ```
+
+### 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>
+	)
+}
+```

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

@@ -15,7 +15,6 @@ Peer items exceed the width and horizontal paging is the intended reading order.
 
 ```tsx fragment — import-only example
 import { Carousel } from "themelia-ui/base/carousel"
-import "themelia-ui/base/carousel.css"
 ```
 
 ## Composition
@@ -212,7 +211,7 @@ export default function Controls() {
 		<Carousel controls="overlay" label="Gallery">
 			{["One", "Two", "Three"].map((name) => (
 				<CarouselSlide key={name}>
-					<Stack align="center" justify="center" className={styles.slide}>
+					<Stack gap="sm" align="center" justify="center" className={styles.slide}>
 						<Text size="lg" weight="semibold">{name}</Text>
 					</Stack>
 				</CarouselSlide>