themelia-ui 3.0.0 → 3.2.0

package/docs/generated/components/{patterns--analytics.md → blocks--analytics.md}

@@ -1,6 +1,6 @@
 <!-- GENERATED by scripts/gen-consumer-docs.mjs — do not edit. -->
 
-# `patterns/analytics`
+# `blocks/analytics`
 
 Figures are summarised — metric tiles, trends, comparisons, a heatmap or a titled chart card.
 
@@ -14,8 +14,7 @@ Figures are summarised — metric tiles, trends, comparisons, a heatmap or a tit
 ## Import
 
 ```tsx fragment — import-only example
-import { ActivityHeatmap } from "themelia-ui/patterns/analytics"
-import "themelia-ui/patterns/analytics.css"
+import { ActivityHeatmap } from "themelia-ui/blocks/analytics"
 ```
 
 ## Optional peers
@@ -96,7 +95,7 @@ date-fns locale: the heatmap needs abbreviations sized to its columns.
 | --- | :-: | --- | --- |
 | `metricErrorLabel` | yes | `string` | Shown in place of the figure when `error` is set. |
 | `metricProgressLabel` | yes | `(label: string) => string` | Names the `colored` variant's progress bar for a screen reader. |
-| `metricInfoLabel` | no | `string` | Names the info affordance beside a label that carries a `tooltip`. Optional for<br>backward compatibility; the default applies. |
+| `metricInfoLabel` | yes | `string` | Names the info affordance beside a label that carries a `tooltip`. |
 
 ### `ChartCard`
 
@@ -162,6 +161,16 @@ Kind: callable.
 
 Kind: callable.
 
+**Use when:** One quantitative measure needs value hierarchy and optional comparison, trend or progress.
+
+**Avoid when:** An ordinary fact or a group that MetricGrid already arranges.
+
+**Compose:** Read MetricProps for state and surface variants; they are not shared by every analytics export. The analytics module requires recharts.
+
+**Capabilities:** single quantitative measure; metric comparison trend.
+
+**Alternatives:** MetricGrid, MetadataList.
+
 ```text
 ({ data, variant, tone, showSparkline, showChange, showIcon, loading, error, strings, progress, className, ...props }: MetricProps) => import("react").JSX.Element
 ```
@@ -319,6 +328,16 @@ Four pairs off the categorical ramp. Named for the look, not for a meaning.
 
 Kind: callable.
 
+**Use when:** Several quantitative measures need responsive tiles with comparison or trend.
+
+**Avoid when:** Ordinary label/value facts, identifiers or prose summaries.
+
+**Compose:** Pass MetricData and the period context. Use null for an unavailable quantity, zero for measured zero. The module requires recharts and already owns tile arrangement.
+
+**Capabilities:** quantitative metrics; dashboard figures; responsive metric tiles.
+
+**Alternatives:** Metric, MetadataList.
+
 ```text
 ({ metrics, variant, tone, columns, showSparklines, showChanges, showIcons, loading, className, ...props }: MetricGridProps) => import("react").JSX.Element
 ```
@@ -570,10 +589,34 @@ Kind: interface.
 
 Preview route: Analytics — `/analytics`
 
+### Communications overview reference
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+import { useState } from "react"
+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 { Text } from "themelia-ui/base/typography"
+import { MetricGrid } from "themelia-ui/blocks/analytics"
+
+export default function CommunicationsReference() {
+	const [retried, setRetried] = useState(false)
+	return <Stack>
+		<MetricGrid metrics={[{ id: "delivered", label: "Messages delivered during the selected reporting period", value: 128, valueType: "number" }, { id: "retry", label: "Messages awaiting retry", value: retried ? 0 : 3, valueType: "number" }]} variant="card" />
+		<Card title="Latest communication" headerAction={<Button disabled={retried} onClick={() => setRetried(true)}>Retry delivery</Button>}>
+			<MetadataList items={[{ id: "subject", label: "Subject", value: "Workspace invitation" }, { id: "status", label: "Delivery state", value: retried ? "Delivered" : "Retry available" }, { id: "recipient", label: "Recipient", value: "member@example.test" }, { id: "time", label: "Last attempt", value: { kind: "datetime", value: "2026-09-01T09:30:00Z" } }, { id: "opened", label: "Opened", value: "Unknown; tracking unavailable" }]} />
+			<Text>The application owns delivery policy and permission checks. Metrics describe quantities; this subject and its delivery facts stay in a record surface.</Text>
+		</Card>
+		<Text role="status">{retried ? "Mock retry completed" : "Mock delivery is waiting"}</Text>
+	</Stack>
+}
+```
+
 ### Metric bar
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-import { MetricBar } from "themelia-ui/patterns/analytics"
+import { MetricBar } from "themelia-ui/blocks/analytics"
 
 import { METRICS } from "./data"
 
@@ -591,7 +634,7 @@ export default function AnalyticsBar() {
 ### Metric grid
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-import { MetricGrid } from "themelia-ui/patterns/analytics"
+import { MetricGrid } from "themelia-ui/blocks/analytics"
 
 import { METRICS } from "./data"
 
@@ -606,13 +649,13 @@ export default function AnalyticsGrid() {
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
 import { Stack } from "themelia-ui/base/structure"
-import { Metric, MetricGrid } from "themelia-ui/patterns/analytics"
+import { Metric, MetricGrid } from "themelia-ui/blocks/analytics"
 
 import { CHURN, FULFILMENT, ORDERS, REVENUE } from "./data"
 
 export default function AnalyticsVariants() {
 	return (
-		<Stack gap="xl">
+		<Stack>
 			<MetricGrid metrics={[REVENUE, CHURN]} variant="bordered" columns={2} />
 			<MetricGrid metrics={[ORDERS, FULFILMENT]} variant="compact" columns={2} />
 			<MetricGrid metrics={[REVENUE, CHURN]} variant="accent" columns={2} />
@@ -626,7 +669,7 @@ export default function AnalyticsVariants() {
 ### Comparison
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-import { MetricComparison } from "themelia-ui/patterns/analytics"
+import { MetricComparison } from "themelia-ui/blocks/analytics"
 
 export default function AnalyticsComparison() {
 	return (
@@ -643,7 +686,7 @@ export default function AnalyticsComparison() {
 ### Gradient hero
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-import { MetricGradient } from "themelia-ui/patterns/analytics"
+import { MetricGradient } from "themelia-ui/blocks/analytics"
 
 import { SERIES } from "./data"
 
@@ -666,7 +709,7 @@ export default function AnalyticsHero() {
 ### Micro grid
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-import { MetricMicroGrid } from "themelia-ui/patterns/analytics"
+import { MetricMicroGrid } from "themelia-ui/blocks/analytics"
 
 const MICRO = [
 	{ label: "Sessions", value: "18.2k", data: [4, 9, 6, 12, 10, 17] },
@@ -690,7 +733,7 @@ export default function AnalyticsMicro() {
 import { Area, AreaChart, CartesianGrid, XAxis } from "recharts"
 
 import type { ChartConfig } from "themelia-ui/base/chart"
-import { ChartCard } from "themelia-ui/patterns/analytics"
+import { ChartCard } from "themelia-ui/blocks/analytics"
 
 import { SERIES } from "./data"
 
@@ -721,7 +764,7 @@ export default function AnalyticsChartCard() {
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
 import {
 	ActivityHeatmap, type ActivityHeatmapDay, type ActivityLevel,
-} from "themelia-ui/patterns/analytics"
+} from "themelia-ui/blocks/analytics"
 
 /* A fixed, cyclic pattern, not random data, for stable visual baselines. */
 const HEATMAP: ActivityHeatmapDay[] = Array.from({ length: 182 }, (_, index) => {
@@ -742,7 +785,7 @@ export default function AnalyticsHeatmap() {
 ### Time ruler
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-import { TimeRuler } from "themelia-ui/patterns/analytics"
+import { TimeRuler } from "themelia-ui/blocks/analytics"
 
 const HOURS = [
 	0, 0, 0, 0, 1, 2, 5, 9, 14, 18, 22, 25,

package/docs/generated/components/{patterns--onboarding.md → blocks--onboarding.md}

@@ -1,6 +1,6 @@
 <!-- GENERATED by scripts/gen-consumer-docs.mjs — do not edit. -->
 
-# `patterns/onboarding`
+# `blocks/onboarding`
 
 A checklist tracks setup tasks the user completes over time.
 
@@ -8,14 +8,13 @@ A checklist tracks setup tasks the user completes over time.
 
 - **Use when:** A checklist tracks setup tasks the user completes over time.
 - **Avoid when:** The steps are one linear flow with a current position.
-- **Consider instead:** `patterns/timelines`
+- **Consider instead:** `blocks/timelines`
 - **Stability:** stable.
 
 ## Import
 
 ```tsx fragment — import-only example
-import { Checklist } from "themelia-ui/patterns/onboarding"
-import "themelia-ui/patterns/onboarding.css"
+import { Checklist } from "themelia-ui/blocks/onboarding"
 ```
 
 ## Composition
@@ -106,7 +105,7 @@ import { Badge } from "themelia-ui/base/badge"
 import { Button } from "themelia-ui/base/buttons"
 import { Stack } from "themelia-ui/base/structure"
 import { Text } from "themelia-ui/base/typography"
-import { Checklist } from "themelia-ui/patterns/onboarding"
+import { Checklist } from "themelia-ui/blocks/onboarding"
 
 export default function BlocksChecklist() {
 	return (
@@ -120,11 +119,11 @@ export default function BlocksChecklist() {
 					title: "Connect a data source",
 					badge: <Badge tone="warning">Required</Badge>,
 					content: (
-						<Stack gap="md">
+						<Stack gap="sm">
 							<Text type="secondary">Pick where your data lives. You can add more later.</Text>
 							<Stack direction="horizontal" gap="sm" wrap>
 								<Button tone="primary">Connect Postgres</Button>
-								<Button tone="secondary" buttonStyle="outline">Upload a CSV</Button>
+								<Button tone="secondary" appearance="outline">Upload a CSV</Button>
 							</Stack>
 						</Stack>
 					),

package/docs/generated/components/{patterns--timelines.md → blocks--timelines.md}

@@ -1,6 +1,6 @@
 <!-- GENERATED by scripts/gen-consumer-docs.mjs — do not edit. -->
 
-# `patterns/timelines`
+# `blocks/timelines`
 
 A sequence is presented as changelog entries, milestones, or a step tracker.
 
@@ -14,8 +14,7 @@ A sequence is presented as changelog entries, milestones, or a step tracker.
 ## Import
 
 ```tsx fragment — import-only example
-import { ChangelogTimeline } from "themelia-ui/patterns/timelines"
-import "themelia-ui/patterns/timelines.css"
+import { ChangelogTimeline } from "themelia-ui/blocks/timelines"
 ```
 
 ## Composition
@@ -231,7 +230,7 @@ Preview route: Timelines, onboarding & admin — `/blocks-admin`
 ### Changelog
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-import { ChangelogTimeline, type ChangelogEntry } from "themelia-ui/patterns/timelines"
+import { ChangelogTimeline, type ChangelogEntry } from "themelia-ui/blocks/timelines"
 
 const CHANGELOG: ChangelogEntry[] = [
 	{
@@ -277,7 +276,7 @@ export default function BlocksChangelog() {
 ### Milestones
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-import { MilestonesTimeline, type Milestone } from "themelia-ui/patterns/timelines"
+import { MilestonesTimeline, type Milestone } from "themelia-ui/blocks/timelines"
 
 const MILESTONES: Milestone[] = [
 	{ id: "1", title: "Discovery", description: "Interviews with eight teams.", status: "completed", dueDate: "12 Jun" },
@@ -298,7 +297,7 @@ export default function BlocksMilestones() {
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
 import { Stack } from "themelia-ui/base/structure"
-import { Steps, StepsBar, type Step } from "themelia-ui/patterns/timelines"
+import { Steps, StepsBar, type Step } from "themelia-ui/blocks/timelines"
 
 const STEPS: Step[] = [
 	{ id: "1", title: "Create your workspace", description: "Name it and pick a region.", status: "completed", timestamp: "Done 14 Aug" },
@@ -309,7 +308,7 @@ const STEPS: Step[] = [
 
 export default function BlocksSteps() {
 	return (
-		<Stack gap="2xl">
+		<Stack>
 			<StepsBar steps={STEPS} />
 			<Steps steps={STEPS} />
 		</Stack>

package/docs/generated/components/features--actions.md

@@ -15,7 +15,6 @@ The same operation runs from a table row, a card menu and the command palette, a
 
 ```tsx fragment — import-only example
 import { ActionHttpError } from "themelia-ui/features/actions"
-import "themelia-ui/features/actions.css"
 ```
 
 ## Composition
@@ -35,12 +34,12 @@ Kind: const.
 unknown
 ```
 
-### `ActionButtonStyle`
+### `ActionAppearance`
 
 Kind: type.
 
 ```text
-(typeof ACTION_BUTTON_STYLES)[number]
+(typeof ACTION_APPEARANCES)[number]
 ```
 
 ### `ActionContext`
@@ -266,7 +265,6 @@ Kind: interface.
 | `confirmLabel` | no | `ActionMessage<TPayload, TValues, TResult>` |  |
 | `cancelLabel` | no | `ActionMessage<TPayload, TValues, TResult>` |  |
 | `tone` | no | `ActionTone` |  |
-| `size` | no | `ActionOverlaySize` |  |
 | `drawerDirection` | no | `ActionDrawerDirection` |  |
 | `formId` | no | `string` |  |
 | `showCancel` | no | `boolean` |  |
@@ -281,7 +279,7 @@ Kind: interface.
 | `closeOnEscape` | no | `boolean` |  |
 | `closeOnSuccess` | no | `boolean` |  |
 | `closeOnBackdropClick` | no | `boolean` |  |
-| `confirmStyle` | no | `Extract<ActionButtonStyle, 'solid' \| 'outline'>` |  |
+| `confirmAppearance` | no | `Extract<ActionAppearance, 'solid' \| 'outline'>` |  |
 | `footer` | no | `ReactNode` |  |
 | `alertMessage` | no | `ActionMessage<TPayload, TValues, TResult>` |  |
 | `render` | no | `BivariantCallback<[ context: ActionRenderContext<TPayload, TValues> ], ReactNode>` |  |
@@ -313,14 +311,6 @@ Kind: interface.
 | --- | :-: | --- | --- |
 | `strings` | no | `StringsProp<ActionOverlayStrings>` |  |
 
-### `ActionOverlaySize`
-
-Kind: type.
-
-```text
-'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl' | '5xl' | 'full'
-```
-
 ### `ActionOverlayStrings`
 
 Kind: interface.
@@ -787,7 +777,7 @@ Kind: callable.
 Kind: callable.
 
 ```text
-(action: ResolvedAction<TPayload, TValues, TResult>) => { label: string; onClick: () => void; disabled: boolean; icon: import('react').ComponentType<{ className?: string; }> | undefined; tone: string; buttonStyle: string | undefined; }
+(action: ResolvedAction<TPayload, TValues, TResult>) => { label: string; onClick: () => void; disabled: boolean; icon: import('react').ComponentType<{ className?: string; }> | undefined; tone: string; appearance: string | undefined; }
 ```
 
 ### `toPageAction`
@@ -795,7 +785,7 @@ Kind: callable.
 Kind: callable.
 
 ```text
-(action: ResolvedAction<TPayload, TValues, TResult>) => { id: string; label: import('react').ReactNode; onClick: () => void; disabled: boolean; loading: boolean; icon: import('react').ComponentType<{ className?: string; }> | undefined; tone: string | undefined; buttonStyle: string | undefined; visible: boolean; group: string | undefined; placement: ActionPlacement; }
+(action: ResolvedAction<TPayload, TValues, TResult>) => { id: string; label: import('react').ReactNode; onClick: () => void; disabled: boolean; loading: boolean; icon: import('react').ComponentType<{ className?: string; }> | undefined; tone: string | undefined; appearance: string | undefined; visible: boolean; group: string | undefined; placement: ActionPlacement; }
 ```
 
 ### `toTableAction`
@@ -803,7 +793,7 @@ Kind: callable.
 Kind: callable.
 
 ```text
-(action: ResolvedAction<TData>) => { id: string; label: string; onClick: (row: TData) => void; disabled: boolean; isDisabled: () => boolean; isVisible: () => boolean; icon: import('react').ReactElement<{ className?: string; }, string | import('react').JSXElementConstructor<any>> | undefined; tone: string; buttonStyle: string | undefined; }
+(action: ResolvedAction<TData>) => { id: string; label: string; onClick: (row: TData) => void; disabled: boolean; isDisabled: () => boolean; isVisible: () => boolean; icon: import('react').ReactElement<{ className?: string; }, string | import('react').JSXElementConstructor<any>> | undefined; tone: string; appearance: string | undefined; }
 ```
 
 ### `useAction`
@@ -970,8 +960,8 @@ function ActionsDemo() {
 	const cardActions = useActionSurface({ surface: "card", scope: "invoice", payload: "INV-4418" })
 
 	return (
-		<Stack gap="xl" style={{ width: "100%" }}>
-			<Stack direction="horizontal" gap="md" align="center">
+		<Stack style={{ width: "100%" }}>
+			<Stack direction="horizontal" gap="sm" align="center">
 				{pageActions.map((action) => (
 					<Button
 						key={action.key}

package/docs/generated/components/features--activities.md

@@ -8,14 +8,13 @@ An audit or activity log renders actor, change and time, grouped by day.
 
 - **Use when:** An audit or activity log renders actor, change and time, grouped by day.
 - **Avoid when:** The entries are milestones or a changelog, or the thread is a discussion.
-- **Consider instead:** `patterns/timelines`, `features/comments`
+- **Consider instead:** `blocks/timelines`, `features/comments`
 - **Stability:** stable.
 
 ## Import
 
 ```tsx fragment — import-only example
 import { ActivityActionsMenu } from "themelia-ui/features/activities"
-import "themelia-ui/features/activities.css"
 ```
 
 ## Optional peers
@@ -144,20 +143,6 @@ renders nothing.
 ({ label, first, className, }: { label: string; first: boolean; className?: string; }) => import("react").JSX.Element | null
 ```
 
-### `ActivityDensity`
-
-Kind: type.
-
-How much of a row is drawn.
-
-`compact` a dot and one line, for an audit trail read by scanning.
-`default` an icon and a second line, for a record's own history.
-`rich`    the whole row: metadata, changes, resources, actions.
-
-```text
-"compact" | "default" | "rich"
-```
-
 ### `ActivityEmptyState`
 
 Kind: callable.
@@ -254,7 +239,7 @@ The timeline of events, grouped by date on one rail.
 **Alternatives:** Comments, ActivityLog.
 
 ```text
-({ activities, density, itemSpacing, groupByDate, expandedByDefault, detailsCollapsible, defaultExpandedIds, expandedIds, onExpandedIdsChange, currentUserId, loading, error, onRetry, eventConfig, strings, slots, rowClassNames, className, locale, formatRelativeTime, formatAbsoluteTime, formatDateGroupLabel, getSourceLabel, actionsForActivity, onActivityClick, onActorClick, onResourceClick, onAction, onActivityExpandedChange, resources, onResourcesChange, }: ActivityFeedProps<TData>) => import("react").JSX.Element
+({ activities, variant, itemSpacing, groupByDate, expandedByDefault, detailsCollapsible, defaultExpandedIds, expandedIds, onExpandedIdsChange, currentUserId, loading, error, onRetry, eventConfig, strings, slots, rowClassNames, className, locale, formatRelativeTime, formatAbsoluteTime, formatDateGroupLabel, getSourceLabel, actionsForActivity, onActivityClick, onActorClick, onResourceClick, onAction, onActivityExpandedChange, resources, onResourcesChange, }: ActivityFeedProps<TData>) => import("react").JSX.Element
 ```
 
 ### `ActivityFeedAccessors`
@@ -291,7 +276,7 @@ Extends: `ActivityFeedAccessors<TData>`, `ActivityFeedCallbacks<TData>`, `Activi
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
 | `activities` | no | `ReadonlyArray<ActivityItem<TData>>` | In display order. Grouped by date as they come, not bucketed — bucketing would silently<br>reorder a feed sorted by something other than date. |
-| `density` | no | `ActivityDensity` | How much of a row is drawn. `rich` adds metadata, changes, resources, and actions. |
+| `variant` | no | `ActivityVariant` | How much of a row is drawn. `rich` adds metadata, changes, resources, and actions. |
 | `itemSpacing` | no | `ActivityItemSpacing` | The rhythm between rows, independent of how much each row draws. |
 | `groupByDate` | no | `boolean` |  |
 | `expandedByDefault` | no | `boolean` |  |
@@ -391,7 +376,7 @@ Kind: type.
 The rhythm between rows, independent of how much each row draws.
 
 ```text
-"compact" | "default" | "relaxed"
+"default" | "sm"
 ```
 
 ### `ActivityKeyedItem`
@@ -595,7 +580,7 @@ The dot on the rail. It knows whether it is last, because the connector below it
 tells a reader the run has ended.
 
 ```text
-({ icon, tone, density, last, className }: ActivityMarkerProps) => import("react").JSX.Element
+({ icon, tone, variant, last, className }: ActivityMarkerProps) => import("react").JSX.Element
 ```
 
 ### `ActivityMarkerProps`
@@ -606,7 +591,7 @@ Kind: interface.
 | --- | :-: | --- | --- |
 | `icon` | yes | `ReactNode` |  |
 | `tone` | yes | `ActivityTone` |  |
-| `density` | yes | `ActivityDensity` |  |
+| `variant` | yes | `ActivityVariant` |  |
 | `last` | yes | `boolean` | The rail stops at the last row rather than running into nothing. |
 | `className` | no | `string` |  |
 
@@ -618,7 +603,7 @@ Everything a custom renderer needs about where its row sits.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `density` | yes | `ActivityDensity` |  |
+| `variant` | yes | `ActivityVariant` |  |
 | `isLast` | yes | `boolean` |  |
 | `isFirstInGroup` | yes | `boolean` |  |
 | `activity` | yes | `ActivityItem<TData>` |  |
@@ -704,12 +689,12 @@ Kind: interface.
 
 Kind: callable.
 
-One entry on the rail. Density changes the marker size and the row rhythm together —
+One entry on the rail. The variant changes the marker size and the row rhythm together —
 changing one without the other is what makes a compact feed look mis-aligned rather than
 dense.
 
 ```text
-({ activity, density, itemSpacing, eventConfig, tone, last, expanded, onExpandedChange, detailsCollapsible, detailLabels, relativeTime, absoluteTime, sourceLabel, youLabel, showChangesLabel, hideChangesLabel, moreLabel, actionsLabel, currentUserId, actions, onActivityClick, onActorClick, onResourceClick, onAction, getResourceConfig, headlineOverride, markerOverride, customDetails, rowClassName, markerClassName, contentClassName, detailsClassName, }: ActivityRowProps<TData>) => import("react").JSX.Element
+({ activity, variant, itemSpacing, eventConfig, tone, last, expanded, onExpandedChange, detailsCollapsible, detailLabels, relativeTime, absoluteTime, sourceLabel, youLabel, showChangesLabel, hideChangesLabel, moreLabel, actionsLabel, currentUserId, actions, onActivityClick, onActorClick, onResourceClick, onAction, getResourceConfig, headlineOverride, markerOverride, customDetails, rowClassName, markerClassName, contentClassName, detailsClassName, }: ActivityRowProps<TData>) => import("react").JSX.Element
 ```
 
 ### `ActivityRowClassNames`
@@ -740,7 +725,7 @@ Kind: interface.
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
 | `activity` | yes | `ActivityItem<TData>` |  |
-| `density` | yes | `ActivityDensity` |  |
+| `variant` | yes | `ActivityVariant` |  |
 | `itemSpacing` | yes | `ActivityItemSpacing` |  |
 | `eventConfig` | yes | `ActivityEventConfig` |  |
 | `tone` | yes | `ActivityTone` |  |
@@ -780,6 +765,20 @@ Kind: type.
 SemanticTone
 ```
 
+### `ActivityVariant`
+
+Kind: type.
+
+How much of a row is drawn.
+
+`compact` a dot and one line, for an audit trail read by scanning.
+`default` an icon and a second line, for a record's own history.
+`rich`    the whole row: metadata, changes, resources, actions.
+
+```text
+"compact" | "default" | "rich"
+```
+
 ### `createActivityEventAdapter`
 
 Kind: callable.
@@ -926,13 +925,13 @@ import { ExternalLinkIcon, RotateCwIcon } from "lucide-react"
 import { PillRadioGroup, Select } from "themelia-ui/base/choice-inputs"
 import { Stack } from "themelia-ui/base/structure"
 import { Text } from "themelia-ui/base/typography"
-import { ActivityFeed, type ActivityDensity } from "themelia-ui/features/activities"
+import { ActivityFeed, type ActivityVariant } from "themelia-ui/features/activities"
 
 import styles from "./activities.module.css"
 import { ACTIVITIES, REGISTRY } from "./data"
 
 export default function ActivityFeedExample() {
-	const [density, setDensity] = useState<ActivityDensity>("rich")
+	const [variant, setVariant] = useState<ActivityVariant>("rich")
 	const [activities, setActivities] = useState(ACTIVITIES)
 	const [feedState, setFeedState] = useState("ready")
 	const [log, setLog] = useState<string[]>([])
@@ -943,8 +942,8 @@ export default function ActivityFeedExample() {
 		<>
 			<Stack direction="horizontal" gap="sm" wrap>
 				<PillRadioGroup
-					value={density}
-					onValueChange={(next) => next && setDensity(next as ActivityDensity)}
+					value={variant}
+					onValueChange={(next) => next && setVariant(next as ActivityVariant)}
 					options={[
 						{ value: "compact", label: "compact" },
 						{ value: "default", label: "default" },
@@ -965,7 +964,7 @@ export default function ActivityFeedExample() {
 				loading={feedState === "refreshing" || feedState === "loading"}
 				error={feedState === "error" || feedState === "initial-error" ? "The activity service is unavailable. Try again to reload history." : undefined}
 				onRetry={() => setFeedState("ready")}
-				density={density}
+				variant={variant}
 				currentUserId="u1"
 				resources={REGISTRY}
 				onActorClick={(actor) => note(`actor: ${actor.name}`)}
@@ -1041,8 +1040,8 @@ export default function ActivityLogExample() {
 	return (
 		<>
 			<Stack direction="horizontal" gap="sm" wrap>
-				<Button tone="neutral" buttonStyle="outline" onClick={() => setEntries([])} disabled={entries.length === 0}>Show empty log</Button>
-				<Button tone="neutral" buttonStyle="outline" onClick={() => setEntries(ENTRIES)}>Restore sample</Button>
+				<Button tone="neutral" appearance="outline" onClick={() => setEntries([])} disabled={entries.length === 0}>Show empty log</Button>
+				<Button tone="neutral" appearance="outline" onClick={() => setEntries(ENTRIES)}>Restore sample</Button>
 				<Select aria-label="Log state" value={logState} className={styles.stateSelect}
 					options={[{ value: "ready", label: "Loaded" }, { value: "loading", label: "Updating" }, { value: "error", label: "Failed" }]}
 					onValueChange={(value) => value && setLogState(value)} />

package/docs/generated/components/features--ai-chat.md

@@ -15,7 +15,6 @@ A conversational surface streams assistant messages, tool calls, artifacts and a
 
 ```tsx fragment — import-only example
 import { AiAgent } from "themelia-ui/features/ai-chat"
-import "themelia-ui/features/ai-chat.css"
 ```
 
 ## Composition
@@ -814,7 +813,7 @@ waiting on. It paints through `background-clip`, so its colour is transparent by
 contrast probe reading `color` alone will call it a 1:1 failure.
 
 ```text
-({ children, paused, duration, className, }: AiShimmerProps) => import("react").JSX.Element
+({ children, paused, duration, size, className, }: AiShimmerProps) => import("react").JSX.Element
 ```
 
 ### `AiShimmerProps`
@@ -826,6 +825,7 @@ Kind: interface.
 | `children` | no | `ReactNode` | Defaults to the "Thinking…" placeholder. |
 | `paused` | no | `boolean` | Renders the text still, in the muted foreground. |
 | `duration` | no | `number` | Sweep duration, in seconds. |
+| `size` | no | `TextProps["size"]` | Step on the type scale, as on `Text`. Unset, the provider's default size. |
 | `className` | no | `string` |  |
 
 ### `AiSourceItem`
@@ -895,7 +895,7 @@ One task of an agent's plan, with its status and its sub-tasks. A task reports w
 done, not merely that something is.
 
 ```text
-({ task, density, indent, className, strings, }: AiTaskProps) => import("react").JSX.Element
+({ task, defaultExpanded, indent, className, strings, }: AiTaskProps) => import("react").JSX.Element
 ```
 
 ### `AiTaskItem`
@@ -919,8 +919,8 @@ Kind: interface.
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
 | `task` | yes | `AiTaskItem` |  |
-| `density` | no | `"compact" \| "expanded"` | `compact` collapses the sub-tasks behind a toggle; `expanded` always shows them. |
-| `indent` | no | `number` | Indent per nesting level, as a multiple of `--space-xl`. |
+| `defaultExpanded` | no | `boolean` | Opens every level of sub-tasks at first. Off, only the top level starts open and the rest<br>sit behind their toggles. @default false |
+| `indent` | no | `number` | Indent per nesting level, as a multiple of `--padding`. |
 | `className` | no | `string` |  |
 | `strings` | no | `Partial<Strings.AiTaskStrings>` |  |
 
@@ -1249,7 +1249,7 @@ export default function Chat() {
 						status: streaming ? "working" : "idle",
 					}}
 					headerActions={
-						<Button type="button" tone="neutral" buttonStyle="ghost" onClick={() => note("settings")}>
+						<Button type="button" tone="neutral" appearance="ghost" onClick={() => note("settings")}>
 							Settings
 						</Button>
 					}
@@ -1294,7 +1294,7 @@ export default function Turn() {
 
 	return (
 		<>
-			<Stack gap="lg">
+			<Stack>
 				<AiMessageBubble
 					role="user"
 					authorName="You"
@@ -1357,7 +1357,7 @@ const CHAIN = [
 
 export default function Thinking() {
 	return (
-		<Stack gap="lg">
+		<Stack>
 			<AiReasoning durationSeconds={4}>
 				The totals are summed as floats. 0.1 + 0.2 is 0.30000000000000004, and rounding
 				each line before summing compounds the error across a long invoice.
@@ -1366,7 +1366,7 @@ export default function Thinking() {
 				Checking whether the backfill needs to run per tenant…
 			</AiReasoning>
 			<AiChainOfThought steps={CHAIN} streaming />
-			<AiTask task={PLAN} density="expanded" />
+			<AiTask task={PLAN} defaultExpanded />
 		</Stack>
 	)
 }
@@ -1382,7 +1382,7 @@ import { AiToolCall } from "themelia-ui/features/ai-chat"
 
 export default function Tools() {
 	return (
-		<Stack gap="md">
+		<Stack gap="sm">
 			<AiToolCall name="read_file" status="pending" />
 			<AiToolCall
 				name="search_codebase"
@@ -1432,7 +1432,7 @@ export default function Output() {
 
 	return (
 		<>
-			<Stack gap="lg">
+			<Stack>
 				<AiArtifact
 					title="totals.ts"
 					subtitle="TypeScript · 11 lines"
@@ -1453,7 +1453,7 @@ export default function Output() {
 				<AiSources sources={SOURCES} defaultExpanded />
 				<AiSources sources={SOURCES} variant="avatars" />
 
-				<Stack direction="horizontal" gap="md" wrap>
+				<Stack direction="horizontal" gap="sm" wrap>
 					{attachments.map((attachment) => (
 						<AiAttachment
 							key={attachment.id}
@@ -1497,7 +1497,7 @@ export default function Approval() {
 	const [approval, setApproval] = useState<"pending" | "approved" | "rejected">("pending")
 
 	return (
-		<Stack gap="lg">
+		<Stack>
 			<AiConfirmation
 				title="Run the backfill on 4,102 invoices"
 				description="Rewrites every stored amount into cents. There is no undo."
@@ -1507,8 +1507,8 @@ export default function Approval() {
 				onReject={() => setApproval("rejected")}
 			/>
 			{approval !== "pending" && (
-				<Stack direction="horizontal" gap="md">
-					<Button type="button" tone="neutral" buttonStyle="outline" onClick={() => setApproval("pending")}>
+				<Stack direction="horizontal" gap="sm">
+					<Button type="button" tone="neutral" appearance="outline" onClick={() => setApproval("pending")}>
 						Ask again
 					</Button>
 				</Stack>