# VPN Website — Task Tracker

> **Brand:** SuperVPN Proxy (placeholder — globally changeable via `lib/site-config.ts`)
> **Company:** GREEN DIGITAL CONSULTING LLP
> **Stack:** Next.js 16.2.9 | React 19 | TypeScript | Tailwind CSS v4 | Framer Motion
> **Target:** Lighthouse 95/95/95/100

---

## Reference Files
- **PDF Spec:** `/Users/p21-0059/Downloads/VPN Website Design & Development Specification.pdf`
- **HTML Content Source:** `/Users/p21-0059/Downloads/vpn-mac-site_2.html`
- **Plan File:** `/Users/p21-0059/.claude/plans/atomic-sparking-kazoo.md`

---

## Phase 0: Foundation Setup
**Status:** COMPLETED
**Goal:** Dependencies installed, fonts configured, Tailwind v4 theme set, dev server clean.

- [x] Install deps: `framer-motion`, `lucide-react`, `@radix-ui/react-accordion`, `class-variance-authority`, `clsx`, `tailwind-merge`
- [x] Create `lib/cn.ts` — clsx + twMerge utility
- [x] Create `lib/site-config.ts` — brand name ("SuperVPN Proxy"), company name ("GREEN DIGITAL CONSULTING LLP"), placeholder URLs
- [x] Set up fonts in `app/layout.tsx`: **Bricolage Grotesque** (headings) + **Inter** (body) via `next/font/google`, exposed as CSS variables `--font-heading` / `--font-body`
- [x] Rewrite `app/globals.css` with Tailwind v4 `@theme inline {}`: full brand color palette (#0A84FF primary from PDF spec), font families, border radius
- [x] Read `node_modules/next/dist/docs/` for Next.js 16 breaking changes — document findings
- [x] Clear boilerplate from `app/page.tsx`, replace with minimal test page
- [x] Delete unused default SVGs from `public/` (next.svg, vercel.svg, globe.svg, file.svg, window.svg)

**Verify:**
- [x] `npm run dev` starts clean (no errors/warnings)
- [x] `npm run build` succeeds
- [x] `npm run lint` passes
- [x] Fonts render correctly (Bricolage Grotesque heading + Inter body)
- [x] Brand color `#0A84FF` available as Tailwind utility (`bg-brand`, `text-brand`)

---

## Phase 1: Shared Utilities + UI Primitives
**Status:** COMPLETED
**Goal:** All reusable building blocks created before any section code.

- [x] `lib/types.ts` — TypeScript interfaces: PricingPlan, FAQItem, Review, Feature, TrustMetric, WhyVPNItem, Step, PaymentMethod
- [x] `lib/constants.ts` — All static data extracted from HTML reference:
  - Pricing: 3 plans (Monthly $11.99, Yearly $59.99, 2-Year $79.99) with per-day rates and save percentages
  - FAQ: 7 items (Is it free?, Is it safe?, Free vs Premium?, 3-day trial?, Cancel/refund?, Logs?, Mac support?)
  - Reviews: 3 testimonials (Alexander T., Stix & Stoned, Maria L.)
  - Trust metrics: Free, 10M+, No-logs, 30 days
  - Free features: 4 items | Premium features: 4 items | Benefits: 6 items
  - Why VPN: 4 cards (Hide IP, Safe WiFi, Stream & Access, No Logs/Ads)
  - Steps: 3 (Download, Install, Connect)
  - Payment methods: Cards, UPI, Wallets, Net Banking, Visa, Mastercard, RuPay
- [x] `lib/animations.ts` — Framer Motion variant presets:
  - `fadeInUp`, `fadeIn`, `fadeInDown`, `fadeInLeft`, `fadeInRight` (section reveals: 400-700ms, easeOut)
  - `staggerContainer` + `staggerItem` (0.1s delay between items)
  - `heroStagger` + `heroItem` (slower, more dramatic)
  - `scaleIn` (subtle scale from 0.95)
  - `buttonHover` + `buttonTap` (lift + press)
  - `cardHover` (elevation)
- [x] `lib/metadata.ts` — SEO constants (site name, URL, description, keywords)
- [x] `components/ui/Container.tsx` — max-width 1080px responsive wrapper with horizontal padding
- [x] `components/ui/SectionWrapper.tsx` — "use client", wraps sections with `whileInView` scroll-triggered fadeInUp, accepts `id`, `className`, `children`
- [x] `components/ui/Button.tsx` — "use client", CVA variants (primary blue / light transparent / ghost), Framer Motion `whileHover` lift + `whileTap` scale
- [x] `components/ui/Badge.tsx` — CVA variants (brand / success / free), small label component
- [x] `components/ui/Card.tsx` — "use client", reusable card with border, rounded corners, optional hover elevation + highlighted state

**Verify:**
- [x] `npm run build` passes (compiled successfully)
- [x] `npm run lint` passes (no errors)
- [ ] Visual verification pending (will test with sections in Phase 2)

**Notes:**
- Button component had type conflict between Framer Motion and React's HTMLButtonElement props — fixed by using explicit prop interface instead of extending HTMLButtonAttributes
- Added `heroStagger`/`heroItem` animation variants (slower than regular stagger) for the hero section
- Badge uses CVA variants like Button for consistency

---

## Phase 2: Header + Hero + Trust Metrics + Footer (Page Skeleton)
**Status:** COMPLETED
**Goal:** Page frame — first and last things users see.

- [x] `components/sections/Header.tsx` — Sticky nav, backdrop blur, Key icon logo + brand name from site-config, "Download Free" CTA
- [x] `components/sections/Hero.tsx` — Promo countdown, free badge, H1, subtitle, 2 CTAs, trust indicators, OS note, two-column desktop layout, gradient bg + dot pattern, staggered entrance
- [x] `components/ui/AppMockup.tsx` — Full macOS app mockup: traffic lights, sidebar (Home/Support/Settings + card), main panel (Go Premium, Optimal, status, connection ring, server bar). All CSS/Tailwind, no images.
- [x] `components/sections/TrustMetrics.tsx` — 4-column grid with count-up animation (custom useCountUp hook with easeOutCubic)
- [x] `components/sections/Footer.tsx` — Server Component. Links, copyright, Apple disclaimer.
- [x] Wired into `app/page.tsx`

**Verify:**
- [x] `npm run build` passes
- [x] `npm run lint` passes
- [ ] Visual verification pending (run `npm run dev` to check)

---

## Phase 3: Feature Sections (Comparison + Benefits + Why VPN)
**Status:** COMPLETED
**Goal:** Value proposition sections.

- [x] `components/sections/FreeVsPremium.tsx` — Two-column comparison with green (free) and blue (premium) check icons. Premium card highlighted with brand border + shadow + "Premium" badge. Responsive 2-col/1-col.
- [x] `components/sections/PremiumBenefits.tsx` — 6-item grid inside white card. Blue check icons. 3-col/2-col/1-col responsive.
- [x] `components/sections/WhyUseVPN.tsx` — 4 cards with Lucide icons (Shield, Wifi, Play, Ban). Tinted icon backgrounds. 4-col/2-col/1-col responsive.
- [x] Wired into `page.tsx` with `id="features"` on FreeVsPremium

**Verify:**
- [x] `npm run build` passes
- [x] `npm run lint` passes
- [ ] Visual verification pending

---

## Phase 4: Pricing + Payments (Core Conversion)
**Status:** COMPLETED
**Goal:** Plan picker, payment, guarantee.

- [x] `components/ui/PlanCard.tsx` — Radio-style plan card with animated radio dot (scale transition), hover scale, keyboard support (Enter/Space), role="radio" + aria-checked, dark mode variant for FinalCTA. Save badges, strikethrough prices, large per-day display.
- [x] `components/sections/Pricing.tsx` — Full section: eyebrow/H2/lead with staggered animation, 3 PlanCards in radiogroup, payment card (Razorpay branding, 7 method chips with hover lift, CTA button, animated renewal text keyed to selection), guarantee card with Shield icon, laurel "Trusted worldwide" badge with SVG decorations. `id="plans"` for anchor.
- [x] Plan selection: `useState('yearly')` default, renewal text animates on change with `motion.p key={selectedId}`

**Verify:**
- [x] `npm run build` passes
- [x] `npm run lint` passes (fixed unused siteConfig import)
- [ ] Visual verification pending

**Enhancements added:**
- Payment method chips have subtle hover lift animation
- Renewal text fades in when plan selection changes
- Laurel SVG badge between pricing and next section

---

## Phase 5: Remaining Sections (How It Works + FAQ + Reviews + Final CTA)
**Status:** COMPLETED
**Goal:** Complete all content sections.

- [x] `components/sections/HowItWorks.tsx` — 3 step cards with number badges, connecting chevron arrows on desktop, gradient glow on hover, staggered entrance. Flex row desktop / column mobile.
- [x] `components/sections/FAQ.tsx` — Custom accordion (not Radix — simpler, smoother). AnimatePresence for height animation, rotating plus icon, one-open-at-a-time, first item open by default. ARIA: aria-expanded, aria-controls, role="region".
- [x] `components/sections/Reviews.tsx` — 3 cards with gradient avatars, gold stars, hover lift + brand shadow. 3-col/2-col/1-col responsive grid.
- [x] `components/sections/FinalCTA.tsx` — Dark gradient section. Staggered header, download button (light variant), independent plan picker with dark-themed PlanCards, CTA + renewal text + Razorpay note.
- [x] All wired into `page.tsx` — complete page with all 11 sections + header + footer

**Verify:**
- [x] `npm run build` passes
- [x] `npm run lint` passes
- [ ] Visual verification pending

**Enhancements added:**
- FAQ uses Framer Motion AnimatePresence instead of Radix (smoother height animation, no extra dependency needed)
- HowItWorks cards have gradient glow overlay on hover + connecting arrows
- Review cards have brand-colored shadow on hover
- FreeVsPremium cards have hover lift + shadow enhancement
- WhyVPN icon boxes change to brand bg with white icon on hover

---

## Phase 6: SEO + Metadata
**Status:** NOT STARTED
**Goal:** Lighthouse SEO 100.

- [ ] Update `app/layout.tsx` metadata export:
  - Title: "Free, Fast VPN for Mac — Download for macOS | SuperVPN Proxy"
  - Description: from HTML meta tag
  - Keywords: VPN, Mac VPN, free VPN, macOS VPN, etc.
  - OpenGraph: title, description, url, siteName, images, locale, type
  - Twitter: card (summary_large_image), title, description, images
  - Canonical URL
  - Robots: index, follow
- [ ] `app/sitemap.ts` — single entry (homepage)
- [ ] `app/robots.ts` — allow all crawlers, reference sitemap
- [ ] JSON-LD in `app/page.tsx`:
  - `SoftwareApplication` schema (name, OS, price, rating, download URL)
  - `Organization` schema (name, URL, logo)
  - `FAQPage` schema (from FAQ items — major SEO boost)
- [ ] OG image: `app/opengraph-image.png` (static) or `app/opengraph-image.tsx` (dynamic)

**Verify:**
- [ ] View page source: `<title>`, `<meta description>`, OG tags, Twitter cards all present
- [ ] `/sitemap.xml` returns valid XML
- [ ] `/robots.txt` returns valid content
- [ ] JSON-LD validates at schema.org validator
- [ ] Lighthouse SEO audit = 100

---

## Phase 7: Accessibility
**Status:** NOT STARTED
**Goal:** Lighthouse Accessibility 95+.

- [ ] Skip-to-content link: first focusable element in `layout.tsx`, hidden until focused, links to `#main-content`
- [ ] `id="main-content"` on `<main>` wrapper in `page.tsx`
- [ ] Heading hierarchy: single `<h1>` in Hero, `<h2>` per section, `<h3>` for subsections
- [ ] ARIA on FAQ accordion: `aria-expanded`, `aria-controls`, `role="region"`
- [ ] ARIA on plan picker: `role="radiogroup"`, `role="radio"`, `aria-checked`, `aria-label`
- [ ] Visible focus rings: `focus-visible:ring-2 focus-visible:ring-brand focus-visible:ring-offset-2` on all interactive elements
- [ ] `prefers-reduced-motion`: disable Framer Motion animations, use `useReducedMotion()` hook
- [ ] Color contrast audit: all text on backgrounds meets WCAG AA (4.5:1 normal, 3:1 large)
- [ ] All images/icons have `alt` text or `aria-hidden="true"` for decorative ones
- [ ] App mockup: `aria-hidden="true"` (decorative)

**Verify:**
- [ ] Tab through entire page: every interactive element reachable with visible focus
- [ ] Screen reader: logical reading order, landmarks, images described
- [ ] Lighthouse accessibility = 95+
- [ ] `prefers-reduced-motion` tested: no animations

---

## Phase 8: Performance Optimization
**Status:** NOT STARTED
**Goal:** Lighthouse Performance 95+, LCP < 2.5s, CLS ~ 0.

- [ ] Lazy-load below-fold sections with `next/dynamic`: Reviews, FinalCTA, possibly FAQ
- [ ] Keep Hero + TrustMetrics eager (above fold)
- [ ] `next/image` everywhere with explicit `width`/`height`, `priority` on hero image only, `sizes` for responsive
- [ ] Framer Motion: use `LazyMotion` + `domAnimation` feature bundle to reduce bundle (~16KB saved)
- [ ] Font optimization: `display: 'swap'`, load only needed weights:
  - Bricolage Grotesque: 600, 700, 800
  - Inter: 400, 500, 600, 700
- [ ] Narrow `"use client"` boundaries where possible
- [ ] Review Tailwind output: no unused custom CSS

**Verify:**
- [ ] `npm run build` — check bundle sizes
- [ ] Lighthouse Performance: 95+ desktop, 90+ mobile
- [ ] LCP < 2.5s, CLS < 0.1, INP excellent
- [ ] No render-blocking resources

---

## Phase 9: Final Polish
**Status:** NOT STARTED
**Goal:** Production-ready, cross-browser tested.

- [ ] `app/not-found.tsx` — custom 404 page (branded, link back to home)
- [ ] `app/error.tsx` — error boundary (branded, retry button)
- [ ] Smooth scroll: CSS `scroll-behavior: smooth` or JS with offset for sticky header
- [ ] Responsive audit at all breakpoints: 375px, 768px, 860px, 1440px
- [ ] Cross-browser: Chrome, Safari, Firefox, Edge
- [ ] Full Lighthouse audit (incognito): all 4 categories
- [ ] All CTA buttons functional (scroll to correct anchors)
- [ ] No console errors or warnings
- [ ] No horizontal overflow on any screen size
- [ ] All animations smooth at 60fps

**Verify:**
- [ ] Lighthouse: Performance 95+, Accessibility 95+, Best Practices 95+, SEO 100
- [ ] All links/buttons work
- [ ] No console errors
- [ ] Smooth scroll accounts for sticky header height

---

## Review Notes
_(Updated after each phase completion)_

### Phase 0 Review
- Status: COMPLETED
- Issues found: Turbopack warns about multiple lockfiles (root ~/package-lock.json vs project). Non-blocking.
- Decisions made: Used `data-scroll-behavior="smooth"` on `<html>` per Next.js 16 docs. Brand color #0A84FF from PDF spec (not #0054FC from HTML). Added `prefers-reduced-motion` CSS reset in globals.css.
- Next.js 16 key findings: params/searchParams are async (doesn't affect us — no dynamic routes), middleware.ts renamed to proxy.ts (we don't use it), Turbopack is default.

### Phase 1 Review
- Status: COMPLETED
- Issues found: Framer Motion `motion.button` conflicts with React's `HTMLButtonElement` onDrag types. Fixed by using explicit prop interface.
- Decisions made: Added `PaymentMethod` type. Animation variants include both regular and hero-specific stagger timings. WhyVPNItem uses Lucide icon name strings instead of JSX components (resolved at render time).

### Phase 2 Review
- Status: COMPLETED
- Font changed: Dropped Bricolage Grotesque (user didn't like it). Now using **Inter** for both headings and body (same as ProtonVPN). Single font variable `--font-inter`.
- Header uses Lucide `Key` icon for logo (shield-like VPN icon)
- Hero countdown uses `useCountdown` custom hook with `useState` for end time
- TrustMetrics uses custom `useCountUp` hook with `requestAnimationFrame` + easeOutCubic
- AppMockup is entirely CSS — no images, built from HTML reference structure

### Phase 3 Review
- Status: COMPLETED
- FreeVsPremium uses inline SVG check icons (green for free, blue for premium) — not Lucide, to match the exact look from HTML reference
- WhyUseVPN maps icon name strings from constants to Lucide components via `iconMap` record
- All sections use consistent eyebrow + H2 + lead text pattern
- SectionWrapper handles scroll-triggered animation for all sections

### Phase 4 Review
- Status: COMPLETED
- PlanCard supports both light and dark mode via `dark` prop
- Radio dot uses Framer Motion scale animation (0→1) instead of CSS opacity for smoother feel
- Payment chips have individual hover lift animations
- Renewal text is keyed by selectedId so it animates on plan change
- Laurel badge included in Pricing section (was standalone in HTML)

### Phase 5 Review
- Status: COMPLETED
- Used custom FAQ accordion with AnimatePresence instead of @radix-ui/react-accordion — simpler, smoother, and the Radix dep is now unused (can be removed later)
- HowItWorks has connecting chevron arrows between steps on desktop using absolute positioning
- FinalCTA has independent plan selection state (not shared with Pricing section) — simpler, no prop drilling or context needed
- All hover effects enhanced: WhyVPN icon color change, FreeVsPremium card elevation, Review brand shadow

### Phase 6 Review
- Status: _pending_

### Phase 7 Review
- Status: _pending_

### Phase 8 Review
- Status: _pending_

### Phase 9 Review
- Status: _pending_