From c4857b6be28355f9f420f7263f983bfbb9d7f2d8 Mon Sep 17 00:00:00 2001
From: mitul-s <mitulxshah@gmail.com>
Date: Fri, 29 May 2026 14:21:47 -0400
Subject: [PATCH 1/2] tooltips

---
 .changeset/trace-nav-tooltips.md              |  5 ++
 .../new-trace-viewer/trace-viewer.tsx         | 67 +++++++++++++------
 .../src/components/ui/icon-button.tsx         | 18 ++---
 packages/web-shared/src/components/ui/kbd.tsx | 21 ++++++
 .../web-shared/src/components/ui/tooltip.tsx  | 49 ++++++++++++++
 5 files changed, 130 insertions(+), 30 deletions(-)
 create mode 100644 .changeset/trace-nav-tooltips.md
 create mode 100644 packages/web-shared/src/components/ui/kbd.tsx
 create mode 100644 packages/web-shared/src/components/ui/tooltip.tsx

diff --git a/.changeset/trace-nav-tooltips.md b/.changeset/trace-nav-tooltips.md
new file mode 100644
index 0000000000..7a14ff91f8
--- /dev/null
+++ b/.changeset/trace-nav-tooltips.md
@@ -0,0 +1,5 @@
+---
+'@workflow/web-shared': patch
+---
+
+Add keyboard-shortcut tooltips to the up/down span navigation buttons in the trace viewer detail panel.
diff --git a/packages/web-shared/src/components/new-trace-viewer/trace-viewer.tsx b/packages/web-shared/src/components/new-trace-viewer/trace-viewer.tsx
index 9614a48d5b..f4282c21ba 100644
--- a/packages/web-shared/src/components/new-trace-viewer/trace-viewer.tsx
+++ b/packages/web-shared/src/components/new-trace-viewer/trace-viewer.tsx
@@ -29,6 +29,7 @@ import { useSidebarDataOptional } from '../sidebar/sidebar-data-context';
 import type { Trace } from '../trace-viewer/types';
 import { formatDuration, getHighResInMs } from '../trace-viewer/util/timing';
 import { IconButton } from '../ui/icon-button';
+import { Kbd } from '../ui/kbd';
 import EventList from './components/event-list';
 import { SplitPane } from './components/split-pane';
 import {
@@ -36,6 +37,12 @@ import {
   Timeline,
   TimelineHeader,
 } from './components/timeline';
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from '../ui/tooltip';
 import { ActiveSpanProvider, useActiveSpan } from './context';
 import { DetailPanel } from './detail-panel';
 import { searchSpans } from './search';
@@ -154,9 +161,11 @@ function useSelectedSpanInfo(): SelectedSpanInfo | null {
 
 export function NewTraceViewer({ trace }: NewTraceViewerProps): ReactNode {
   return (
-    <ActiveSpanProvider spans={trace.spans}>
-      <NewTraceViewerContent trace={trace} />
-    </ActiveSpanProvider>
+    <TooltipProvider delayDuration={300}>
+      <ActiveSpanProvider spans={trace.spans}>
+        <NewTraceViewerContent trace={trace} />
+      </ActiveSpanProvider>
+    </TooltipProvider>
   );
 }
 
@@ -634,22 +643,42 @@ function NewTraceViewerContent({ trace }: NewTraceViewerProps): ReactNode {
               {selectedSpanName}
             </span>
             <div className="flex items-center gap-0.5 shrink-0">
-              <IconButton
-                aria-label="Navigate to previous span"
-                aria-keyshortcuts="K"
-                onClick={handleSelectPrevSpan}
-                disabled={!prevSpanId}
-              >
-                <ChevronUp className="w-4 h-4" />
-              </IconButton>
-              <IconButton
-                aria-label="Navigate to next span"
-                aria-keyshortcuts="J"
-                onClick={handleSelectNextSpan}
-                disabled={!nextSpanId}
-              >
-                <ChevronDown className="w-4 h-4" />
-              </IconButton>
+              <Tooltip>
+                <TooltipTrigger asChild>
+                  <IconButton
+                    aria-label="Navigate up"
+                    aria-keyshortcuts="K"
+                    onClick={handleSelectPrevSpan}
+                    disabled={!prevSpanId}
+                  >
+                    <ChevronUp className="w-4 h-4" />
+                  </IconButton>
+                </TooltipTrigger>
+                {prevSpanId ? (
+                  <TooltipContent>
+                    Navigate up
+                    <Kbd>K</Kbd>
+                  </TooltipContent>
+                ) : null}
+              </Tooltip>
+              <Tooltip>
+                <TooltipTrigger asChild>
+                  <IconButton
+                    aria-label="Navigate down"
+                    aria-keyshortcuts="J"
+                    onClick={handleSelectNextSpan}
+                    disabled={!nextSpanId}
+                  >
+                    <ChevronDown className="w-4 h-4" />
+                  </IconButton>
+                </TooltipTrigger>
+                {nextSpanId ? (
+                  <TooltipContent>
+                    Navigate down
+                    <Kbd>J</Kbd>
+                  </TooltipContent>
+                ) : null}
+              </Tooltip>
               <div aria-hidden className="w-px h-4 bg-gray-alpha-400 mx-1" />
               <IconButton
                 aria-label="Close span details"
diff --git a/packages/web-shared/src/components/ui/icon-button.tsx b/packages/web-shared/src/components/ui/icon-button.tsx
index 633935bce2..6cdab49b6f 100644
--- a/packages/web-shared/src/components/ui/icon-button.tsx
+++ b/packages/web-shared/src/components/ui/icon-button.tsx
@@ -1,5 +1,5 @@
 import { cva, type VariantProps } from 'class-variance-authority';
-import type * as React from 'react';
+import * as React from 'react';
 import { cn } from '../../lib/utils';
 
 const iconButtonVariants = cva(
@@ -38,20 +38,16 @@ export type IconButtonProps = Omit<
     type?: 'button' | 'submit' | 'reset';
   };
 
-export function IconButton({
-  className,
-  variant,
-  size,
-  type = 'button',
-  ...props
-}: IconButtonProps) {
-  return (
+export const IconButton = React.forwardRef<HTMLButtonElement, IconButtonProps>(
+  ({ className, variant, size, type = 'button', ...props }, ref) => (
     <button
+      ref={ref}
       type={type}
       className={cn(iconButtonVariants({ variant, size, className }))}
       {...props}
     />
-  );
-}
+  )
+);
+IconButton.displayName = 'IconButton';
 
 export { iconButtonVariants };
diff --git a/packages/web-shared/src/components/ui/kbd.tsx b/packages/web-shared/src/components/ui/kbd.tsx
new file mode 100644
index 0000000000..f6b6e9f597
--- /dev/null
+++ b/packages/web-shared/src/components/ui/kbd.tsx
@@ -0,0 +1,21 @@
+import type { ReactNode } from 'react';
+import { cn } from '../../lib/utils';
+
+export function Kbd({
+  children,
+  className,
+}: {
+  children: ReactNode;
+  className?: string;
+}): ReactNode {
+  return (
+    <kbd
+      className={cn(
+        'inline-flex h-5 min-w-5 items-center justify-center rounded bg-background-100/20 px-1 text-center font-sans text-xs leading-none',
+        className
+      )}
+    >
+      {children}
+    </kbd>
+  );
+}
diff --git a/packages/web-shared/src/components/ui/tooltip.tsx b/packages/web-shared/src/components/ui/tooltip.tsx
new file mode 100644
index 0000000000..70e4467006
--- /dev/null
+++ b/packages/web-shared/src/components/ui/tooltip.tsx
@@ -0,0 +1,49 @@
+'use client';
+
+import * as TooltipPrimitive from '@radix-ui/react-tooltip';
+import * as React from 'react';
+import { cn } from '../../lib/utils';
+
+const TooltipProvider = TooltipPrimitive.Provider;
+
+const Tooltip = TooltipPrimitive.Root;
+
+const TooltipTrigger = TooltipPrimitive.Trigger;
+
+const TooltipContent = React.forwardRef<
+  React.ElementRef<typeof TooltipPrimitive.Content>,
+  React.ComponentPropsWithoutRef<typeof TooltipPrimitive.Content> & {
+    /** Render the directional caret arrow (Geist default). */
+    showArrow?: boolean;
+  }
+>(
+  (
+    { className, sideOffset = 8, showArrow = true, children, ...props },
+    ref
+  ) => (
+    <TooltipPrimitive.Portal>
+      <TooltipPrimitive.Content
+        ref={ref}
+        sideOffset={sideOffset}
+        // Inverted surface, matching the Geist tooltip.
+        className={cn(
+          'z-[99999] flex items-center gap-1 rounded-[10px] bg-gray-1000 px-2 py-1.5 !text-label-13 text-background-100 shadow-md select-none',
+          className
+        )}
+        {...props}
+      >
+        {children}
+        {showArrow ? (
+          <TooltipPrimitive.Arrow
+            width={11}
+            height={5}
+            className="fill-gray-1000"
+          />
+        ) : null}
+      </TooltipPrimitive.Content>
+    </TooltipPrimitive.Portal>
+  )
+);
+TooltipContent.displayName = TooltipPrimitive.Content.displayName;
+
+export { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider };

From 882ea34afd1cfc129caf30e5f6814f92a612a796 Mon Sep 17 00:00:00 2001
From: Mitul Shah <mitulxshah@gmail.com>
Date: Fri, 29 May 2026 14:27:32 -0400
Subject: [PATCH 2/2] Apply suggestions from code review

Co-authored-by: Mitul Shah <mitulxshah@gmail.com>
Signed-off-by: Mitul Shah <mitulxshah@gmail.com>
---
 packages/web-shared/src/components/ui/tooltip.tsx | 2 --
 1 file changed, 2 deletions(-)

diff --git a/packages/web-shared/src/components/ui/tooltip.tsx b/packages/web-shared/src/components/ui/tooltip.tsx
index 70e4467006..c753b60993 100644
--- a/packages/web-shared/src/components/ui/tooltip.tsx
+++ b/packages/web-shared/src/components/ui/tooltip.tsx
@@ -13,7 +13,6 @@ const TooltipTrigger = TooltipPrimitive.Trigger;
 const TooltipContent = React.forwardRef<
   React.ElementRef<typeof TooltipPrimitive.Content>,
   React.ComponentPropsWithoutRef<typeof TooltipPrimitive.Content> & {
-    /** Render the directional caret arrow (Geist default). */
     showArrow?: boolean;
   }
 >(
@@ -25,7 +24,6 @@ const TooltipContent = React.forwardRef<
       <TooltipPrimitive.Content
         ref={ref}
         sideOffset={sideOffset}
-        // Inverted surface, matching the Geist tooltip.
         className={cn(
           'z-[99999] flex items-center gap-1 rounded-[10px] bg-gray-1000 px-2 py-1.5 !text-label-13 text-background-100 shadow-md select-none',
           className