feat(ux): add comprehensive onboarding and help system for non-technical users

- Add welcome modal for first-time visitors with 3-step setup overview
- Add setup progress tracker on homepage showing completion status
- Add step-by-step API key setup guide in settings page
- Add contextual help buttons (?) with detailed explanations for all fields
- Add help content database covering API key, Audience ID, sender email, CSV import
- Add SmartAlert component for user-friendly error messages with actionable guidance
- Add error messages library with solutions for common issues
- Track email sends for progress completion
- Update contacts page with improved sync error messages and help buttons
- Update send page with SmartAlert for missing configuration warnings

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

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: ChanMeng666

app/contacts/page.tsx

@@ -1,6 +1,7 @@
 'use client'
 
 import { useState, useEffect, useRef } from 'react'
+import Link from 'next/link'
 import {
   Plus,
   Search,
@@ -13,11 +14,14 @@ import {
   X,
   Check,
   AlertCircle,
-  Loader2
+  Loader2,
+  HelpCircle
 } from 'lucide-react'
 import { Button } from '@/components/ui/button'
 import { Input } from '@/components/ui/input'
 import { Card } from '@/components/ui/card'
+import { SmartAlert, SuccessAlert } from '@/components/shared/SmartAlert'
+import { HelpButton } from '@/components/help/HelpButton'
 
 interface Contact {
   id: string
@@ -301,28 +305,34 @@ export default function ContactsPage() {
             Manage your email recipients
           </p>
         </div>
-        <div className="flex gap-2">
-          <Button
-            variant="outline"
-            className="neo-border"
-            onClick={handleImportCSV}
-          >
-            <Upload className="w-4 h-4 mr-2" />
-            Import CSV
-          </Button>
-          <Button
-            variant="outline"
-            className="neo-border"
-            onClick={handleSyncResend}
-            disabled={syncStatus === 'loading'}
-          >
-            {syncStatus === 'loading' ? (
-              <Loader2 className="w-4 h-4 mr-2 animate-spin" />
-            ) : (
-              <RefreshCw className="w-4 h-4 mr-2" />
-            )}
-            Sync Resend
-          </Button>
+        <div className="flex gap-2 items-center">
+          <div className="flex items-center gap-1">
+            <Button
+              variant="outline"
+              className="neo-border"
+              onClick={handleImportCSV}
+            >
+              <Upload className="w-4 h-4 mr-2" />
+              Import CSV
+            </Button>
+            <HelpButton topic="csv-import" />
+          </div>
+          <div className="flex items-center gap-1">
+            <Button
+              variant="outline"
+              className="neo-border"
+              onClick={handleSyncResend}
+              disabled={syncStatus === 'loading'}
+            >
+              {syncStatus === 'loading' ? (
+                <Loader2 className="w-4 h-4 mr-2 animate-spin" />
+              ) : (
+                <RefreshCw className="w-4 h-4 mr-2" />
+              )}
+              Sync Resend
+            </Button>
+            <HelpButton topic="resend-sync" />
+          </div>
           <Button
             className="neo-button bg-neo-green text-white"
             onClick={() => setShowAddForm(true)}
@@ -334,15 +344,27 @@ export default function ContactsPage() {
       </div>
 
       {/* Sync Status Message */}
-      {syncMessage && (
-        <div className={`mb-6 p-4 neo-border flex items-center gap-2 ${
-          syncStatus === 'success' ? 'bg-green-50 text-green-800' :
-          syncStatus === 'error' ? 'bg-red-50 text-red-800' :
-          'bg-blue-50 text-blue-800'
-        }`}>
-          {syncStatus === 'success' && <Check className="w-5 h-5" />}
-          {syncStatus === 'error' && <AlertCircle className="w-5 h-5" />}
-          {syncStatus === 'loading' && <Loader2 className="w-5 h-5 animate-spin" />}
+      {syncMessage && syncStatus === 'success' && (
+        <SuccessAlert
+          title="Sync Complete"
+          description={syncMessage}
+          className="mb-6"
+        />
+      )}
+      {syncMessage && syncStatus === 'error' && (
+        <SmartAlert
+          message={{
+            title: 'Sync Failed',
+            description: syncMessage,
+            severity: 'error',
+            action: syncMessage.includes('Settings') ? { text: 'Go to Settings', href: '/settings' } : undefined,
+          }}
+          className="mb-6"
+        />
+      )}
+      {syncMessage && syncStatus === 'loading' && (
+        <div className="mb-6 p-4 neo-border flex items-center gap-2 bg-blue-50 text-blue-800 border-blue-300">
+          <Loader2 className="w-5 h-5 animate-spin" />
           {syncMessage}
         </div>
       )}

app/page.tsx

@@ -1,5 +1,6 @@
 'use client'
 
+import { useState, useEffect } from 'react'
 import Link from 'next/link'
 import {
   Mail,
@@ -13,11 +14,41 @@ import {
   Newspaper
 } from 'lucide-react'
 import { Button } from '@/components/ui/button'
+import { WelcomeModal } from '@/components/onboarding/WelcomeModal'
+import { SetupProgress } from '@/components/progress/SetupProgress'
+
+const ONBOARDING_KEY = 'email-platform-onboarding'
 
 export default function HomePage() {
+  const [showWelcome, setShowWelcome] = useState(false)
+
+  useEffect(() => {
+    // Check if this is the first visit
+    const saved = localStorage.getItem(ONBOARDING_KEY)
+    if (!saved) {
+      setShowWelcome(true)
+    }
+  }, [])
+
+  const handleWelcomeComplete = () => {
+    localStorage.setItem(ONBOARDING_KEY, JSON.stringify({
+      hasCompletedWelcome: true,
+      completedAt: new Date().toISOString(),
+    }))
+    setShowWelcome(false)
+  }
+
   return (
     <div className="p-8">
-      {/* 页面标题 */}
+      {/* Welcome Modal for first-time visitors */}
+      {showWelcome && (
+        <WelcomeModal
+          onGetStarted={handleWelcomeComplete}
+          onSkip={handleWelcomeComplete}
+        />
+      )}
+
+      {/* Page Header */}
       <div className="mb-8">
         <h1 className="text-4xl font-black uppercase tracking-tight mb-2">
           Email Template Platform
@@ -27,7 +58,10 @@ export default function HomePage() {
         </p>
       </div>
 
-      {/* 快速操作卡片 */}
+      {/* Setup Progress - shows until all steps are complete */}
+      <SetupProgress />
+
+      {/* Quick Action Cards */}
       <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-6 mb-12">
         <QuickActionCard
           icon={<Palette className="w-8 h-8" />}

app/send/page.tsx

@@ -21,6 +21,9 @@ import {
 import { Button } from '@/components/ui/button'
 import { Input } from '@/components/ui/input'
 import { Card } from '@/components/ui/card'
+import { SmartAlert } from '@/components/shared/SmartAlert'
+
+const EMAILS_SENT_KEY = 'email-platform-emails-sent'
 
 const TEMPLATES_STORAGE_KEY = 'email-platform-templates'
 const CONTACTS_STORAGE_KEY = 'email-platform-contacts'
@@ -475,18 +478,7 @@ function StepRecipients({
     return (
       <div>
         <h2 className="text-xl font-bold mb-4">Select Recipients</h2>
-        <div className="flex items-center gap-2 p-4 bg-amber-50 border-2 border-amber-200 mb-4">
-          <AlertCircle className="w-5 h-5 text-amber-600" />
-          <span className="text-amber-700">
-            No contacts found. Please add contacts first.
-          </span>
-        </div>
-        <Link href="/contacts">
-          <Button className="neo-button bg-neo-green text-white">
-            Go to Contacts
-            <ArrowRight className="w-4 h-4 ml-2" />
-          </Button>
-        </Link>
+        <SmartAlert errorCode="NO_CONTACTS" className="mb-4" />
       </div>
     )
   }
@@ -871,26 +863,36 @@ function StepSend({
 
     setSending(false)
     setSent(true)
+
+    // Track successful sends for progress tracking
+    const successfulSends = sendResults.filter(r => r.success).length
+    if (successfulSends > 0) {
+      try {
+        const current = parseInt(localStorage.getItem(EMAILS_SENT_KEY) || '0', 10)
+        localStorage.setItem(EMAILS_SENT_KEY, String(current + successfulSends))
+      } catch (e) {
+        console.error('Failed to track emails sent:', e)
+      }
+    }
   }
 
   if (!sent) {
     return (
       <div className="text-center">
         {error && (
-          <div className="flex items-center gap-2 p-4 bg-red-50 border-2 border-red-200 mb-6 text-left">
-            <AlertCircle className="w-5 h-5 text-red-600" />
-            <span className="text-red-700">{error}</span>
-          </div>
+          <SmartAlert
+            message={{
+              title: 'Configuration Required',
+              description: error,
+              severity: 'error',
+              action: { text: 'Go to Settings', href: '/settings' },
+            }}
+            className="mb-6 text-left"
+          />
         )}
 
-        {!settings.apiKey && (
-          <div className="flex items-center gap-2 p-4 bg-amber-50 border-2 border-amber-200 mb-6 text-left">
-            <AlertCircle className="w-5 h-5 text-amber-600" />
-            <span className="text-amber-700">
-              Please configure your Resend API Key in{' '}
-              <Link href="/settings" className="underline font-bold">Settings</Link>
-            </span>
-          </div>
+        {!settings.apiKey && !error && (
+          <SmartAlert errorCode="API_KEY_MISSING" className="mb-6 text-left" />
         )}
 
         <Send className="w-16 h-16 mx-auto mb-4 text-neo-green" />

app/settings/page.tsx

@@ -7,6 +7,8 @@ import { Input } from '@/components/ui/input'
 import { Label } from '@/components/ui/label'
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card'
 import { useToast } from '@/components/ui/use-toast'
+import { ApiKeySetupGuide } from '@/components/settings/ApiKeySetupGuide'
+import { HelpButton } from '@/components/help/HelpButton'
 
 interface Settings {
   resendApiKey: string
@@ -100,7 +102,10 @@ export default function SettingsPage() {
           </CardHeader>
           <CardContent className="space-y-4">
             <div className="space-y-2">
-              <Label htmlFor="apiKey">Resend API Key</Label>
+              <div className="flex items-center gap-2">
+                <Label htmlFor="apiKey">Resend API Key</Label>
+                <HelpButton topic="resend-api-key" />
+              </div>
               <div className="relative">
                 <Input
                   id="apiKey"
@@ -122,10 +127,15 @@ export default function SettingsPage() {
                   )}
                 </button>
               </div>
+              {/* Show setup guide when API key is empty */}
+              {!settings.resendApiKey && <ApiKeySetupGuide />}
             </div>
 
             <div className="space-y-2">
-              <Label htmlFor="audienceId">Audience ID (Optional)</Label>
+              <div className="flex items-center gap-2">
+                <Label htmlFor="audienceId">Audience ID (Optional)</Label>
+                <HelpButton topic="audience-id" />
+              </div>
               <Input
                 id="audienceId"
                 placeholder="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
@@ -155,7 +165,10 @@ export default function SettingsPage() {
           </CardHeader>
           <CardContent className="space-y-4">
             <div className="space-y-2">
-              <Label htmlFor="senderName">Sender Name</Label>
+              <div className="flex items-center gap-2">
+                <Label htmlFor="senderName">Sender Name</Label>
+                <HelpButton topic="sender-name" />
+              </div>
               <Input
                 id="senderName"
                 placeholder="Your Name"
@@ -166,7 +179,10 @@ export default function SettingsPage() {
             </div>
 
             <div className="space-y-2">
-              <Label htmlFor="senderEmail">Sender Email</Label>
+              <div className="flex items-center gap-2">
+                <Label htmlFor="senderEmail">Sender Email</Label>
+                <HelpButton topic="sender-email" />
+              </div>
               <Input
                 id="senderEmail"
                 type="email"
@@ -176,7 +192,8 @@ export default function SettingsPage() {
                 className="neo-border"
               />
               <p className="text-xs text-gray-500">
-                Must be a verified domain in your Resend account
+                Must be a verified domain in your Resend account.
+                For testing, you can use <code className="bg-gray-100 px-1 rounded">delivered@resend.dev</code>
               </p>
             </div>
           </CardContent>