client-website

# Client Website End-to-end workflow for building a client's website from scratch or recreating/improving an existing one. Produces a modern, SEO-optimized Next.js site with real content, images, video embeds, structured data, and programmatic SEO guide pages. ## Arguments Provide the client name, domain (if any), and existing site URL (if any). Example: `"Paperback Expert at paperbackexpert.com"` ## Prerequisites - **Google Cloud** project under the m13v.com org (or create a new one) - **GitHub** org or personal account - **PostHog** account for analytics - **Google Search Console** access - **Isolated browser MCP** for visual comparison ## Stack - Next.js 16 (App Router) + React 19 + TypeScript - Tailwind CSS 4 (inline theme via `@theme`) - next/image for optimized images - Google Cloud Run for hosting (with HTTPS Load Balancer + Certificate Manager) - PostHog for analytics (CTA clicks, pageviews) --- ## Phase 1: Audit and Research ### 1a. SEO Audit (if existing site) Run parallel SEO agents to baseline the current site: ``` Launch 5 agents in parallel: - seo-technical: crawlability, indexability, Core Web Vitals, mobile - seo-content: E-E-A-T signals, readability, content depth - seo-schema: existing structured data (JSON-LD, Microdata, RDFa) - seo-performance: Lighthouse scores, LCP, CLS, TBT (desktop + mobile) - seo-geo: AI crawler accessibility, llms.txt, citation readiness ``` Record all scores. These become the "before" baseline and the fix list for the new site. ### 1b. Crawl All Pages Use an agent with WebFetch to discover and extract content from every page on the site: 1. Fetch the homepage, extract all navigation and footer links 2. Try common paths: /about, /services, /contact, /faq, /blog, /pricing, /testimonials, /privacy 3. For each discovered page, extract: - URL and page title - All headings (h1 through h6) with hierarchy - Full body text (quotes, testimonials, stats, descriptions) - CTA text and link targets - Form fields (if any) - Navigation links (to discover more pages) **Output:** Complete content inventory organized by page. ### 1c. Extract Visual Assets Use the isolated browser to catalog images, videos, and embeds: ```js // In isolated browser, navigate to each page and run: () => { const imgs = Array.from(document.querySelectorAll('img')).map((img, i) => { const rect = img.getBoundingClientRect(); return { idx: i, src: img.src, y: Math.round(rect.y), w: Math.round(rect.width), h: Math.round(rect.height) }; }).filter(x => x.w > 50); const iframes = Array.from(document.querySelectorAll('iframe')).map(f => f.src); return { imgs, iframes }; } ``` **Key assets to identify and download:** - Logo (usually first image, top of page, ~200px wide) - Hero images or background photos - Client/team headshot photos (circular, 100-200px) - Product images (book covers, screenshots, etc.) - Social proof imagery (awards, certifications, partner logos) - Video embeds (Vimeo, YouTube URLs) - Scheduling widgets (Calendly, Cal.com URLs) - Book cover strips / product galleries Download all identified images to `public/images/` with descriptive filenames. ### 1d. Take Full Page Screenshots Capture full-page screenshots of every key page on the original site for visual reference: ``` For each page: 1. browser_navigate to URL 2. browser_take_screenshot with fullPage: true 3. Save as original-{pagename}-full.png ``` --- ## Phase 2: Scaffold Project ### 2a. Create Next.js App ```bash cd ~ npx create-next-app@latest CLIENT-website --typescript --tailwind --eslint --app --src-dir --no-turbopack --import-alias "@/*" cd ~/CLIENT-website ``` ### 2b. Install @seo/components ```bash npm install @m13v/seo-components@latest npm install @seo/components@npm:@m13v/seo-components@latest ``` Both entries will appear in `package.json`: ```json "@m13v/seo-components": "^0.8.15", "@seo/components": "npm:@m13v/seo-components@^0.8.15" ``` ### 2c. Configure Theme (globals.css) The theme uses CSS custom properties in `:root` mapped into Tailwind 4 via `@theme inline`. Always define both the CSS variable AND the Tailwind mapping. Every client gets a primary color, a dark variant, and an accent color at minimum. ```css @import "tailwindcss"; :root { --background: #ffffff; --foreground: #1a1a1a; --primary: #073c61; /* Main brand color (navy, blue, green, etc.) */ --primary-dark: #052d49; /* Darker shade for footer, dark sections */ --cta: #e11010; /* CTA button color (red, orange, etc.) */ --cta-dark: #ae0c0c; /* CTA hover state */ --accent: #d4a843; /* Accent/highlight color (gold, yellow, etc.) */ --accent-light: #f0d88a; /* Light accent for badges */ } @theme inline { --color-background: var(--background); --color-foreground: var(--foreground); --color-primary: var(--primary); --color-primary-dark: var(--primary-dark); --color-cta: var(--cta); --color-cta-dark: var(--cta-dark); --color-accent: var(--accent); --color-accent-light: var(--accent-light); --font-sans: var(--font-inter); --font-heading: var(--font-oswald); } body { background: var(--background); color: var(--foreground); } html { scroll-behavior: smooth; } ``` **Color naming convention:** Use semantic names (primary, cta, accent) in the skill templates below. When building for a specific client, you can also add client-specific names (e.g., `--color-navy`, `--color-red`, `--color-gold`) for readability. ### 2d. Configure Fonts and @seo/components (layout.tsx) Use `next/font/google` with CSS variable mode. The body font goes on `--font-sans`, the heading font on `--font-heading`. Apply both variables to the `<html>` tag. **IMPORTANT: Route group architecture.** The root layout must NOT include Header/Footer directly. Instead, use a `(main)` route group with its own layout for pages that need the site Header/Footer. SEO guide pages under `/t/` also go inside `(main)` so they share the same Header/Footer as the rest of the site. **Root layout (`src/app/layout.tsx`):** fonts, metadata, Organization JSON-LD, @seo/components styles, and `{children}` only. ```tsx import { Inter, Oswald } from "next/font/google"; import { HeadingAnchors } from "@seo/components"; import { SeoComponentsStyles } from "@seo/components/server"; const inter = Inter({ variable: "--font-inter", subsets: ["latin"] }); const oswald = Oswald({ variable: "--font-oswald", subsets: ["latin"] }); // Root layout: NO Header/Footer here <html lang="en" className={`${inter.variable} ${oswald.variable} h-full antialiased`}> <head> <SeoComponentsStyles /> </head> <body className="min-h-full flex flex-col font-sans"> <HeadingAnchors /> {children} {/* Organization JSON-LD here */} </body> </html> ``` - `SeoComponentsStyles` injects the package's prebuilt Tailwind CSS for all @seo/components - `HeadingAnchors` auto-injects `id` attributes on H2 elements for sidebar linking and anchor navigation **Main layout (`src/app/(main)/layout.tsx`):** wraps all pages with Header/Footer. ```tsx import { Header } from "@/components/Header"; import { Footer } from "@/components/Footer"; export default function MainLayout({ children }: { children: React.ReactNode }) { return ( <> <Header /> <main className="flex-1">{children}</main> <Footer /> </> ); } ``` All page routes (homepage, about, wins, faq, precall, AND `/t/` guide pages) go inside `src/app/(main)/`. The `(main)` directory is a Next.js route group: it does not affect URLs. **Font pairing guide:** - Professional services: Inter + Oswald (clean, authoritative) - Creative/lifestyle: Lato + Playfair Display - Tech/SaaS: DM Sans + Space Grotesk - Legal/finance: Source Sans 3 + Merriweather --- ## Phase 3: Build All Pages (Design System & Component Blueprints) This section contains the exact design patterns, Tailwind class combinations, and component structures that produce a polished, professional website. Follow these blueprints precisely for every client site. ### 3a. Header Component Blueprint Sticky nav with logo, dropdown menus, mobile hamburger, and CTA button. ```tsx "use client"; import Image from "next/image"; import Link from "next/link"; import { useState } from "react"; // PATTERN: Separate simple links from dropdown groups const navLinks = [ { href: "/", label: "Home" }, { href: "/how-it-works", label: "How It Works" }, { href: "/wins", label: "Client Results" }, ]; const dropdowns = [ { label: "About", items: [ { href: "/about", label: "Our Story" }, { href: "/faq", label: "FAQ" }, { href: "/blog", label: "Blog" }, { href: "/contact", label: "Contact" }, ], }, // Add more dropdown groups as needed ]; export function Header() { const [mobileOpen, setMobileOpen] = useState(false); return ( <header className="sticky top-0 z-50 bg-white border-b border-gray-100 shadow-sm"> <div className="mx-auto max-w-7xl px-4 sm:px-6 lg:px-8"> <div className="flex h-16 items-center justify-between"> {/* Logo: always use next/image with priority */} <Link href="/" className="flex items-center"> <Image src="/images/logo.png" alt="CLIENT_NAME" width={200} height={66} priority /> </Link> {/* Desktop Nav */} <nav className="hidden lg:flex items-center gap-6"> {navLinks.map((link) => ( <Link key={link.href} href={link.href} className="font-heading text-sm font-semibold uppercase tracking-wider text-gray-700 hover:text-primary transition-colors" /> ))} {/* DROPDOWN PATTERN: group + group-hover for CSS-only dropdowns */} {dropdowns.map((dropdown) => ( <div key={dropdown.label} className="relative group"> <button className="font-heading text-sm font-semibold uppercase tracking-wider text-gray-700 hover:text-primary transition-colors flex items-center gap-1"> {dropdown.label} <svg className="h-4 w-4 transition-transform group-hover:rotate-180" fill="none" viewBox="0 0 24 24" stroke="currentColor"> <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M19 9l-7 7-7-7" /> </svg> </button> <div className="invisible opacity-0 group-hover:visible group-hover:opacity-100 transition-all duration-200 absolute top-full left-0 mt-1 w-56 rounded-md bg-white shadow-lg ring-1 ring-black/5 py-2 z-50"> {dropdown.items.map((item) => ( <Link key={item.href} href={item.href} className="block px-4 py-2 text-sm text-gray-700 hover:bg-gray-50 hover:text-primary transition-colors" /> ))} </div> </div> ))} {/* CTA BUTTON in nav */} <Link href="/precall" className="rounded-md bg-cta px-5 py-2.5 font-heading text-sm font-semibold uppercase tracking-wider text-white hover:bg-cta-dark transition-colors" /> </nav> {/* MOBILE HAMBURGER */} <button className="lg:hidden p-2 text-gray-700" onClick={() => setMobileOpen(!mobileOpen)}> <svg className="h-6 w-6" fill="none" viewBox="0 0 24 24" stroke="currentColor"> {mobileOpen ? ( <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M6 18L18 6M6 6l12 12" /> ) : ( <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M4 6h16M4 12h16M4 18h16" /> )} </svg> </button> </div> {/* MOBILE NAV: flat list with section headers */} {mobileOpen && ( <nav className="lg:hidden pb-4 space-y-1"> {navLinks.map((link) => (