docs(02-01): complete marketing site shell plan — nav, hero, testimonials, footer

- Create 02-01-SUMMARY.md with execution results and deviation docs - Update STATE.md position and session continuity - Update ROADMAP.md phase 02 progress - Mark MKTG-01, MKTG-02, MKTG-04 requirements complete
2026-03-19 15:04:15 -06:00
parent a33b4c9520
commit ffb1ab629d
4 changed files with 178 additions and 23 deletions
--- a/.planning/phases/02-marketing-site/02-01-SUMMARY.md
+++ b/.planning/phases/02-marketing-site/02-01-SUMMARY.md
@@ -0,0 +1,145 @@
+---
+phase: 02-marketing-site
+plan: 01
+subsystem: ui
+tags: [react, nextjs, lucide-react, testimonials, carousel, sticky-nav, hero]
+
+# Dependency graph
+requires:
+  - phase: 01-foundation
+    provides: Next.js app router setup, globals.css, layout.tsx, page.tsx scaffold
+provides:
+  - Sticky navy nav with desktop links and mobile hamburger
+  - Split-panel hero section with next/image and brand CTA
+  - Auto-rotating testimonials carousel with arrow/dot controls
+  - Listings Coming Soon placeholder section with brand colors
+  - Site footer with license number and copyright
+  - Public homepage composed from all marketing section components
+affects:
+  - 02-contact-form
+  - 02-listings
+  - future-brand-refinement
+
+# Tech tracking
+tech-stack:
+  added: [lucide-react]
+  patterns:
+    - CSS hover classes in server components (no event handlers — required for server component compatibility)
+    - _components directory convention for route-co-located components
+    - inline <style> blocks in server components for scoped responsive CSS
+
+key-files:
+  created:
+    - teressa-copeland-homes/src/app/_components/SiteNav.tsx
+    - teressa-copeland-homes/src/app/_components/HeroSection.tsx
+    - teressa-copeland-homes/src/app/_components/TestimonialsSection.tsx
+    - teressa-copeland-homes/src/app/_components/ListingsPlaceholder.tsx
+    - teressa-copeland-homes/src/app/_components/SiteFooter.tsx
+  modified:
+    - teressa-copeland-homes/src/app/page.tsx
+    - teressa-copeland-homes/src/app/globals.css
+    - teressa-copeland-homes/package.json
+
+key-decisions:
+  - "CSS hover classes in server components — onMouseEnter/onMouseLeave not valid in server component props; using className + <style> block instead"
+  - "lucide-react installed for icons (Home, Menu, X, ChevronLeft, ChevronRight)"
+  - "TestimonialsSection as 'use client' — requires useState/useEffect/useRef; all other components stay as server components"
+  - "clearInterval returned from useEffect cleanup — prevents memory leak on pause state change"
+  - "ContactSection (from prior commit 39f233d) included in page.tsx section order — already existed with contact-action.ts server action"
+
+patterns-established:
+  - "Server components use CSS classes + inline <style> for hover effects rather than JS event handlers"
+  - "Placeholder copy always wrapped in clearly labelled // PLACEHOLDER comments"
+  - "All brand colors applied via inline style or <style> blocks: navy #1B2B4B, gold #C9A84C, cream #FAF9F7"
+
+requirements-completed: [MKTG-01, MKTG-02, MKTG-04]
+
+# Metrics
+duration: 5min
+completed: 2026-03-19
+---
+
+# Phase 02 Plan 01: Marketing Site Shell Summary
+
+**Sticky nav, split-panel hero with next/image, auto-rotating testimonials carousel, and brand-styled listings placeholder built as Next.js server/client components with lucide-react icons**
+
+## Performance
+
+- **Duration:** ~5 min
+- **Started:** 2026-03-19T20:57:58Z
+- **Completed:** 2026-03-19T21:02:31Z
+- **Tasks:** 2
+- **Files modified:** 8
+
+## Accomplishments
+- SiteNav with sticky positioning, responsive hamburger, and anchor links to all page sections
+- HeroSection split-panel with next/image fill, brand copy, and gold CTA button
+- TestimonialsSection client component — 5 placeholder reviews, 5s auto-rotate, hover-pause, arrow controls, dot indicators, clearInterval cleanup
+- ListingsPlaceholder section with Home icon, navy background, and gold bordered CTA
+- SiteFooter with license number, TODO verify comment, copyright year, and nav links
+- page.tsx composed in correct order: SiteNav → HeroSection → TestimonialsSection → ListingsPlaceholder → ContactSection → SiteFooter
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Scaffold nav, hero, listings, footer** - `c26a0b1` (feat)
+2. **Task 2: Testimonials carousel** - `6d701b7` (feat)
+3. **Fix: Restore TestimonialsSection in page.tsx order** - `a33b4c9` (fix)
+
+## Files Created/Modified
+- `src/app/_components/SiteNav.tsx` - Sticky navy nav, desktop links, mobile hamburger with Menu/X toggle
+- `src/app/_components/HeroSection.tsx` - Split-panel hero, next/image fill, PLACEHOLDER-commented copy
+- `src/app/_components/TestimonialsSection.tsx` - Client carousel, useState/useEffect, clearInterval cleanup, arrow+dot controls
+- `src/app/_components/ListingsPlaceholder.tsx` - Navy section, Home icon, listings CTA
+- `src/app/_components/SiteFooter.tsx` - License with TODO verify comment, copyright, nav links
+- `src/app/page.tsx` - Composing all section components in order
+- `src/app/globals.css` - scroll-behavior: smooth, scroll-margin-top: 72px
+- `package.json` - Added lucide-react dependency
+
+## Decisions Made
+- CSS hover classes used in server components instead of onMouseEnter/onMouseLeave event handlers — event handlers cannot be passed to Client Component props in Next.js 16 server components
+- TestimonialsSection is 'use client' because carousel requires useState, useEffect, and useRef
+- clearInterval called in useEffect cleanup function to prevent memory leak when paused state changes
+- ContactSection (created in prior commit 39f233d from an out-of-plan automated action) was wired into page.tsx since it already existed with its contact-action.ts server action dependency
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 1 - Bug] Removed event handler props from server components**
+- **Found during:** Task 1 (Build verification)
+- **Issue:** `onMouseEnter` / `onMouseLeave` on HeroSection and ListingsPlaceholder caused Next.js prerender error: "Event handlers cannot be passed to Client Component props"
+- **Fix:** Replaced inline event handler props with CSS class hover rules in inline `<style>` blocks
+- **Files modified:** `src/app/_components/HeroSection.tsx`, `src/app/_components/ListingsPlaceholder.tsx`
+- **Verification:** `npm run build` exits 0 with no TypeScript errors after fix
+- **Committed in:** `c26a0b1` (Task 1 commit)
+
+**2. [Rule 1 - Bug] Restored TestimonialsSection in page.tsx after linter rewrite**
+- **Found during:** Task 2 completion check
+- **Issue:** An automated linter/tool rewrote page.tsx to import ContactSection, omitting TestimonialsSection and removing the section id="contact" stub
+- **Fix:** Rewrote page.tsx with both TestimonialsSection and ContactSection imports in correct order
+- **Files modified:** `src/app/page.tsx`
+- **Verification:** `npm run build` exits 0; all sections present in correct order
+- **Committed in:** `a33b4c9` (fix commit)
+
+---
+
+**Total deviations:** 2 auto-fixed (2x Rule 1 - Bug)
+**Impact on plan:** Both fixes required for correctness — no scope creep.
+
+## Issues Encountered
+- Linter/tool repeatedly rewrote page.tsx mid-execution to include a ContactSection import. The ContactSection component had been created in an earlier out-of-plan commit (39f233d), so the build still passed but TestimonialsSection was lost from the section order. Required an extra fix commit to restore correct ordering.
+
+## User Setup Required
+None - no external service configuration required.
+
+## Next Phase Readiness
+- Public homepage shell is complete and passes build
+- All placeholder copy clearly labelled with PLACEHOLDER comments for future content replacement
+- License number has TODO verify comment for Teressa to confirm before launch
+- Ready for Phase 02-02 contact form integration and Phase 02-03 listings section
+
+---
+*Phase: 02-marketing-site*
+*Completed: 2026-03-19*