feat(web): add tooltip component and integrate into VCP sections

devakone · devakone · commit 699433c0f1a3 · 2026-01-21T23:31:05.000-05:00
- Introduced a new Tooltip component using Radix UI for enhanced user interaction.
- Updated VCP components (AxisInfoTooltip, VCPAxesGrid, RepoAxesSection, UnifiedAxesSection) to utilize the new tooltip for displaying additional information about axes.
- Enhanced AxisMetadata to include long descriptions for better context in tooltips.
- Refactored layout in `route.tsx` to improve QR code generation and story image rendering.

This update improves user experience by providing contextual information through tooltips, enhancing the overall interactivity of the VCP display.
diff --git a/apps/web/package.json b/apps/web/package.json
@@ -12,6 +12,7 @@
   "dependencies": {
     "@radix-ui/react-popover": "^1.1.15",
     "@radix-ui/react-toast": "^1.2.15",
+    "@radix-ui/react-tooltip": "^1.2.8",
     "@supabase/ssr": "^0.5.2",
     "@supabase/supabase-js": "^2.47.14",
     "@vercel/og": "^0.8.6",
diff --git a/apps/web/src/app/api/share/story/[userId]/route.tsx b/apps/web/src/app/api/share/story/[userId]/route.tsx
@@ -280,15 +280,17 @@ const renderStoryImage = async (story: StoryData, qrDataUrl: string) => {
         <div
           style={{
             marginTop: 40,
-            display: "grid",
-            gridTemplateColumns: "repeat(2, minmax(0, 1fr))",
-            gap: 18,
+            display: "flex",
+            flexWrap: "wrap",
+            justifyContent: "space-between",
           }}
         >
           {story.metrics.map((metric) => (
             <div
               key={metric.label}
               style={{
+                width: "48%",
+                marginBottom: 18,
                 borderRadius: 28,
                 padding: "18px 20px",
                 background: "rgba(255,255,255,0.1)",
@@ -456,6 +458,7 @@ export async function GET(
     return NextResponse.json({ error: "not_found" }, { status: 404 });
   }
 
-  const qrDataUrl = await QRCode.toDataURL(storyData.url, { width: 260 });
+  const qrSvg = await QRCode.toString(storyData.url, { type: "svg", width: 260, margin: 0 });
+  const qrDataUrl = `data:image/svg+xml;utf8,${encodeURIComponent(qrSvg)}`;
   return renderStoryImage(storyData, qrDataUrl);
 }
diff --git a/apps/web/src/components/ui/tooltip.tsx b/apps/web/src/components/ui/tooltip.tsx
@@ -0,0 +1,61 @@
+"use client"
+
+import * as React from "react"
+import * as TooltipPrimitive from "@radix-ui/react-tooltip"
+
+import { cn } from "@/lib/utils"
+
+function TooltipProvider({
+  delayDuration = 0,
+  ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Provider>) {
+  return (
+    <TooltipPrimitive.Provider
+      data-slot="tooltip-provider"
+      delayDuration={delayDuration}
+      {...props}
+    />
+  )
+}
+
+function Tooltip({
+  ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Root>) {
+  return (
+    <TooltipProvider>
+      <TooltipPrimitive.Root data-slot="tooltip" {...props} />
+    </TooltipProvider>
+  )
+}
+
+function TooltipTrigger({
+  ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Trigger>) {
+  return <TooltipPrimitive.Trigger data-slot="tooltip-trigger" {...props} />
+}
+
+function TooltipContent({
+  className,
+  sideOffset = 0,
+  children,
+  ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Content>) {
+  return (
+    <TooltipPrimitive.Portal>
+      <TooltipPrimitive.Content
+        data-slot="tooltip-content"
+        sideOffset={sideOffset}
+        className={cn(
+          "bg-foreground text-background animate-in fade-in-0 zoom-in-95 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 z-50 w-fit origin-(--radix-tooltip-content-transform-origin) rounded-md px-3 py-1.5 text-xs text-balance",
+          className
+        )}
+        {...props}
+      >
+        {children}
+        <TooltipPrimitive.Arrow className="bg-foreground fill-foreground z-50 size-2.5 translate-y-[calc(-50%_-_2px)] rotate-45 rounded-[2px]" />
+      </TooltipPrimitive.Content>
+    </TooltipPrimitive.Portal>
+  )
+}
+
+export { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider }
diff --git a/apps/web/src/components/vcp/AxisInfoTooltip.tsx b/apps/web/src/components/vcp/AxisInfoTooltip.tsx
@@ -0,0 +1,49 @@
+import { Info } from "lucide-react";
+
+import { cn } from "@/lib/utils";
+import type { AxisMetadata } from "./constants";
+import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";
+
+type AxisInfoTooltipVariant = "light" | "dark";
+
+interface AxisInfoTooltipProps {
+  meta: AxisMetadata;
+  variant?: AxisInfoTooltipVariant;
+  className?: string;
+}
+
+const VARIANT_STYLES: Record<AxisInfoTooltipVariant, string> = {
+  light: "text-zinc-400 hover:text-zinc-600",
+  dark: "text-white/40 hover:text-white/70",
+};
+
+export function AxisInfoTooltip({
+  meta,
+  variant = "light",
+  className,
+}: AxisInfoTooltipProps) {
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <button
+          type="button"
+          aria-label={`${meta.name} details`}
+          className={cn(
+            "inline-flex items-center justify-center rounded-full transition",
+            VARIANT_STYLES[variant],
+            className
+          )}
+        >
+          <Info className="h-3.5 w-3.5" aria-hidden="true" />
+        </button>
+      </TooltipTrigger>
+      <TooltipContent side="top" sideOffset={6} className="max-w-xs">
+        <p className="text-xs font-semibold">{meta.name}</p>
+        <p className="mt-1 text-xs text-background/85">{meta.longDescription}</p>
+        <p className="mt-2 text-[11px] text-background/70">
+          Score is 0-100. Lower means {meta.lowLabel}, higher means {meta.highLabel}.
+        </p>
+      </TooltipContent>
+    </Tooltip>
+  );
+}
diff --git a/apps/web/src/components/vcp/blocks/VCPAxesGrid.tsx b/apps/web/src/components/vcp/blocks/VCPAxesGrid.tsx
@@ -2,6 +2,7 @@ import { cn } from "@/lib/utils";
 import type { VCPAxesGridProps, AxisKey } from "../types";
 import { VCPProgressBar } from "../primitives";
 import { AXIS_METADATA, AXIS_ORDER } from "../constants";
+import { AxisInfoTooltip } from "../AxisInfoTooltip";
 
 /**
  * VCPAxesGrid - Grid display of all six vibe axes
@@ -26,7 +27,10 @@ export function VCPAxesGrid({
         {axisEntries.map(({ key, score, level, meta }) => (
           <div key={key} className="space-y-1">
             <div className="flex items-center justify-between text-sm">
-              <span className="font-medium text-white/80">{meta.name}</span>
+              <div className="flex items-center gap-1">
+                <span className="font-medium text-white/80">{meta.name}</span>
+                <AxisInfoTooltip meta={meta} variant="dark" />
+              </div>
               <span className="text-white/60">{score}</span>
             </div>
             <VCPProgressBar value={score} size="md" />
@@ -52,9 +56,12 @@ export function VCPAxesGrid({
           className="rounded-xl bg-white/5 p-4"
         >
           <div className="flex items-center justify-between">
-            <span className="text-xs font-semibold uppercase tracking-wider text-white/50">
-              {meta.name}
-            </span>
+            <div className="flex items-center gap-1">
+              <span className="text-xs font-semibold uppercase tracking-wider text-white/50">
+                {meta.name}
+              </span>
+              <AxisInfoTooltip meta={meta} variant="dark" />
+            </div>
             <span className="text-lg font-bold text-white">{score}</span>
           </div>
           <VCPProgressBar value={score} size="sm" className="mt-2" />
diff --git a/apps/web/src/components/vcp/constants.ts b/apps/web/src/components/vcp/constants.ts
@@ -14,6 +14,7 @@ export interface AxisMetadata {
   name: string;
   shortName: string;
   description: string;
+  longDescription: string;
   lowLabel: string;
   highLabel: string;
 }
@@ -23,41 +24,53 @@ export const AXIS_METADATA: Record<AxisKey, AxisMetadata> = {
     name: "Automation",
     shortName: "Auto",
     description: "How much you leverage AI/automation for large-scale changes",
+    longDescription:
+      'How "agentic" your workflow looks, driven by large commits and chunky PRs. Higher scores indicate more automation-heavy changes.',
     lowLabel: "Manual",
     highLabel: "AI-Heavy",
   },
   guardrail_strength: {
     name: "Guardrails",
     shortName: "Guard",
     description: "How early and consistently tests/CI/docs appear in your workflow",
+    longDescription:
+      "How much you stabilize work with tests, CI, and docs early in the lifecycle. Higher scores mean guardrails appear sooner and more consistently.",
     lowLabel: "Light",
     highLabel: "Rigorous",
   },
   iteration_loop_intensity: {
     name: "Iteration",
     shortName: "Iter",
     description: "How quickly you cycle through fix-forward loops after changes",
+    longDescription:
+      'How often you run rapid "generate → run → fix → run" cycles. Higher scores mean faster, denser iteration loops.',
     lowLabel: "Stable",
     highLabel: "Rapid",
   },
   planning_signal: {
     name: "Planning",
     shortName: "Plan",
     description: "How much upfront structure (issues, specs, docs-first) appears",
+    longDescription:
+      "How much intent and structure appear up front: linked issues, structured commits, and docs-first patterns. Higher scores indicate more planning.",
     lowLabel: "Emergent",
     highLabel: "Structured",
   },
   surface_area_per_change: {
     name: "Surface Area",
     shortName: "Scope",
     description: "How many subsystems your typical change touches",
+    longDescription:
+      "How broad each unit of work is across subsystems. Higher scores mean typical changes span more areas of the codebase.",
     lowLabel: "Narrow",
     highLabel: "Wide",
   },
   shipping_rhythm: {
     name: "Rhythm",
     shortName: "Rhythm",
     description: "Your shipping pattern — steady vs bursty",
+    longDescription:
+      "Bursty versus steady shipping over time. Higher scores indicate bursty sessions with gaps; lower scores indicate a steadier cadence.",
     lowLabel: "Steady",
     highLabel: "Bursty",
   },
diff --git a/apps/web/src/components/vcp/repo/RepoAxesSection.tsx b/apps/web/src/components/vcp/repo/RepoAxesSection.tsx
@@ -3,6 +3,7 @@
 import { cn } from "@/lib/utils";
 import type { VibeAxes } from "@vibed/core";
 import { AXIS_METADATA, AXIS_ORDER } from "../constants";
+import { AxisInfoTooltip } from "../AxisInfoTooltip";
 
 interface RepoAxesSectionProps {
   /** Vibe axes data */
@@ -37,7 +38,12 @@ export function RepoAxesSection({ axes, className }: RepoAxesSectionProps) {
             >
               <div className="flex items-start justify-between">
                 <div>
-                  <p className="text-sm font-semibold text-zinc-900">{meta.name}</p>
+                  <div className="flex items-center gap-1">
+                    <p className="text-sm font-semibold text-zinc-900">
+                      {meta.name}
+                    </p>
+                    <AxisInfoTooltip meta={meta} />
+                  </div>
                   <p className="mt-0.5 text-xs text-zinc-500">{meta.description}</p>
                 </div>
                 <div className="text-right">
diff --git a/apps/web/src/components/vcp/unified/UnifiedAxesSection.tsx b/apps/web/src/components/vcp/unified/UnifiedAxesSection.tsx
@@ -3,6 +3,7 @@
 import { cn } from "@/lib/utils";
 import type { VibeAxes } from "@vibed/core";
 import { AXIS_METADATA, AXIS_ORDER } from "../constants";
+import { AxisInfoTooltip } from "../AxisInfoTooltip";
 
 interface UnifiedAxesSectionProps {
   /** Vibe axes data */
@@ -42,7 +43,12 @@ export function UnifiedAxesSection({
             >
               <div className="flex items-start justify-between">
                 <div>
-                  <p className="text-sm font-semibold text-zinc-900">{meta.name}</p>
+                  <div className="flex items-center gap-1">
+                    <p className="text-sm font-semibold text-zinc-900">
+                      {meta.name}
+                    </p>
+                    <AxisInfoTooltip meta={meta} />
+                  </div>
                   <p className="mt-0.5 text-xs text-zinc-500">{meta.description}</p>
                 </div>
                 <span className="text-xl font-bold text-zinc-900">{score}</span>
diff --git a/docs/implementation-trackers/information-architecture-restructure.md b/docs/implementation-trackers/information-architecture-restructure.md
@@ -309,7 +309,7 @@ This tracker covers all implementation work for the Information Architecture Res
 
 ### X2. Polish & Testing
 
-**Status:** `[ ] Not Started`  
+**Status:** `[~] In Progress`  
 **Depends on:** P1, P3, P4, P5, X1  
 **Blocks:** X3
 
@@ -365,7 +365,7 @@ This tracker covers all implementation work for the Information Architecture Res
 | P5: Vertical Stories ShareCard | 7 | 6 | `[~] In Progress` |
 | P6: LLM Tagline Generation | 5 | 5 | `[x] Complete` |
 | X1: Migration & Redirects | 5 | 4 | `[~] In Progress` |
-| X2: Polish & Testing | 7 | 0 | `[ ] Not Started` |
+| X2: Polish & Testing | 7 | 0 | `[~] In Progress` |
 | X3: Documentation | 5 | 0 | `[ ] Not Started` |
 | **Total** | **91** | **68** | **75%** |
 
diff --git a/package-lock.json b/package-lock.json
