From e706be2d22c2a8c5364fe8279e9649718ec554cc Mon Sep 17 00:00:00 2001
From: Aryan-Agarwal-creator <aryanagarwal7612@gmail.com>
Date: Wed, 3 Jun 2026 02:38:44 +0530
Subject: [PATCH 1/2] enhancements done

---
 app/page.tsx                       | 560 +++++++++++++++++++++--------
 components/AnimatedStatsBanner.tsx | 290 +++++++++++++++
 components/HowItWorks.tsx          | 239 ++++++++++++
 components/UsernameInput.tsx       | 294 +++++++++++++++
 4 files changed, 1236 insertions(+), 147 deletions(-)
 create mode 100644 components/AnimatedStatsBanner.tsx
 create mode 100644 components/HowItWorks.tsx
 create mode 100644 components/UsernameInput.tsx

diff --git a/app/page.tsx b/app/page.tsx
index c1ef63b3d..59a3ce505 100644
--- a/app/page.tsx
+++ b/app/page.tsx
@@ -6,22 +6,30 @@ import { useRef, useState, useEffect } from 'react';
 import { AnimatePresence, motion } from 'framer-motion';
 import { gsap } from 'gsap';
 import { useGSAP } from '@gsap/react';
-import { X } from 'lucide-react';
 
 import { CommitPulseLogo } from '@/components/commitpulse-logo';
 import { CustomizeCTA } from './components/CustomizeCTA';
 import { useRecentSearches } from '@/hooks/useRecentSearches';
 import { useDebounce } from '@/hooks/useDebounce';
 import { Footer } from '@/app/components/Footer';
+import { UsernameInput } from '@/components/UsernameInput';
+import { HowItWorks } from '@/components/HowItWorks';
+import { AnimatedStatsBanner } from '@/components/AnimatedStatsBanner';
 
 import { FeatureCard, FeatureCardsSection } from '@/components/FeatureCards';
 import { DiscordButton } from '@/components/DiscordButton';
 
 import { WallOfLove } from '@/components/WallOfLove';
 
+/** Well-known GitHub accounts used as sample demo chips */
+const DEMO_USERNAMES = ['torvalds', 'gaearon', 'vercel', 'sindresorhus'];
+
+/** The fallback sample account shown before first search */
+const SAMPLE_USERNAME = 'torvalds';
+
 const Icons = {
   Github: () => (
-    <svg height="24" width="24" viewBox="0 0 16 16" fill="currentColor">
+    <svg height="24" width="24" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true">
       <path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z" />
     </svg>
   ),
@@ -36,6 +44,7 @@ const Icons = {
       strokeWidth="2"
       strokeLinecap="round"
       strokeLinejoin="round"
+      aria-hidden="true"
     >
       <rect width="14" height="14" x="8" y="8" rx="2" ry="2" />
       <path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2" />
@@ -52,6 +61,7 @@ const Icons = {
       strokeWidth="2"
       strokeLinecap="round"
       strokeLinejoin="round"
+      aria-hidden="true"
     >
       <path d="M13 2 L3 14 L12 14 L11 22 L21 10 L12 10 L13 2 Z" />
     </svg>
@@ -68,10 +78,29 @@ const Icons = {
       strokeWidth="3"
       strokeLinecap="round"
       strokeLinejoin="round"
+      aria-hidden="true"
     >
       <polyline points="20 6 9 17 4 12" />
     </svg>
   ),
+  BadgeIcon: () => (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="18"
+      height="18"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <path d="M3.85 8.62a4 4 0 0 1 4.78-4.77 4 4 0 0 1 6.74 0 4 4 0 0 1 4.78 4.78 4 4 0 0 1 0 6.74 4 4 0 0 1-4.77 4.78 4 4 0 0 1-6.75 0 4 4 0 0 1-4.78-4.77 4 4 0 0 1 0-6.76Z" />
+      <line x1="9" x2="15" y1="12" y2="12" />
+      <line x1="12" x2="12" y1="9" y2="15" />
+    </svg>
+  ),
 };
 
 export default function LandingPage() {
@@ -88,11 +117,29 @@ export default function LandingPage() {
   const { searches, addSearch, clearSearches, removeSearch } = useRecentSearches();
   const [mounted, setMounted] = useState(false);
 
+  // Recent search avatar cache
+  const [recentAvatars, setRecentAvatars] = useState<Record<string, string>>({});
+
   useEffect(() => {
     // eslint-disable-next-line react-hooks/set-state-in-effect
     setMounted(true);
   }, []);
 
+  // Prefetch avatars for recent searches
+  useEffect(() => {
+    searches.forEach((s) => {
+      if (!recentAvatars[s]) {
+        const url = `https://avatars.githubusercontent.com/${s}?size=40`;
+        const img = new Image();
+        img.src = url;
+        img.onload = () => {
+          setRecentAvatars((prev) => ({ ...prev, [s]: url }));
+        };
+      }
+    });
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [searches]);
+
   useGSAP(
     () => {
       if (!heroRef.current) return;
@@ -121,14 +168,23 @@ export default function LandingPage() {
   const debouncedUsername = useDebounce(trimmedUsername, 500);
   const hasUsername = debouncedUsername.length > 0;
 
-  const badgeUrl = `/api/streak?user=${debouncedUsername}`;
+  // Whether to show sample (torvalds) or user's actual badge
+  const showSample = !hasUsername;
+
+  const activeBadgeUser = showSample ? SAMPLE_USERNAME : debouncedUsername;
+  const badgeUrl = `/api/streak?user=${activeBadgeUser}`;
   const siteUrl = process.env.NEXT_PUBLIC_SITE_URL ?? 'https://commitpulse.vercel.app';
   const markdown = `![CommitPulse](${siteUrl}/api/streak?user=${trimmedUsername})`;
 
   // Derived — automatically false when debouncedUsername changes
-  const badgeLoaded =
-    badgeResult?.username === debouncedUsername && badgeResult?.status === 'loaded';
-  const badgeError = badgeResult?.username === debouncedUsername && badgeResult?.status === 'error';
+  const badgeLoaded = badgeResult?.username === activeBadgeUser && badgeResult?.status === 'loaded';
+  const badgeError = badgeResult?.username === activeBadgeUser && badgeResult?.status === 'error';
+
+  // When switching from sample to user, reset badge result
+  useEffect(() => {
+    // eslint-disable-next-line react-hooks/set-state-in-effect
+    setBadgeResult(null);
+  }, [activeBadgeUser]);
 
   const copyToClipboard = async () => {
     if (trimmedUsername.length === 0) return;
@@ -151,12 +207,13 @@ export default function LandingPage() {
 
   return (
     <div className="min-h-screen overflow-x-hidden bg-transparent font-sans text-black dark:text-white selection:bg-black/20 dark:selection:bg-white/20">
-      <div className="pointer-events-none fixed inset-0 overflow-hidden">
+      <div className="pointer-events-none fixed inset-0 overflow-hidden" aria-hidden="true">
         <div className="absolute -left-[10%] -top-[10%] h-[40%] w-[40%] rounded-full bg-emerald-500/5 blur-[120px]" />
         <div className="absolute -right-[10%] top-[20%] h-[30%] w-[30%] rounded-full bg-cyan-500/5 blur-[120px]" />
       </div>
 
       <main className="relative z-10 mx-auto max-w-6xl px-6 mt-32">
+        {/* ── Hero ── */}
         <div className="mb-16 text-center">
           <DiscordButton />
 
@@ -181,194 +238,394 @@ export default function LandingPage() {
           </motion.p>
         </div>
 
-        <section className="mx-auto mb-32 max-w-4xl relative z-20">
+        {/* ── Input + Badge Section ── */}
+        <section className="mx-auto mb-32 max-w-4xl relative z-20" aria-label="Badge generator">
           <div className="rounded-3xl border border-black/5 bg-white/60 p-4 shadow-xl shadow-black/5 backdrop-blur-xl dark:border-white/10 dark:bg-[#0a0a0a]/80 dark:shadow-2xl dark:shadow-black/50 md:p-8">
             <form
               onSubmit={(e) => {
                 e.preventDefault();
                 copyToClipboard();
               }}
-              className="flex flex-col sm:flex-row gap-4 w-full"
+              noValidate
             >
-              <div className="relative flex-1 flex items-center flex-col">
-                <div className="relative flex-1 flex items-center w-full">
-                  <input
-                    type="text"
-                    suppressHydrationWarning
-                    placeholder="Enter GitHub Username"
-                    className="flex-1 rounded-2xl border border-black/10 bg-white px-5 py-4 text-sm text-black outline-none transition-all duration-300 placeholder:text-gray-400 focus:outline-none focus:ring-2 focus:ring-emerald-400 focus:border-transparent dark:border-white/10 dark:bg-black/60 dark:text-white dark:placeholder:text-gray-500 shadow-inner"
-                    value={username}
-                    onChange={(e) => setUsername(e.target.value)}
-                    maxLength={39}
-                  />
-                  {username.length > 0 ? (
+              {/* ── Demo username chips — Phase 5 ── */}
+              <div className="mb-4">
+                <p className="mb-2.5 text-xs font-semibold uppercase tracking-[0.18em] text-gray-400 dark:text-white/40">
+                  Try a quick example
+                </p>
+                <div
+                  className="flex flex-wrap gap-2"
+                  role="group"
+                  aria-label="Quick-start example usernames"
+                >
+                  {DEMO_USERNAMES.map((demo) => (
                     <button
-                      onClick={() => setUsername('')}
-                      className="absolute right-4 top-1/2 -translate-y-1/2 text-gray-500 transition-colors hover:text-black dark:text-white/65 dark:hover:text-white"
-                      aria-label="Clear input"
+                      key={demo}
                       type="button"
+                      onClick={() => setUsername(demo)}
+                      aria-label={`Try username ${demo}`}
+                      aria-pressed={trimmedUsername === demo}
+                      className={`inline-flex items-center gap-1.5 rounded-full border px-3 py-1.5 text-xs font-semibold transition-all duration-200 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-emerald-400 focus-visible:ring-offset-1 ${
+                        trimmedUsername === demo
+                          ? 'border-emerald-400/60 bg-emerald-500/15 text-emerald-700 dark:text-emerald-300 scale-[1.05]'
+                          : 'border-black/10 bg-white text-gray-600 hover:border-emerald-400/40 hover:bg-emerald-50 hover:text-emerald-700 hover:scale-[1.04] dark:border-white/10 dark:bg-white/5 dark:text-white/65 dark:hover:border-emerald-400/30 dark:hover:bg-emerald-500/10 dark:hover:text-emerald-300'
+                      } active:scale-[0.97]`}
                     >
-                      <X size={18} />
+                      <span className="opacity-50" aria-hidden="true">
+                        @
+                      </span>
+                      {demo}
                     </button>
-                  ) : null}
+                  ))}
                 </div>
-                {mounted && username.length === 0 && (
-                  <p className="text-amber-500 text-xs mt-1 self-start pl-1">
-                    Please enter a GitHub username to copy your badge link.
-                  </p>
-                )}
-                {username.length === 39 && (
-                  <p className="text-red-500 text-xs mt-1 self-start pl-1">
-                    GitHub username limit reached (39 characters maximum)
-                  </p>
-                )}
               </div>
-              <div className="flex flex-col sm:flex-row gap-4">
-                <button
-                  type="submit"
-                  suppressHydrationWarning
-                  disabled={!mounted || trimmedUsername.length === 0}
-                  className={`relative flex min-w-[160px] items-center justify-center gap-2 overflow-hidden rounded-2xl px-6 py-4 text-sm font-semibold transition-all duration-300 transform cursor-pointer hover:scale-[1.02] hover:shadow-lg active:scale-[0.98] disabled:cursor-not-allowed ${
-                    mounted && trimmedUsername.length > 0
-                      ? 'bg-black text-white hover:bg-zinc-800 dark:bg-white dark:text-black dark:hover:bg-gray-100 shadow-md'
-                      : 'bg-gray-100 text-gray-400 dark:bg-white/5 dark:text-white/55'
-                  }`}
-                >
-                  <AnimatePresence mode="wait">
-                    {copied ? (
-                      <motion.div
-                        key="check"
-                        initial={{ y: 10 }}
-                        animate={{ y: 0 }}
-                        className="flex items-center gap-2"
-                      >
-                        <Icons.Check /> Copied
-                      </motion.div>
-                    ) : (
-                      <motion.div
-                        key="copy"
-                        initial={{ y: -10 }}
-                        animate={{ y: 0 }}
-                        className="flex items-center gap-2"
-                      >
-                        <Icons.Copy /> Copy Link
-                      </motion.div>
+
+              {/* ── Input row ── */}
+              <div className="flex flex-col sm:flex-row gap-4 w-full">
+                {/* Phase 4 — enhanced input with avatar validation */}
+                <UsernameInput
+                  value={username}
+                  onChange={setUsername}
+                  onClear={() => setUsername('')}
+                />
+
+                {/* ── Action buttons ── */}
+                <div className="flex flex-col sm:flex-row gap-3 shrink-0">
+                  {/* Phase 3 — Primary CTA "Generate My Badge" */}
+                  <button
+                    type="submit"
+                    id="generate-badge-btn"
+                    suppressHydrationWarning
+                    disabled={!mounted || trimmedUsername.length === 0}
+                    aria-label={
+                      trimmedUsername.length === 0
+                        ? 'Enter a GitHub username to generate your badge'
+                        : `Generate badge for ${trimmedUsername}`
+                    }
+                    className={`relative flex min-w-[180px] items-center justify-center gap-2 overflow-hidden rounded-2xl px-6 py-4 text-sm font-bold transition-all duration-300 transform cursor-pointer focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-emerald-400 focus-visible:ring-offset-2 disabled:cursor-not-allowed ${
+                      mounted && trimmedUsername.length > 0
+                        ? 'bg-gradient-to-r from-emerald-500 to-cyan-500 text-white shadow-lg shadow-emerald-500/25 hover:shadow-emerald-500/40 hover:scale-[1.03] active:scale-[0.97] hover:from-emerald-400 hover:to-cyan-400'
+                        : 'bg-gray-100 text-gray-400 dark:bg-white/5 dark:text-white/35 shadow-none'
+                    }`}
+                  >
+                    {/* Shimmer overlay on active state */}
+                    {mounted && trimmedUsername.length > 0 && (
+                      <span
+                        className="pointer-events-none absolute inset-0 -translate-x-full animate-[shimmer_2s_infinite] bg-gradient-to-r from-transparent via-white/20 to-transparent"
+                        aria-hidden="true"
+                      />
                     )}
-                  </AnimatePresence>
-                </button>
-                <Link
-                  href={
-                    mounted && trimmedUsername.length > 0 ? `/dashboard/${trimmedUsername}` : '/'
-                  }
-                  suppressHydrationWarning
-                  aria-disabled={!mounted || trimmedUsername.length === 0}
-                  onClick={(e) => {
-                    if (!mounted || trimmedUsername.length === 0) {
-                      e.preventDefault();
-                    } else {
-                      trackUser(trimmedUsername);
-                      addSearch(trimmedUsername);
+
+                    <AnimatePresence mode="wait">
+                      {copied ? (
+                        <motion.div
+                          key="check"
+                          initial={{ y: 10, opacity: 0 }}
+                          animate={{ y: 0, opacity: 1 }}
+                          exit={{ y: -10, opacity: 0 }}
+                          className="flex items-center gap-2"
+                        >
+                          <Icons.Check /> Copied!
+                        </motion.div>
+                      ) : (
+                        <motion.div
+                          key="generate"
+                          initial={{ y: -10, opacity: 0 }}
+                          animate={{ y: 0, opacity: 1 }}
+                          exit={{ y: 10, opacity: 0 }}
+                          className="flex items-center gap-2"
+                        >
+                          <Icons.BadgeIcon /> Generate My Badge
+                        </motion.div>
+                      )}
+                    </AnimatePresence>
+                  </button>
+
+                  {/* Secondary: Watch Dashboard */}
+                  <Link
+                    href={
+                      mounted && trimmedUsername.length > 0 ? `/dashboard/${trimmedUsername}` : '/'
                     }
-                  }}
-                  className={`relative flex min-w-[160px] items-center justify-center gap-2 overflow-hidden rounded-2xl border px-6 py-4 text-sm font-semibold transition-all duration-300 hover:scale-[1.02] hover:shadow-lg active:scale-[0.98] ${
-                    mounted && trimmedUsername.length > 0
-                      ? 'border-black/10 bg-white text-black hover:bg-gray-50 dark:border-white/10 dark:bg-white/5 dark:text-white dark:hover:bg-white/10 shadow-sm'
-                      : 'border-black/5 bg-gray-50 text-gray-400 dark:border-white/5 dark:bg-transparent dark:text-white/55'
-                  }`}
-                >
-                  Watch Dashboard
-                </Link>
+                    suppressHydrationWarning
+                    aria-disabled={!mounted || trimmedUsername.length === 0}
+                    aria-label={
+                      trimmedUsername.length > 0
+                        ? `View dashboard for ${trimmedUsername}`
+                        : 'Enter a username to view dashboard'
+                    }
+                    onClick={(e) => {
+                      if (!mounted || trimmedUsername.length === 0) {
+                        e.preventDefault();
+                      } else {
+                        trackUser(trimmedUsername);
+                        addSearch(trimmedUsername);
+                      }
+                    }}
+                    className={`relative flex min-w-[160px] items-center justify-center gap-2 overflow-hidden rounded-2xl border px-6 py-4 text-sm font-semibold transition-all duration-300 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-emerald-400 focus-visible:ring-offset-2 hover:scale-[1.02] hover:shadow-lg active:scale-[0.98] ${
+                      mounted && trimmedUsername.length > 0
+                        ? 'border-black/10 bg-white text-black hover:bg-gray-50 dark:border-white/10 dark:bg-white/5 dark:text-white dark:hover:bg-white/10 shadow-sm'
+                        : 'border-black/5 bg-gray-50 text-gray-400 dark:border-white/5 dark:bg-transparent dark:text-white/35'
+                    }`}
+                  >
+                    Watch Dashboard
+                  </Link>
+                </div>
               </div>
             </form>
           </div>
 
+          {/* ── Phase 7: Enhanced recent searches with avatars ── */}
           {searches.length > 0 && (
-            <div className="flex flex-wrap items-center gap-2 mb-6 mt-3">
-              <span className="text-xs text-[#A1A1AA]">Recent:</span>
+            <motion.div
+              initial={{ opacity: 0, y: -8 }}
+              animate={{ opacity: 1, y: 0 }}
+              className="flex flex-wrap items-center gap-2 mb-6 mt-4"
+              role="region"
+              aria-label="Recent searches"
+            >
+              <span className="text-xs font-semibold uppercase tracking-[0.15em] text-gray-400 dark:text-[#A1A1AA]">
+                Recent:
+              </span>
               {searches.map((s) => (
                 <span
                   key={s}
-                  className="inline-flex items-center gap-1.5 rounded-full border border-[rgba(255,255,255,0.08)] bg-[#111] pl-3 pr-2 py-1 text-xs text-white/70 transition-all hover:border-[rgba(255,255,255,0.2)] hover:text-white group/pill"
+                  className="inline-flex items-center gap-1.5 rounded-full border border-[rgba(0,0,0,0.08)] bg-white pl-1.5 pr-2 py-1 text-xs text-gray-700 shadow-sm transition-all hover:border-black/20 hover:shadow-md group/pill dark:border-[rgba(255,255,255,0.08)] dark:bg-[#111] dark:text-white/70 dark:hover:border-[rgba(255,255,255,0.2)] dark:hover:text-white"
                 >
+                  {/* Avatar thumbnail */}
+                  {recentAvatars[s] ? (
+                    <img
+                      src={recentAvatars[s]}
+                      alt=""
+                      width={18}
+                      height={18}
+                      className="h-[18px] w-[18px] rounded-full object-cover ring-1 ring-black/10 dark:ring-white/10 shrink-0"
+                      aria-hidden="true"
+                    />
+                  ) : (
+                    <span
+                      className="flex h-[18px] w-[18px] shrink-0 items-center justify-center rounded-full bg-gradient-to-br from-emerald-400 to-cyan-500 text-[8px] font-bold text-white"
+                      aria-hidden="true"
+                    >
+                      {s[0]?.toUpperCase()}
+                    </span>
+                  )}
+
                   <button
                     type="button"
                     onClick={() => setUsername(s)}
-                    className="transition-colors hover:text-white"
+                    aria-label={`Search again for ${s}`}
+                    className="transition-colors hover:text-black dark:hover:text-white font-medium"
                   >
                     {s}
                   </button>
+
+                  {/* Quick regenerate */}
+                  <button
+                    type="button"
+                    onClick={() => {
+                      setUsername(s);
+                      // Slight delay to allow state update before form submission
+                      setTimeout(() => {
+                        const form = document.querySelector('form');
+                        if (form) {
+                          const event = new Event('submit', { bubbles: true, cancelable: true });
+                          form.dispatchEvent(event);
+                        }
+                      }, 50);
+                    }}
+                    aria-label={`Regenerate badge for ${s}`}
+                    className="rounded-full p-0.5 text-gray-400 hover:bg-emerald-500/15 hover:text-emerald-600 transition-all flex items-center justify-center dark:text-white/40 dark:hover:text-emerald-400"
+                    title="Regenerate"
+                  >
+                    <svg
+                      xmlns="http://www.w3.org/2000/svg"
+                      width="10"
+                      height="10"
+                      viewBox="0 0 24 24"
+                      fill="none"
+                      stroke="currentColor"
+                      strokeWidth="2.5"
+                      strokeLinecap="round"
+                      strokeLinejoin="round"
+                      aria-hidden="true"
+                    >
+                      <path d="M13 2 L3 14 L12 14 L11 22 L21 10 L12 10 L13 2 Z" />
+                    </svg>
+                  </button>
+
+                  {/* Remove */}
                   <button
                     type="button"
                     onClick={() => removeSearch(s)}
-                    className="rounded-full p-0.5 text-white/40 hover:bg-white/10 hover:text-white transition-all flex items-center justify-center"
+                    className="rounded-full p-0.5 text-gray-300 hover:bg-red-500/15 hover:text-red-500 transition-all flex items-center justify-center dark:text-white/30 dark:hover:text-red-400"
                     aria-label={`Remove ${s} from recent searches`}
                   >
-                    <X size={10} />
+                    <svg
+                      xmlns="http://www.w3.org/2000/svg"
+                      width="10"
+                      height="10"
+                      viewBox="0 0 24 24"
+                      fill="none"
+                      stroke="currentColor"
+                      strokeWidth="3"
+                      strokeLinecap="round"
+                      strokeLinejoin="round"
+                      aria-hidden="true"
+                    >
+                      <line x1="18" y1="6" x2="6" y2="18" />
+                      <line x1="6" y1="6" x2="18" y2="18" />
+                    </svg>
                   </button>
                 </span>
               ))}
               <button
                 onClick={clearSearches}
-                className="text-xs text-[#A1A1AA] underline hover:text-white transition-colors"
+                className="text-xs text-gray-400 underline hover:text-black transition-colors dark:text-[#A1A1AA] dark:hover:text-white"
+                aria-label="Clear all recent searches"
               >
-                Clear
+                Clear all
               </button>
-            </div>
+            </motion.div>
           )}
 
-          <div className="group relative mt-10">
-            <div className="absolute -inset-1 rounded-[2.5rem] bg-gradient-to-r from-emerald-500/20 to-cyan-500/20 opacity-50 blur-2xl transition duration-1000 group-hover:opacity-100" />
-            <div className="relative flex min-h-[480px] md:min-h-[520px] items-center justify-center overflow-hidden rounded-3xl border border-black/5 bg-white/50 p-8 backdrop-blur-xl shadow-2xl dark:border-white/10 dark:bg-[#0a0a0a]/80">
-              {hasUsername ? (
-                <div className="w-full flex flex-col items-center justify-center gap-4">
-                  {!badgeLoaded && !badgeError && (
-                    <div className="h-[240px] w-full max-w-[700px] rounded-2xl bg-black/5 dark:bg-white/5 animate-pulse" />
-                  )}
-                  {badgeError && (
-                    <div className="flex flex-col items-center justify-center gap-4 py-12 text-center">
-                      <div className="flex h-16 w-16 items-center justify-center rounded-3xl border border-red-500/20 bg-red-500/10 shadow-inner">
-                        <X size={32} className="text-red-500" />
-                      </div>
-                      <div>
-                        <p className="text-lg font-bold text-gray-900 dark:text-white tracking-tight">
-                          GitHub user not found
-                        </p>
-                        <p className="text-sm text-gray-500 dark:text-white/65 mt-1">
-                          Please check the username and try again.
-                        </p>
-                      </div>
+          {/* ── Phase 6: Animated stats banner ── */}
+          <div className="mt-6">
+            <AnimatedStatsBanner
+              showDemo={showSample}
+              username={hasUsername ? debouncedUsername : undefined}
+            />
+          </div>
+
+          {/* ── Badge Preview Area (Phase 2 — sample + Phase 9 — skeleton) ── */}
+          <div className="group relative">
+            <div
+              className="absolute -inset-1 rounded-[2.5rem] bg-gradient-to-r from-emerald-500/20 to-cyan-500/20 opacity-50 blur-2xl transition duration-1000 group-hover:opacity-100"
+              aria-hidden="true"
+            />
+            <div
+              className="relative flex min-h-[480px] md:min-h-[520px] items-center justify-center overflow-hidden rounded-3xl border border-black/5 bg-white/50 p-8 backdrop-blur-xl shadow-2xl dark:border-white/10 dark:bg-[#0a0a0a]/80"
+              role="region"
+              aria-label={
+                showSample
+                  ? 'Sample badge preview for torvalds'
+                  : `Badge preview for ${debouncedUsername}`
+              }
+              aria-live="polite"
+              aria-busy={!badgeLoaded && !badgeError && (hasUsername || showSample)}
+            >
+              {/* Sample preview label */}
+              <AnimatePresence>
+                {showSample && (
+                  <motion.div
+                    initial={{ opacity: 0, y: -8 }}
+                    animate={{ opacity: 1, y: 0 }}
+                    exit={{ opacity: 0, y: -8 }}
+                    transition={{ duration: 0.3 }}
+                    className="absolute top-4 left-1/2 -translate-x-1/2 z-10"
+                  >
+                    <span className="inline-flex items-center gap-1.5 rounded-full border border-amber-400/30 bg-amber-400/10 px-3 py-1 text-[10px] font-bold uppercase tracking-[0.2em] text-amber-600 backdrop-blur-sm dark:text-amber-400">
+                      <span
+                        className="h-1.5 w-1.5 rounded-full bg-amber-500 animate-pulse"
+                        aria-hidden="true"
+                      />
+                      Sample Preview — @torvalds
+                    </span>
+                  </motion.div>
+                )}
+              </AnimatePresence>
+
+              <div className="w-full flex flex-col items-center justify-center gap-4">
+                {/* Phase 9: Skeleton loader */}
+                {!badgeLoaded && !badgeError && (
+                  <div
+                    className="h-[240px] w-full max-w-[700px] rounded-2xl overflow-hidden"
+                    aria-label="Loading badge..."
+                    role="status"
+                  >
+                    <div className="h-full w-full bg-black/5 dark:bg-white/5 relative overflow-hidden">
+                      <div
+                        className="absolute inset-0 -translate-x-full animate-[shimmer_1.5s_infinite] bg-gradient-to-r from-transparent via-black/[0.04] to-transparent dark:via-white/[0.07]"
+                        aria-hidden="true"
+                      />
                     </div>
-                  )}
-                  <motion.img
-                    key={badgeUrl}
-                    data-testid="badge-img"
-                    src={badgeUrl}
-                    alt={`CommitPulse badge for ${debouncedUsername}`}
-                    initial={{ opacity: 0, scale: 0.95 }}
-                    animate={{ opacity: badgeLoaded ? 1 : 0, scale: badgeLoaded ? 1 : 0.95 }}
-                    transition={{ duration: 0.5, ease: 'easeOut' }}
-                    className="w-full max-w-[700px] h-auto drop-shadow-[0_30px_60px_rgba(0,0,0,0.15)] dark:drop-shadow-[0_30px_60px_rgba(0,0,0,0.5)]"
-                    onLoad={() => setBadgeResult({ username: debouncedUsername, status: 'loaded' })}
-                    onError={() => setBadgeResult({ username: debouncedUsername, status: 'error' })}
-                  />
-                </div>
-              ) : (
-                <div className="flex w-full max-w-2xl flex-col items-center justify-center rounded-3xl border border-dashed border-black/10 bg-black/[0.02] px-6 py-16 text-center dark:border-white/10 dark:bg-white/[0.02]">
-                  <div className="mb-6 flex h-16 w-16 items-center justify-center rounded-3xl border border-black/10 bg-white text-gray-600 shadow-sm dark:border-white/10 dark:bg-white/5 dark:text-white/80">
-                    <Icons.Github />
                   </div>
-                  <p className="text-xl font-bold tracking-tight text-gray-900 dark:text-white">
-                    Ready to visualize your rhythm?
-                  </p>
-                  <p className="mt-3 max-w-md text-sm leading-relaxed text-gray-500 dark:text-white/65">
-                    Enter a GitHub username above to instantly generate your streak badge.
-                  </p>
-                </div>
-              )}
+                )}
+
+                {/* Error state (only for actual user search, not sample) */}
+                {badgeError && hasUsername && (
+                  <motion.div
+                    initial={{ opacity: 0, scale: 0.95 }}
+                    animate={{ opacity: 1, scale: 1 }}
+                    className="flex flex-col items-center justify-center gap-4 py-12 text-center"
+                    role="alert"
+                  >
+                    <div className="flex h-16 w-16 items-center justify-center rounded-3xl border border-red-500/20 bg-red-500/10 shadow-inner">
+                      <svg
+                        xmlns="http://www.w3.org/2000/svg"
+                        width="28"
+                        height="28"
+                        viewBox="0 0 24 24"
+                        fill="none"
+                        stroke="#ef4444"
+                        strokeWidth="2"
+                        strokeLinecap="round"
+                        strokeLinejoin="round"
+                        aria-hidden="true"
+                      >
+                        <circle cx="12" cy="12" r="10" />
+                        <line x1="15" y1="9" x2="9" y2="15" />
+                        <line x1="9" y1="9" x2="15" y2="15" />
+                      </svg>
+                    </div>
+                    <div>
+                      <p className="text-lg font-bold text-gray-900 dark:text-white tracking-tight">
+                        GitHub user not found
+                      </p>
+                      <p className="text-sm text-gray-500 dark:text-white/65 mt-1">
+                        Please check the username and try again.
+                      </p>
+                    </div>
+                  </motion.div>
+                )}
+
+                {/* The actual badge image */}
+                <motion.img
+                  key={badgeUrl}
+                  data-testid="badge-img"
+                  src={badgeUrl}
+                  alt={
+                    showSample
+                      ? 'Sample CommitPulse badge showing torvalds GitHub contribution history'
+                      : `CommitPulse badge for ${debouncedUsername}`
+                  }
+                  initial={{ opacity: 0, scale: 0.95 }}
+                  animate={{ opacity: badgeLoaded ? 1 : 0, scale: badgeLoaded ? 1 : 0.95 }}
+                  transition={{ duration: 0.5, ease: 'easeOut' }}
+                  className="w-full max-w-[700px] h-auto drop-shadow-[0_30px_60px_rgba(0,0,0,0.15)] dark:drop-shadow-[0_30px_60px_rgba(0,0,0,0.5)]"
+                  onLoad={() => setBadgeResult({ username: activeBadgeUser, status: 'loaded' })}
+                  onError={() => setBadgeResult({ username: activeBadgeUser, status: 'error' })}
+                />
+
+                {/* CTA below sample: invite to generate own */}
+                <AnimatePresence>
+                  {showSample && badgeLoaded && (
+                    <motion.p
+                      initial={{ opacity: 0, y: 8 }}
+                      animate={{ opacity: 1, y: 0 }}
+                      exit={{ opacity: 0, y: 8 }}
+                      transition={{ delay: 0.4 }}
+                      className="text-xs text-gray-500 dark:text-white/50 text-center max-w-xs"
+                    >
+                      ↑ Enter your GitHub username above to generate your own 3D badge
+                    </motion.p>
+                  )}
+                </AnimatePresence>
+              </div>
             </div>
           </div>
         </section>
 
+        {/* ── Success guide after copy ── */}
         <div ref={guideRef}>
           <AnimatePresence>
             {copied && (
@@ -381,6 +638,9 @@ export default function LandingPage() {
           </AnimatePresence>
         </div>
 
+        {/* ── Phase 8: How It Works ── */}
+        <HowItWorks />
+
         <CustomizeCTA />
 
         <FeatureCardsSection>
@@ -458,13 +718,18 @@ function SuccessGuide({
       exit={{ opacity: 0, y: 24, scale: 0.97 }}
       transition={{ type: 'spring', stiffness: 260, damping: 28 }}
       className="mx-auto mb-12 max-w-4xl"
+      role="status"
+      aria-label="Badge copied — deployment guide"
     >
       <div className="relative overflow-hidden rounded-xl border border-black/10 bg-white dark:border-[rgba(255,255,255,0.1)] dark:bg-[#0a0a0a]">
-        <div className="pointer-events-none absolute -top-24 left-1/2 h-48 w-3/4 -translate-x-1/2 rounded-full bg-white/3 blur-[80px]" />
+        <div
+          className="pointer-events-none absolute -top-24 left-1/2 h-48 w-3/4 -translate-x-1/2 rounded-full bg-white/3 blur-[80px]"
+          aria-hidden="true"
+        />
 
         <div className="flex items-start justify-between border-b border-black/10 px-8 pb-6 pt-8 dark:border-white/5">
           <div className="flex items-center gap-4">
-            <span className="relative mt-1 flex h-2 w-2">
+            <span className="relative mt-1 flex h-2 w-2" aria-hidden="true">
               <span className="absolute inline-flex h-full w-full animate-ping rounded-full bg-black/40 opacity-40 dark:bg-white/70" />
               <span className="relative inline-flex h-2 w-2 rounded-full bg-black dark:bg-white shadow-[0_0_10px_rgba(255,255,255,0.9)]" />
             </span>
@@ -493,6 +758,7 @@ function SuccessGuide({
               strokeWidth="2.5"
               strokeLinecap="round"
               strokeLinejoin="round"
+              aria-hidden="true"
             >
               <line x1="18" y1="6" x2="6" y2="18" />
               <line x1="6" y1="6" x2="18" y2="18" />
diff --git a/components/AnimatedStatsBanner.tsx b/components/AnimatedStatsBanner.tsx
new file mode 100644
index 000000000..2037950e1
--- /dev/null
+++ b/components/AnimatedStatsBanner.tsx
@@ -0,0 +1,290 @@
+'use client';
+
+import { useRef, useState, useEffect } from 'react';
+import { motion, AnimatePresence } from 'framer-motion';
+
+interface StatItem {
+  label: string;
+  demoValue: number;
+  suffix?: string;
+  icon: React.ReactNode;
+  accentClass: string;
+  accentGlow: string;
+}
+
+const STATS: StatItem[] = [
+  {
+    label: 'Current Streak',
+    demoValue: 42,
+    suffix: 'd',
+    icon: (
+      <svg
+        xmlns="http://www.w3.org/2000/svg"
+        width="16"
+        height="16"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="2.5"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        aria-hidden="true"
+      >
+        <path d="M13 2 L3 14 L12 14 L11 22 L21 10 L12 10 L13 2 Z" />
+      </svg>
+    ),
+    accentClass: 'text-emerald-500',
+    accentGlow: 'rgba(16,185,129,0.12)',
+  },
+  {
+    label: 'Longest Streak',
+    demoValue: 127,
+    suffix: 'd',
+    icon: (
+      <svg
+        xmlns="http://www.w3.org/2000/svg"
+        width="16"
+        height="16"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="2.5"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        aria-hidden="true"
+      >
+        <polyline points="23 6 13.5 15.5 8.5 10.5 1 18" />
+        <polyline points="17 6 23 6 23 12" />
+      </svg>
+    ),
+    accentClass: 'text-cyan-500',
+    accentGlow: 'rgba(6,182,212,0.12)',
+  },
+  {
+    label: 'Total Contributions',
+    demoValue: 3847,
+    icon: (
+      <svg
+        xmlns="http://www.w3.org/2000/svg"
+        width="16"
+        height="16"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="2.5"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        aria-hidden="true"
+      >
+        <rect x="3" y="3" width="7" height="7" rx="1" />
+        <rect x="14" y="3" width="7" height="7" rx="1" />
+        <rect x="14" y="14" width="7" height="7" rx="1" />
+        <rect x="3" y="14" width="7" height="7" rx="1" />
+      </svg>
+    ),
+    accentClass: 'text-purple-500',
+    accentGlow: 'rgba(139,92,246,0.12)',
+  },
+  {
+    label: 'Public Repos',
+    demoValue: 58,
+    icon: (
+      <svg
+        xmlns="http://www.w3.org/2000/svg"
+        width="16"
+        height="16"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="2.5"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        aria-hidden="true"
+      >
+        <path d="M3 3h18v18H3z" rx="2" />
+        <path d="M3 9h18" />
+        <path d="M9 21V9" />
+      </svg>
+    ),
+    accentClass: 'text-orange-500',
+    accentGlow: 'rgba(249,115,22,0.12)',
+  },
+];
+
+function useCountUp(target: number, duration: number = 1200, active: boolean = false) {
+  const [count, setCount] = useState(0);
+  const frameRef = useRef<number | null>(null);
+  const startRef = useRef<number | null>(null);
+
+  useEffect(() => {
+    if (!active) {
+      // eslint-disable-next-line react-hooks/set-state-in-effect
+      setCount(0);
+      return;
+    }
+
+    const animate = (timestamp: number) => {
+      if (!startRef.current) startRef.current = timestamp;
+      const elapsed = timestamp - startRef.current;
+      const progress = Math.min(elapsed / duration, 1);
+      // Ease-out cubic
+      const eased = 1 - Math.pow(1 - progress, 3);
+      setCount(Math.round(eased * target));
+
+      if (progress < 1) {
+        frameRef.current = requestAnimationFrame(animate);
+      }
+    };
+
+    frameRef.current = requestAnimationFrame(animate);
+    return () => {
+      if (frameRef.current) cancelAnimationFrame(frameRef.current);
+      startRef.current = null;
+    };
+  }, [target, duration, active]);
+
+  return count;
+}
+
+function StatCard({ stat, active, delay }: { stat: StatItem; active: boolean; delay: number }) {
+  const count = useCountUp(stat.demoValue, 1400, active);
+
+  return (
+    <motion.div
+      initial={{ opacity: 0, y: 16 }}
+      animate={{ opacity: 1, y: 0 }}
+      transition={{ duration: 0.45, delay }}
+      className="group relative flex flex-1 flex-col items-center justify-center gap-1.5 rounded-2xl border border-black/5 bg-white/60 p-4 text-center backdrop-blur-xl shadow-sm transition-all duration-300 hover:-translate-y-0.5 hover:shadow-md dark:border-white/[0.08] dark:bg-[#0a0a0a]/80"
+      style={{
+        boxShadow: `0 0 0 0 ${stat.accentGlow}`,
+      }}
+    >
+      {/* Glow bg */}
+      <div
+        className="pointer-events-none absolute inset-0 rounded-2xl opacity-0 transition-opacity duration-500 group-hover:opacity-100"
+        style={{ background: `radial-gradient(circle, ${stat.accentGlow}, transparent 70%)` }}
+        aria-hidden="true"
+      />
+
+      {/* Icon */}
+      <span className={`relative z-10 ${stat.accentClass}`}>{stat.icon}</span>
+
+      {/* Animated number */}
+      <AnimatePresence mode="wait">
+        <motion.span
+          key={active ? 'counted' : 'idle'}
+          initial={{ opacity: 0, scale: 0.85 }}
+          animate={{ opacity: 1, scale: 1 }}
+          exit={{ opacity: 0, scale: 0.85 }}
+          transition={{ duration: 0.25 }}
+          className="relative z-10 text-xl font-black tracking-tight text-gray-900 dark:text-white"
+          aria-live="polite"
+          aria-label={`${stat.label}: ${active ? count : '—'}${stat.suffix ?? ''}`}
+        >
+          {active ? `${count.toLocaleString()}${stat.suffix ?? ''}` : '—'}
+        </motion.span>
+      </AnimatePresence>
+
+      {/* Label */}
+      <span className="relative z-10 text-[10px] font-semibold uppercase tracking-[0.15em] text-gray-400 dark:text-white/40">
+        {stat.label}
+      </span>
+    </motion.div>
+  );
+}
+
+interface AnimatedStatsBannerProps {
+  /** When true, show demo values with animated counters */
+  showDemo: boolean;
+  /** Username for the "View Dashboard" link */
+  username?: string;
+}
+
+export function AnimatedStatsBanner({ showDemo, username }: AnimatedStatsBannerProps) {
+  const ref = useRef<HTMLDivElement>(null);
+  const [hasBeenVisible, setHasBeenVisible] = useState(false);
+
+  useEffect(() => {
+    if (!ref.current) return;
+
+    const observer = new IntersectionObserver(
+      ([entry]) => {
+        if (entry.isIntersecting) {
+          setHasBeenVisible(true);
+          observer.disconnect();
+        }
+      },
+      { threshold: 0.2 }
+    );
+    observer.observe(ref.current);
+    return () => observer.disconnect();
+  }, []);
+
+  const isActive = showDemo && hasBeenVisible;
+
+  return (
+    <div ref={ref} className="mb-6">
+      {/* Sample label */}
+      <AnimatePresence>
+        {showDemo && (
+          <motion.div
+            initial={{ opacity: 0, y: -8 }}
+            animate={{ opacity: 1, y: 0 }}
+            exit={{ opacity: 0, y: -8 }}
+            className="mb-3 flex items-center justify-center gap-2"
+          >
+            <span className="inline-flex items-center gap-1.5 rounded-full border border-amber-400/30 bg-amber-400/10 px-2.5 py-0.5 text-[10px] font-semibold uppercase tracking-[0.18em] text-amber-600 dark:text-amber-400">
+              <span
+                className="h-1.5 w-1.5 rounded-full bg-amber-500 animate-pulse"
+                aria-hidden="true"
+              />
+              Sample Stats — torvalds
+            </span>
+          </motion.div>
+        )}
+        {!showDemo && username && (
+          <motion.div
+            initial={{ opacity: 0, y: -8 }}
+            animate={{ opacity: 1, y: 0 }}
+            exit={{ opacity: 0, y: -8 }}
+            className="mb-3 flex items-center justify-center"
+          >
+            <a
+              href={`/dashboard/${username}`}
+              className="inline-flex items-center gap-1.5 rounded-full border border-emerald-400/30 bg-emerald-400/10 px-3 py-1 text-[10px] font-semibold uppercase tracking-[0.18em] text-emerald-600 transition-all hover:border-emerald-400/60 hover:bg-emerald-400/20 dark:text-emerald-400"
+            >
+              View {username}&apos;s full dashboard
+              <svg
+                xmlns="http://www.w3.org/2000/svg"
+                width="10"
+                height="10"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="2.5"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                aria-hidden="true"
+              >
+                <path d="M5 12h14M12 5l7 7-7 7" />
+              </svg>
+            </a>
+          </motion.div>
+        )}
+      </AnimatePresence>
+
+      {/* Stat cards row */}
+      <div
+        className="flex flex-wrap gap-2 sm:flex-nowrap"
+        role="region"
+        aria-label={
+          showDemo ? 'Sample GitHub statistics for torvalds' : `GitHub statistics for ${username}`
+        }
+      >
+        {STATS.map((stat, i) => (
+          <StatCard key={stat.label} stat={stat} active={isActive} delay={i * 0.08} />
+        ))}
+      </div>
+    </div>
+  );
+}
diff --git a/components/HowItWorks.tsx b/components/HowItWorks.tsx
new file mode 100644
index 000000000..6b21d41b2
--- /dev/null
+++ b/components/HowItWorks.tsx
@@ -0,0 +1,239 @@
+'use client';
+
+import { useRef } from 'react';
+import { motion, useInView } from 'framer-motion';
+
+const HOW_IT_WORKS_STEPS = [
+  {
+    number: '01',
+    title: 'Enter GitHub Username',
+    description: 'Type any GitHub username into the search field above.',
+    icon: (
+      <svg
+        xmlns="http://www.w3.org/2000/svg"
+        width="22"
+        height="22"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        aria-hidden="true"
+      >
+        <circle cx="11" cy="11" r="8" />
+        <path d="m21 21-4.35-4.35" />
+      </svg>
+    ),
+    accent: 'from-emerald-500 to-cyan-500',
+    glow: 'rgba(16,185,129,0.15)',
+  },
+  {
+    number: '02',
+    title: 'Generate Badge',
+    description: 'Click "Generate My Badge" and watch your 3D city materialise instantly.',
+    icon: (
+      <svg
+        xmlns="http://www.w3.org/2000/svg"
+        width="22"
+        height="22"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        aria-hidden="true"
+      >
+        <path d="M13 2 L3 14 L12 14 L11 22 L21 10 L12 10 L13 2 Z" />
+      </svg>
+    ),
+    accent: 'from-cyan-500 to-blue-500',
+    glow: 'rgba(6,182,212,0.15)',
+  },
+  {
+    number: '03',
+    title: 'Copy the Snippet',
+    description: 'Hit copy and the Markdown snippet lands on your clipboard automatically.',
+    icon: (
+      <svg
+        xmlns="http://www.w3.org/2000/svg"
+        width="22"
+        height="22"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        aria-hidden="true"
+      >
+        <rect width="14" height="14" x="8" y="8" rx="2" ry="2" />
+        <path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2" />
+      </svg>
+    ),
+    accent: 'from-blue-500 to-purple-500',
+    glow: 'rgba(139,92,246,0.15)',
+  },
+  {
+    number: '04',
+    title: 'Add to README',
+    description: 'Paste into your GitHub profile README.md and commit. Your badge is live.',
+    icon: (
+      <svg
+        xmlns="http://www.w3.org/2000/svg"
+        width="22"
+        height="22"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        aria-hidden="true"
+      >
+        <path d="M14.5 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7.5L14.5 2z" />
+        <polyline points="14 2 14 8 20 8" />
+        <path d="M12 18v-6" />
+        <path d="M9 15l3 3 3-3" />
+      </svg>
+    ),
+    accent: 'from-purple-500 to-pink-500',
+    glow: 'rgba(236,72,153,0.15)',
+  },
+];
+
+const containerVariants = {
+  hidden: {},
+  visible: {
+    transition: {
+      staggerChildren: 0.12,
+    },
+  },
+};
+
+const cardVariants = {
+  hidden: { opacity: 0, y: 32, scale: 0.95 },
+  visible: {
+    opacity: 1,
+    y: 0,
+    scale: 1,
+    transition: { duration: 0.5, ease: 'easeOut' as const },
+  },
+};
+
+export function HowItWorks() {
+  const ref = useRef<HTMLDivElement>(null);
+  const isInView = useInView(ref, { once: true, margin: '-80px' });
+
+  return (
+    <section ref={ref} aria-labelledby="how-it-works-heading" className="mx-auto mb-24 max-w-4xl">
+      {/* Section heading */}
+      <motion.div
+        initial={{ opacity: 0, y: 20 }}
+        animate={isInView ? { opacity: 1, y: 0 } : {}}
+        transition={{ duration: 0.5 }}
+        className="mb-10 text-center"
+      >
+        <p className="mb-2 text-xs font-bold uppercase tracking-[0.25em] text-emerald-600 dark:text-emerald-400">
+          Getting Started
+        </p>
+        <h2
+          id="how-it-works-heading"
+          className="text-2xl font-extrabold tracking-tight text-gray-900 dark:text-white md:text-3xl"
+        >
+          Live in under 60 seconds
+        </h2>
+        <p className="mt-2 text-sm text-gray-500 dark:text-white/60">
+          Four steps from zero to a live 3D badge on your GitHub profile.
+        </p>
+      </motion.div>
+
+      {/* Step cards */}
+      <motion.div
+        variants={containerVariants}
+        initial="hidden"
+        animate={isInView ? 'visible' : 'hidden'}
+        className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-4"
+        role="list"
+      >
+        {HOW_IT_WORKS_STEPS.map((step, index) => (
+          <motion.div
+            key={step.number}
+            variants={cardVariants}
+            role="listitem"
+            className="group relative overflow-hidden rounded-2xl border border-black/5 bg-white/60 p-6 backdrop-blur-xl shadow-sm transition-all duration-300 hover:shadow-lg hover:-translate-y-1 dark:border-white/[0.08] dark:bg-[#0a0a0a]/80"
+            style={{
+              boxShadow: `0 0 0 0 ${step.glow}`,
+            }}
+            whileHover={{
+              boxShadow: `0 8px 32px ${step.glow}`,
+            }}
+          >
+            {/* Connector line (desktop only, not on last item) */}
+            {index < HOW_IT_WORKS_STEPS.length - 1 && (
+              <div
+                className="absolute -right-2 top-1/2 z-10 hidden -translate-y-1/2 lg:block"
+                aria-hidden="true"
+              >
+                <svg
+                  width="16"
+                  height="16"
+                  viewBox="0 0 16 16"
+                  fill="none"
+                  className="text-gray-300 dark:text-white/20"
+                >
+                  <path
+                    d="M4 8h8M9 5l3 3-3 3"
+                    stroke="currentColor"
+                    strokeWidth="1.5"
+                    strokeLinecap="round"
+                    strokeLinejoin="round"
+                  />
+                </svg>
+              </div>
+            )}
+
+            {/* Background glow on hover */}
+            <div
+              className="pointer-events-none absolute inset-0 rounded-2xl opacity-0 transition-opacity duration-500 group-hover:opacity-100"
+              style={{
+                background: `radial-gradient(circle at 30% 30%, ${step.glow}, transparent 70%)`,
+              }}
+              aria-hidden="true"
+            />
+
+            {/* Step number pill */}
+            <div className="mb-4 flex items-center gap-3">
+              <span
+                className={`inline-flex h-7 w-7 shrink-0 items-center justify-center rounded-lg bg-gradient-to-br ${step.accent} text-xs font-black text-white shadow-sm`}
+                aria-hidden="true"
+              >
+                {step.number}
+              </span>
+              {/* Icon */}
+              <div
+                className={`flex h-9 w-9 items-center justify-center rounded-xl bg-gradient-to-br ${step.accent} bg-opacity-10 text-white shadow-sm`}
+                style={{
+                  background: `linear-gradient(135deg, ${step.glow.replace('0.15', '0.25')}, ${step.glow.replace('0.15', '0.1')})`,
+                }}
+              >
+                <span className="text-gray-700 dark:text-white/80">{step.icon}</span>
+              </div>
+            </div>
+
+            {/* Title */}
+            <h3 className="mb-1.5 text-sm font-bold tracking-tight text-gray-900 dark:text-white">
+              {step.title}
+            </h3>
+
+            {/* Description */}
+            <p className="text-xs leading-relaxed text-gray-500 dark:text-white/55">
+              {step.description}
+            </p>
+          </motion.div>
+        ))}
+      </motion.div>
+    </section>
+  );
+}
diff --git a/components/UsernameInput.tsx b/components/UsernameInput.tsx
new file mode 100644
index 000000000..b81f8567b
--- /dev/null
+++ b/components/UsernameInput.tsx
@@ -0,0 +1,294 @@
+'use client';
+
+import { useState, useEffect, useRef } from 'react';
+import { AnimatePresence, motion } from 'framer-motion';
+import { useDebounce } from '@/hooks/useDebounce';
+
+type ValidationState = 'idle' | 'loading' | 'valid' | 'invalid';
+
+interface UsernameInputProps {
+  value: string;
+  onChange: (val: string) => void;
+  onClear: () => void;
+}
+
+function XIcon({ size = 18 }: { size?: number }) {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width={size}
+      height={size}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <line x1="18" y1="6" x2="6" y2="18" />
+      <line x1="6" y1="6" x2="18" y2="18" />
+    </svg>
+  );
+}
+
+function Spinner() {
+  return (
+    <svg
+      className="animate-spin"
+      xmlns="http://www.w3.org/2000/svg"
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <path d="M21 12a9 9 0 1 1-6.219-8.56" />
+    </svg>
+  );
+}
+
+function CheckIcon() {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="14"
+      height="14"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="#10b981"
+      strokeWidth="3"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <polyline points="20 6 9 17 4 12" />
+    </svg>
+  );
+}
+
+/**
+ * Enhanced username input with:
+ * - Real-time GitHub avatar validation (debounced)
+ * - Visual states: idle → loading → valid / invalid
+ * - Avatar preview when valid
+ * - Accessible status announcements
+ */
+export function UsernameInput({ value, onChange, onClear }: UsernameInputProps) {
+  const [validationState, setValidationState] = useState<ValidationState>('idle');
+  const [avatarUrl, setAvatarUrl] = useState<string | null>(null);
+  const abortRef = useRef<AbortController | null>(null);
+
+  const trimmed = value.trim();
+  const debouncedUsername = useDebounce(trimmed, 600);
+
+  // GitHub username regex — 1-39 alphanumeric / hyphens, no leading/trailing hyphen
+  const isValidFormat =
+    debouncedUsername.length > 0 &&
+    /^[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,37}[a-zA-Z0-9])?$/.test(debouncedUsername);
+
+  useEffect(() => {
+    // Reset when input cleared
+    if (debouncedUsername.length === 0) {
+      // eslint-disable-next-line react-hooks/set-state-in-effect
+      setValidationState('idle');
+      setAvatarUrl(null);
+      return;
+    }
+
+    if (!isValidFormat) {
+      setValidationState('invalid');
+      setAvatarUrl(null);
+      return;
+    }
+
+    // Abort previous in-flight request
+    abortRef.current?.abort();
+    const controller = new AbortController();
+    abortRef.current = controller;
+
+    setValidationState('loading');
+    setAvatarUrl(null);
+
+    // Use GitHub's avatar URL as a lightweight existence check
+    const url = `https://avatars.githubusercontent.com/${debouncedUsername}?size=80`;
+    const img = new Image();
+    img.src = url;
+
+    img.onload = () => {
+      if (controller.signal.aborted) return;
+      setValidationState('valid');
+      setAvatarUrl(url);
+    };
+
+    img.onerror = () => {
+      if (controller.signal.aborted) return;
+      setValidationState('invalid');
+      setAvatarUrl(null);
+    };
+
+    return () => {
+      controller.abort();
+    };
+  }, [debouncedUsername, isValidFormat]);
+
+  // Show loading spinner while user is typing (before debounce settles)
+  const isTyping = trimmed !== debouncedUsername && trimmed.length > 0;
+  const displayState: ValidationState = isTyping ? 'loading' : validationState;
+
+  const ringClass =
+    displayState === 'valid'
+      ? 'ring-2 ring-emerald-400 border-transparent'
+      : displayState === 'invalid'
+        ? 'ring-2 ring-red-400 border-transparent'
+        : displayState === 'loading'
+          ? 'ring-2 ring-cyan-400/60 border-transparent'
+          : 'border-black/10 dark:border-white/10 focus-within:ring-2 focus-within:ring-emerald-400 focus-within:border-transparent';
+
+  const statusMessage =
+    displayState === 'valid'
+      ? `GitHub user ${debouncedUsername} found`
+      : displayState === 'invalid' && debouncedUsername.length > 0
+        ? `GitHub user ${debouncedUsername} not found`
+        : '';
+
+  return (
+    <div className="relative flex-1 flex flex-col">
+      {/* Screen-reader live region */}
+      <span className="sr-only" aria-live="polite" aria-atomic="true">
+        {statusMessage}
+      </span>
+
+      <div
+        className={`relative flex items-center w-full rounded-2xl border bg-white transition-all duration-250 shadow-inner dark:bg-black/60 ${ringClass}`}
+      >
+        {/* Avatar preview (left side) */}
+        <AnimatePresence>
+          {avatarUrl && displayState === 'valid' && (
+            <motion.div
+              initial={{ opacity: 0, scale: 0.7, x: -4 }}
+              animate={{ opacity: 1, scale: 1, x: 0 }}
+              exit={{ opacity: 0, scale: 0.7, x: -4 }}
+              transition={{ duration: 0.2, ease: 'easeOut' }}
+              className="absolute left-3 flex items-center gap-2 pointer-events-none z-10"
+              aria-hidden="true"
+            >
+              <img
+                src={avatarUrl}
+                alt=""
+                width={28}
+                height={28}
+                className="h-7 w-7 rounded-full object-cover ring-1 ring-emerald-400/40"
+              />
+            </motion.div>
+          )}
+        </AnimatePresence>
+
+        <input
+          type="text"
+          id="github-username-input"
+          autoComplete="off"
+          autoCorrect="off"
+          autoCapitalize="none"
+          spellCheck={false}
+          suppressHydrationWarning
+          placeholder="Enter GitHub Username"
+          aria-label="GitHub username"
+          aria-describedby="username-hint"
+          aria-invalid={displayState === 'invalid'}
+          className={`flex-1 rounded-2xl bg-transparent py-4 text-sm text-black outline-none placeholder:text-gray-400 dark:text-white dark:placeholder:text-gray-500 transition-all duration-250 ${
+            avatarUrl && displayState === 'valid' ? 'pl-14 pr-10' : 'px-5 pr-10'
+          }`}
+          value={value}
+          onChange={(e) => onChange(e.target.value)}
+          maxLength={39}
+        />
+
+        {/* Right-side indicator */}
+        <div className="absolute right-4 top-1/2 -translate-y-1/2 flex items-center gap-1.5">
+          <AnimatePresence mode="wait">
+            {displayState === 'loading' && (
+              <motion.span
+                key="spinner"
+                initial={{ opacity: 0 }}
+                animate={{ opacity: 1 }}
+                exit={{ opacity: 0 }}
+                className="text-cyan-500"
+              >
+                <Spinner />
+              </motion.span>
+            )}
+            {displayState === 'valid' && (
+              <motion.span
+                key="check"
+                initial={{ opacity: 0, scale: 0.5 }}
+                animate={{ opacity: 1, scale: 1 }}
+                exit={{ opacity: 0, scale: 0.5 }}
+                className="flex h-5 w-5 items-center justify-center rounded-full bg-emerald-500/15"
+              >
+                <CheckIcon />
+              </motion.span>
+            )}
+          </AnimatePresence>
+
+          {value.length > 0 && (
+            <button
+              onClick={onClear}
+              className="text-gray-400 transition-colors hover:text-black dark:text-white/50 dark:hover:text-white"
+              aria-label="Clear username input"
+              type="button"
+            >
+              <XIcon size={16} />
+            </button>
+          )}
+        </div>
+      </div>
+
+      {/* Contextual hint messages */}
+      <div id="username-hint" aria-live="polite">
+        <AnimatePresence mode="wait">
+          {displayState === 'valid' && debouncedUsername && (
+            <motion.p
+              key="valid"
+              initial={{ opacity: 0, y: -4 }}
+              animate={{ opacity: 1, y: 0 }}
+              exit={{ opacity: 0, y: -4 }}
+              transition={{ duration: 0.2 }}
+              className="mt-1.5 flex items-center gap-1.5 self-start pl-1 text-xs text-emerald-600 dark:text-emerald-400"
+            >
+              <CheckIcon />
+              {debouncedUsername} found
+            </motion.p>
+          )}
+          {displayState === 'invalid' && debouncedUsername.length > 0 && (
+            <motion.p
+              key="invalid"
+              initial={{ opacity: 0, y: -4 }}
+              animate={{ opacity: 1, y: 0 }}
+              exit={{ opacity: 0, y: -4 }}
+              transition={{ duration: 0.2 }}
+              className="mt-1.5 self-start pl-1 text-xs text-red-500"
+            >
+              GitHub user not found
+            </motion.p>
+          )}
+          {value.length === 39 && (
+            <motion.p
+              key="limit"
+              initial={{ opacity: 0, y: -4 }}
+              animate={{ opacity: 1, y: 0 }}
+              exit={{ opacity: 0, y: -4 }}
+              className="mt-1.5 self-start pl-1 text-xs text-red-500"
+            >
+              GitHub username limit reached (39 characters maximum)
+            </motion.p>
+          )}
+        </AnimatePresence>
+      </div>
+    </div>
+  );
+}

From 0791a918316a6d93568e0f723fbd91c6c89496aa Mon Sep 17 00:00:00 2001
From: Aryan-Agarwal-creator <aryanagarwal7612@gmail.com>
Date: Wed, 3 Jun 2026 02:59:07 +0530
Subject: [PATCH 2/2] CL issues fixed

---
 app/page.test.tsx | 94 ++++++++++++++++++++++++++++++++++-------------
 app/page.tsx      |  8 +++-
 2 files changed, 75 insertions(+), 27 deletions(-)

diff --git a/app/page.test.tsx b/app/page.test.tsx
index 5f803b33a..41bf44fdc 100644
--- a/app/page.test.tsx
+++ b/app/page.test.tsx
@@ -22,6 +22,34 @@ vi.mock('@/components/DiscordButton', () => ({
   DiscordButton: () => <button data-testid="discord-button">Discord Button</button>,
 }));
 
+// Mock new UX components added in the UX improvement pass
+vi.mock('@/components/HowItWorks', () => ({
+  HowItWorks: () => <div data-testid="how-it-works">How It Works</div>,
+}));
+
+vi.mock('@/components/AnimatedStatsBanner', () => ({
+  AnimatedStatsBanner: () => <div data-testid="animated-stats-banner">Stats Banner</div>,
+}));
+
+vi.mock('@/components/UsernameInput', () => ({
+  UsernameInput: ({ value, onChange, onClear }: any) => (
+    <div>
+      <input
+        type="text"
+        placeholder="Enter GitHub Username"
+        value={value}
+        onChange={(e) => onChange(e.target.value)}
+        maxLength={39}
+      />
+      {value.length > 0 && (
+        <button onClick={onClear} aria-label="Clear input" type="button">
+          ×
+        </button>
+      )}
+    </div>
+  ),
+}));
+
 // next/image is no longer used — SVG preview is fetched via useEffect and
 // rendered inline. The mock below keeps the import from erroring if any
 // other test file still imports it.
@@ -154,6 +182,7 @@ vi.mock('framer-motion', () => ({
     ),
   },
   AnimatePresence: ({ children }: any) => <>{children}</>,
+  useInView: () => true,
 }));
 
 const mockRecentSearches = {
@@ -207,10 +236,11 @@ describe('LandingPage', () => {
   it('renders recent searches and applies a recent search when clicked', () => {
     render(<LandingPage />);
     const input = screen.getByPlaceholderText('Enter GitHub Username') as HTMLInputElement;
-    const octocatButton = screen.getByRole('button', { name: 'octocat' });
+    // Recent searches render as buttons with the username as the accessible label
+    const octocatButton = screen.getByRole('button', { name: 'Search again for octocat' });
 
     expect(octocatButton).toBeDefined();
-    expect(screen.getByRole('button', { name: 'Clear' })).toBeDefined();
+    expect(screen.getByRole('button', { name: 'Clear all recent searches' })).toBeDefined();
 
     fireEvent.click(octocatButton);
 
@@ -219,10 +249,10 @@ describe('LandingPage', () => {
 
   it('renders an empty state before a username is entered', () => {
     render(<LandingPage />);
-
-    expect(screen.getByText(/Enter a GitHub username above to instantly generate/i)).toBeDefined();
-    // No badge img should be present yet
-    expect(screen.queryByTestId('badge-img')).toBeNull();
+    // The sample badge pill label is always shown before user interaction
+    expect(screen.getByText(/Sample Preview/i)).toBeDefined();
+    // badge-img is always present (sample preview loads from production)
+    expect(screen.getByTestId('badge-img')).toBeDefined();
   });
 
   it('updates the username when input changes and shows the badge img', async () => {
@@ -250,7 +280,8 @@ describe('LandingPage', () => {
 
   it('disables the Watch Dashboard link when the username is empty', () => {
     render(<LandingPage />);
-    const dashboardLink = screen.getByRole('link', { name: 'Watch Dashboard' });
+    // next/link mock renders as <a data-testid="next-link">; select by text
+    const dashboardLink = screen.getByText('Watch Dashboard').closest('a')!;
 
     expect(dashboardLink.getAttribute('aria-disabled')).toBe('true');
     expect(dashboardLink.getAttribute('href')).toBe('/');
@@ -262,7 +293,7 @@ describe('LandingPage', () => {
 
     fireEvent.change(input, { target: { value: 'octocat' } });
 
-    const dashboardLink = screen.getByRole('link', { name: 'Watch Dashboard' });
+    const dashboardLink = screen.getByText('Watch Dashboard').closest('a')!;
     expect(dashboardLink.getAttribute('aria-disabled')).not.toBe('true');
     expect(dashboardLink.getAttribute('href')).toBe('/dashboard/octocat');
   });
@@ -272,7 +303,8 @@ describe('LandingPage', () => {
     const input = screen.getByPlaceholderText('Enter GitHub Username') as HTMLInputElement;
     fireEvent.change(input, { target: { value: 'jhasourav07' } });
 
-    const copyButton = screen.getByText('Copy Link').closest('button');
+    // CTA is now "Generate My Badge" — find the primary submit button
+    const copyButton = screen.getByRole('button', { name: /Generate badge for jhasourav07/i });
     fireEvent.click(copyButton!);
 
     expect(navigator.clipboard.writeText).toHaveBeenCalledWith(
@@ -280,8 +312,8 @@ describe('LandingPage', () => {
     );
 
     await waitFor(() => {
-      // The button text should change to Copied
-      expect(screen.getByText('Copied')).toBeDefined();
+      // The button text should change to Copied!
+      expect(screen.getByText('Copied!')).toBeDefined();
       // The SuccessGuide should appear
       expect(screen.getByText('Your Monolith is Ready - Deploy It in 4 Steps')).toBeDefined();
     });
@@ -294,7 +326,7 @@ describe('LandingPage', () => {
     const input = screen.getByPlaceholderText('Enter GitHub Username') as HTMLInputElement;
     fireEvent.change(input, { target: { value: 'jhasourav07' } });
 
-    const copyButton = screen.getByText('Copy Link').closest('button');
+    const copyButton = screen.getByRole('button', { name: /Generate badge for jhasourav07/i });
     fireEvent.click(copyButton!);
 
     await waitFor(() => {
@@ -303,24 +335,29 @@ describe('LandingPage', () => {
       );
     });
 
-    expect(screen.queryByText('Copied')).toBeNull();
+    expect(screen.queryByText('Copied!')).toBeNull();
     expect(screen.queryByText('Your Monolith is Ready - Deploy It in 4 Steps')).toBeNull();
   });
 
   it('disables Copy Link button when username is empty', () => {
     render(<LandingPage />);
 
-    const copyButton = screen.getByText('Copy Link').closest('button');
+    // Primary button: aria-label "Enter a GitHub username to generate your badge" when disabled
+    const generateButton = screen.getByRole('button', {
+      name: /Enter a GitHub username to generate your badge/i,
+    });
 
-    expect(copyButton?.disabled).toBe(true);
+    expect((generateButton as HTMLButtonElement).disabled).toBe(true);
   });
 
   it('does not copy link when username is empty', () => {
     render(<LandingPage />);
 
-    const copyButton = screen.getByText('Copy Link').closest('button');
+    const generateButton = screen.getByRole('button', {
+      name: /Enter a GitHub username to generate your badge/i,
+    });
 
-    fireEvent.click(copyButton!);
+    fireEvent.click(generateButton!);
 
     expect(navigator.clipboard.writeText).not.toHaveBeenCalled();
   });
@@ -354,7 +391,7 @@ describe('LandingPage', () => {
     fireEvent.change(input, { target: { value: 'jhasourav07' } });
 
     // Trigger copy to show guide
-    const copyButton = screen.getByText('Copy Link').closest('button');
+    const copyButton = screen.getByRole('button', { name: /Generate badge for jhasourav07/i });
     fireEvent.click(copyButton!);
 
     await waitFor(() => {
@@ -374,6 +411,7 @@ describe('LandingPage', () => {
     render(<LandingPage />);
     const input = screen.getByPlaceholderText('Enter GitHub Username') as HTMLInputElement;
 
+    // UsernameInput mock shows "Clear input" button only when value.length > 0
     expect(screen.queryByLabelText('Clear input')).toBeNull();
 
     fireEvent.change(input, { target: { value: 'a' } });
@@ -407,12 +445,15 @@ describe('LandingPage', () => {
     render(<LandingPage />);
     const input = screen.getByPlaceholderText('Enter GitHub Username') as HTMLInputElement;
 
-    await act(async () => {
-      fireEvent.change(input, { target: { value: 'invalid_user' } });
+    fireEvent.change(input, { target: { value: 'invalid_user' } });
+
+    // Wait for the debounced username to settle and the badge img to point at the user's URL
+    await waitFor(() => {
+      const img = screen.getByTestId('badge-img') as HTMLImageElement;
+      expect(img.src).toContain('user=invalid_user');
     });
 
-    // Badge img renders; simulate the browser failing to load it (e.g. API returned 400)
-    await waitFor(() => screen.getByTestId('badge-img'));
+    // Simulate the browser failing to load the badge image
     await act(async () => {
       fireEvent.error(screen.getByTestId('badge-img'));
     });
@@ -429,12 +470,15 @@ describe('LandingPage', () => {
     render(<LandingPage />);
     const input = screen.getByPlaceholderText('Enter GitHub Username') as HTMLInputElement;
 
-    await act(async () => {
-      fireEvent.change(input, { target: { value: 'octocat' } });
+    fireEvent.change(input, { target: { value: 'octocat' } });
+
+    // Wait for the debounced username to settle and the badge img to point at the user's URL
+    await waitFor(() => {
+      const img = screen.getByTestId('badge-img') as HTMLImageElement;
+      expect(img.src).toContain('user=octocat');
     });
 
     // Simulate the browser failing to load the badge image
-    await waitFor(() => screen.getByTestId('badge-img'));
     await act(async () => {
       fireEvent.error(screen.getByTestId('badge-img'));
     });
diff --git a/app/page.tsx b/app/page.tsx
index 59a3ce505..8c9e91660 100644
--- a/app/page.tsx
+++ b/app/page.tsx
@@ -171,9 +171,13 @@ export default function LandingPage() {
   // Whether to show sample (torvalds) or user's actual badge
   const showSample = !hasUsername;
 
-  const activeBadgeUser = showSample ? SAMPLE_USERNAME : debouncedUsername;
-  const badgeUrl = `/api/streak?user=${activeBadgeUser}`;
   const siteUrl = process.env.NEXT_PUBLIC_SITE_URL ?? 'https://commitpulse.vercel.app';
+  const activeBadgeUser = showSample ? SAMPLE_USERNAME : debouncedUsername;
+  // Sample always loads from production so it works in local dev without GITHUB_TOKEN.
+  // The user's own badge uses the local API endpoint as expected.
+  const badgeUrl = showSample
+    ? `https://commitpulse.vercel.app/api/streak?user=${SAMPLE_USERNAME}`
+    : `/api/streak?user=${debouncedUsername}`;
   const markdown = `![CommitPulse](${siteUrl}/api/streak?user=${trimmedUsername})`;
 
   // Derived — automatically false when debouncedUsername changes