⚠️ READ FIRST: PNPM_11_REQUIREMENTS.md in this skill dir. Webdev containers (where Mike previews your sites) run pnpm 11.1.1 since 2026-05-13. EVERY new project MUST declare pnpm.onlyBuiltDependencies in package.json (at minimum: ["sharp"] for any Next.js project) or the dev server WILL NOT START. Skip this and the container restart-loops, the site goes 502, and the user blames you. 60-second read; ignore at your peril.

Website Builder — Complete Next.js Website Skill

Research-driven, design-intentional website building. Every decision backed by data, every section justified by research.

When to Use This Skill

TRIGGER when the user asks to:

Build a new website
Create a website for their business
Start a new web project
"Make me a site"

DO NOT USE for:

Canvas pages (use canvas-web-design skill instead)
Editing an existing website project (follow that project's .claude/CLAUDE.md)
Remotion video projects (use remotion-video skill)

NON-NEGOTIABLE RULES

NEVER write code before completing research and design planning. Phases 1-4 produce zero code. That's correct.
NEVER deliver a page with template defaults. If you see "Logo", "(555) 000-0000", "[email protected]", "Service One" — you FAILED.
NEVER write copy without keyword research. Every headline targets a specific keyword from Phase 3.
NEVER skip the design plan. Every section, color, and animation must have a documented REASON.
NEVER use scare tactics or fear-based headlines. Write benefit-focused, SEO-targeted copy.
ALWAYS run the placeholder sweep before presenting any site. Zero tolerance.
ALWAYS customize every section. If a section renders built-in defaults, you forgot to pass props.
NEVER ship back-button hijacking. No history.pushState loops, redirect-traps, or modal/overlay chains that stop the browser Back button from returning the user to the SERP — a Google spam-policy violation (malicious practices, enforced 2026-06-15) carrying manual-action + demotion risk. Audit exit-intent scripts, interstitials, and any included ad/library code (the violation often originates there, not first-party). Verify in Phase 12. (developers.google.com/search/blog/2026/04/back-button-hijacking)

Site Types

Identify during intake — it changes everything:

Type	Goal	Key Sections	Copy Style
SEO Leadgen	Rank + capture leads	Hero + TrustBar + CoverageGrid + HowItWorks + FAQ + Testimonials + CTA	Keyword-rich, benefit-focused, professional
Local Service	Phone calls + forms	Hero + TrustBar + Services + ServiceAreas + Reviews + CTA	Direct, trust-building, location-targeted
Portfolio	Showcase work	Hero + ProjectGrid + About + Process + Contact	Visual, minimal copy, let work speak
SaaS / Product	Signups / trials	Hero + Features + Pricing + Testimonials + FAQ + CTA	Benefit-focused, comparison-driven

Local Service sites: See the Local Service CRO Rules section below before building any home service or contractor site. Most local sites convert under 1%. These rules get to 3–5%.

Local Service CRO Rules

Source: Noah Igler (@noahiglerSEO) conversion audit of home service sites (plumbers, HVAC, roofers, electricians, landscapers, etc.). Most sites get fine traffic but the phone doesn't ring — because the site leaks leads, not traffic.

Most home service sites convert under 1%. These rules target 3–5% with the same traffic.

Above the Fold (80% of conversions won or lost here)

Within 3 seconds of landing, visitors must know: what you do, where you do it, that you're trustworthy, and how to call you. Every element below is required — not optional.

Headline format: "[Service] in [City]" or "[City]'s Trusted [Service] Company" — NOT "Your Trusted Home Service Partner Since 2003"
Phone number: Top right, large font, sticky as user scrolls — wire directly to tel: link (NO modal, NO popup, NO confirmation step — a modal caused one client a 30% drop in calls)
Trust bar / subheadline: Star rating + review count + years in business + license number + service area — all in the hero
Primary CTA: "Call Now" or "Get Free Quote" — show the phone number ON the button or immediately below it
Hero image: Real photos of your team in branded shirts, trucks on job sites, or actual work — NO stock photos of smiling families (visitors spot them instantly; trust flips negative)

Phone Visibility — The Single Biggest Lever

Sticky header: phone number always visible on mobile as user scrolls
Sticky footer bar on mobile: two buttons — "Call Now" (tel: link) and "Book Online" — always in view
Floating action button on long pages
Adds 15–25% to call volume in practice

Forms — Every Extra Field Costs ~10% of Conversions

Maximum 4 fields for any home service lead form:

Name
Phone
Service needed (dropdown — not free text)
Address

Never add: email, "best time to call", "how did you hear about us", comments box, address proof, or any qualifying questions. You're not running a credit application — you're getting their phone number so you can call back. The qualifying happens on the call.

Mobile Speed — Non-Negotiable

Below PageSpeed 50 on mobile = lose 2–3 Map Pack spots
Below PageSpeed 70 = lose 20–30% of mobile visitors before page loads
Target: PageSpeed 70+ mobile, page load < 2 seconds

Speed fixes (in order of impact):

Compress hero image to 200–400KB (most sites ship 2–3MB hero images)
Remove unnecessary plugins and tracking scripts
Use a real CDN (not just the host's bundled option)
Lazy load everything below the fold
Minimize third-party widgets (live chat, social embeds, review aggregators) — they load late and cover the phone number

Reviews / Social Proof — Must Appear at Every Scroll Depth

Don't put all proof in one testimonial section halfway down. Visitors need to see it at every level:

Above fold: "4.9 stars from 312 Google reviews" — count + rating in the hero trust bar
Hero section: 2–3 short pull quotes from real reviews, preferably dynamic from GBP
Service pages: dedicated review section pulling quotes that mention that specific service
By the form: repeat proof right before the ask

The goal: by the time they reach the form, they've seen proof 5–6 times.

Photos — Real Images Over Stock Every Time

Real photos of team in branded shirts on job sites
Trucks parked at actual customer homes
Before-and-after shots (drain cleaning, panel work, AC installs, ductwork, roof replacements)
License documents, manufacturer certifications, insurance certificates photographed and displayed
The site should look like a physical business with real people, not a template a marketing agency dropped a logo into

Financing — Required for High-Ticket Services ($5K+)

~60% of customers for replacement-level jobs want financing. If your competitor shows the Synchrony / GreenSky / Wisetack logo and you don't, they close the deal before you get to quote.

Logo of financing partner visible above the fold on service pages
"0% financing available" or "Payments as low as $89/month" callout in the hero
Separate financing page linked from main nav
Pre-qualification widget embedded on high-ticket service pages

Common Mistakes That Kill Conversions

These appear constantly in audits — do not ship any of them:

Longer forms to "qualify" leads — you're not qualifying them, you're losing them
Hiding the phone to force form fills — they just leave instead
Auto-playing video in the hero section — kills mobile speed, annoys the visitor
Pop-ups on first visit — immediate back-button trigger on mobile
Live chat widgets — take 4s to load, cover the phone number, add zero value for home service

Tech Stack (every project)

Tool	Package	Purpose
Next.js 15	`next`	App Router, server components, server actions
React 19	`react`	UI framework
TypeScript	`typescript`	Type safety
Tailwind CSS v3	`tailwindcss`	Utility-first styling (v3 — NOT v4, v4 has PostCSS issues)
shadcn/ui	`shadcn` (CLI)	Component library (Radix + Tailwind)
Motion	`motion`	Animations (spring physics, scroll, layout)
Lenis	`lenis`	Smooth scroll (< 4kb, accessible)
Lucide React	`lucide-react`	SVG icons

Optional (install when needed)

Tool	Package	When
Pretext	`@chenglou/pretext`	Text measurement without DOM reflow — virtualized lists, chat UIs, masonry grids, auto-sizing text containers, canvas text rendering. ~500x faster than getBoundingClientRect. Zero deps. See `/mnt/shared-skills/pretext/SKILL.md`
GSAP	`gsap`	Complex scroll sequences, SplitText, MorphSVG
Three.js	`three` + `@react-three/fiber`	3D backgrounds or hero elements
MDX	`@next/mdx`	Blog with rich content
Prisma	`prisma`	Database access

13-Phase Workflow

Follow these phases IN ORDER. Do not skip phases. Phases 1-4 produce ZERO code — they produce research and a plan. That's the point.

Phase 1: DISCOVER

Read: instructions/brand-intake.md

Ask the client the brand intake questions BEFORE anything else:

Business identity, industry, target customer
Brand colors, tone, personality
SEO goals, competitors, what customers search for
Pages needed, special features, primary CTA
Site type (SEO leadgen, local service, portfolio, SaaS)

Deliverable: Completed intake answers

Phase 2: SETUP

Read: instructions/folder-setup.md

Create the ai/ folder structure inside the project directory:

Create all research directories (01-07)
Create design, content, and blog-research directories
Initialize research-status.json
Populate 01-business-profile/profile.md from intake answers

Deliverable: Complete ai/ folder structure with business profile filled in

Phase 3: RESEARCH (the foundation — DO NOT RUSH)

Read: instructions/research-plan.md

Six research tasks that inform EVERYTHING that follows:

Keyword research — Find 50-100+ keywords across primary, secondary, long-tail, location categories. Document in ai/research/02-keyword-research/. Search Google, capture PAA questions, build keyword clusters.
Competitor deep analysis — Review 5-10 competitor sites in detail. For each one: document their homepage sections, hero layout, CTAs, visual design, typography, animations, content quality, strengths, weaknesses. Create per-competitor review files in ai/research/03-competitor-analysis/site-reviews/. Then synthesize into pattern-analysis.md (common patterns across niche) and gaps-opportunities.md (what we exploit).
Content strategy — Map every page: URL, keywords, sections, H1, meta tags. Create per-page content briefs in ai/research/04-content-strategy/content-briefs/. Research FAQ questions from PAA, Reddit, forums.
Topical map — Build topic cluster architecture: pillar pages, cluster content, internal linking strategy. Document in ai/research/05-topical-map/.
Local SEO (if applicable) — Target service areas, local competitors, city-specific keywords. Document in ai/research/06-local-seo/.
Conversion patterns — Analyze competitor CTAs, trust signals, social proof patterns. Map the conversion funnel. Document in ai/research/07-conversion-patterns/.

Deliverable: 20-40 research files across 7 directories. Update research-status.json.

Phase 4: DESIGN PLAN (the thinking phase — every decision intentional)

Read: instructions/design-plan.md

This is where a site goes from "another template" to something that WORKS. Six design documents:

Competitor visual audit (ai/design/competitor-visual-audit.md) — Review all competitor sites for visual patterns: hero types, section ordering, color schemes, typography, animations, photography style. Rank them by visual quality. Identify what to beat.
Style direction (ai/design/style-direction.md) — Choose aesthetic with reasoning. Colors, fonts, dark/light mode, spacing — every choice traced to brand intake + competitor analysis + industry context.
Component plan (ai/design/component-plan.md) — Every component needed, in order, with its purpose. Why this hero layout? Why this trust bar style? Why these sections in this order? Map to the conversion funnel.
Animation plan (ai/design/animation-plan.md) — What moves, why, how. Entrance animations, hover states, scroll effects. Intentional motion, not random decoration.
Page wireframes (ai/design/page-wireframes.md) — Section-by-section layout for every page. ASCII wireframes showing structure.
Design brief (ai/design/design-brief.md) — Master document. Summarizes all design decisions, lists what makes this site "pop" vs competitors, connects every choice to research.

Deliverable: 6 design documents. The design brief is the reference for the entire build.

Phase 5: SCAFFOLD

Read: instructions/architecture.md Use: templates/project/ directory

Copy templates/project/ to Websites/<project-name>/
Run pnpm install
Install shadcn: pnpm dlx shadcn@latest init
Install core shadcn components: pnpm dlx shadcn@latest add button card badge separator input textarea label
Install animation deps: pnpm add motion lenis
Initialize git, commit scaffold
Create private GitHub repo, push, create web-dev branch
Fill in .claude/CLAUDE.md using templates/config/claude-project.md

Phase 6: DESIGN SYSTEM

Read: instructions/design-system.md Use: templates/config/design-tokens.css

Apply the style direction from Phase 4:

Set color palette (chosen in design plan, not random)
Set font pairing (chosen in design plan, not random)
Configure CSS variables in globals.css
Configure tailwind.config.ts with brand colors
Cross-reference: python3 /mnt/shared-skills/ui-ux-pro-max/scripts/search.py

Phase 7: CONTENT WRITING

Read: instructions/content-writing.md

Write ALL copy BEFORE building pages. Save to ai/content/ — one file per page:

Reference content briefs from Phase 3
Write every headline, paragraph, bullet, CTA, testimonial, FAQ answer
Every headline targets a keyword from Phase 3
Every paragraph is benefit-focused and industry-specific
No generic filler — real numbers, real scenarios, real language
Review against competitor gaps — our content must be MORE specific

Deliverable: Complete copy files in ai/content/ for every page

Phase 8: BUILD PAGES

Read: instructions/animations.md, instructions/scroll-effects.md If Local Service / Home Service site: ALSO read instructions/home-service-conversion.md — contains required implementation patterns for phone wiring, form fields, sticky CTAs, hero images, and trust placement. Do not build a local service site without reading this first. Use: templates/sections/, templates/animations/, templates/pages/

Now — and ONLY now — you write code. For each page:

Follow the wireframe from Phase 4
Select section templates from templates/sections/
Pass ALL content from Phase 7 via props — NO template defaults
Apply animations from the animation plan (Phase 4)
Generate/source images as you build (read instructions/images.md)

Section selection by site type:

Site Type	Required Sections
SEO Leadgen	Navbar + Hero + TrustBar + Stats + CoverageGrid/Features + HowItWorks + Testimonials + FAQ + CTA + Footer
Local Service	Navbar + Hero + TrustBar + Services + ServiceAreas + Stats + Reviews + FAQ + CTA + Footer
Portfolio	Navbar + Hero + ProjectGrid + About + Process + CTA + Footer
SaaS	Navbar + Hero + Features + Pricing + Testimonials + FAQ + CTA + Footer

Phase 8b: COMPILE CHECK (required)

cd <project-dir> && pnpm build

Fix all errors before moving on.

Phase 9: FORMS & BACKEND

Read: instructions/forms-backend.md

Build industry-specific form fields (NOT generic name/email/message)
Create /api/contact route (file-based JSON storage)
Test form submission end-to-end

Phase 10: BLOG (if needed)

Read: instructions/blog-setup.md

Install MDX dependencies
Create blog index and [slug] dynamic route
Write 2-3 starter posts targeting long-tail keywords from Phase 3
Add to sitemap

Phase 11: SEO FINALIZATION

Read: instructions/seo.md, instructions/performance.md

Metadata in layout.tsx — use keywords from Phase 3
Per-page metadata with page-specific keywords
sitemap.ts and robots.ts
Structured data (JSON-LD) for business type
Error/404 pages
Image optimization

Phase 12: QUALITY GATE (MANDATORY)

Read: instructions/quality-checklist.md

Placeholder sweep — zero tolerance:

grep -rn "example\.com\|placeholder\|TODO\|FIXME\|Lorem\|project-name\|REPLACE:\|UPDATE:\|000-0000\|hello@\|Service One\|Service Two\|Service Three\|A short description\|Your Headline\|Business Name\.\|Sarah Johnson\|Mike Chen\|Lisa Rodriguez" src/ --include="*.tsx" --include="*.ts"

Every match = failure.

Also verify:

Phase 13: DEPLOYMENT

Read: instructions/deployment.md

pnpm build — fix any errors
Commit, push to web-dev branch

JamBot: cd Websites/<name> && pnpm install && pnpm build, then canvas URL. No container: Tell user admin needs jambot-add-website.sh. External: Vercel/Netlify/Docker per instructions/deployment.md.

Style Rules

DESIGN SOURCE PRECEDENCE (check FIRST, before any styling decision): If Stitch is available (the stitch skill / MCP responds), the styled template comes from Stitch — either supplied screens, the chosen 4-style Creator variant, or a generated home screen — and that template is the locked style contract for every other page on the site (WEBSITE-BUILD.md RULE 0 tiers; same-project generate_screen_from_text style-continuation for additional pages). Hand-styling from scratch is the FALLBACK for when Stitch is genuinely unavailable after retries — never the first move.

SECTION RHYTHM — NO MONOTONE PAGES (applies to every page, both paths):

Adjacent sections must NEVER share the same background — the page is a stack of visibly distinct full-width bands
Rotate ≥3 background treatments per page: base color · tinted/elevated band · inverted contrast band (dark band on a light site / light band on a dark site) · accent wash · full-bleed image band with overlay
At least one inverted contrast band per page (trust bar, testimonials, or CTA are the natural spots)
Every section boundary must be obvious in a zoomed-out thumbnail; one continuous white sheet ("bright document") or dark sheet with dark containers ("dark hole") = FAILED design
Cards must contrast against their band — never dark-box-on-dark-band or white-box-on-white-band

REQUIRED:

Light vs dark mode is an INDUSTRY decision, not a default: local/home-service and professional-service sites are light-dominant (dark bands as punctuation); SaaS/tech/portfolio may be dark-dominant (with at least one light band for breathing room). See WEBSITE-BUILD.md "DESIGN RULES BY BUSINESS TYPE".
Brand accent colors via CSS variables (not hardcoded)
All interactive elements: hover state + cursor-pointer
Animations respect prefers-reduced-motion
Mobile-first responsive (375px → up)
SVG icons from lucide-react only

CLOUDFLARE COMPATIBILITY (critical for JamBot dev sites):

Cloudflare "Email Address Obfuscation" breaks React hydration
Do not render bare email addresses in JSX — use onClick handlers or encode

BANNED:

Purple (#764ba2, #667eea, #8b5cf6), pink, magenta as primary colors
Emoji as UI icons
Lorem ipsum or placeholder text in delivered pages
href="#" on buttons (use <button> or real links)
External CDN scripts
Inline styles (use Tailwind classes)
Fear-based / scare-tactic headlines
Generic "we deliver quality service" copy without specifics
Defaulting new builds to AMP — since 2026-07-01 Google serves AMP from the publisher's own host (AMP Cache / viewer / signed-exchange retired), so AMP's speed edge is gone and it ranks like any page; build a fast responsive page with good CWV instead

Fetching Fresh Docs (On Demand)

curl -s https://ui.shadcn.com/llms.txt | head -200      # shadcn/ui
curl -s https://nextjs.org/docs/llms.txt | head -200      # Next.js
curl -s https://tailwindcss.com/docs/llms.txt | head -200  # Tailwind

Cross-Skill References (DO NOT DUPLICATE)

Need	Command
Color palettes	`python3 /mnt/shared-skills/ui-ux-pro-max/scripts/search.py "<query>" --domain color`
Font pairings	`python3 /mnt/shared-skills/ui-ux-pro-max/scripts/search.py "<query>" --domain typography`
UX rules	`python3 /mnt/shared-skills/ui-ux-pro-max/scripts/search.py "<query>" --domain ux`
Full design system	`python3 /mnt/shared-skills/ui-ux-pro-max/scripts/search.py "<industry> <type>" --design-system`
Copywriting	Read `/mnt/shared-skills/marketing/copywriting/SKILL.md`
Site architecture	Read `/mnt/shared-skills/marketing/site-architecture/SKILL.md`
CRO / conversion	Read `/mnt/shared-skills/marketing/page-cro/SKILL.md`
SEO	Read `/mnt/shared-skills/marketing/local-seo/SKILL.md`
Theme presets	Read `/mnt/shared-skills/theme-factory/SKILL.md`

File Index

instructions/
  brand-intake.md        — Discovery questions (SEO + competitor questions included)
  folder-setup.md        — /ai/ directory structure initialization
  research-plan.md       — Deep foundational research: keywords, competitors, content, topical map, conversion
  design-plan.md         — Design thinking: visual audit, style direction, component plan, wireframes
  content-writing.md     — Copy guidelines by site type, tone, and industry
  design-system.md       — Color, typography, theme setup
  architecture.md        — Next.js project structure and conventions
  animations.md          — 15 animation patterns with Motion.dev/GSAP/CSS code
  scroll-effects.md      — Lenis + scroll-triggered animations + parallax
  images.md              — Image strategy, OG images, favicons, optimization
  blog-setup.md          — Full MDX blog system with dynamic routing
  forms-backend.md       — Contact form server actions (Resend/AgentMail/file)
  seo.md                 — Metadata, OG, sitemap, structured data, robots
  performance.md         — Image optimization, fonts, code splitting, Core Web Vitals
  deployment.md          — JamBot dev server, static build, Vercel, Netlify, Docker
  quality-checklist.md   — 40+ point pre-delivery audit
  references.md          — llms.txt URLs, ui-ux-pro-max queries, component reference

templates/
  project/               — Full Next.js 15 starter (copy to scaffold)
  sections/              — 18 section components (Navbar, Hero, Features, FAQ, etc.)
  animations/            — 9 reusable wrappers (FadeIn, Stagger, Parallax, etc.)
  pages/                 — 5 full page compositions (Home, About, Services, Contact, Blog)
  config/                — Project CLAUDE.md template, CSS design tokens

tools/
  scaffold.sh            — Create project, copy templates, install deps, git init
  github-setup.sh        — Create private repo, push, set up web-dev branch

在你喜歡的 AI 中提問

說明文件