@moldable-ai/ui 0.2.26 → 0.2.31

package/src/components/ui/progress.md

@@ -0,0 +1,31 @@
+# Progress
+
+`Progress` shows determinate completion for an operation. The current visual
+track expects `value` to be a percentage from `0` to `100`.
+
+```tsx
+import { Progress } from '@moldable-ai/ui'
+
+;<div>
+  <p id="sync-progress">Syncing changes: {percent}%</p>
+  <Progress aria-labelledby="sync-progress" value={percent} />
+</div>
+```
+
+## API
+
+- `Progress` accepts the Radix progress root props and `className`.
+- `value` controls the indicator transform; omitted or zero values render an
+  empty track.
+- The track and indicator use the shared primary color tokens.
+
+## Quality and accessibility
+
+- Clamp the supplied percentage to `0–100`.
+- Give the progress bar an accessible name with `aria-label` or
+  `aria-labelledby`.
+- Include the exact percentage in nearby text when users need it announced or
+  compared.
+- Use `Spinner` when duration or completion cannot be estimated.
+- Remove the progress bar or replace it with a clear completion state when the
+  operation finishes.

package/src/components/ui/radio-group.md

@@ -0,0 +1,36 @@
+# Radio Group
+
+`RadioGroup` lets a user choose one value from a visible set of mutually
+exclusive options.
+
+```tsx
+import { Label, RadioGroup, RadioGroupItem } from '@moldable-ai/ui'
+
+;<RadioGroup defaultValue="normal" aria-label="Priority">
+  <div className="flex items-center gap-2">
+    <RadioGroupItem id="priority-normal" value="normal" />
+    <Label htmlFor="priority-normal">Normal</Label>
+  </div>
+  <div className="flex items-center gap-2">
+    <RadioGroupItem id="priority-high" value="high" />
+    <Label htmlFor="priority-high">High</Label>
+  </div>
+</RadioGroup>
+```
+
+## API
+
+- `RadioGroup` exposes the Radix root props, including controlled `value` and
+  `onValueChange`, uncontrolled `defaultValue`, `name`, `required`, and
+  `disabled`.
+- `RadioGroupItem` requires a unique `value` and exposes the Radix item props.
+- The root lays options out as a grid; use `className` to change the layout.
+
+## Quality and accessibility
+
+- Give the group a visible label, `aria-label`, or `aria-labelledby`.
+- Connect every item to a concise text label with matching `id` and `htmlFor`.
+- Use a stable default only when one option is genuinely preferred.
+- Show validation in text and apply `aria-invalid` when the choice is invalid.
+- Use `Checkbox` for independent choices and `ToggleGroup` for compact view
+  modes rather than form options.

package/src/components/ui/resizable.md

@@ -35,7 +35,8 @@ Use `orientation="vertical"` for editor/results splits. Each panel should establ
 ## API summary
 
 - `ResizablePanelGroup`: wraps `react-resizable-panels` `Group`; `orientation` is `"horizontal"` or `"vertical"` and defaults upstream to horizontal.
-- `ResizablePanel`: wraps `Panel` and accepts its sizing, collapse, callback, id, and ref props.
+- `ResizablePanel`: wraps the upstream `Panel` and accepts its sizing,
+  collapse, callback, id, `elementRef`, and imperative `panelRef` props.
 - `ResizablePanel` also accepts `groupResizeBehavior` for compatibility, but the current wrapper intentionally does not forward or act on it.
 - `ResizableHandle`: wraps `Separator`; `withHandle` adds a visible grip.
 - All parts accept `className` where supported by their underlying primitive.

package/src/components/ui/scroll-area.md

@@ -32,12 +32,14 @@ configuration.
 
 ## API summary
 
-- `ScrollArea`: Radix Scroll Area root with a full-size viewport, vertical `ScrollBar`, and corner.
+- `ScrollArea`: Radix Scroll Area root with a full-size viewport and the
+  scrollbar configuration selected by `scrollbars`.
 - Accepts Radix root props, forwarded `ref`, and `className`.
 - `scrollbars`: `vertical`, `horizontal`, `both`, or `none`.
 - `viewportClassName`: styles the actual scrolling viewport.
 - `safeBottom`: adds the shared chat-safe padding to the viewport exactly once.
 - `ScrollBar`: exported scrollbar primitive with `orientation="vertical" | "horizontal"`; defaults to vertical.
+- A corner is rendered only when both scrollbars are enabled.
 - The root’s direct children are rendered inside the viewport.
 - The viewport supplies focus-visible outline and ring treatment.
 

package/src/components/ui/search-field.md

@@ -19,7 +19,12 @@ import { SearchField } from '@moldable-ai/ui'
 />
 ```
 
-Use `value`/`onValueChange` for a controlled field or `defaultValue` for an uncontrolled field. `variant` is `default` or `filled`; `density` is `compact`, `default`, or `comfortable`. `clearable` defaults to true. Escape and the clear action empty a non-empty field, refocus it, and call `onClear`.
+Use `value`/`onValueChange` for a controlled field or `defaultValue` for an
+uncontrolled field. `variant` is `default` or `filled`; `density` is `compact`,
+`default`, or `comfortable`. `controlSize` accepts `mini`, `small`, `medium`,
+`large`, or `xl` and overrides the size token derived from density. `clearable`
+defaults to true. Escape and the clear action empty a non-empty field, refocus
+it, and call `onClear`.
 
 ## Quality bar
 

package/src/components/ui/segmented-control.md

@@ -22,7 +22,12 @@ import { SegmentedControl, SegmentedControlItem } from '@moldable-ai/ui'
 </SegmentedControl>
 ```
 
-The root supports controlled `value`/`onValueChange` and uncontrolled `defaultValue`. `variant` is `muted` or `outline`; `density` is `compact`, `default`, or `comfortable`; `fullWidth` lets each item share the available width.
+The root supports controlled `value`/`onValueChange` and uncontrolled
+`defaultValue`. `variant` is `muted` or `outline`; `density` is `compact`,
+`default`, or `comfortable`; and `orientation` defaults to `horizontal`.
+`controlSize` accepts `mini`, `small`, `medium`, `large`, or `xl` and overrides
+the size token derived from density. `fullWidth` lets each item share the
+available width.
 
 ## Quality bar
 

package/src/components/ui/separator.md

@@ -0,0 +1,35 @@
+# Separator
+
+`Separator` draws a semantic-token divider between related regions. It is
+decorative by default.
+
+```tsx
+import { Separator } from '@moldable-ai/ui'
+
+;<section>
+  <h2>Workspace</h2>
+  <Separator className="my-3" />
+  <div className="flex h-8 items-center gap-3">
+    <span>Local</span>
+    <Separator orientation="vertical" />
+    <span>Synced</span>
+  </div>
+</section>
+```
+
+## API
+
+- `orientation` is `horizontal` by default and also accepts `vertical`.
+- `decorative` defaults to `true`. Set `decorative={false}` when the divider
+  represents a meaningful structural boundary.
+- Other Radix separator props and `className` pass through.
+
+## Quality and accessibility
+
+- Prefer spacing alone when a line does not clarify grouping.
+- Keep decorative separators out of the accessibility tree with the default
+  behavior.
+- Use a non-decorative separator sparingly; headings and landmarks usually
+  communicate structure more clearly.
+- Give a vertical separator a parent with an explicit height because it uses
+  the full available height.

package/src/components/ui/sidebar.md

@@ -55,7 +55,9 @@ import {
 </SidebarProvider>
 ```
 
-Keep each menu item’s icon and last text span direct children of `SidebarMenuButton`; the component uses that shape for icon sizing and text truncation.
+Keep each menu item’s icon and last text span direct children of
+`SidebarMenuButton`; the component uses that shape for icon sizing, active
+icon tint, and text truncation.
 
 ## API summary
 
@@ -63,7 +65,7 @@ Keep each menu item’s icon and last text span direct children of `SidebarMenuB
 
 - `SidebarProvider`: required context. Supports uncontrolled `defaultOpen`, controlled `open`/`onOpenChange`, and CSS variable overrides through `style`.
 - `useSidebar()`: returns `state`, `open`, `setOpen`, `openMobile`, `setOpenMobile`, `isMobile`, and `toggleSidebar`.
-- `Sidebar`: `side="left" | "right"`, `variant="sidebar" | "floating" | "inset"`, and `collapsible="offcanvas" | "icon" | "none"`.
+- `Sidebar`: `side="left" | "right"`, `variant="sidebar" | "floating" | "inset"`, `sidebarStyle="platform" | "floating" | "edge-to-edge"`, and `collapsible="offcanvas" | "icon" | "none"`.
 - `SidebarInset`: main content surface paired with the sidebar.
 - `SidebarTrigger`: compact toggle button.
 - `SidebarRail`: pointer target along the sidebar edge.
@@ -77,7 +79,7 @@ Keep each menu item’s icon and last text span direct children of `SidebarMenuB
 ### Menus
 
 - `SidebarMenu` and `SidebarMenuItem` provide list structure.
-- `SidebarMenuButton`: `isActive`, `variant="default" | "outline"`, `size="default" | "sm" | "lg"`, optional `asChild`, and `tooltip`.
+- `SidebarMenuButton`: `isActive`, `variant="default" | "outline"`, `size="default" | "sm" | "lg"`, optional `asChild`, and `tooltip`. Active state applies the semantic selection fill and foreground to its direct icon and text.
 - `SidebarMenuAction`: optional `asChild` and `showOnHover`.
 - `SidebarMenuBadge`: compact trailing count.
 - `SidebarMenuSkeleton`: optional `showIcon`.
@@ -111,3 +113,18 @@ Override the shell for the embedded full-height environment with `h-full min-h-0
 The built-in Command/Ctrl+B shortcut must not conflict with editor-local bold formatting or another essential command in the same context. If it does, control sidebar state elsewhere or revisit the shortcut at the package level.
 
 Use semantic `sidebar-*` tokens already provided by the component. In an object browser, post the active connection, collection, or selected object to desktop chat instructions and expose frequent switches through app commands.
+
+### Sidebar style selection
+
+Choose the visual anatomy independently from the application's base platform:
+
+- `edge-to-edge` is the default.
+- `floating` uses the macOS inset, material-backed shell and forces the
+  component's resolved variant to `floating`.
+- `edge-to-edge` uses the macOS joined window/sidebar anatomy and forces the
+  resolved variant to `sidebar`.
+  It has no independent fill, blur, shadow, or internal divider and reveals
+  the app/window background beneath it.
+- `platform` follows the selected platform pack and preserves the existing `variant` behavior.
+
+Set `sidebarStyle` on `ThemeProvider` for the whole application, or on an individual `Sidebar` for a local override. Apps and components must use these semantic names and the stable `--m-ui-sidebar-*` roles rather than importing versioned source values.

package/src/components/ui/skeleton.md

@@ -0,0 +1,36 @@
+# Skeleton
+
+## Purpose
+
+`Skeleton` is a neutral, pulsing placeholder for content whose shape is known
+while its data is loading. Size it to approximate the final content so the
+layout remains stable.
+
+## Usage
+
+```tsx
+import { Skeleton } from '@moldable-ai/ui'
+
+;<div role="status" aria-busy="true">
+  <span className="sr-only">Loading project</span>
+  <Skeleton className="h-5 w-40" />
+  <Skeleton className="mt-3 h-20 w-full" />
+</div>
+```
+
+## API
+
+- Accepts native `div` props and `className`.
+- Uses the semantic accent surface, the shared control radius, and a pulse
+  animation by default.
+- Has no size or visual variants; set dimensions and layout with `className`.
+- Exports `Skeleton`.
+
+## Guidance
+
+- Match the number and approximate dimensions of the content being replaced.
+- Put loading semantics and concise screen-reader status text on the containing
+  region.
+- Keep skeletons non-interactive and remove them when the content resolves.
+- Do not add a separate accessible name to every placeholder or use skeletons
+  for errors and empty states.

package/src/components/ui/slider.md

@@ -0,0 +1,58 @@
+# Slider
+
+## Purpose
+
+`Slider` selects one value or a bounded range along a horizontal or vertical
+track. Use it when relative adjustment is more useful than exact text entry.
+
+## Usage
+
+```tsx
+import { Slider } from '@moldable-ai/ui'
+
+;<Slider
+  defaultValue={[50]}
+  min={0}
+  max={100}
+  step={5}
+  thumbAriaLabels={['Volume']}
+/>
+```
+
+For a range, provide two values and a name for each thumb:
+
+```tsx
+<Slider
+  value={[minimum, maximum]}
+  onValueChange={([nextMinimum, nextMaximum]) => {
+    setMinimum(nextMinimum)
+    setMaximum(nextMaximum)
+  }}
+  thumbAriaLabels={['Minimum price', 'Maximum price']}
+/>
+```
+
+## API
+
+- Accepts Radix Slider root props, including `value`, `defaultValue`,
+  `onValueChange`, `min`, `max`, `step`, `orientation`, and `disabled`.
+- `min` defaults to `0`; `max` defaults to `100`.
+- The number of rendered thumbs follows the length of `value` or
+  `defaultValue`. If both are omitted, the component still renders two thumb
+  elements, so pass an explicit value array.
+- `thumbAriaLabels` assigns accessible names to thumbs in value order and is
+  required for a range.
+- `rangeContent` renders inside the filled range; `thumbContent` renders inside
+  every thumb.
+- Exports `Slider`.
+
+## Guidance
+
+- Pass an explicit one-element `value` or `defaultValue` for a single-value
+  slider and two elements for a range.
+- Show the current numeric value nearby when precision matters; pair the slider
+  with a number field when direct entry is important.
+- Give every thumb an accessible name, keep range labels distinct, and preserve
+  the supplied keyboard and focus behavior.
+- Do not use a slider for a small set of named choices; use a radio or segmented
+  control instead.

package/src/components/ui/spinner.md

@@ -0,0 +1,41 @@
+# Spinner
+
+## Purpose
+
+`Spinner` communicates indeterminate work when progress cannot be measured. It
+renders a compact rotating loading icon with status semantics.
+
+## Usage
+
+```tsx
+import { Spinner } from '@moldable-ai/ui'
+
+;<Spinner aria-label="Loading results" />
+```
+
+When visible text already announces the state, hide the duplicate icon from
+assistive technology:
+
+```tsx
+<div className="flex items-center gap-2" role="status">
+  <Spinner aria-hidden="true" />
+  Loading results…
+</div>
+```
+
+## API
+
+- Accepts native SVG props and `className`.
+- Defaults to `role="status"` and `aria-label="Loading"`; either may be
+  overridden by passed props.
+- Defaults to `size-4`, spins continuously, and disables the animation when the
+  user prefers reduced motion.
+- Exports `Spinner`.
+
+## Guidance
+
+- Use a specific accessible label when the spinner is the only status content.
+- Use `aria-hidden="true"` when adjacent status text already conveys the same
+  information.
+- Keep surrounding content stable while work is in progress.
+- Use `Progress` instead when a meaningful completion percentage is available.

package/src/components/ui/split-view.md

@@ -1,6 +1,6 @@
 # SplitView
 
-Semantic naming over resizable panel primitives.
+`SplitView` composes the resizable panel primitives with pane-oriented names.
 
 ```tsx
 <SplitView orientation="horizontal">
@@ -10,6 +10,10 @@ Semantic naming over resizable panel primitives.
 </SplitView>
 ```
 
-Use when pane resizing is part of the workflow. Provide sensible minimum and
-default sizes, preserve important content, and persist sizes only when that
-improves repeated work. Use `PanelGroup` for non-resizable layouts.
+`orientation` defaults to `horizontal`. `SplitViewPane` accepts the underlying
+panel sizing and collapse props. `SplitViewHandle` accepts separator props and
+adds an optional visible grip with `withHandle`.
+
+Use it when pane resizing is part of the workflow. Provide sensible minimum
+and default sizes, keep a handle between every adjacent pane, and preserve
+important content. Use ordinary flex or grid for a non-resizable layout.

package/src/components/ui/switch.md

@@ -0,0 +1,44 @@
+# Switch
+
+## Purpose
+
+`Switch` changes a boolean setting that takes effect as soon as it is toggled.
+Use it for preferences such as notifications, syncing, or visibility.
+
+## Usage
+
+```tsx
+import { Label, Switch } from '@moldable-ai/ui'
+
+;<div className="flex items-center justify-between gap-3">
+  <Label htmlFor="sync-changes">Sync changes</Label>
+  <Switch
+    id="sync-changes"
+    checked={syncChanges}
+    onCheckedChange={setSyncChanges}
+  />
+</div>
+```
+
+## API
+
+- Accepts Radix Switch root props, including `checked`, `defaultChecked`,
+  `onCheckedChange`, `disabled`, `required`, `name`, and `value`.
+- `size` is `default` or `sm` and defaults to `default`.
+- `controlSize` accepts the shared `ControlSize` values (`mini`, `small`,
+  `medium`, `large`, or `xl`) and overrides the size-derived token setting.
+- Without `controlSize`, `size="sm"` resolves to `small`; the default resolves
+  to `medium`.
+- Supports checked, unchecked, active, focus-visible, and disabled states.
+- Exports `Switch`.
+
+## Guidance
+
+- Pair the switch with a visible `Label` using `htmlFor` and `id`, or provide an
+  `aria-label` when no visible label is possible.
+- Use controlled state when the value is persisted or shared with another
+  surface.
+- Write labels for the setting itself, such as “Sync changes,” rather than
+  “Enable” or “On.”
+- Use a checkbox for selections submitted as a group and a button for one-shot
+  actions.

package/src/components/ui/table.md

@@ -28,10 +28,10 @@ Structured, comparable data with shared density and row-selection behavior.
 Use `compact` for inspector-like datasets, `default` for general work, and
 `comfortable` where scanning matters more than density.
 
-When a row is selectable, selection is controlled by the caller and can be
-toggled with pointer, Enter, or Space. Independent buttons, links, form
-controls, and editable descendants keep their own pointer and keyboard
-behavior without toggling the containing row. Call `event.preventDefault()` in
-a row event handler only when an app needs to cancel the built-in row response.
-For rich grid navigation, column sorting, or cell editing, use a dedicated data
-grid rather than layering those interactions onto a basic table.
+Pass `selected` and `onSelectionChange` together for a selectable row; either
+prop alone marks the row as selectable. Selection is controlled by the caller
+and toggles with pointer, Enter, or Space. Independent buttons, links, form
+controls, and editable descendants keep their own behavior without toggling
+the row. Call `event.preventDefault()` in a row event handler only when an app
+needs to cancel the built-in response. For rich grid navigation, column
+sorting, or cell editing, use a dedicated data grid.

package/src/components/ui/tabs.md

@@ -36,7 +36,9 @@ Use the `line` variant in dense app chrome where a filled segmented control woul
 
 ## API summary
 
-- `Tabs`: Radix Tabs root; supports controlled `value`/`onValueChange`, `defaultValue`, `orientation`, activation direction, and other root props. Orientation defaults to `horizontal`.
+- `Tabs`: Radix Tabs root; supports controlled `value`/`onValueChange`,
+  `defaultValue`, `orientation`, text direction, activation mode, and other root
+  props. Orientation defaults to `horizontal`.
 - `TabsList`: `variant="default"` or `"line"`. Defaults to `default`.
 - `TabsTrigger`: requires a `value` matching a content panel; supports `disabled`.
 - `TabsContent`: requires a matching `value`.

package/src/components/ui/textarea.md

@@ -0,0 +1,41 @@
+# Textarea
+
+## Purpose
+
+`Textarea` is a native multiline text field for notes, descriptions, comments,
+and other freeform input.
+
+## Usage
+
+```tsx
+import { Label, Textarea } from '@moldable-ai/ui'
+
+;<div className="grid gap-2">
+  <Label htmlFor="description">Description</Label>
+  <Textarea
+    id="description"
+    name="description"
+    placeholder="Describe this project"
+    maxLength={500}
+  />
+</div>
+```
+
+## API
+
+- Accepts native `textarea` props, event handlers, and `className`.
+- Supports controlled `value`/`onChange` and uncontrolled `defaultValue`.
+- Uses content-based field sizing with a minimum height of `4rem`.
+- Includes placeholder, focus-visible, disabled, and `aria-invalid` styling.
+- Exports `Textarea`.
+
+## Guidance
+
+- Always provide a visible label; use `aria-describedby` for help or validation
+  text.
+- Set `aria-invalid="true"` only when an error is present, and associate the
+  error message with the field.
+- Add `maxLength` and a visible character count when input length is constrained.
+- Preserve the native keyboard, selection, form, and resize behavior.
+- Use `Input` for a single line and a rich-text editor only when formatting is
+  genuinely required.

package/src/components/ui/toggle-group.md

@@ -51,8 +51,8 @@ Multiple selection:
 
 - `ToggleGroup`: Radix Toggle Group root. `type="single"` uses a string value; `type="multiple"` uses a string array.
 - Supports controlled `value`/`onValueChange` and uncontrolled `defaultValue`.
-- `variant`: `default` or `outline`, shared with each item.
-- `size`: `default`, `sm`, or `lg`, shared with each item.
+- `variant`: `default`, `outline`, or `filled`, shared with each item.
+- `size`: `xs`, `sm`, `default`, or `lg`, shared with each item.
 - `spacing`: numeric Tailwind spacing multiplier; defaults to `0`. At zero, items join into one segmented shape.
 - `ToggleGroupItem`: requires `value`; may override `variant` or `size` when the group does not supply them.
 - Both parts accept corresponding Radix primitive props and `className`.

package/src/components/ui/toggle.md

@@ -9,8 +9,8 @@ Use `Button` for a one-shot command and `Switch` for a settings-style boolean th
 ## Usage patterns
 
 ```tsx
-import { WrapText } from 'lucide-react'
-import { Toggle } from '@moldable-ai/ui'
+import { Pin, WrapText } from 'lucide-react'
+import { Toggle, ToggleButton } from '@moldable-ai/ui'
 
 ;<Toggle
   pressed={wrap}
@@ -24,18 +24,18 @@ import { Toggle } from '@moldable-ai/ui'
 </Toggle>
 ```
 
-For an icon-only toolbar control:
+For an icon-only toolbar control, use the typed `ToggleButton` facade:
 
 ```tsx
-<Toggle
+<ToggleButton
+  iconOnly
   defaultPressed
   variant="outline"
   size="sm"
-  className="cursor-pointer px-0"
   aria-label="Pin inspector"
 >
   <Pin />
-</Toggle>
+</ToggleButton>
 ```
 
 Pair icon-only use with a tooltip.
@@ -45,8 +45,8 @@ Pair icon-only use with a tooltip.
 - Built on Radix Toggle and accepts its root props.
 - `pressed` and `onPressedChange`: controlled state.
 - `defaultPressed`: uncontrolled initial state.
-- `variant`: `default` or `outline`.
-- `size`: `default`, `sm`, or `lg`.
+- `variant`: `default`, `outline`, or `filled`.
+- `size`: `xs`, `sm`, `default`, or `lg`.
 - Supports native button accessibility props such as `aria-label` and `disabled`.
 - `toggleVariants` is exported and shared by `ToggleGroup`.
 
@@ -54,7 +54,7 @@ Pair icon-only use with a tooltip.
 
 - Use controlled state when the preference affects another pane or persisted setting.
 - Make the pressed state legible through shape or icon treatment as well as color.
-- Add `cursor-pointer`, an accessible name, and a tooltip for icon-only toggles.
+- Give icon-only toggles an accessible name and a tooltip.
 - Keep toolbar toggles compact and aligned with adjacent controls.
 - Use a specific icon tied to the state.
 

package/src/components/ui/toolbar-controls.md

@@ -0,0 +1,83 @@
+# Toolbar controls
+
+Precomposed controls for native-window-aware `Toolbar` chrome. They use
+Moldable semantic tokens, density, menus, and accessibility behavior while
+keeping app toolbars visually consistent.
+
+```tsx
+<Toolbar position="top">
+  <ToolbarControlGroup aria-label="Navigation">
+    <ToolbarSidebarToggle
+      expanded={sidebarOpen}
+      onExpandedChange={setSidebarOpen}
+    />
+    <ToolbarControlSeparator />
+    <ToolbarBackButton onClick={goBack} />
+  </ToolbarControlGroup>
+  <ToolbarTitleField value={title} onChange={rename} />
+  <ToolbarActions>
+    <ToolbarControlGroup aria-label="History">
+      <ToolbarIconButton label="Undo" onClick={undo}>
+        <Undo2 />
+      </ToolbarIconButton>
+      <ToolbarControlSeparator />
+      <ToolbarIconButton label="Redo" onClick={redo}>
+        <Redo2 />
+      </ToolbarIconButton>
+    </ToolbarControlGroup>
+    <ToolbarOverflowMenu
+      items={[
+        { id: 'history', label: 'Version history' },
+        { id: 'export', label: 'Export' },
+      ]}
+      onSelectItem={handleMoreAction}
+    />
+    <ToolbarButton variant="prominent">Present</ToolbarButton>
+  </ToolbarActions>
+</Toolbar>
+```
+
+## Components
+
+- `ToolbarButton` — text or mixed-content action. Defaults to 36px native
+  chrome; use `variant="prominent"` for the one primary action.
+- `ToolbarIconButton` — required accessible label and optional tooltip.
+- `ToolbarBackButton` — single chevron Back affordance for root-to-detail
+  navigation.
+- `ToolbarSidebarToggle` — controlled sidebar visibility button with accurate
+  pressed state and dynamic label.
+- `ToolbarOverflowMenu` — an ellipsis button backed by Moldable's declarative
+  menu API, including the native host menu when available.
+- `ToolbarControlGroup` — a shared surface for closely related actions such as
+  Undo/Redo. It defaults to `size="xl"`, supports `size="medium"`, and makes
+  children compact quiet controls.
+- `ToolbarControlSeparator` — divider within a related action group.
+- `ToolbarTitleField` — an accessible, inline-editable contextual title.
+
+`ToolbarButton` and `ToolbarIconButton` accept `appearance="quiet"` when a
+standalone action should not have raised chrome. The default `chrome`
+appearance uses the `toolbar` Button variant. `ToolbarControlGroup` also
+accepts `appearance="quiet"` when related controls should not share a raised
+surface. Raised controls use these semantic tokens:
+
+- `--toolbar-control-background`
+- `--toolbar-control-hover`
+- `--toolbar-control-pressed`
+- `--toolbar-control-border`
+- `--toolbar-control-shadow`
+
+The tokens adapt to light/dark appearance, increased contrast, and reduced
+transparency.
+
+## Composition rules
+
+- Keep the current document or view title leading and the primary action last.
+- Use fully rounded standalone controls and shared pill surfaces for related
+  controls. Avoid drawing a separate rounded rectangle around every icon.
+- Prefer icon-only secondary controls and a text-only primary action.
+- Put only genuinely related commands in `ToolbarControlGroup`.
+- Move low-frequency commands such as history, duplicate, export, and delete
+  into `ToolbarOverflowMenu`.
+- Keep roughly five or six visible actions. Tooltips do not replace accessible
+  labels.
+- Use the shared Back and Sidebar controls instead of hand-building arrows.