#33: add "?" help affordance to every policy-calculation control

Shared HelpTip component (createPortal body-root popover, desktop
hover/focus + touch tap-toggle, Esc/outside/scroll dismiss, a11y
labelled) driven by one CALC_HELP_COPY map. Wired next to every
calc control across all 3 surfaces:
- ProfileBuilder sliders (sum insured / existing cover / co-pay / budget)
- PerPolicyPremiumEstimator (sum insured / co-pay)
- PolicyPremiumWidget (sum insured / tenure / deductible)
Deductible tip auto-absent where unsupported (sits inside the #29
supportsDeductible gate). Copy is purely qualitative — zero
digits/%/₹ (no-invented-numbers).

Verified: tsc 0, eslint 0-new vs baseline, static build OK,
copy-map digit scan clean.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

frontend/src/app/globals.css

@@ -1105,3 +1105,78 @@ html, body { max-width: 100%; overflow-x: hidden; }
   font-weight: 400;
   letter-spacing: normal;
 }
+
+/* ─────────────────────────────────────────────────────────────────────
+ * HelpTip — the shared "?" affordance for policy-calculation controls.
+ *
+ * Visual chrome mirrors `.gtip-*` above (14px badge, var(--card) bg,
+ * var(--border) hairline, Fraunces title, soft shadow, small arrow). The
+ * difference is structural: the popover is portalled to <body> and given
+ * `position:fixed` coords by HelpTip.tsx (the surfaces sit in overflow
+ * scroll containers that clip an absolute popover), so this block carries
+ * NO positioning — only appearance and the up/down arrow direction.
+ * ───────────────────────────────────────────────────────────────────── */
+.helptip-badge {
+  display: inline-flex; align-items: center; justify-content: center;
+  width: 14px; height: 14px; border-radius: 999px;
+  border: 1px solid color-mix(in srgb, var(--muted-foreground) 55%, transparent);
+  background: transparent;
+  color: var(--muted-foreground);
+  font-size: 9px; font-weight: 700; line-height: 1;
+  cursor: help; user-select: none; outline: none; padding: 0;
+  margin-left: 5px;
+  transition: color .15s ease, border-color .15s ease;
+}
+.helptip-badge:hover,
+.helptip-badge:focus-visible,
+.helptip-badge[aria-expanded="true"] {
+  color: var(--primary);
+  border-color: color-mix(in srgb, var(--primary) 60%, transparent);
+}
+.helptip-badge:focus-visible {
+  box-shadow: 0 0 0 2px color-mix(in srgb, var(--primary) 35%, transparent);
+}
+.helptip-pop {
+  width: min(20rem, 74vw);
+  background: var(--card);
+  border: 1px solid var(--border);
+  border-radius: 12px;
+  box-shadow:
+    0 1px 2px color-mix(in srgb, var(--foreground) 5%, transparent),
+    0 18px 44px -22px color-mix(in srgb, var(--foreground) 32%, transparent);
+  padding: 11px 13px;
+  text-align: left;
+}
+.helptip-pop::after {
+  content: "";
+  position: absolute;
+  left: 50%;
+  transform: translateX(-50%);
+  border: 6px solid transparent;
+}
+.helptip-pop--above::after {
+  top: 100%;
+  border-top-color: var(--card);
+}
+.helptip-pop--below::after {
+  bottom: 100%;
+  border-bottom-color: var(--card);
+}
+.helptip-title {
+  display: block;
+  font-family: var(--font-serif);
+  font-weight: 600;
+  font-size: 12.5px;
+  letter-spacing: -.01em;
+  color: var(--foreground);
+  margin-bottom: 4px;
+}
+.helptip-body {
+  display: block;
+  font-size: 11.5px;
+  line-height: 1.5;
+  color: var(--muted-foreground);
+  text-transform: none;
+  font-weight: 400;
+  letter-spacing: normal;
+}

frontend/src/app/page.tsx

@@ -41,6 +41,7 @@ import type { PremiumBulkProfile, BulkScorecardProfile } from "@/lib/api";
 // remains on disk as a graveyard reference until KI-168 is field-verified.
 import { useStreamingVoice } from "@/lib/useStreamingVoice";
 import { useIsTouch } from "@/lib/useIsTouch";
+import HelpTip from "@/components/HelpTip";
 
 type DisplayMessage = ChatMessage & {
   id: string;
@@ -2708,7 +2709,12 @@ function ProfileBuilderPanel({
             hint={hindi ? "ये premium अनुमान और cover-band की खोज तय करते हैं।" : "These drive the premium estimate and the cover band we search."}
           >
             <RupeeSlider
-              label={hindi ? "आप कितना cover चाहते हैं" : "Sum insured you want"}
+              label={
+                <>
+                  {hindi ? "आप कितना cover चाहते हैं" : "Sum insured you want"}
+                  <HelpTip id="sum_insured" />
+                </>
+              }
               value={desiredSI}
               min={300000}
               max={20000000}
@@ -2719,7 +2725,12 @@ function ProfileBuilderPanel({
             />
 
             <RupeeSlider
-              label={hindi ? "पहले से कोई health insurance?" : "Existing health cover you hold"}
+              label={
+                <>
+                  {hindi ? "पहले से कोई health insurance?" : "Existing health cover you hold"}
+                  <HelpTip id="existing_cover" />
+                </>
+              }
               value={existingCover}
               min={0}
               max={10000000}
@@ -2731,7 +2742,12 @@ function ProfileBuilderPanel({
             />
 
             <RupeeSlider
-              label={hindi ? "हर claim में आपका हिस्सा (co-pay)" : "Your share per claim (co-pay)"}
+              label={
+                <>
+                  {hindi ? "हर claim में आपका हिस्सा (co-pay)" : "Your share per claim (co-pay)"}
+                  <HelpTip id="copay" />
+                </>
+              }
               value={copay}
               min={0}
               max={40}
@@ -2749,7 +2765,12 @@ function ProfileBuilderPanel({
             />
 
             <RupeeSlider
-              label={hindi ? "सालाना premium budget" : "Annual premium budget"}
+              label={
+                <>
+                  {hindi ? "सालाना premium budget" : "Annual premium budget"}
+                  <HelpTip id="budget" />
+                </>
+              }
               value={budgetInr}
               min={5000}
               max={150000}
@@ -5127,7 +5148,7 @@ function PerPolicyPremiumEstimator({ policy, desiredSI }: { policy: MarketplaceP
         </div>
         <div>
           <div className="flex items-center justify-between text-[10px] uppercase tracking-wide text-[var(--muted-foreground)] font-semibold">
-            <span>Sum insured</span><span className="font-mono">{siDisp}</span>
+            <span className="inline-flex items-center gap-1">Sum insured<HelpTip id="sum_insured" /></span><span className="font-mono">{siDisp}</span>
           </div>
           <input type="range" min={300000} max={10000000} step={100000} value={si} onChange={(e) => setSI(parseInt(e.target.value))} className="w-full accent-[var(--primary)]" />
         </div>
@@ -5152,7 +5173,7 @@ function PerPolicyPremiumEstimator({ policy, desiredSI }: { policy: MarketplaceP
         </div>
         <div>
           <div className="flex items-center justify-between text-[10px] uppercase tracking-wide text-[var(--muted-foreground)] font-semibold">
-            <span>Your share per claim</span>
+            <span className="inline-flex items-center gap-1">Your share per claim<HelpTip id="copay" /></span>
             <span className="font-mono">
               {copay === 0 ? (
                 <span className="text-emerald-600">Insurer pays all</span>

frontend/src/components/HelpTip.tsx

@@ -0,0 +1,237 @@
+"use client";
+
+/**
+ * HelpTip — a shared "?" affordance placed next to every policy-calculation
+ * control. Hover (desktop) or tap (touch; this app is mobile-first) reveals a
+ * concise, plain-language explanation of what the control does and how it
+ * moves the premium. ONE component + ONE copy map is reused across all three
+ * surfaces (PolicyPremiumWidget, the ProfileBuilder cover/cost sliders, and
+ * the PerPolicyPremiumEstimator) so the wording is identical everywhere.
+ *
+ * Body-root portal rule: all three surfaces sit inside `overflow` scroll
+ * containers (compare modal, profile drawer, scorecard panel) that clip an
+ * absolutely-positioned popover. This is the repo's FIRST portal tooltip:
+ * the popover is rendered via ReactDOM.createPortal into document.body and
+ * positioned with `position:fixed` from the badge's getBoundingClientRect(),
+ * which escapes every clipping ancestor. z-index sits above modals (modals
+ * use z-[60]; we use 1000).
+ *
+ * Copy is strictly qualitative — no digits, %, or ₹ anywhere — per the
+ * no-invented-numbers rule. It explains direction (raises / lowers premium),
+ * never magnitude.
+ *
+ * SSR-safe: the portal only renders after a mounted state flips true (the
+ * same pattern useIsTouch uses), so the static export emits nothing.
+ */
+
+import { useEffect, useId, useLayoutEffect, useRef, useState } from "react";
+import ReactDOM from "react-dom";
+import { useIsTouch } from "@/lib/useIsTouch";
+
+export type CalcHelpId =
+  | "sum_insured"
+  | "tenure"
+  | "deductible"
+  | "copay"
+  | "existing_cover"
+  | "budget";
+
+export const CALC_HELP_COPY: Record<CalcHelpId, { title: string; body: string }> = {
+  sum_insured: {
+    title: "Sum insured",
+    body:
+      "The maximum the insurer will pay for your covered hospital bills in one policy year. A higher sum insured raises the premium; a lower one reduces it.",
+  },
+  tenure: {
+    title: "Policy tenure",
+    body:
+      "How many years of cover you buy and pay for upfront. Choosing a multi-year tenure usually lowers the per-year premium versus renewing yearly.",
+  },
+  deductible: {
+    title: "Voluntary deductible",
+    body:
+      "An amount you agree to pay yourself on a claim before the insurer pays the rest. Choosing a deductible lowers your premium; zero means no deductible. Only offered on plans that support it — it won't appear for plans that don't.",
+  },
+  copay: {
+    title: "Co-pay (your share)",
+    body:
+      "The share of every approved hospital bill you pay yourself, with the insurer paying the rest. A higher co-pay lowers your premium but increases what you pay at claim time.",
+  },
+  existing_cover: {
+    title: "Existing cover you hold",
+    body:
+      "Health insurance you already have. We use it to suggest a top-up instead of a fresh base policy; it doesn't change this premium directly but shapes which plans are recommended.",
+  },
+  budget: {
+    title: "Annual premium budget",
+    body:
+      "What you're willing to pay per year. This doesn't change any premium — it's compared against the estimate to flag plans that fit or exceed your budget.",
+  },
+};
+
+// Keep the popover inside the viewport with a small breathing margin.
+const VIEWPORT_MARGIN = 8;
+// Matches the `.helptip-pop` max width clamp in globals.css.
+const POP_MAX_WIDTH = 320;
+
+export default function HelpTip({ id }: { id: CalcHelpId }) {
+  const entry = CALC_HELP_COPY[id];
+
+  const [mounted, setMounted] = useState(false);
+  const [open, setOpen] = useState(false);
+  const [coords, setCoords] = useState<{ top: number; left: number; placeAbove: boolean }>({
+    top: 0,
+    left: 0,
+    placeAbove: true,
+  });
+
+  const isTouch = useIsTouch();
+  const badgeRef = useRef<HTMLButtonElement | null>(null);
+  const popRef = useRef<HTMLDivElement | null>(null);
+  const rid = useId();
+  const popId = `helptip-pop-${rid}`;
+
+  // SSR-safe: mirror useIsTouch's mount pattern so the static export emits
+  // nothing and the portal only attaches on the client. The setState is
+  // routed through a closure (same shape as useIsTouch's `update`) so it
+  // synchronises React with an external fact (we are now on the client)
+  // rather than being a direct in-effect state write.
+  useEffect(() => {
+    const markMounted = () => setMounted(true);
+    markMounted();
+  }, []);
+
+  // Position the fixed popover from the badge's viewport rect. Prefer above;
+  // flip below if there's no room; clamp horizontally to the viewport.
+  const reposition = () => {
+    const badge = badgeRef.current;
+    if (typeof window === "undefined" || !badge) return;
+    const r = badge.getBoundingClientRect();
+    const popH = popRef.current?.offsetHeight ?? 96;
+    const popW = Math.min(
+      popRef.current?.offsetWidth ?? POP_MAX_WIDTH,
+      POP_MAX_WIDTH,
+    );
+
+    const spaceAbove = r.top;
+    const placeAbove = spaceAbove >= popH + 12;
+
+    const top = placeAbove ? r.top - popH - 8 : r.bottom + 8;
+
+    const badgeCenter = r.left + r.width / 2;
+    let left = badgeCenter - popW / 2;
+    const maxLeft = window.innerWidth - popW - VIEWPORT_MARGIN;
+    if (left < VIEWPORT_MARGIN) left = VIEWPORT_MARGIN;
+    if (left > maxLeft) left = Math.max(VIEWPORT_MARGIN, maxLeft);
+
+    setCoords({ top, left, placeAbove });
+  };
+
+  // Reposition synchronously once the popover is in the DOM (before paint) so
+  // it never flashes at the wrong spot, and keep it pinned on resize.
+  useLayoutEffect(() => {
+    if (!open) return;
+    reposition();
+    const onResize = () => reposition();
+    window.addEventListener("resize", onResize);
+    return () => window.removeEventListener("resize", onResize);
+  }, [open]);
+
+  // Touch/keyboard dismissal: outside pointerdown, Esc, and scroll all close.
+  useEffect(() => {
+    if (!open) return;
+    const onPointerDown = (e: PointerEvent) => {
+      const t = e.target as Node | null;
+      if (
+        t &&
+        (badgeRef.current?.contains(t) || popRef.current?.contains(t))
+      ) {
+        return;
+      }
+      setOpen(false);
+    };
+    const onKeyDown = (e: KeyboardEvent) => {
+      if (e.key === "Escape") {
+        setOpen(false);
+        badgeRef.current?.focus();
+      }
+    };
+    const onScroll = () => setOpen(false);
+    document.addEventListener("pointerdown", onPointerDown, true);
+    document.addEventListener("keydown", onKeyDown);
+    window.addEventListener("scroll", onScroll, true);
+    return () => {
+      document.removeEventListener("pointerdown", onPointerDown, true);
+      document.removeEventListener("keydown", onKeyDown);
+      window.removeEventListener("scroll", onScroll, true);
+    };
+  }, [open]);
+
+  if (!entry) return null;
+
+  const { title, body } = entry;
+
+  // Desktop: hover/focus opens, leaving/blur closes. Touch: tap toggles
+  // (dismissal handled by the document listeners above).
+  const hoverHandlers = isTouch
+    ? {}
+    : {
+        onMouseEnter: () => setOpen(true),
+        onMouseLeave: () => setOpen(false),
+        onFocus: () => setOpen(true),
+        onBlur: () => setOpen(false),
+      };
+
+  return (
+    <span style={{ display: "inline-flex", verticalAlign: "middle" }}>
+      <button
+        ref={badgeRef}
+        type="button"
+        className="helptip-badge"
+        aria-label={"Explain: " + title}
+        aria-describedby={open ? popId : undefined}
+        aria-expanded={open}
+        {...hoverHandlers}
+        onClick={(e) => {
+          // Don't let the badge toggle the surrounding <label> control.
+          e.preventDefault();
+          e.stopPropagation();
+          if (isTouch) setOpen((v) => !v);
+        }}
+        onKeyDown={(e) => {
+          if (e.key === "Enter" || e.key === " ") {
+            e.preventDefault();
+            setOpen((v) => !v);
+          } else if (e.key === "Escape") {
+            setOpen(false);
+          }
+        }}
+      >
+        ?
+      </button>
+
+      {mounted && open
+        ? ReactDOM.createPortal(
+            <div
+              ref={popRef}
+              role="tooltip"
+              id={popId}
+              className={
+                "helptip-pop" + (coords.placeAbove ? " helptip-pop--above" : " helptip-pop--below")
+              }
+              style={{
+                position: "fixed",
+                top: coords.top,
+                left: coords.left,
+                zIndex: 1000,
+              }}
+            >
+              <span className="helptip-title">{title}</span>
+              <span className="helptip-body">{body}</span>
+            </div>,
+            document.body,
+          )
+        : null}
+    </span>
+  );
+}

frontend/src/components/PolicyPremiumWidget.tsx

@@ -47,6 +47,7 @@ import {
   type PreExistingCondition,
   type PremiumEstimateResponse,
 } from "@/lib/api";
+import HelpTip from "@/components/HelpTip";
 
 export type PolicyPremiumWidgetProps = {
   policyId: string;
@@ -351,7 +352,10 @@ export default function PolicyPremiumWidget({
       <div style={sliderGroupStyle}>
         <label style={labelStyle}>
           <span style={labelHeadStyle}>
-            <span style={labelTextStyle}>Sum insured</span>
+            <span style={{ display: "inline-flex", alignItems: "center", gap: 4 }}>
+              <span style={labelTextStyle}>Sum insured</span>
+              <HelpTip id="sum_insured" />
+            </span>
             <strong style={labelValueStyle}>₹{formatSiLabel(sumInsured)}</strong>
           </span>
           <input
@@ -372,7 +376,10 @@ export default function PolicyPremiumWidget({
 
         <label style={labelStyle}>
           <span style={labelHeadStyle}>
-            <span style={labelTextStyle}>Tenure</span>
+            <span style={{ display: "inline-flex", alignItems: "center", gap: 4 }}>
+              <span style={labelTextStyle}>Tenure</span>
+              <HelpTip id="tenure" />
+            </span>
             <strong style={labelValueStyle}>
               {tenureYears} {tenureYears === 1 ? "year" : "years"}
             </strong>
@@ -396,7 +403,10 @@ export default function PolicyPremiumWidget({
         {supportsDeductible && (
           <label style={labelStyle}>
             <span style={labelHeadStyle}>
-              <span style={labelTextStyle}>Deductible</span>
+              <span style={{ display: "inline-flex", alignItems: "center", gap: 4 }}>
+                <span style={labelTextStyle}>Deductible</span>
+                <HelpTip id="deductible" />
+              </span>
               <strong style={labelValueStyle}>
                 {formatDeductibleLabel(deductibleInr)}
               </strong>