From 578dc60b11195d31cecdafadd26c0e75f0242ffc Mon Sep 17 00:00:00 2001
From: michael <michael@modernfreedom.com>
Date: Mon, 1 Dec 2025 16:10:21 -0600
Subject: [PATCH] Add tooltip help icons to Audience Brief and Research
 Objective fields
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Clarifies the distinction between these form fields by adding (?) tooltip
icons with explanatory text and expandable examples. Updates placeholder
text and removes redundant FormDescription elements.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .../ai-recruiter/AIRecruiterForm.tsx          | 35 +++++++++------
 src/components/ui/field-tooltip.tsx           | 45 +++++++++++++++++++
 2 files changed, 66 insertions(+), 14 deletions(-)
 create mode 100644 src/components/ui/field-tooltip.tsx

diff --git a/src/components/ai-recruiter/AIRecruiterForm.tsx b/src/components/ai-recruiter/AIRecruiterForm.tsx
index de59c8bc..d2c22903 100644
--- a/src/components/ai-recruiter/AIRecruiterForm.tsx
+++ b/src/components/ai-recruiter/AIRecruiterForm.tsx
@@ -41,6 +41,7 @@ import {
   AccordionItem,
   AccordionTrigger,
 } from "@/components/ui/accordion";
+import { FieldTooltip } from "@/components/ui/field-tooltip";
 
 export const formSchema = z.object({
   audienceBrief: z.string().min(10, {
@@ -169,17 +170,20 @@ export default function AIRecruiterForm({ onSubmit, isGenerating }: AIRecruiterF
               name="audienceBrief"
               render={({ field }) => (
                 <FormItem>
-                  <FormLabel>Audience Brief</FormLabel>
+                  <FormLabel className="flex items-center gap-1.5">
+                    Audience Brief
+                    <FieldTooltip
+                      content="This defines the personas you'll be generating. Imagine you were briefing a recruitment agency to find these people in real life – what would you ask for?"
+                      example="We're looking for UK-based millennials aged 28-35 who are considering switching their streaming service provider. They should be tech-savvy, price-conscious, and currently subscribe to at least two streaming platforms. We want a mix of urban and suburban residents, with varying household sizes."
+                    />
+                  </FormLabel>
                   <FormControl>
-                    <Textarea 
-                      placeholder="Describe your target audience and research goals..." 
+                    <Textarea
+                      placeholder="Describe your target audience(s). Who you want to talk to, their demographics and attitudes..."
                       className="h-40"
-                      {...field} 
+                      {...field}
                     />
                   </FormControl>
-                  <FormDescription>
-                    Provide details about the demographics, behaviors, and attitudes you want to explore
-                  </FormDescription>
                   <FormMessage />
                 </FormItem>
               )}
@@ -190,17 +194,20 @@ export default function AIRecruiterForm({ onSubmit, isGenerating }: AIRecruiterF
               name="researchObjective"
               render={({ field }) => (
                 <FormItem>
-                  <FormLabel>Research Objective</FormLabel>
+                  <FormLabel className="flex items-center gap-1.5">
+                    Research Objective
+                    <FieldTooltip
+                      content="This helps create personas with backgrounds related to your research area. We use the information here to create 'life scenarios' that connect your personas to certain topics. Think of it like letting your participants know what kinds of questions you'll be asking them ahead of time. You will have the chance to write a more detailed research brief later."
+                      example="Understanding switching behaviours in TV streaming markets. We want to explore what triggers consideration of new platforms, how users evaluate alternatives, and what factors drive final switching decisions. We're particularly interested in the role of exclusive content and pricing."
+                    />
+                  </FormLabel>
                   <FormControl>
-                    <Textarea 
-                      placeholder="What is the main research topic or objective you want to explore?" 
+                    <Textarea
+                      placeholder="Describe what you want to learn. What are the main research topics or areas of interest you want to explore? For instance, 'Understanding switching behaviours in TV markets' or 'Learning about Millennial attitudes towards Facebook ads'..."
                       className="h-32"
-                      {...field} 
+                      {...field}
                     />
                   </FormControl>
-                  <FormDescription>
-                    Specify your research focus to generate more targeted persona goals, frustrations, and scenarios
-                  </FormDescription>
                   <FormMessage />
                 </FormItem>
               )}
diff --git a/src/components/ui/field-tooltip.tsx b/src/components/ui/field-tooltip.tsx
new file mode 100644
index 00000000..f7963597
--- /dev/null
+++ b/src/components/ui/field-tooltip.tsx
@@ -0,0 +1,45 @@
+import * as React from "react"
+import { useState } from "react"
+import { HelpCircle } from "lucide-react"
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+} from "@/components/ui/popover"
+
+interface FieldTooltipProps {
+  content: string
+  example: string
+}
+
+export function FieldTooltip({ content, example }: FieldTooltipProps) {
+  const [showExample, setShowExample] = useState(false)
+
+  return (
+    <Popover>
+      <PopoverTrigger asChild>
+        <button
+          type="button"
+          className="inline-flex items-center justify-center rounded-full focus:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2"
+        >
+          <HelpCircle className="h-4 w-4 text-muted-foreground hover:text-foreground transition-colors cursor-pointer" />
+        </button>
+      </PopoverTrigger>
+      <PopoverContent className="w-80" sideOffset={5}>
+        <p className="text-sm text-foreground">{content}</p>
+        <button
+          type="button"
+          onClick={() => setShowExample(!showExample)}
+          className="text-sm text-primary hover:underline mt-3 font-medium"
+        >
+          {showExample ? "Hide example" : "Show example"}
+        </button>
+        {showExample && (
+          <div className="mt-3 p-3 bg-muted rounded-md text-sm text-muted-foreground italic">
+            {example}
+          </div>
+        )}
+      </PopoverContent>
+    </Popover>
+  )
+}