docs: spec for flagship product film (landing-bookended, 5 value pillars, crane CTA close)

2026-05-30 00:30:25 +05:30
parent 34fb4e8226
commit 5acc8591c6
1 changed files with 193 additions and 0 deletions
@@ -0,0 +1,193 @@
 # LynkedUp Pro — Flagship Product Film (Design Spec)
 > **Status:** Design agreed in brainstorming. Pending user review before writing the implementation plan.
 > **Date:** 2026-05-30
 > **Output:** A single comprehensive marketing/product film (~5 min) that conveys the whole product and sells every USP, for a B2B audience of roofing-company **owners** and their **operators**.
 ---
 ## 1. Goal
 Produce one flagship film that makes a roofing-company owner *and* their team believe:
 > "LynkedUp Pro takes us from the storm to the bank in one system — everyone runs it, and the owner controls all of it."
 It must **showcase the real running app** (clicking, form-filling, role switching) as **proof**, organized as a **marketing narrative** (pain → promise → value pillars → payoff → CTA), not a screen-by-screen manual.
 **Length:** ~5 minutes (free to run 4–8; comprehensiveness over brevity). 1080p, 16:9, 30fps.
 ## 2. Audience (B2B, dual)
 - **Owner / operator-buyer** — the economic buyer. Cares about: surviving the storm surge, control/governance as they scale, and *real* profit per job.
 - **Operators** (canvasser, sales rep, project manager/admin, subcontractor) — daily users. Care about: a focused experience that shows them only what they need.
 The dual audience is a **feature, not a problem**: the headline USP is that the *same system gives every role a tailored, permission-bounded experience*. "Dual audience" and "access control" are therefore the **same beat** (Pillar ④).
 ## 3. Constraints
 - **Do not modify any CRM code.** The film is captured from the running app and composited in an isolated sub-project. No edits under `src/`.
 - Self-contained Remotion project at **`marketing/product-film/`** with its own `package.json` (no coupling to the CRM build).
 - Brand consistency: reuse the landing page's visual language (logo, blue/cyan gradient, blueprint grid, the crane, the `craneSwing` curve, the en-US number formatting).
 - Names/numbers on screen must be the canonical demo roster already seeded in the mock store (no fake "Sarah Connor"-style placeholders).
 ## 4. Narrative structure
 **Cold Open → Promise → 5 Value Pillars → Crane CTA Close.** The landing page **bookends** the film (hero open, crane CTA close).
 | Part | Sells | USP |
 |------|-------|-----|
 | Cold Open | The pain: storm hits, leads flood, reps freelance, jobs slip, "where's my margin?" | — |
 | Promise | "One system. Storm to paid. Your team runs it — you control it." | End-to-end + control |
 | ① Turn storms into pipeline | Weather → qualified pipeline, no junk leads | Storm intelligence |
 | ② Right person on every job — automatically | Stop leads going cold; right skills, right roof | AI dispatch |
 | ③ Every job runs on rails | No job slips; crews coordinated | End-to-end execution |
 | ④ Scale with control | Everyone sees only their slice; you set the rules | Role-based access control |
 | ⑤ Know your true profit | Real margin per job; stop flying blind | True profit visibility |
 | Crane CTA Close | The transformation + CTA | — |
 ## 5. Beat sheet
 On-screen text = the **caption**. The **VO line** is the written voiceover script (see §8 — captions + music ship first; real voiceover dropped in later against the same script). Durations approximate.
 ### Cold Open (~12s) — *Animated, landing-hero motif*
 - **Visual:** Echo the landing hero — aerial-scan backdrop, "ROOFING **REVOLUTIONIZED**" wordmark, HUD annotations ("HAIL WATCH ACTIVE · ETA 35 MIN · WIND 24 MPH", "5,847 PROPERTIES TRACKED"). Snap into a 2s chaos montage: ringing phones, a cluttered spreadsheet, sticky notes, a missed-call list — abstracted, fast cuts.
 - **Caption:** "A storm hits. The leads flood in. Then what?"
 - **VO:** "When the storm clears, the race begins. Most roofing teams drown in it."
 ### Promise (~8s) — *Animated, logo reveal*
 - **Visual:** Logo resolves on blueprint grid; tagline types in.
 - **Caption:** "LynkedUp Pro — from the storm to the bank, in one system."
 - **VO:** "LynkedUp Pro turns the chaos into closed, paid jobs — and puts the owner in control of all of it."
 ### ① Turn storms into pipeline (~45s) — *Recording + hybrid*
 - **Screens:** Storm Intel (`StormIntelPage` — hail map, damage zones, `ZoneAssignmentModal`) → Territory Map (`Maps.jsx`) → Pro Canvas (`ProCanvas.jsx`) → Lead Verification (`LeadVerificationPage` — verify identity/insurance; verified → New Lead).
 - **Action choreography:** Storm Intel opens, damage zones light up over Plano → cursor assigns a zone to a canvasser → cut to Lead Verification → cursor opens a pending lead, verifies it → it lands as a New Lead.
 - **Caption beats:** "See the storm before your competition." → "Verify every lead. No junk gets through."
 - **VO:** "Storm Intel maps the damage the moment it lands, so you canvass the right streets first. Every lead that comes back is verified before it ever reaches your pipeline."
 ### ② Right person on every job — automatically (~45s) — *Recording + hybrid*
 - **Screens:** LynkDispatch (`LynkDispatchPage`, `DispatchRecommendationDrawer`, `DispatchMapPanel`) → Skill catalog/matching (`OrgSettings` SkillCatalogSection, `PeopleDirectory` skill scores) → Pipeline kanban (`KanbanPage`) → Lead detail (`LeadProjectPage`).
 - **Action choreography:** Open LynkDispatch → AI recommendation drawer surfaces the best-fit rep (proximity + skill score) → cursor assigns → cut to kanban → cursor drags the lead from Contacted → Estimate.
 - **Caption beats:** "AI picks the right rep — proximity + skill." → "Move every deal forward."
 - **VO:** "LynkDispatch matches each new lead to the closest, best-skilled rep automatically. Deals move through the pipeline instead of going cold."
 ### ③ Every job runs on rails (~50s) — *Recording*
 - **Screens:** Project lifecycle (`OwnerProjectDetail` — advance lifecycle stage) → Inspections + Estimates (`EstimatesPage`, `EstimateBuilder`, `EstimateDetailModal`) → Subcontractor task (`SubcontractorTasksPage`, `AssignTaskModal`) → **Subcontractor Portal** (`SubcontractorTaskDetailPage` — status → review) → Team Management (`TeamManagementPanel`).
 - **Action choreography:** Advance a project stage on the state machine → log an inspection → send an estimate → assign a sub task → **switch into the sub portal** → sub updates status to in-progress, attaches a photo, marks for review.
 - **Caption beats:** "Every job on a clear track." → "Crews get exactly what they need."
 - **VO:** "From inspection to estimate to crew, every job runs on rails. Subcontractors get a focused portal — just their task, nothing else."
 ### ④ Scale with control (~45s) — *Recording, the access-control + dual-audience beat*
 - **Screens:** Org roles (`OrgTeamManagement`) → ABAC permissions (`OrgSettings` access control, `AccessControlPersonModal` — module toggles per role + per-person override) → People directory / Profiles / User Details (`PeopleDirectory`, `UserDetailsPage`).
 - **Live boundary moments:** Owner toggles **Financials = off** for the Sales Rep role → **switch to the rep's view** → Financials nav item is gone. Then the **sub portal** shows only their assigned job. Same app, rendered to each role's permission.
 - **Caption beats:** "You decide who sees what." → "Everyone sees exactly their slice — no more, no less."
 - **VO:** "As you grow, you stay in control. Set permissions by role or by person, and the app reshapes itself — the rep sees only their leads, the crew sees only their job, you see everything."
 ### ⑤ Know your true profit (~45s) — *Recording + hero, the payoff*
 - **Screens:** Financial Overview (`FinancialKPICards`, `FinancialDetailsModal` — cost-to-cost POC, gross/net, drill-down) → Owner Snapshot (`OwnerSnapshot`) → Rep leaderboard (`LeaderboardPage`), commission (`CommissionDistributionPanel`) → **Storm attribution** (dashboard panel; `selectors.stormAttribution`) → Subcontractor performance.
 - **Action choreography:** Open Financial Overview → real gross/net per job (grounded, positive) → drill into one job's revenue recognition → cut to leaderboard → storm attribution ties revenue back to the storm from Pillar ① (narrative bookend).
 - **Caption beats:** "Real margin on every job." → "From that one storm: tracked, attributed, banked."
 - **VO:** "Revenue is recognized job by job on a true cost-to-cost basis — so the profit you see is the profit you have. And every dollar traces back to the storm that started it."
 ### Crane CTA Close (~15s) — *Animated, faithful landing recreation*
 - **Visual:** Recreate the landing crane in Remotion — blueprint tower crane (lattice mast, counter-jib + counterweights, main jib, trolley, dashed hoist cable, hook block). The **CTA card descends on the hoist cable into frame**, then settles into the signature pendulum sway.
  - **Swing:** reproduce `craneSwing` exactly — `rotate(+3deg)` ↔ `rotate(-3deg)`, 4s ease-in-out loop, `transform-origin: top center`. Entry: card starts higher with a slightly larger swing amplitude that damps to ±3°.
  - **Card content (verbatim from landing):** "✓ Project Ready" stamp · headline **"Ready to Build?"** · sub "Whether you protect one home or manage a thousand roofs, the future of roofing starts here." · buttons **"Schedule Demo →"** and **"Start Free Trial →"** · attachment-point dot connecting to the cable.
 - **End plate:** logo · `LynkedUpPro.com` · `866-259-6533`.
 - **Caption:** "Ready to build? Schedule a demo."
 - **VO:** "From the storm to the bank, in one system. Ready to build? Let's get started."
 **Runtime estimate:** ~12 + 8 + 45 + 45 + 50 + 45 + 45 + 15 ≈ **4:25** of content; transitions/title cards bring it to **~5:00**.
 ## 6. Feature → pillar coverage (proves "all functionality")
 | Functionality | Pillar |
 |---|---|
 | Storm Intel / hail map / damage zones / zone assignment | ① |
 | Territory Map | ① |
 | Pro Canvas (canvassing, gamification) | ① |
 | Lead Verification (identity/insurance → New Lead) | ① |
 | LynkDispatch (AI rep recommendation, map, proximity+skill) | ② |
 | Skill catalog + skill scoring | ② / ④ |
 | Leads / Pipeline kanban + lead detail | ② |
 | Project lifecycle state machine | ③ |
 | Inspections | ③ |
 | Estimates / estimate builder / templates | ③ |
 | Subcontractor tasks (state machine) + Subcontractor Portal | ③ |
 | Team Management | ③ / ④ |
 | Org roles & team management | ④ |
 | ABAC permissions (module toggles, per-person overrides) | ④ |
 | People directory / Profiles / User Details | ④ |
 | Financial Overview (cost-to-cost POC, gross/net, drill-down) | ⑤ |
 | Owner dashboards / snapshot | ⑤ |
 | Rep leaderboard / commission | ⑤ |
 | Storm attribution | ⑤ |
 | Subcontractor performance | ⑤ |
 | Landing hero | Cold Open |
 | Landing crane CTA (swing) | Close |
 Nothing is dropped; everything is sold as *5 reasons to buy* across two audiences.
 ## 7. Technical architecture
 ### 7.1 Capture pipeline
 - The CRM runs locally via `npm run dev` (Vite). A capture script drives a browser (Playwright, or the Chrome DevTools / Playwright MCP) to:
  1. Seed the mock store to the required state per beat (via the existing demo seed + in-app actions; no code changes — drive through the UI / `localStorage` the app already uses).
  2. Navigate to each screen, set theme (default **dark** for cinematic look), set a fixed viewport (1920×1080 device-scale 2 for crisp 1080p), and capture **high-res screenshots** of each state. For interaction beats, capture an ordered **sequence of states** (e.g., before/after a drag, before/after a verify) so Remotion can animate between them with a synthetic cursor.
  3. Optionally capture short **screen recordings** (`.webm`) for motion-heavy beats (kanban drag, map zoom) embedded via Remotion `OffthreadVideo`.
 - Captures are written to `marketing/product-film/public/captures/<pillar>/<state>.png`.
 - A `captures.manifest.json` lists every required capture (route, viewport, theme, pre-state) so the set is reproducible and gaps are visible.
 ### 7.2 Remotion project (`marketing/product-film/`)
 ```
 marketing/product-film/
  package.json            # remotion, react, @remotion/cli, tailwind (or inline styles)
  remotion.config.ts
  src/
    Root.tsx              # registerRoot; <Composition id="LynkedUpProFilm" .../>
    Film.tsx              # <Series> of the 8 parts
    theme.ts              # brand tokens (blue/cyan gradient, blueprint grid, crane line vars)
    audio/                # music bed (licensed/royalty-free), optional VO track
    sequences/
      ColdOpen.tsx
      Promise.tsx
      Pillar1Storms.tsx
      Pillar2Dispatch.tsx
      Pillar3Rails.tsx
      Pillar4Control.tsx
      Pillar5Profit.tsx
      CraneClose.tsx
    components/
      ScreenFrame.tsx     # rounded browser-chrome frame around a capture
      Cursor.tsx          # synthetic cursor: spring-tween between targets + click pulse
      KenBurns.tsx        # slow pan/zoom on a still capture
      Caption.tsx         # animated lower-third / center caption
      PillarTitle.tsx     # animated section title card ("① Turn storms into pipeline")
      TypeReveal.tsx      # types text into a field (for form-fill beats)
      Transition.tsx      # wipe/blueprint-line transitions between parts
      Crane.tsx           # blueprint tower-crane SVG (ported from Landing.jsx)
      CraneCard.tsx       # the suspended CTA card with craneSwing reproduction
    captures.manifest.json
  public/captures/...
  out/                    # rendered mp4 (gitignored)
 ```
 - **Root composition:** `LynkedUpProFilm`, 1920×1080, fps 30, `durationInFrames` = sum of part durations.
 - **Cursor:** a single `Cursor` component animates between named targets per beat (spring easing) with a click-pulse keyframe; this is what makes still captures feel "live."
 - **Form-fill beats:** `TypeReveal` overlays typed text onto a capture of the empty form, then crossfades to the captured filled/submitted state.
 - **Crane:** `Crane.tsx` ports the exact SVG line art from `Landing.jsx`; `CraneCard.tsx` reproduces the `craneSwing` keyframe via `interpolate`/`spring` (±3°, 4s, top-center origin) with a damped entry.
 ### 7.3 Audio
 - **Music:** one royalty-free cinematic-corporate bed, ducked under captions; energy build into Pillar ⑤ and the crane close.
 - **Voiceover:** the VO lines in §5 are the **script**. Captions + music ship in v1; a real voiceover can be recorded later and dropped onto the same timeline (sequence timings are authored to the script's pacing). *(Confirm in review: ship captions+music first, VO later — vs. synth/AI VO now.)*
 ### 7.4 Render
 - `npx remotion render LynkedUpProFilm out/lynkedup-pro-film.mp4` → H.264, 1080p, 30fps. A 720p/social cut can be derived later if needed.
 ## 8. Open decisions for review
 1. **Audio:** ship **captions + music now, real VO later** against the §5 script (recommended), or generate an AI voiceover now?
 2. **Theme:** capture the app in **dark mode** (recommended, more cinematic) or light?
 3. **Runtime:** target ~5 min as scoped here, or expand any pillar (e.g., a deeper estimate/insurance beat)?
 ## 9. Out of scope (this spec)
 - Plan 8 ABAC backend, homeowner portal, and any CRM code changes. The film only *depicts* the existing UI.
 - Multi-language captions, social cut-downs, A/B variants — derivable later from the master timeline.