@moldable-ai/ui 0.2.19 → 0.2.21

package/src/components/ui/panel.md

@@ -0,0 +1,11 @@
+# Panel
+
+Semantic app panes with fixed chrome and independently scrolling content.
+
+`PanelGroup` lays out panes horizontally or vertically. `Panel` owns the
+surface; `PanelHeader`, `PanelContent`, and `PanelFooter` define its regions.
+Use `surface="sidebar"` for source/navigation panes and reserve `Card` for
+bounded content groups inside a pane.
+
+The group and its containing shell need a definite height. Long content belongs
+in `PanelContent`, and chat-safe padding belongs on that scrolling region.

package/src/components/ui/popover.md

@@ -0,0 +1,31 @@
+# Popover
+
+Use `Popover` for a small, interactive surface anchored to a control. Use
+`Tooltip` for terse non-interactive help, `HoverCard` for a preview, and
+`Dialog` for a blocking task.
+
+```tsx
+<Popover>
+  <PopoverTrigger asChild>
+    <Button variant="outline">View options</Button>
+  </PopoverTrigger>
+  <PopoverContent size="sm" material="regular">
+    <PopoverHeader>
+      <PopoverTitle>View options</PopoverTitle>
+      <PopoverDescription>Choose what appears in the list.</PopoverDescription>
+    </PopoverHeader>
+    {/* interactive controls */}
+  </PopoverContent>
+</Popover>
+```
+
+Sizes are `content`, `sm`, `default`, and `lg`. Content is capped to the
+collision-aware available width and height and scrolls when necessary.
+`material="regular"` is the standard temporary overlay. Use `clear` only above
+media or a richly colored canvas where the stronger sampled effect has a clear
+layering purpose.
+
+`PopoverClose`, `PopoverPortal`, and `PopoverArrow` are available when the
+composition needs them. Provide an accessible name on an icon-only close
+action. Keep required instructions and critical actions discoverable without
+hover.

package/src/components/ui/resizable.md

@@ -0,0 +1,66 @@
+# Resizable
+
+## Purpose
+
+The resizable primitives create user-adjustable panes for technical and object-heavy workspaces. Use them when two or more views need to stay visible, such as navigation/editor/inspector or query/results.
+
+Use a stable flex split when resizing does not materially help. Use `Sidebar` for application navigation that needs collapse and narrow-screen sheet behavior.
+
+## Usage patterns
+
+```tsx
+import {
+  ResizableHandle,
+  ResizablePanel,
+  ResizablePanelGroup,
+} from '@moldable-ai/ui'
+
+;<ResizablePanelGroup orientation="horizontal" className="h-full min-h-0">
+  <ResizablePanel defaultSize="24%" minSize="14%">
+    <nav className="h-full min-h-0 overflow-y-auto pb-[calc(var(--chat-safe-padding,0px)+1rem)]">
+      {/* Object browser */}
+    </nav>
+  </ResizablePanel>
+  <ResizableHandle withHandle />
+  <ResizablePanel minSize="35%">
+    <section className="h-full min-h-0 overflow-hidden">
+      {/* Workspace */}
+    </section>
+  </ResizablePanel>
+</ResizablePanelGroup>
+```
+
+Use `orientation="vertical"` for editor/results splits. Each panel should establish its own overflow behavior; the panel group itself should remain bounded by a full-height parent.
+
+## 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` 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.
+
+Refer to the installed `react-resizable-panels` version for precise size units and imperative ref APIs; keep all panels on the same convention.
+
+## Do
+
+- Give the group and all ancestors a stable `h-full min-h-0`.
+- Set sensible default and minimum sizes based on the content’s real scan width.
+- Use `withHandle` when a one-pixel divider would be difficult to discover.
+- Keep each pane’s toolbar fixed and its content intentionally scrollable.
+- Preserve keyboard focus indication on separators.
+- Collapse or replace secondary panes at narrow widths when necessary.
+
+## Don't
+
+- Do not make every surface resizable.
+- Do not allow a pane to shrink until labels, editors, or controls become unusable.
+- Do not put document scrolling on the panel group or `body`.
+- Do not animate pane size for decoration.
+- Do not assume resizable desktop panes automatically become a good narrow layout.
+
+## Moldable considerations
+
+Resizable layouts are the default fit for database, code, file, debugging, and inspector-style apps. Keep pane toolbars around `h-8` or `h-9`, use mono text for code/data, and avoid nested card shells.
+
+Every independently scrolling pane that reaches the bottom needs its own `--chat-safe-padding`. A bottom control dock may require additional space beyond the standard pane padding. When selection changes in any pane, keep the other panes, app commands, and desktop chat context synchronized.

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

@@ -0,0 +1,72 @@
+# Scroll Area
+
+## Purpose
+
+`ScrollArea` provides a styled vertical scrollbar while preserving a native-feeling scroll viewport. Use it for bounded lists, object browsers, menus, and panes where consistent scrollbar appearance is useful.
+
+For simple content, a native `overflow-y-auto` region is often sufficient. The important design decision is which pane scrolls, not whether every pane uses a custom scrollbar.
+
+## Usage patterns
+
+```tsx
+import { ScrollArea } from '@moldable-ai/ui'
+
+;<ScrollArea className="h-full min-h-0" safeBottom>
+  <div className="px-3 pt-3">{/* Long list */}</div>
+</ScrollArea>
+```
+
+For a grouped list:
+
+```tsx
+<ScrollArea className="h-full px-5 pt-3">
+  <div className="mx-auto w-full max-w-[44rem] space-y-8 pb-[calc(var(--chat-safe-padding,0px)+6rem)]">
+    {/* Groups */}
+  </div>
+</ScrollArea>
+```
+
+The current `ScrollArea` composition installs a vertical scrollbar by default.
+Set `scrollbars` to `horizontal`, `both`, or `none` for another explicit
+configuration.
+
+## API summary
+
+- `ScrollArea`: Radix Scroll Area root with a full-size viewport, vertical `ScrollBar`, and corner.
+- 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.
+- The root’s direct children are rendered inside the viewport.
+- The viewport supplies focus-visible outline and ring treatment.
+
+## Do
+
+- Give the scroll area a definite height through its own class and full-height ancestors.
+- Put padding on an inner content wrapper when it should scroll with the content.
+- Add `min-h-0` to flex or grid ancestors.
+- Enable `safeBottom` on every owning scroll region that reaches the webview bottom.
+- Keep sticky headers inside the same scrolling context as their content.
+- Test keyboard, wheel, trackpad, and scrollbar-thumb interaction.
+
+## Don't
+
+- Do not rely on document/body scrolling for a full Moldable app.
+- Do not nest scroll areas unless each axis or pane has a clear purpose.
+- Do not put fixed controls inside the moving content when they must remain reachable.
+- Do not hide focus outlines.
+- Do not assume padding on a sibling pane protects this viewport from desktop chat.
+- Do not add `ScrollBar` as a child of `ScrollArea`; children belong to its
+  viewport. Use the `scrollbars` prop.
+
+## Moldable considerations
+
+Choose padding based on the surface:
+
+- General full-view content: `pb-[calc(var(--chat-safe-padding,0px)+6rem)]`
+- Long document/editor content: `pb-[calc(var(--chat-safe-padding,0px)+8rem)]`
+- Tables and inspectors: `pb-[var(--chat-safe-padding,0px)]`
+- Side panes and object browsers: `pb-[calc(var(--chat-safe-padding,0px)+1rem)]`
+
+Increase it when a fixed action dock also occupies the bottom. Empty, error, and loading states rendered in a scroll area need the same clearance as normal content.

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

@@ -0,0 +1,33 @@
+# Search Field
+
+## Purpose
+
+`SearchField` is a native search input with consistent icon, density, loading, clear, invalid, disabled, and focus states. It supports controlled and uncontrolled values without replacing browser text-entry behavior.
+
+## Usage
+
+```tsx
+import { SearchField } from '@moldable-ai/ui'
+
+;<SearchField
+  aria-label="Search projects"
+  value={query}
+  onValueChange={setQuery}
+  placeholder="Search projects"
+  density="compact"
+  loading={isSearching}
+/>
+```
+
+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`.
+
+## Quality bar
+
+- Provide a visible label or an accessible `aria-label`.
+- Keep placeholder text short; it is a hint, not the field’s name.
+- Debounce network-backed filtering outside the component and use `loading` while results update.
+- Keep keyboard focus in the field after clearing.
+- Announce result counts or no-results changes in the results region when that feedback matters.
+- Do not add a second clear button, bind Escape to close a parent view while the field contains text, or replace native editing shortcuts.
+
+Search fields in narrow toolbars should use compact density and a useful minimum width. A global app or command search may be surfaced by the host, but local collection filtering remains app-owned.

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

@@ -0,0 +1,36 @@
+# Segmented Control
+
+## Purpose
+
+`SegmentedControl` switches between a small set of mutually exclusive modes. It uses radio-group semantics, so one option is selected and arrow keys move selection without requiring custom keyboard code.
+
+Use it for choices such as list/grid, week/month, or preview/edit. Use `Tabs` when each option labels a corresponding content panel, and use `RadioGroup` for form choices that need longer supporting text.
+
+## Usage
+
+```tsx
+import { SegmentedControl, SegmentedControlItem } from '@moldable-ai/ui'
+
+;<SegmentedControl
+  aria-label="Calendar view"
+  value={view}
+  onValueChange={setView}
+  density="compact"
+>
+  <SegmentedControlItem value="week">Week</SegmentedControlItem>
+  <SegmentedControlItem value="month">Month</SegmentedControlItem>
+</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.
+
+## Quality bar
+
+- Keep two to five literal, parallel labels in one group.
+- Give the group an `aria-label` or `aria-labelledby`.
+- Keep icon-only items exceptional. When used, set `iconOnly` and give every item an `aria-label`.
+- Let the radio-group implementation own focus, arrow-key movement, and selected semantics.
+- Use `fullWidth` only when equal-width choices improve scanning in a narrow pane.
+- Do not use a segmented control for commands, independent toggles, or navigation between unrelated destinations.
+
+In a standalone app window, keep compact segments in a title toolbar or near the content they change. Do not imitate host window controls or place app actions inside a host-owned control inset.

package/src/components/ui/sheet.md

@@ -0,0 +1,30 @@
+# Sheet
+
+`Sheet` presents a secondary region from an edge while preserving the current
+workspace. It is appropriate for narrow-window navigation, filters, or an
+inspector that cannot remain beside the canvas.
+
+```tsx
+<Sheet>
+  <SheetTrigger asChild>
+    <Button variant="outline">Filters</Button>
+  </SheetTrigger>
+  <SheetContent side="right" size="default">
+    <SheetHeader>
+      <SheetTitle>Filters</SheetTitle>
+      <SheetDescription>Limit the visible results.</SheetDescription>
+    </SheetHeader>
+    <SheetBody>{/* scrolling controls */}</SheetBody>
+    <SheetFooter>{/* persistent actions */}</SheetFooter>
+  </SheetContent>
+</Sheet>
+```
+
+Side sheets support `sm`, `default`, and `lg`. All sides respect host window
+insets; their bottom edge also clears the embedded chat safe area. `SheetBody`
+is the only flexing scroll owner, leaving its header, close action, and footer
+reachable.
+
+Use `Dialog` when the task is centered and blocking, `Drawer` for touch-first
+presentation, and `Inspector` when contextual properties should remain visible
+beside the canvas. Do not use a sheet as permanent desktop navigation.

package/src/components/ui/sidebar.md

@@ -0,0 +1,113 @@
+# Sidebar
+
+## Purpose
+
+The sidebar primitives build persistent app navigation or an object browser that can collapse on desktop and become a sheet on narrow screens. Use them when users need to switch repeatedly among sections, collections, or saved objects while keeping a working surface visible.
+
+Do not add a sidebar to a focused single-workflow app. A list-to-detail layout may need only a stable list pane, while technical workspaces may be better served by `ResizablePanelGroup`.
+
+## Usage patterns
+
+```tsx
+import { Inbox } from 'lucide-react'
+import {
+  Sidebar,
+  SidebarContent,
+  SidebarGroup,
+  SidebarGroupContent,
+  SidebarGroupLabel,
+  SidebarInset,
+  SidebarMenu,
+  SidebarMenuButton,
+  SidebarMenuItem,
+  SidebarProvider,
+  SidebarTrigger,
+} from '@moldable-ai/ui'
+
+;<SidebarProvider className="h-full min-h-0">
+  <Sidebar collapsible="icon">
+    <SidebarContent className="pb-[calc(var(--chat-safe-padding,0px)+1rem)]">
+      <SidebarGroup>
+        <SidebarGroupLabel>Mailboxes</SidebarGroupLabel>
+        <SidebarGroupContent>
+          <SidebarMenu>
+            <SidebarMenuItem>
+              <SidebarMenuButton
+                isActive
+                tooltip="Inbox"
+                className="cursor-pointer"
+              >
+                <Inbox />
+                <span>Inbox</span>
+              </SidebarMenuButton>
+            </SidebarMenuItem>
+          </SidebarMenu>
+        </SidebarGroupContent>
+      </SidebarGroup>
+    </SidebarContent>
+  </Sidebar>
+  <SidebarInset className="h-full min-h-0 overflow-hidden">
+    <header className="border-border/70 flex h-9 shrink-0 items-center border-b px-2">
+      <SidebarTrigger className="cursor-pointer" />
+    </header>
+    {/* Main pane */}
+  </SidebarInset>
+</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.
+
+## API summary
+
+### State and shell
+
+- `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"`.
+- `SidebarInset`: main content surface paired with the sidebar.
+- `SidebarTrigger`: compact toggle button.
+- `SidebarRail`: pointer target along the sidebar edge.
+
+### Structure
+
+- `SidebarHeader`, `SidebarFooter`, `SidebarContent`, and `SidebarSeparator` divide the vertical shell.
+- `SidebarInput` is a compact search/filter input.
+- `SidebarGroup`, `SidebarGroupLabel`, `SidebarGroupAction`, and `SidebarGroupContent` organize sections.
+
+### Menus
+
+- `SidebarMenu` and `SidebarMenuItem` provide list structure.
+- `SidebarMenuButton`: `isActive`, `variant="default" | "outline"`, `size="default" | "sm" | "lg"`, optional `asChild`, and `tooltip`.
+- `SidebarMenuAction`: optional `asChild` and `showOnHover`.
+- `SidebarMenuBadge`: compact trailing count.
+- `SidebarMenuSkeleton`: optional `showIcon`.
+- `SidebarMenuSub`, `SidebarMenuSubItem`, and `SidebarMenuSubButton`: one nested level; sub-button size is `sm` or `md`.
+
+The provider persists expanded state in the `sidebar_state` cookie and handles Command/Ctrl+B. Collapsed-menu tooltips are built into `SidebarMenuButton` when `tooltip` is provided.
+
+## Do
+
+- Put the provider around both sidebar and inset.
+- Use one clear active item and update it with navigation state.
+- Add tooltips to icon-collapsible menu buttons.
+- Give group and menu actions accessible names; make hover actions visible on focus.
+- Keep labels in a truncatable span and counts/actions in stable trailing positions.
+- Use `SidebarContent` as the intentional scrolling region.
+- Test expanded, collapsed, off-canvas, and narrow-sheet states.
+
+## Don't
+
+- Do not restate the app name as a large sidebar or content heading.
+- Do not add more than one meaningful nesting level.
+- Do not use the sidebar as a dumping ground for every command.
+- Do not place the only access to an action in a hover-only control.
+- Do not assume desktop width is always available inside a webview pane.
+- Do not add an app-local chat or assistant section.
+
+## Moldable considerations
+
+Override the shell for the embedded full-height environment with `h-full min-h-0` and keep the main inset `overflow-hidden`. Add chat-safe bottom padding to `SidebarContent`, because object browsers and navigation lists can extend behind desktop chat independently of the main pane.
+
+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.

package/src/components/ui/sonner.md

@@ -0,0 +1,37 @@
+# Toasts
+
+Mount one `Toaster` near the app root and call the shared `toast` API from
+actions, mutations, and background work.
+
+```tsx
+import { Toaster, toast } from '@moldable-ai/ui'
+
+function App() {
+  return (
+    <>
+      <Workspace />
+      <Toaster position="bottom-center" />
+    </>
+  )
+}
+
+async function save() {
+  await toast.promise(saveDocument(), {
+    loading: 'Saving…',
+    success: 'Saved',
+    error: 'Could not save',
+  })
+}
+```
+
+## Recipes
+
+- Use a success toast only when the result is not already obvious in the
+  canvas.
+- Keep loading, success, and error text stable for a single promise.
+- Put undo in the toast action for reversible destructive work.
+- Use an alert or inline field message when the user must resolve the problem
+  before continuing.
+- Keep one `Toaster` per app window. A host shell must not absorb app-owned
+  notifications.
+- Toast text must describe the result, not expose transport or server details.

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

@@ -0,0 +1,15 @@
+# SplitView
+
+Semantic naming over resizable panel primitives.
+
+```tsx
+<SplitView orientation="horizontal">
+  <SplitViewPane defaultSize="30%">…</SplitViewPane>
+  <SplitViewHandle />
+  <SplitViewPane>…</SplitViewPane>
+</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.

package/src/components/ui/status.md

@@ -0,0 +1,12 @@
+# Status
+
+Compact dot-and-label feedback for state.
+
+```tsx
+<Status variant="running" animated>Recording</Status>
+<Status variant="success">Synced</Status>
+```
+
+Use `running` or `pending` animation only for active work. Use `Badge` for
+categories and labels. Keep a text label when the meaning is important; color
+alone is insufficient.

package/src/components/ui/table.md

@@ -0,0 +1,37 @@
+# Table
+
+Structured, comparable data with shared density and row-selection behavior.
+
+```tsx
+<Table density="compact">
+  <TableHeader>
+    <TableRow>
+      <TableHead>Name</TableHead>
+      <TableHead>Status</TableHead>
+    </TableRow>
+  </TableHeader>
+  <TableBody>
+    {rows.map((row) => (
+      <TableRow
+        key={row.id}
+        selected={selection.has(row.id)}
+        onSelectionChange={(selected) => updateSelection(row.id, selected)}
+      >
+        <TableCell>{row.name}</TableCell>
+        <TableCell>{row.status}</TableCell>
+      </TableRow>
+    ))}
+  </TableBody>
+</Table>
+```
+
+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.

package/src/components/ui/tabs.md

@@ -0,0 +1,66 @@
+# Tabs
+
+## Purpose
+
+Tabs switch between peer views of the same object or workspace without changing the overall context. Use them for compact modes such as Notes/Transcript, Query/Results, or Details/Activity.
+
+Use navigation when each destination is a distinct location. Use `ToggleGroup` for display controls that do not own tab panels.
+
+## Usage patterns
+
+```tsx
+import { Tabs, TabsContent, TabsList, TabsTrigger } from '@moldable-ai/ui'
+
+;<Tabs defaultValue="notes" className="h-full min-h-0">
+  <TabsList aria-label="Meeting view">
+    <TabsTrigger value="notes">Notes</TabsTrigger>
+    <TabsTrigger value="transcript">Transcript</TabsTrigger>
+  </TabsList>
+  <TabsContent value="notes" className="min-h-0 overflow-y-auto">
+    {/* Notes */}
+  </TabsContent>
+  <TabsContent value="transcript" className="min-h-0 overflow-y-auto">
+    {/* Transcript */}
+  </TabsContent>
+</Tabs>
+```
+
+Use the `line` variant in dense app chrome where a filled segmented control would be too prominent:
+
+```tsx
+<TabsList variant="line">
+  <TabsTrigger value="schema">Schema</TabsTrigger>
+  <TabsTrigger value="data">Data</TabsTrigger>
+</TabsList>
+```
+
+## API summary
+
+- `Tabs`: Radix Tabs root; supports controlled `value`/`onValueChange`, `defaultValue`, `orientation`, activation direction, 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`.
+- `tabsListVariants` is exported for compatible composition.
+- Components accept the corresponding Radix primitive props and `className`.
+
+## Do
+
+- Use short, parallel labels.
+- Keep the number of tabs small enough to fit without ambiguous truncation.
+- Use controlled state when the active tab affects URL state, commands, or desktop chat context.
+- Put scrolling on the active content pane with `min-h-0`, not on the whole app.
+- Preserve keyboard navigation and focus states supplied by Radix.
+
+## Don't
+
+- Do not use tabs as a substitute for primary navigation or a command toolbar.
+- Do not mix actions such as “Add” or “Refresh” into the tab list.
+- Do not put unrelated workflows behind peer tabs.
+- Do not change tab labels or order unpredictably.
+- Do not rely on a subtle color change alone; retain the active background or line indicator.
+
+## Moldable considerations
+
+Tabs belong in compact chrome, not a large page header. In document and paneled layouts, keep their bar around `h-8` or `h-9`. When a tab panel scrolls to the bottom of the webview, add `pb-[calc(var(--chat-safe-padding,0px)+1rem)]` or the larger padding appropriate to an editor or dock.
+
+Changing tabs should update app commands and chat instructions when it materially changes the active object or mode. Do not create an “AI chat” tab; Moldable’s desktop chat is the conversational surface.

package/src/components/ui/text.md

@@ -0,0 +1,17 @@
+# Text
+
+Semantic typography for app content and chrome.
+
+## Usage
+
+```tsx
+<Text as="h1" variant="heading1">Library</Text>
+<Text variant="small" color="secondary">12 local items</Text>
+```
+
+Use the `as` prop for correct HTML semantics and `variant` for visual hierarchy.
+`truncate` is appropriate only when the full value remains available through
+context or a tooltip. Use mono variants for identifiers, code, and numeric
+readouts—not body copy.
+
+Do not recreate the type scale with arbitrary font sizes.

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

@@ -0,0 +1,48 @@
+# ToggleButton
+
+`ToggleButton` is a single pressed/unpressed action. It is a semantic facade
+over `Toggle`, so both share one Radix interaction model and one style source.
+
+```tsx
+<ToggleButton pressed={showGrid} onPressedChange={setShowGrid}>
+  Show grid
+</ToggleButton>
+```
+
+For an icon-only toggle, opt in explicitly and provide its accessible name:
+
+```tsx
+<ToggleButton
+  iconOnly
+  aria-label="Pin inspector"
+  pressed={pinned}
+  onPressedChange={setPinned}
+>
+  <PinIcon />
+</ToggleButton>
+```
+
+## Variants and sizes
+
+- `variant`: `default`, `outline`, or `filled`.
+- `size`: `xs`, `sm`, `default`, or `lg`.
+- `iconOnly` makes the control square and requires `aria-label`.
+
+## Choosing the right control
+
+- Use `Button` for a momentary action.
+- Use `ToggleButton` for one independent visible mode or tool.
+- Use `SegmentedControl` for exactly one choice from a small set.
+- Use `Switch` for a persistent setting that takes effect immediately.
+
+## Keyboard and accessibility
+
+Radix supplies button and `aria-pressed` semantics. Space and Enter toggle the
+state. A visible text label or `aria-label` must identify the action; state
+must not be communicated through color alone.
+
+## Don't
+
+- Do not use a toggle for a one-time command.
+- Do not group unrelated toggles into a segmented control.
+- Do not put a checkbox inside a toggle button.