portifolio-evandrodevbr/docs/superpowers/plans/2026-07-08-random-hero-variations.md

Random Hero Variations Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Build six weighted, randomly selected Hero Section layouts with matching 3D scene modes.

Architecture: Add data-driven hero variant configuration in Hero.tsx, choose a variant once on client mount, and render layout-specific panel/accent components from that config. Update HeroScene.tsx to accept a scene variant prop and switch geometry composition without adding dependencies.

Tech Stack: Next.js, React 19, TypeScript, Framer Motion, @react-three/fiber, @react-three/drei, Three.js.

---

Task 1: Add variant data and weighted picker

Files:

• Modify: app/components/Hero.tsx

• Define HeroVariantId, HeroSceneVariant, and HeroVariant types.

• Add six approved variant objects with copy, points, proof items, side panel mode, layout mode, CTA text, and weights.

• Add pickWeightedHeroVariant() using Math.random() and relative weights.

• Keep HERO_VARIANTS[0] as deterministic SSR/default fallback.

Task 2: Render six hero layouts from shared primitives

Files:

• Modify: app/components/Hero.tsx

• Replace fixed hero text with selected variant data.

• Add layout-specific class maps for Command Center, Launch Sequence, Rescue Split, IoT Signal Map, Diagnostic Report, and Cinematic Portrait.

• Add side panel renderer that draws distinct visual panels for each mode using existing CSS/Tailwind utilities.

• Keep primary WhatsApp CTA and secondary cases/CV actions.

Task 3: Parameterize the 3D scene

Files:

• Modify: app/components/cinematic/HeroScene.tsx

• Export/accept a HeroSceneVariant-compatible prop locally as string union.

• Pass the selected scene mode from Hero.tsx into HeroScene.

• Change floating geometry positions/geometries per scene mode.

• Keep reduced motion behavior unchanged: no HeroScene render when reduced motion is enabled.

Task 4: Update tests

Files:

• Modify: app/components/Hero.test.tsx

• Modify: app/components/Hero.reducedMotion.test.tsx

• Update assertions to current commercial CTA/copy.

• Assert at least one approved hero layout renders.

• Assert CTA remains a button and cases/CV remain available.

• Assert reduced-motion content still renders without animation-specific failures.

Task 5: Verify

Commands:

• pnpm exec tsc --noEmit --pretty false
• pnpm test -- Hero.test.tsx Hero.reducedMotion.test.tsx --runInBand
• pnpm build

Expected: all commands exit 0.