themelia-ui 2.0.0 → 3.0.0

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

@@ -20,7 +20,7 @@ import "themelia-ui/base/display.css"
 
 ## Composition
 
-This family composes `base/badge`, `base/buttons`, `base/structure`, `base/tooltip`, `base/typography`.
+This module composes `base/badge`, `base/buttons`, `base/structure`, `base/tooltip`, `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.
@@ -31,6 +31,8 @@ outside the package and arrives through the public props, callbacks, slots, or a
 
 Kind: callable.
 
+A yes/no state as a dot and a word. The word is required, since colour alone fails.
+
 ```text
 ({ value, strings, className, ...props }: BooleanIndicatorProps) => React.JSX.Element
 ```
@@ -43,8 +45,8 @@ Extends: `Omit<React.ComponentProps<"span">, "children">`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `value` | no | `boolean \| null` |  |
-| `strings` | no | `Partial<BooleanIndicatorStrings>` | Overrides what each state is called. Yes/No, Enabled/Disabled, Paid/Unpaid. |
+| `value` | no | `boolean \| null` | The state, drawn as a dot and a word so it does not rely on colour alone. |
+| `strings` | no | `Partial<BooleanIndicatorStrings>` | Overrides what each state is called: `strings.true` and `strings.false`, the two words.<br>Yes/No, Enabled/Disabled, Paid/Unpaid — "Active"/"Paused" beats "true"/"false". |
 
 ### `BooleanIndicatorStrings`
 
@@ -59,6 +61,8 @@ Kind: interface.
 
 Kind: callable.
 
+A disclosure that animates to its content's natural height, in CSS alone.
+
 ```text
 ({ open, defaultOpen, onOpenChange, className, children, ...props }: CollapsibleProps) => React.JSX.Element
 ```
@@ -67,6 +71,9 @@ Kind: callable.
 
 Kind: callable.
 
+The disclosed region. It stays mounted while collapsed, to animate, and is inert then, so
+its controls leave the tab order.
+
 ```text
 ({ className, children, ...props }: React.ComponentProps<"div">) => React.JSX.Element
 ```
@@ -79,14 +86,16 @@ Extends: `Omit<React.ComponentProps<"div">, "onToggle">`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `open` | no | `boolean` |  |
-| `defaultOpen` | no | `boolean` |  |
-| `onOpenChange` | no | `(open: boolean) => void` |  |
+| `open` | no | `boolean` | Whether the content is shown, for controlled state. |
+| `defaultOpen` | no | `boolean` | Whether the content starts shown, for uncontrolled state. |
+| `onOpenChange` | no | `(open: boolean) => void` | Fires on every toggle, from the pointer or the keyboard. |
 
 ### `CollapsibleTrigger`
 
 Kind: callable.
 
+The control. Carries `aria-expanded` and points at the content.
+
 ```text
 ({ className, children, onClick, ...props }: React.ComponentProps<"button">) => React.JSX.Element
 ```
@@ -95,6 +104,8 @@ Kind: callable.
 
 Kind: callable.
 
+A titled region inside a panel, not a panel itself: use it instead of nesting Cards.
+
 **Use when:** A titled section within a page or existing surface.
 
 **Avoid when:** Needing a full card contract or a modal interaction.
@@ -117,13 +128,13 @@ Extends: `Omit<ComponentProps<"div">, "title">`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `title` | no | `ReactNode` |  |
-| `description` | no | `ReactNode` |  |
-| `icon` | no | `ReactNode` | Glyph on the title line. |
+| `title` | no | `ReactNode` | The heading. Either it or `description` renders the header; neither, and the block is a<br>bare surface. |
+| `description` | no | `ReactNode` | Supporting copy on its own row, so a long one wraps under the whole header. |
+| `icon` | no | `ReactNode` | Leading glyph on the title line. |
 | `titleSuffix` | no | `ReactNode` | Content immediately after the title — a badge, a count. |
 | `headerEnd` | no | `ReactNode` | Controls at the end of the title line. |
-| `surface` | no | `ContentBlockSurface` |  |
-| `flush` | no | `boolean` | Drops the surface's inset and clips to its radius, for content that runs to the edge<br>(divided cells, ruled rows); children pay their own inset. Only meaningful on a surface. |
+| `surface` | no | `ContentBlockSurface` | Outer chrome. What separates `bordered` from `card` is the ground: a bordered block is a<br>ruled region and the page shows through it; a card block lifts off it. |
+| `flush` | no | `boolean` | Drops the surface's inset and clips to its radius, for content that runs to the edge<br>(divided cells, ruled rows); children pay their own inset. Only meaningful on a surface<br>that has an inset to drop. |
 | `children` | no | `ReactNode` |  |
 
 ### `ContentBlockSurface`
@@ -141,6 +152,9 @@ through. `muted`: a tinted region. `card`: `bordered` on the card ground.
 
 Kind: callable.
 
+A date as a calendar leaf, rendered as `<time>` with a machine-readable `dateTime`, so the
+stacked fragments stay one parseable value.
+
 ```text
 ({ date, time, dateTime, layout, boxed, showWeekday, showMonth, showYear, weekdayFormat, dayFormat, monthFormat, yearFormat, className, ...props }: DateBlockProps) => import("react").JSX.Element | null
 ```
@@ -161,18 +175,18 @@ Extends: `Omit<ComponentProps<"time">, "children" | "dateTime">`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `date` | no | `Date \| string \| number \| null` | A Date, an ISO string, or a timestamp. |
-| `time` | no | `ReactNode` | Already-formatted time or range — "09:00 – 10:30". |
-| `dateTime` | no | `string` | Overrides the machine-readable value. |
-| `layout` | no | `DateBlockLayout` |  |
-| `boxed` | no | `boolean` | A bounded surface. Defaults on for stacked, off for inline. |
-| `showWeekday` | no | `boolean` |  |
-| `showMonth` | no | `boolean` |  |
+| `date` | no | `Date \| string \| number \| null` | A Date, an ISO string, or a timestamp. Nothing parseable renders nothing — an empty leaf<br>would be a claim. |
+| `time` | no | `ReactNode` | An already-formatted time or range — "09:00 – 10:30" — under the weekday in the stacked<br>layout. |
+| `dateTime` | no | `string` | Overrides the machine-readable value, which is otherwise the date's ISO string. |
+| `layout` | no | `DateBlockLayout` | A calendar leaf, or a phrase at the size of the line it sits in. |
+| `boxed` | no | `boolean` | The leaf's box and month band: a bounded surface. Defaults on for stacked and off for<br>inline; turn it off for a surface that already frames the leaf. @default true |
+| `showWeekday` | no | `boolean` | Shows the weekday. |
+| `showMonth` | no | `boolean` | Shows the month. Without it there is no band. |
 | `showYear` | no | `boolean` | Adds the year under the month, for a date outside the current one. |
-| `weekdayFormat` | no | `string` | date-fns patterns for the fragments. Names come from the scope's date-fns locale, so<br>these are patterns, not strings. |
-| `dayFormat` | no | `string` |  |
-| `monthFormat` | no | `string` |  |
-| `yearFormat` | no | `string` |  |
+| `weekdayFormat` | no | `string` | date-fns pattern for the weekday. Names come from the `UIProvider`'s date-fns locale, so<br>these are patterns, not strings: a Greek scope reads "Κυρ" without a strings object. |
+| `dayFormat` | no | `string` | date-fns pattern for the day. |
+| `monthFormat` | no | `string` | date-fns pattern for the month, named in the scope's locale. |
+| `yearFormat` | no | `string` | date-fns pattern for the year. |
 
 ### `defaultBooleanIndicatorStrings`
 
@@ -194,6 +208,9 @@ MetadataListStrings
 
 Kind: callable.
 
+A glyph in a tinted medallion. Its size comes from `--icon-badge-size`, so a caller
+needing a smaller mark re-points the token instead of redrawing the badge.
+
 ```text
 ({ icon, children, tone, shape, solid, bordered, className, ...props }: IconBadgeProps) => import("react").JSX.Element
 ```
@@ -206,10 +223,10 @@ Extends: `Omit<ComponentProps<"span">, "children">`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `icon` | no | `ComponentType<{ className?: string; }> \| ReactNode` | A component or a rendered node. |
+| `icon` | no | `ComponentType<{ className?: string; }> \| ReactNode` | A component or a rendered node. A component is called with `aria-hidden`, because the<br>badge is a mark beside a name that already says it. |
 | `children` | no | `ReactNode` |  |
-| `tone` | no | `IconBadgeTone` |  |
-| `shape` | no | `IconBadgeShape` |  |
+| `tone` | no | `IconBadgeTone` | Sets the fill and the glyph together, so the two cannot come from different tones. |
+| `shape` | no | `IconBadgeShape` | A rounded square, or a circle. |
 | `solid` | no | `boolean` | Fills with the tone and inverts the glyph — for the one badge that must stand out. |
 | `bordered` | no | `boolean` | A hairline outline, for a badge on a surface it would otherwise blend into. |
 
@@ -256,15 +273,19 @@ Extends: `Omit<ComponentProps<"div">, "children">`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `label` | yes | `ReactNode` | Names the fact. |
-| `value` | no | `ReactNode` | The fact itself. Absent renders the empty marker. |
-| `layout` | no | `InlineStatLayout` |  |
-| `mono` | no | `boolean` | Tabular figures, for amounts and counters, so a column of these compares cleanly. |
+| `label` | yes | `ReactNode` | Names the fact. Rendered as a `DisplayLabel`, which has one style everywhere. |
+| `value` | no | `ReactNode` | The fact itself. Absent renders the empty marker rather than collapsing the row to its<br>label — a dash says the fact was looked for. |
+| `layout` | no | `InlineStatLayout` | How the free space between label and value is spent — the only thing the three change. |
+| `mono` | no | `boolean` | Tabular figures, for an amount or a counter — what makes a column of these compare down<br>the page instead of jittering with each digit's width. |
 
 ### `Kbd`
 
 Kind: callable.
 
+One key, or one chord pressed together written as a single string — "⌘K", not three caps,
+because nested `Kbd`s are announced element by element. A native `<kbd>`: every native
+attribute passes through.
+
 ```text
 ({ className, ...props }: ComponentProps<"kbd">) => import("react").JSX.Element
 ```
@@ -273,7 +294,9 @@ Kind: callable.
 
 Kind: callable.
 
-Several caps as a sequence ("⌘ then K"); the gap between caps marks it as a sequence, not a chord.
+Several `Kbd` in a row, for a sequence pressed one after another — "G then I". The caps sit
+further apart than the characters inside one, and that gap is what tells a reader the keys
+are pressed in turn rather than together.
 
 ```text
 ({ className, ...props }: ComponentProps<"span">) => import("react").JSX.Element
@@ -367,6 +390,9 @@ DescriptorBase & ValueFallback & DisplayOverride & { kind: "link"; href: string;
 
 Kind: callable.
 
+Label/value facts about one thing, in three layouts over the same data. Returns `null`
+when the list is empty, so a caller can render it unconditionally.
+
 **Use when:** Read-only metadata and label/value facts about one record.
 
 **Avoid when:** Editing values or rendering a list of actionable records.
@@ -385,15 +411,17 @@ Kind: callable.
 
 Kind: interface.
 
+One fact: a label and a value, and optionally a description, a tooltip and an icon.
+
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
 | `id` | no | `string` | Stable identity. Without one the label and index stand in. |
-| `label` | yes | `ReactNode` |  |
+| `label` | yes | `ReactNode` | Names the fact. |
 | `value` | no | `ReactNode \| MetadataValueDescriptor \| null` | A node, or a descriptor that names the fact's kind. |
 | `description` | no | `ReactNode \| null` | Supporting copy under the value. |
-| `tooltip` | no | `ReactNode` | Shown from an info trigger beside the label — for a fact that needs explaining. |
-| `icon` | no | `ComponentType<{ className?: string; }>` |  |
-| `emptyLabel` | no | `ReactNode` |  |
+| `tooltip` | no | `ReactNode` | Shown from an info trigger beside the label — for a fact that needs explaining. The<br>trigger is named after the label through `strings.formatInfoLabel` ("Amount info"), a<br>function rather than a suffix because word order differs by language. |
+| `icon` | no | `ComponentType<{ className?: string; }>` | A glyph before the label. |
+| `emptyLabel` | no | `ReactNode` | Shown when this fact's value is absent, in place of the list's `emptyLabel`. |
 | `render` | no | `(item: MetadataListItem) => ReactNode` | Takes over the value entirely, for one fact that none of the kinds cover. |
 
 ### `MetadataListProps`
@@ -485,6 +513,10 @@ MetadataValueDescriptor
 
 Kind: callable.
 
+Diagonal hatching for a region with nothing in it yet — a chart with no data, a slot
+awaiting an upload. It reads as deliberately empty; a blank box reads as broken. Not a
+Skeleton, which says "loading".
+
 ```text
 ({ className, ...props }: PlaceholderPatternProps) => import("react").JSX.Element
 ```
@@ -501,6 +533,9 @@ ComponentProps<"div">
 
 Kind: callable.
 
+A scroll container with the kit's scrollbar treatment, contained so reaching the end
+doesn't scroll the page behind. Give it a max height; it does not impose one.
+
 **Use when:** A constrained scrollable region that needs consistent scrollbars.
 
 **Avoid when:** Making the entire document scroll or hiding overflowing interactive content.
@@ -519,6 +554,10 @@ Kind: callable.
 
 Kind: callable.
 
+A rule between content, horizontal or vertical; a vertical separator needs a height from
+its container. An unlabelled separator exposes separator semantics: set `aria-hidden` to
+hide a decorative rule from assistive technology.
+
 ```text
 ({ className, orientation, variant, thickness, label, style, ...props }: SeparatorProps) => React.JSX.Element
 ```
@@ -527,13 +566,13 @@ Kind: callable.
 
 Kind: interface.
 
-Extends: `SeparatorPrimitive.Props`.
+Extends: `SeparatorPrimitive.Props`, `Pick<SeparatorPrimitive.Props, "aria-hidden">`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `variant` | no | `SeparatorVariant` |  |
+| `variant` | no | `SeparatorVariant` | How the rule is drawn. Structural, not semantic — a dashed rule is the same divider,<br>drawn as provisional. |
 | `thickness` | no | `string \| number` | The rule's thickness: a CSS length, or a number in pixels. Overrides<br>`--separator-thickness` for this rule, e.g. a seam between panels. |
-| `label` | no | `React.ReactNode` | Text set into a gap in the rule — "OR", "More options". Horizontal only. |
+| `label` | no | `React.ReactNode` | Text set into a gap in the rule — "OR", "More options". Horizontal only. It drops the<br>separator role, because the rule is then decoration around real text. |
 
 ### `SeparatorVariant`
 
@@ -549,6 +588,9 @@ How the rule is drawn — structural, so a `variant`. Dashed and dotted read as
 
 Kind: callable.
 
+Present to assistive technology, absent on screen. Not `display: none`, which removes it
+from both.
+
 ```text
 ({ className, render, ...props }: VisuallyHiddenProps) => React.JSX.Element
 ```
@@ -570,167 +612,578 @@ Preview route: Collapsible — `/collapsible`
 ### Collapsible
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Collapsible>
-  <CollapsibleTrigger>Advanced options</CollapsibleTrigger>
-  <CollapsibleContent>…</CollapsibleContent>
-</Collapsible>
+import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "themelia-ui/base/display"
+import { Stack } from "themelia-ui/base/structure"
+import { Text } from "themelia-ui/base/typography"
+
+export default function CollapsibleExample() {
+	return (
+		<Collapsible>
+			<CollapsibleTrigger>
+				<Text tag="span" size="sm" weight="medium">
+					Advanced options
+				</Text>
+			</CollapsibleTrigger>
+			<CollapsibleContent>
+				<Stack gap="sm" style={{ paddingTop: "var(--space-md)" }}>
+					<Text type="secondary" size="sm">
+						Content that expands to its natural height.
+					</Text>
+					<Text type="secondary" size="sm">
+						However many lines it happens to be.
+					</Text>
+				</Stack>
+			</CollapsibleContent>
+		</Collapsible>
+	)
+}
 ```
 
 ### Four surfaces
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<ContentBlock surface="card" title="Contract" description="…">
-  …
-</ContentBlock>
+import { ShieldCheckIcon } from "lucide-react"
+
+import { ContentBlock } from "themelia-ui/base/display"
+import { Grid, GridCell } from "themelia-ui/base/structure"
+import { Text } from "themelia-ui/base/typography"
+
+export default function ContentBlockSurfaces() {
+	return (
+		<Grid columns={{ base: 1, sm: 2 }} gap="lg">
+			{(["plain", "bordered", "muted", "card"] as const).map((surface) => (
+				<GridCell key={surface}>
+					<ContentBlock
+						surface={surface}
+						icon={<ShieldCheckIcon aria-hidden="true" />}
+						title={`surface="${surface}"`}
+						description="The header renders only when there is something to put in it."
+					>
+						<Text size="xs" type="secondary">
+							A block with no title, description, icon or headerEnd draws no header at all —
+							which is what makes it usable as a bare surface.
+						</Text>
+					</ContentBlock>
+				</GridCell>
+			))}
+		</Grid>
+	)
+}
 ```
 
 ### flush
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<ContentBlock surface="card" flush>
-  <ItemGroup ruled>…</ItemGroup>
-</ContentBlock>
+import { KeyRoundIcon } from "lucide-react"
+
+import { Badge } from "themelia-ui/base/badge"
+import { ContentBlock, IconBadge } from "themelia-ui/base/display"
+import { Item, ItemContent, ItemGroup, ItemMedia, ItemTitle } from "themelia-ui/base/item"
+import { Grid, GridCell } from "themelia-ui/base/structure"
+import { Text } from "themelia-ui/base/typography"
+
+export default function ContentBlockFlush() {
+	return (
+		<Grid columns={2} gap="lg">
+			<GridCell>
+				<ContentBlock surface="card" flush>
+					<ItemGroup ruled>
+						{[
+							{ name: "Production", value: "sk_live_••••0b3d" },
+							{ name: "Staging", value: "sk_test_••••a771" },
+						].map((row) => (
+							<Item key={row.name} style={{ paddingInline: "var(--space-xl)" }}>
+								<ItemMedia>
+									<IconBadge icon={KeyRoundIcon} />
+								</ItemMedia>
+								<ItemContent>
+									<ItemTitle>{row.name}</ItemTitle>
+									<Text size="xs" type="secondary">
+										{row.value}
+									</Text>
+								</ItemContent>
+							</Item>
+						))}
+					</ItemGroup>
+				</ContentBlock>
+			</GridCell>
+			<GridCell>
+				<ContentBlock
+					surface="card"
+					title="Not flush"
+					titleSuffix={<Badge tone="neutral">for contrast</Badge>}
+				>
+					<Text size="xs" type="secondary">
+						The block pays the inset here, so nothing inside it can touch the border. Right
+						for prose and for a stack of controls; wrong for a run of ruled rows.
+					</Text>
+				</ContentBlock>
+			</GridCell>
+		</Grid>
+	)
+}
 ```
 
 ### The header assembles itself
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<ContentBlock
-  icon={<TruckIcon />}
-  title="Shipment"
-  titleSuffix={<Badge tone="info">In transit</Badge>}
-  headerEnd={<Button buttonStyle="ghost">Track</Button>}
-/>
+import { TruckIcon } from "lucide-react"
+
+import { Badge } from "themelia-ui/base/badge"
+import { Button } from "themelia-ui/base/buttons"
+import { ContentBlock, Separator } from "themelia-ui/base/display"
+import { Stack } from "themelia-ui/base/structure"
+import { Text } from "themelia-ui/base/typography"
+
+export default function ContentBlockHeader() {
+	return (
+		<Stack gap="lg">
+			<ContentBlock
+				surface="card"
+				icon={<TruckIcon aria-hidden="true" />}
+				title="Shipment"
+				titleSuffix={<Badge tone="info">In transit</Badge>}
+				headerEnd={
+					<Button tone="neutral" buttonStyle="ghost">
+						Track
+					</Button>
+				}
+				description="A description is its own row, so a long one wraps under the whole header rather than squeezing the title."
+			>
+				<Separator />
+				<Text size="xs" type="secondary">
+					Children follow, spaced by the block's own gap.
+				</Text>
+			</ContentBlock>
+		</Stack>
+	)
+}
 ```
 
 ### IconBadge
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<IconBadge icon={CreditCardIcon} tone="success" />
-<IconBadge icon={CreditCardIcon} tone="success" shape="circle" solid />
+import { CreditCardIcon } from "lucide-react"
+
+import { IconBadge } from "themelia-ui/base/display"
+import { Stack } from "themelia-ui/base/structure"
+
+export default function IconBadgeExample() {
+	return (
+		<Stack gap="xl">
+			<Stack direction="horizontal" gap="lg" wrap align="center">
+				{(["neutral", "primary", "success", "warning", "destructive", "info"] as const).map(
+					(tone) => (
+						<IconBadge key={tone} icon={CreditCardIcon} tone={tone} />
+					),
+				)}
+			</Stack>
+			<Stack direction="horizontal" gap="lg" wrap align="center">
+				{(["neutral", "primary", "success", "warning", "destructive", "info"] as const).map(
+					(tone) => (
+						<IconBadge key={tone} icon={CreditCardIcon} tone={tone} shape="circle" solid />
+					),
+				)}
+			</Stack>
+		</Stack>
+	)
+}
 ```
 
 ### PlaceholderPattern
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<PlaceholderPattern style={{ height: "8rem" }} />
+import { PlaceholderPattern } from "themelia-ui/base/display"
+
+export default function PlaceholderPatternExample() {
+	return (
+		<PlaceholderPattern style={{ height: "8rem", borderRadius: "var(--radius)" }} />
+	)
+}
+```
+
+### DirectionProvider and Slot
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+import { ContentBlock } from "themelia-ui/base/display"
+import { DirectionProvider } from "themelia-ui/base/direction"
+import { Slot } from "themelia-ui/base/slot"
+import { Stack } from "themelia-ui/base/structure"
+import { Text } from "themelia-ui/base/typography"
+
+export default function DirectionSlot() {
+	return (
+		<Stack gap="lg">
+			<DirectionProvider direction="rtl">
+				<div dir="rtl">
+					<ContentBlock surface="card" title="اتجاه من اليمين إلى اليسار">
+						<Text size="xs" type="secondary">كل هامش وفجوة وحد هنا خاصية منطقية.</Text>
+					</ContentBlock>
+				</div>
+			</DirectionProvider>
+			<Text size="xs" type="secondary">
+				Every inset, gap and border in the block above is a logical property, so <code>dir</code> on
+				the region mirrors it without a stylesheet per direction. The provider tells the menus and
+				popovers inside it the same thing.
+			</Text>
+			<Slot className={undefined}>
+				<Text size="xs" type="secondary">
+					Slot renders its child, merged. There is nothing of its own on the page.
+				</Text>
+			</Slot>
+		</Stack>
+	)
+}
 ```
 
 ### DateBlock
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<DateBlock date="2026-08-16" />
+import { DateBlock } from "themelia-ui/base/display"
+import { Stack } from "themelia-ui/base/structure"
+
+export default function DateBlockExample() {
+	return (
+		<Stack direction="horizontal" gap="lg" wrap align="start">
+			<DateBlock date="2026-08-16" />
+			<DateBlock date="2026-12-31" />
+			<DateBlock date="2027-01-04" showYear />
+			<DateBlock date="2026-09-28" time="09:00" />
+		</Stack>
+	)
+}
 ```
 
 ### Parts
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<DateBlock date={date} showWeekday={false} />
-<DateBlock date={date} showMonth={false} />
-<DateBlock date={date} showYear />
-<DateBlock date={date} time="09:00 – 10:30" />
+import { DateBlock } from "themelia-ui/base/display"
+import { Stack } from "themelia-ui/base/structure"
+
+export default function DateBlockParts() {
+	return (
+		<Stack direction="horizontal" gap="lg" wrap align="start">
+			<DateBlock date="2026-09-02" showWeekday={false} />
+			<DateBlock date="2026-09-02" showMonth={false} />
+			<DateBlock date="2026-09-02" showYear />
+			<DateBlock date="2026-09-02" time="09:00 – 10:30" />
+		</Stack>
+	)
+}
 ```
 
 ### In a list
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Item>
-  <ItemMedia><DateBlock date={event.date} /></ItemMedia>
-  <ItemContent>
-    <ItemTitle>{event.title}</ItemTitle>
-    <ItemDescription>{event.meta}</ItemDescription>
-  </ItemContent>
-</Item>
+import { Badge } from "themelia-ui/base/badge"
+import { DateBlock } from "themelia-ui/base/display"
+import {
+	Item, ItemActions, ItemContent, ItemDescription, ItemGroup, ItemMedia, ItemTitle,
+} from "themelia-ui/base/item"
+import { Stack } from "themelia-ui/base/structure"
+
+const EVENTS = [
+	{ id: "kickoff", date: "2026-09-28", title: "Quarterly kickoff", meta: "09:00 – 10:30 · Main hall", tone: "info" as const, badge: "All hands" },
+	{ id: "review", date: "2026-10-02", title: "Design review", meta: "14:00 – 15:00 · Room 4", tone: "neutral" as const, badge: "Team" },
+	{ id: "release", date: "2026-10-09", title: "2.0 release", meta: "All day", tone: "success" as const, badge: "Milestone" },
+]
+
+export default function DateBlockInAList() {
+	return (
+		<Stack maxWidth="36rem" gap="none">
+			<ItemGroup ruled>
+				{EVENTS.map((event) => (
+					<Item key={event.id}>
+						<ItemMedia>
+							<DateBlock date={event.date} />
+						</ItemMedia>
+						<ItemContent>
+							<ItemTitle>{event.title}</ItemTitle>
+							<ItemDescription>{event.meta}</ItemDescription>
+						</ItemContent>
+						<ItemActions>
+							<Badge tone={event.tone}>{event.badge}</Badge>
+						</ItemActions>
+					</Item>
+				))}
+			</ItemGroup>
+		</Stack>
+	)
+}
 ```
 
 ### Unboxed and inline
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<DateBlock date={date} boxed={false} />
-<DateBlock date={date} layout="inline" time="09:00" />
+import { DateBlock } from "themelia-ui/base/display"
+import { Stack } from "themelia-ui/base/structure"
+import { Text } from "themelia-ui/base/typography"
+
+export default function DateBlockUnboxed() {
+	return (
+		<Stack gap="lg">
+			<Stack direction="horizontal" gap="xl" wrap align="start">
+				<DateBlock date="2026-08-27" boxed={false} />
+				<DateBlock date="2026-08-27" boxed={false} showWeekday={false} />
+			</Stack>
+			<Stack direction="horizontal" gap="sm" align="baseline">
+				<Text size="sm" type="secondary">Next session</Text>
+				<DateBlock date="2026-08-27" layout="inline" time="· 09:00" />
+			</Stack>
+		</Stack>
+	)
+}
 ```
 
 ### Three layouts for one fact
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<InlineStat label="Subtotal" value="€ 1,240.00" mono />
-<InlineStat layout="inline" label="Region" value="eu-west-1" mono />
-<InlineStat layout="stacked" label="Open invoices" value="14" mono />
+import { Card, CardContent } from "themelia-ui/base/cards"
+import { InlineStat } from "themelia-ui/base/display"
+import { Stack } from "themelia-ui/base/structure"
+
+export default function InlineStatExample() {
+	return (
+		<Stack gap="xl">
+			<Card style={{ maxWidth: "24rem" }}>
+				<CardContent>
+					<Stack gap="md">
+						<InlineStat label="Subtotal" value="€ 1,240.00" mono />
+						<InlineStat label="Shipping" value="€ 18.50" mono />
+						<InlineStat label="Discount" value={null} mono />
+					</Stack>
+				</CardContent>
+			</Card>
+			<Stack direction="horizontal" gap="2xl" wrap>
+				<InlineStat layout="inline" label="Region" value="eu-west-1" mono />
+				<InlineStat layout="inline" label="Plan" value="Team" />
+				<InlineStat layout="inline" label="Seats" value="12" mono />
+			</Stack>
+			<Stack direction="horizontal" gap="2xl" wrap>
+				<InlineStat layout="stacked" label="Open invoices" value="14" mono />
+				<InlineStat layout="stacked" label="Overdue" value="3" mono />
+				<InlineStat layout="stacked" label="Collected" value="€ 48,200.00" mono />
+			</Stack>
+		</Stack>
+	)
+}
 ```
 
 ### Kbd
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Kbd>⌘K</Kbd>
-
-// A sequence — pressed one after another — is a group:
-<KbdGroup><Kbd>G</Kbd><Kbd>I</Kbd></KbdGroup>
+import { Kbd, KbdGroup } from "themelia-ui/base/display"
+import { Stack } from "themelia-ui/base/structure"
+import { Text } from "themelia-ui/base/typography"
+
+export default function KbdExample() {
+	return (
+		<Stack gap="sm">
+			<Stack direction="horizontal" gap="md" align="center">
+				<Text size="sm" type="secondary">Open the palette with</Text>
+				<Kbd>⌘K</Kbd>
+				<Text size="sm" type="secondary">or</Text>
+				<Kbd>Ctrl K</Kbd>
+				<Text size="sm" type="secondary">· close with</Text>
+				<Kbd>Esc</Kbd>
+			</Stack>
+			<Stack direction="horizontal" gap="md" align="center">
+				<Text size="sm" type="secondary">Go to the inbox with</Text>
+				{/* A sequence: G, then I. The wider gap between caps says "in turn". */}
+				<KbdGroup>
+					<Kbd>G</Kbd>
+					<Kbd>I</Kbd>
+				</KbdGroup>
+			</Stack>
+		</Stack>
+	)
+}
 ```
 
 ### grid
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<MetadataList
-  columns={3}
-  items={[
-    { label: "Reference", value: { kind: "mono", value: "INV-4417" } },
-    { label: "Amount", value: { kind: "money", value: 48200, currency: "USD" } },
-    { label: "Status", value: { kind: "badge", value: "Overdue", badgeTone: "destructive" } },
-  ]}
-/>
+import { MetadataList } from "themelia-ui/base/display"
+
+import { FACTS } from "./data"
+
+export default function MetadataGrid() {
+	return (
+		<MetadataList items={FACTS} columns={3} />
+	)
+}
 ```
 
 ### rows
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<MetadataList layout="rows" itemSeparator items={facts} />
+import { MetadataList } from "themelia-ui/base/display"
+
+import { FACTS } from "./data"
+
+export default function MetadataRows() {
+	return (
+		<MetadataList layout="rows" itemSeparator items={FACTS} />
+	)
+}
 ```
 
 ### inline
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<MetadataList layout="inline" itemSeparator items={summary} />
+import { MetadataList, type MetadataInlineListItem } from "themelia-ui/base/display"
+import { Stack } from "themelia-ui/base/structure"
+
+// Typed for the inline layout, which has no second line to put a description on.
+const SUMMARY: MetadataInlineListItem[] = [
+	{ label: "Created", value: { kind: "date", value: "2026-08-14" } },
+	{ label: "By", value: "Alice Mercer" },
+	{ label: "Version", value: { kind: "mono", value: "v3.2" } },
+]
+
+export default function MetadataInline() {
+	return (
+		<Stack gap="lg">
+			<MetadataList layout="inline" itemSeparator items={SUMMARY} />
+			<MetadataList layout="inline" itemSeparator="—" density="compact" items={SUMMARY} />
+		</Stack>
+	)
+}
 ```
 
 ### density
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<MetadataList density="compact" columns={2} items={facts} />
+import { MetadataList } from "themelia-ui/base/display"
+
+import { FACTS } from "./data"
+
+export default function MetadataDensity() {
+	return (
+		<MetadataList density="compact" columns={2} items={FACTS.slice(0, 4)} title="Invoice" titleSeparator />
+	)
+}
 ```
 
 ### ScrollArea
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<ScrollArea style={{ maxHeight: "8rem" }}>…</ScrollArea>
+import { ScrollArea } from "themelia-ui/base/display"
+import { Stack } from "themelia-ui/base/structure"
+import { Text } from "themelia-ui/base/typography"
+
+// A card's edge and inset, so the demo frames the region the way a real surface would.
+const SCROLL_FRAME = {
+	maxHeight: "9rem",
+	border: "var(--border-width) solid var(--border)",
+	borderRadius: "var(--radius)",
+	padding: "var(--surface-y) var(--surface-x)",
+} as const
+
+export default function ScrollAreaExample() {
+	return (
+		<ScrollArea style={SCROLL_FRAME}>
+			<Stack gap="xs">
+				{Array.from({ length: 12 }, (_, index) => (
+					<Text key={index} size="sm" type="secondary">
+						Scrollable line {index + 1}
+					</Text>
+				))}
+			</Stack>
+		</ScrollArea>
+	)
+}
 ```
 
 ### BooleanIndicator
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<BooleanIndicator value strings={{ true: "Active", false: "Paused" }} />
+import { BooleanIndicator } from "themelia-ui/base/display"
+import { Stack } from "themelia-ui/base/structure"
+
+export default function BooleanIndicatorExample() {
+	return (
+		<Stack direction="horizontal" gap="xl">
+			<BooleanIndicator value strings={{ true: "Active", false: "Paused" }} />
+			<BooleanIndicator value={false} strings={{ true: "Active", false: "Paused" }} />
+		</Stack>
+	)
+}
 ```
 
 ### VisuallyHidden
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Text>
-  Saved
-  <VisuallyHidden> at 09:32 by Jane McDonald</VisuallyHidden>
-</Text>
+import { VisuallyHidden } from "themelia-ui/base/display"
+import { Text } from "themelia-ui/base/typography"
+
+export default function VisuallyHiddenExample() {
+	return (
+		<Text size="sm" type="secondary">
+			This sentence has a hidden note for screen readers.
+			<VisuallyHidden> Only assistive technology reads this.</VisuallyHidden>
+		</Text>
+	)
+}
 ```
 
 ### Separator
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Separator />
-<Separator label="OR" />
-<Separator orientation="vertical" />
+import { Separator } from "themelia-ui/base/display"
+import { Stack } from "themelia-ui/base/structure"
+import { Text } from "themelia-ui/base/typography"
+
+export default function SeparatorExample() {
+	return (
+		<Stack gap="lg" style={{ width: "100%" }}>
+			<Separator />
+			<Separator label="OR" />
+			<Stack direction="horizontal" gap="md" align="center" style={{ height: "1.5rem" }}>
+				<Text size="sm">Left</Text>
+				<Separator orientation="vertical" />
+				<Text size="sm">Right</Text>
+			</Stack>
+		</Stack>
+	)
+}
 ```
 
 ### Variants and thickness
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Separator variant="dashed" />
-<Separator variant="dotted" />
-<Separator thickness={2} />
+import { Separator } from "themelia-ui/base/display"
+import { Stack } from "themelia-ui/base/structure"
+import { Text } from "themelia-ui/base/typography"
+
+
+export default function SeparatorVariants() {
+	return (
+		<Stack gap="xl" style={{ maxWidth: "26rem", width: "100%" }}>
+			<Stack gap="xs">
+				<Text size="xs" type="secondary">solid</Text>
+				<Separator />
+			</Stack>
+			<Stack gap="xs">
+				<Text size="xs" type="secondary">dashed</Text>
+				<Separator variant="dashed" />
+			</Stack>
+			<Stack gap="xs">
+				<Text size="xs" type="secondary">dotted</Text>
+				<Separator variant="dotted" />
+			</Stack>
+			<Stack gap="xs">
+				<Text size="xs" type="secondary">thickness=&#123;2&#125;</Text>
+				<Separator thickness={2} />
+			</Stack>
+			<Stack direction="horizontal" gap="lg" style={{ height: "3rem" }}>
+				<Text size="sm">Vertical</Text>
+				<Separator orientation="vertical" variant="dashed" />
+				<Text size="sm">rules</Text>
+				<Separator orientation="vertical" thickness={2} />
+				<Text size="sm">too</Text>
+			</Stack>
+		</Stack>
+	)
+}
 ```