@adea-ai/ui 0.97.7 → 0.99.0

package/dist/r/src/components/composites/action-button/action-button.tsx

@@ -27,6 +27,7 @@ import { Tooltip, TooltipContent, TooltipTrigger } from '../../ui/tooltip'
 export type ActionButtonProps<T extends ValidComponent = 'button'> = ButtonProps<T> & {
   /** A short explanation, also shown on keyboard focus. The Button still needs its own name. */
   tooltip?: string
+  /** Placement of the explanation; icon actions live in bars, so it defaults below the control. */
   tooltipSide?: 'top' | 'right' | 'bottom' | 'left'
   /** Disables the action and announces the busy label through a polite status region. */
   busy?: boolean
@@ -173,7 +174,7 @@ export function ActionButton<T extends ValidComponent = 'button'>(props: ActionB
           >
             {contents()}
           </TooltipTrigger>
-          <TooltipContent side={local.tooltipSide}>{local.tooltip}</TooltipContent>
+          <TooltipContent side={local.tooltipSide ?? 'bottom'}>{local.tooltip}</TooltipContent>
         </Tooltip>
       </Show>
       <Show when={busy()}>

package/dist/r/src/components/layout/side-rail/side-rail.tsx

@@ -2,6 +2,7 @@ import { Polymorphic, type PolymorphicProps } from '@kobalte/core/polymorphic'
 import type { ComponentProps, JSX, ValidComponent } from 'solid-js'
 import { Show, createMemo, createSignal, splitProps } from 'solid-js'
 import { Portal } from 'solid-js/web'
+import { tooltipTip } from '../../../lib/overlay'
 import { cn } from '../../../lib/utils'
 import { SideRailContext, createSideRailValue } from './side-rail-context'
 
@@ -305,8 +306,8 @@ export function SideRailItem<T extends ValidComponent = 'a'>(props: SideRailItem
               aria-hidden="true"
               data-slot="side-rail-tip"
               class={cn(
-                'bg-card text-card-foreground border-border pointer-events-none fixed z-(--z-tooltip)',
-                'flex items-center gap-2.5 rounded-md border ps-3 pe-3 text-sm font-medium whitespace-nowrap shadow-lg'
+                tooltipTip,
+                'pointer-events-none fixed z-(--z-tooltip) flex items-center gap-2.5 ps-3 pe-3 whitespace-nowrap'
               )}
               style={{
                 top: `${position().top}px`,
@@ -398,7 +399,10 @@ export function SideRailButton(
             <div
               aria-hidden="true"
               data-slot="side-rail-tip"
-              class="bg-card text-card-foreground border-border pointer-events-none fixed z-(--z-tooltip) flex items-center gap-2.5 rounded-md border ps-3 pe-3 text-sm font-medium whitespace-nowrap shadow-lg"
+              class={cn(
+                tooltipTip,
+                'pointer-events-none fixed z-(--z-tooltip) flex items-center gap-2.5 ps-3 pe-3 whitespace-nowrap'
+              )}
               style={{
                 top: `${position().top}px`,
                 left: `${position().left}px`,

package/dist/r/src/components/layout/split-layout/split-layout.tsx

@@ -171,7 +171,8 @@ export function SplitLayout<L extends SplitLayoutLeaf>(props: SplitLayoutProps<L
       role="group"
       aria-label={props.label}
       data-slot="split-layout"
-      class={cn('relative size-full min-h-0 min-w-0', props.class)}
+      data-dragging={drag() ? '' : undefined}
+      class={cn('relative size-full min-h-0 min-w-0 data-[dragging]:cursor-grabbing', props.class)}
     >
       <For each={leaves().map((leaf) => leaf.id)}>
         {(id) => {
@@ -194,6 +195,7 @@ export function SplitLayout<L extends SplitLayoutLeaf>(props: SplitLayoutProps<L
               tabIndex={props.paneTabIndex ?? -1}
               data-pane-id={id}
               data-focused={props.state.focusedLeafId === id ? '' : undefined}
+              data-drag-source={drag()?.id === id ? '' : undefined}
               data-drop-direction={intent()?.direction}
               data-drop-placement={intent()?.placement}
               onDragOver={(event) => {
@@ -234,14 +236,16 @@ export function SplitLayout<L extends SplitLayoutLeaf>(props: SplitLayoutProps<L
                 props.onMove?.(current.id, id, next)
               }}
               style={rectStyle(frames().get(id)?.rect ?? { x: 0, y: 0, width: 0, height: 0 })}
-              class="absolute flex min-h-0 min-w-0 flex-col overflow-hidden border border-border data-[focused]:border-primary bg-background text-foreground focus-visible:outline focus-visible:outline-2 focus-visible:outline-ring"
+              class="absolute flex min-h-0 min-w-0 flex-col overflow-hidden border border-border transition-opacity data-[drag-source]:opacity-40 data-[focused]:border-primary bg-background text-foreground focus-visible:outline focus-visible:outline-2 focus-visible:outline-ring"
               onFocusIn={() => props.onFocus?.(id)}
             >
               <header class="flex min-w-0 shrink-0 items-center gap-2 bg-surface px-2">
                 <span
                   data-pane-drag-handle=""
                   draggable={Boolean(props.onMove)}
-                  class="flex min-w-0 flex-1 items-center gap-2 truncate text-sm"
+                  class={cn('flex min-w-0 flex-1 items-center gap-2 truncate text-sm', {
+                    'cursor-grab': Boolean(props.onMove),
+                  })}
                   title={props.onMove ? `Drag ${props.labelForLeaf(leaf())} to move` : undefined}
                   onDragStart={(event) => {
                     if (!props.onMove || !event.dataTransfer) {
@@ -252,6 +256,18 @@ export function SplitLayout<L extends SplitLayoutLeaf>(props: SplitLayoutProps<L
                     setDrag({ id, token })
                     event.dataTransfer.setData(PANE_DRAG_TYPE, token)
                     event.dataTransfer.effectAllowed = 'move'
+                    // The ghost is the pane itself, not the handle strip: the
+                    // browser snapshots the region before the drag state dims
+                    // this section, so the dragged pane stays readable while
+                    // its source visibly recedes.
+                    const source = refs.get(id)
+                    const frame = source?.getBoundingClientRect()
+                    if (source && frame && typeof event.dataTransfer.setDragImage === 'function')
+                      event.dataTransfer.setDragImage(
+                        source,
+                        Math.max(0, Math.round(event.clientX - frame.left)),
+                        Math.max(0, Math.round(event.clientY - frame.top))
+                      )
                   }}
                   onDragEnd={clearDrag}
                 >

package/dist/r/src/components/layout/top-bar/top-bar.tsx

@@ -125,6 +125,13 @@ export type TopBarSearchProps = ComponentProps<'button'> & {
   placeholder?: string
   /** The shortcut chip drawn at the trailing edge, e.g. "⌘K". */
   shortcut?: string
+  /**
+   * The parseable chord behind `shortcut`, e.g. `Meta+K`. The chip is
+   * `aria-hidden` — reading it out would pollute the button's accessible
+   * name — so this is what assistive technology announces instead. Supply it
+   * whenever `shortcut` is drawn.
+   */
+  keyshortcuts?: string
 }
 
 /**
@@ -137,7 +144,7 @@ export type TopBarSearchProps = ComponentProps<'button'> & {
  * like from the user's side.
  */
 export function TopBarSearch(props: TopBarSearchProps) {
-  const [local, rest] = splitProps(props, ['class', 'placeholder', 'shortcut'])
+  const [local, rest] = splitProps(props, ['class', 'placeholder', 'shortcut', 'keyshortcuts'])
 
   return (
     <button
@@ -151,12 +158,16 @@ export function TopBarSearch(props: TopBarSearchProps) {
         'window-no-drag',
         local.class
       )}
+      aria-keyshortcuts={local.keyshortcuts}
       {...rest}
     >
       <Search aria-hidden="true" class="size-4 shrink-0 sm:hidden" />
       <span class="sr-only sm:not-sr-only sm:truncate">{local.placeholder ?? 'Search'}</span>
       <Show when={local.shortcut}>
-        <kbd class="bg-muted ms-auto hidden h-5 shrink-0 items-center rounded-sm border border-border px-1.5 font-mono text-2xs sm:flex">
+        <kbd
+          aria-hidden="true"
+          class="bg-muted ms-auto hidden h-5 shrink-0 items-center rounded-sm border border-border px-1.5 font-mono text-2xs sm:flex"
+        >
           {local.shortcut}
         </kbd>
       </Show>

package/dist/r/src/components/ui/kbd/kbd.tsx

@@ -20,8 +20,6 @@ export function Kbd(props: ComponentProps<'kbd'>) {
       data-slot="kbd"
       class={cn(
         'bg-muted text-muted-foreground pointer-events-none inline-flex h-5 min-w-5 items-center justify-center gap-1 rounded-sm border border-border px-1 font-mono text-2xs font-medium select-none',
-        /* Inside a hover/selected row the key needs to recede with the row. */
-        'in-data-[slot=br-tooltip-content]:bg-background/20 in-data-[slot=br-tooltip-content]:text-scrim-foreground in-data-[slot=br-tooltip-content]:border-transparent',
         local.class
       )}
       {...rest}

package/dist/r/src/components/ui/status-chip/status-chip.tsx

@@ -99,9 +99,7 @@ export function StatusChip(props: StatusChipProps) {
           <TooltipTrigger as="span" class="inline-flex">
             {chip}
           </TooltipTrigger>
-          <TooltipContent data-slot="tooltip-content" hideArrow>
-            {detail()}
-          </TooltipContent>
+          <TooltipContent data-slot="tooltip-content">{detail()}</TooltipContent>
         </Tooltip>
       )}
     </Show>

package/dist/r/src/components/ui/tooltip/tooltip.tsx

@@ -10,6 +10,7 @@ import {
   useContext,
 } from 'solid-js'
 import { isServer } from 'solid-js/web'
+import { tooltipTip } from '../../../lib/overlay'
 import { cn } from '../../../lib/utils'
 
 /**
@@ -348,16 +349,12 @@ export function TooltipTrigger(props: ComponentProps<typeof KobalteTooltip.Trigg
   )
 }
 
-export type TooltipContentProps = ComponentProps<typeof KobalteTooltip.Content> & {
-  /** Hide the caret pointing at the trigger. */
-  hideArrow?: boolean
-}
+export type TooltipContentProps = ComponentProps<typeof KobalteTooltip.Content>
 
 export function TooltipContent(props: TooltipContentProps) {
   const interaction = useContext(TooltipInteractionContext)
   const [local, rest] = splitProps(props, [
     'class',
-    'hideArrow',
     'children',
     'aria-hidden',
     'onEscapeKeyDown',
@@ -371,7 +368,11 @@ export function TooltipContent(props: TooltipContentProps) {
     <KobalteTooltip.Portal>
       <KobalteTooltip.Content
         class={cn(
-          'bg-scrim text-scrim-foreground z-(--z-tooltip) w-fit max-w-64 rounded-md px-2 py-1 text-xs',
+          tooltipTip,
+          // The max width is a token, not a fixed measure: it has to fall
+          // behind the viewport at large root font sizes or the tip — which
+          // Kobalte can shift but never shrink — forces a horizontal scroll.
+          'z-(--z-tooltip) w-fit max-w-(--tooltip-max-width) px-2 py-1',
           'origin-(--kb-tooltip-content-transform-origin) text-balance',
           'data-expanded:animate-in data-expanded:fade-in-0 data-expanded:zoom-in-95',
           'data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95',
@@ -390,7 +391,6 @@ export function TooltipContent(props: TooltipContentProps) {
         {...rest}
       >
         {local.children}
-        {!local.hideArrow && <KobalteTooltip.Arrow aria-hidden="true" />}
       </KobalteTooltip.Content>
     </KobalteTooltip.Portal>
   )

package/dist/r/src/lib/overlay.ts

@@ -21,6 +21,15 @@ export const overlayPositioner = 'fixed inset-0 z-(--z-dialog) grid place-items-
 export const overlayScrim =
   'fixed inset-0 z-(--z-dialog) bg-scrim/50 supports-[backdrop-filter]:backdrop-blur-xs'
 
+/**
+ * The tip: the card-toned bubble an explanation shows in. The side rail draws
+ * it flush to a collapsed row and every floating tooltip composes the same
+ * fill, edge, and type, so a control never explains itself in two visual
+ * languages.
+ */
+export const tooltipTip =
+  'bg-card text-card-foreground rounded-md border border-border text-sm font-medium shadow-lg'
+
 /**
  * Entrance and exit motion, expressed as data-state classes.
  *

package/dist/r/src/lib/tokens.ts

@@ -542,6 +542,12 @@ export const densityTokens: TokenDefinition[] = [
   },
   { name: 'topbar-height', kind: 'dimension', description: '48px — the window title row.' },
   { name: 'statusbar-height', kind: 'dimension', description: '28px — the bottom readout strip.' },
+  {
+    name: 'tooltip-max-width',
+    kind: 'dimension',
+    description:
+      'The lesser of the 16rem readable measure and one viewport minus a gutter — a tip wraps before it can push its document wider than itself.',
+  },
 ]
 
 export const elevationTokens: TokenDefinition[] = [

package/dist/r/src/styles/theme.css

@@ -614,6 +614,11 @@
   --sidebar-width-compact: 3rem;
   --topbar-height: 3rem;
   --statusbar-height: 1.75rem;
+  /* A tip wraps before it can overflow the window carrying it: the 16rem
+     readable measure governs on a desktop, but the measure scales with the root
+     font while the window does not, so at a 200% zoom the viewport term wins and
+     a tooltip can never push its document wider than itself. */
+  --tooltip-max-width: min(16rem, calc(100vw - 1.5rem));
 
   /* Shadows. Two parts on purpose: a tinted spread that reads as elevation, plus a
      hairline that keeps an edge visible when the surface behind a panel is the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adea-ai/ui",
-  "version": "0.97.7",
+  "version": "0.99.0",
   "description": "The Adea design system: Kobalte-backed Solid components, semantic OKLCH tokens, and the app-shell layout primitives shared by Adea and Cortana.",
   "keywords": [
     "adea",

package/src/components/composites/action-button/action-button.tsx

@@ -27,6 +27,7 @@ import { Tooltip, TooltipContent, TooltipTrigger } from '../../ui/tooltip'
 export type ActionButtonProps<T extends ValidComponent = 'button'> = ButtonProps<T> & {
   /** A short explanation, also shown on keyboard focus. The Button still needs its own name. */
   tooltip?: string
+  /** Placement of the explanation; icon actions live in bars, so it defaults below the control. */
   tooltipSide?: 'top' | 'right' | 'bottom' | 'left'
   /** Disables the action and announces the busy label through a polite status region. */
   busy?: boolean
@@ -173,7 +174,7 @@ export function ActionButton<T extends ValidComponent = 'button'>(props: ActionB
           >
             {contents()}
           </TooltipTrigger>
-          <TooltipContent side={local.tooltipSide}>{local.tooltip}</TooltipContent>
+          <TooltipContent side={local.tooltipSide ?? 'bottom'}>{local.tooltip}</TooltipContent>
         </Tooltip>
       </Show>
       <Show when={busy()}>

package/src/components/layout/side-rail/side-rail.tsx

@@ -2,6 +2,7 @@ import { Polymorphic, type PolymorphicProps } from '@kobalte/core/polymorphic'
 import type { ComponentProps, JSX, ValidComponent } from 'solid-js'
 import { Show, createMemo, createSignal, splitProps } from 'solid-js'
 import { Portal } from 'solid-js/web'
+import { tooltipTip } from '#lib/overlay'
 import { cn } from '#lib/utils'
 import { SideRailContext, createSideRailValue } from './side-rail-context'
 
@@ -305,8 +306,8 @@ export function SideRailItem<T extends ValidComponent = 'a'>(props: SideRailItem
               aria-hidden="true"
               data-slot="side-rail-tip"
               class={cn(
-                'bg-card text-card-foreground border-border pointer-events-none fixed z-(--z-tooltip)',
-                'flex items-center gap-2.5 rounded-md border ps-3 pe-3 text-sm font-medium whitespace-nowrap shadow-lg'
+                tooltipTip,
+                'pointer-events-none fixed z-(--z-tooltip) flex items-center gap-2.5 ps-3 pe-3 whitespace-nowrap'
               )}
               style={{
                 top: `${position().top}px`,
@@ -398,7 +399,10 @@ export function SideRailButton(
             <div
               aria-hidden="true"
               data-slot="side-rail-tip"
-              class="bg-card text-card-foreground border-border pointer-events-none fixed z-(--z-tooltip) flex items-center gap-2.5 rounded-md border ps-3 pe-3 text-sm font-medium whitespace-nowrap shadow-lg"
+              class={cn(
+                tooltipTip,
+                'pointer-events-none fixed z-(--z-tooltip) flex items-center gap-2.5 ps-3 pe-3 whitespace-nowrap'
+              )}
               style={{
                 top: `${position().top}px`,
                 left: `${position().left}px`,

package/src/components/layout/split-layout/split-layout.tsx

@@ -171,7 +171,8 @@ export function SplitLayout<L extends SplitLayoutLeaf>(props: SplitLayoutProps<L
       role="group"
       aria-label={props.label}
       data-slot="split-layout"
-      class={cn('relative size-full min-h-0 min-w-0', props.class)}
+      data-dragging={drag() ? '' : undefined}
+      class={cn('relative size-full min-h-0 min-w-0 data-[dragging]:cursor-grabbing', props.class)}
     >
       <For each={leaves().map((leaf) => leaf.id)}>
         {(id) => {
@@ -194,6 +195,7 @@ export function SplitLayout<L extends SplitLayoutLeaf>(props: SplitLayoutProps<L
               tabIndex={props.paneTabIndex ?? -1}
               data-pane-id={id}
               data-focused={props.state.focusedLeafId === id ? '' : undefined}
+              data-drag-source={drag()?.id === id ? '' : undefined}
               data-drop-direction={intent()?.direction}
               data-drop-placement={intent()?.placement}
               onDragOver={(event) => {
@@ -234,14 +236,16 @@ export function SplitLayout<L extends SplitLayoutLeaf>(props: SplitLayoutProps<L
                 props.onMove?.(current.id, id, next)
               }}
               style={rectStyle(frames().get(id)?.rect ?? { x: 0, y: 0, width: 0, height: 0 })}
-              class="absolute flex min-h-0 min-w-0 flex-col overflow-hidden border border-border data-[focused]:border-primary bg-background text-foreground focus-visible:outline focus-visible:outline-2 focus-visible:outline-ring"
+              class="absolute flex min-h-0 min-w-0 flex-col overflow-hidden border border-border transition-opacity data-[drag-source]:opacity-40 data-[focused]:border-primary bg-background text-foreground focus-visible:outline focus-visible:outline-2 focus-visible:outline-ring"
               onFocusIn={() => props.onFocus?.(id)}
             >
               <header class="flex min-w-0 shrink-0 items-center gap-2 bg-surface px-2">
                 <span
                   data-pane-drag-handle=""
                   draggable={Boolean(props.onMove)}
-                  class="flex min-w-0 flex-1 items-center gap-2 truncate text-sm"
+                  class={cn('flex min-w-0 flex-1 items-center gap-2 truncate text-sm', {
+                    'cursor-grab': Boolean(props.onMove),
+                  })}
                   title={props.onMove ? `Drag ${props.labelForLeaf(leaf())} to move` : undefined}
                   onDragStart={(event) => {
                     if (!props.onMove || !event.dataTransfer) {
@@ -252,6 +256,18 @@ export function SplitLayout<L extends SplitLayoutLeaf>(props: SplitLayoutProps<L
                     setDrag({ id, token })
                     event.dataTransfer.setData(PANE_DRAG_TYPE, token)
                     event.dataTransfer.effectAllowed = 'move'
+                    // The ghost is the pane itself, not the handle strip: the
+                    // browser snapshots the region before the drag state dims
+                    // this section, so the dragged pane stays readable while
+                    // its source visibly recedes.
+                    const source = refs.get(id)
+                    const frame = source?.getBoundingClientRect()
+                    if (source && frame && typeof event.dataTransfer.setDragImage === 'function')
+                      event.dataTransfer.setDragImage(
+                        source,
+                        Math.max(0, Math.round(event.clientX - frame.left)),
+                        Math.max(0, Math.round(event.clientY - frame.top))
+                      )
                   }}
                   onDragEnd={clearDrag}
                 >

package/src/components/layout/top-bar/top-bar.tsx

@@ -125,6 +125,13 @@ export type TopBarSearchProps = ComponentProps<'button'> & {
   placeholder?: string
   /** The shortcut chip drawn at the trailing edge, e.g. "⌘K". */
   shortcut?: string
+  /**
+   * The parseable chord behind `shortcut`, e.g. `Meta+K`. The chip is
+   * `aria-hidden` — reading it out would pollute the button's accessible
+   * name — so this is what assistive technology announces instead. Supply it
+   * whenever `shortcut` is drawn.
+   */
+  keyshortcuts?: string
 }
 
 /**
@@ -137,7 +144,7 @@ export type TopBarSearchProps = ComponentProps<'button'> & {
  * like from the user's side.
  */
 export function TopBarSearch(props: TopBarSearchProps) {
-  const [local, rest] = splitProps(props, ['class', 'placeholder', 'shortcut'])
+  const [local, rest] = splitProps(props, ['class', 'placeholder', 'shortcut', 'keyshortcuts'])
 
   return (
     <button
@@ -151,12 +158,16 @@ export function TopBarSearch(props: TopBarSearchProps) {
         'window-no-drag',
         local.class
       )}
+      aria-keyshortcuts={local.keyshortcuts}
       {...rest}
     >
       <Search aria-hidden="true" class="size-4 shrink-0 sm:hidden" />
       <span class="sr-only sm:not-sr-only sm:truncate">{local.placeholder ?? 'Search'}</span>
       <Show when={local.shortcut}>
-        <kbd class="bg-muted ms-auto hidden h-5 shrink-0 items-center rounded-sm border border-border px-1.5 font-mono text-2xs sm:flex">
+        <kbd
+          aria-hidden="true"
+          class="bg-muted ms-auto hidden h-5 shrink-0 items-center rounded-sm border border-border px-1.5 font-mono text-2xs sm:flex"
+        >
           {local.shortcut}
         </kbd>
       </Show>

package/src/components/ui/kbd/kbd.tsx

@@ -20,8 +20,6 @@ export function Kbd(props: ComponentProps<'kbd'>) {
       data-slot="kbd"
       class={cn(
         'bg-muted text-muted-foreground pointer-events-none inline-flex h-5 min-w-5 items-center justify-center gap-1 rounded-sm border border-border px-1 font-mono text-2xs font-medium select-none',
-        /* Inside a hover/selected row the key needs to recede with the row. */
-        'in-data-[slot=br-tooltip-content]:bg-background/20 in-data-[slot=br-tooltip-content]:text-scrim-foreground in-data-[slot=br-tooltip-content]:border-transparent',
         local.class
       )}
       {...rest}

package/src/components/ui/status-chip/status-chip.tsx

@@ -99,9 +99,7 @@ export function StatusChip(props: StatusChipProps) {
           <TooltipTrigger as="span" class="inline-flex">
             {chip}
           </TooltipTrigger>
-          <TooltipContent data-slot="tooltip-content" hideArrow>
-            {detail()}
-          </TooltipContent>
+          <TooltipContent data-slot="tooltip-content">{detail()}</TooltipContent>
         </Tooltip>
       )}
     </Show>

package/src/components/ui/tooltip/tooltip.tsx

@@ -10,6 +10,7 @@ import {
   useContext,
 } from 'solid-js'
 import { isServer } from 'solid-js/web'
+import { tooltipTip } from '#lib/overlay'
 import { cn } from '#lib/utils'
 
 /**
@@ -348,16 +349,12 @@ export function TooltipTrigger(props: ComponentProps<typeof KobalteTooltip.Trigg
   )
 }
 
-export type TooltipContentProps = ComponentProps<typeof KobalteTooltip.Content> & {
-  /** Hide the caret pointing at the trigger. */
-  hideArrow?: boolean
-}
+export type TooltipContentProps = ComponentProps<typeof KobalteTooltip.Content>
 
 export function TooltipContent(props: TooltipContentProps) {
   const interaction = useContext(TooltipInteractionContext)
   const [local, rest] = splitProps(props, [
     'class',
-    'hideArrow',
     'children',
     'aria-hidden',
     'onEscapeKeyDown',
@@ -371,7 +368,11 @@ export function TooltipContent(props: TooltipContentProps) {
     <KobalteTooltip.Portal>
       <KobalteTooltip.Content
         class={cn(
-          'bg-scrim text-scrim-foreground z-(--z-tooltip) w-fit max-w-64 rounded-md px-2 py-1 text-xs',
+          tooltipTip,
+          // The max width is a token, not a fixed measure: it has to fall
+          // behind the viewport at large root font sizes or the tip — which
+          // Kobalte can shift but never shrink — forces a horizontal scroll.
+          'z-(--z-tooltip) w-fit max-w-(--tooltip-max-width) px-2 py-1',
           'origin-(--kb-tooltip-content-transform-origin) text-balance',
           'data-expanded:animate-in data-expanded:fade-in-0 data-expanded:zoom-in-95',
           'data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95',
@@ -390,7 +391,6 @@ export function TooltipContent(props: TooltipContentProps) {
         {...rest}
       >
         {local.children}
-        {!local.hideArrow && <KobalteTooltip.Arrow aria-hidden="true" />}
       </KobalteTooltip.Content>
     </KobalteTooltip.Portal>
   )

package/src/lib/overlay.ts

@@ -21,6 +21,15 @@ export const overlayPositioner = 'fixed inset-0 z-(--z-dialog) grid place-items-
 export const overlayScrim =
   'fixed inset-0 z-(--z-dialog) bg-scrim/50 supports-[backdrop-filter]:backdrop-blur-xs'
 
+/**
+ * The tip: the card-toned bubble an explanation shows in. The side rail draws
+ * it flush to a collapsed row and every floating tooltip composes the same
+ * fill, edge, and type, so a control never explains itself in two visual
+ * languages.
+ */
+export const tooltipTip =
+  'bg-card text-card-foreground rounded-md border border-border text-sm font-medium shadow-lg'
+
 /**
  * Entrance and exit motion, expressed as data-state classes.
  *

package/src/lib/tokens.ts

@@ -542,6 +542,12 @@ export const densityTokens: TokenDefinition[] = [
   },
   { name: 'topbar-height', kind: 'dimension', description: '48px — the window title row.' },
   { name: 'statusbar-height', kind: 'dimension', description: '28px — the bottom readout strip.' },
+  {
+    name: 'tooltip-max-width',
+    kind: 'dimension',
+    description:
+      'The lesser of the 16rem readable measure and one viewport minus a gutter — a tip wraps before it can push its document wider than itself.',
+  },
 ]
 
 export const elevationTokens: TokenDefinition[] = [

package/src/styles/theme.css

@@ -614,6 +614,11 @@
   --sidebar-width-compact: 3rem;
   --topbar-height: 3rem;
   --statusbar-height: 1.75rem;
+  /* A tip wraps before it can overflow the window carrying it: the 16rem
+     readable measure governs on a desktop, but the measure scales with the root
+     font while the window does not, so at a 200% zoom the viewport term wins and
+     a tooltip can never push its document wider than itself. */
+  --tooltip-max-width: min(16rem, calc(100vw - 1.5rem));
 
   /* Shadows. Two parts on purpose: a tinted spread that reads as elevation, plus a
      hairline that keeps an edge visible when the surface behind a panel is the