biohazard-vfx/docs/prd.md

# Biohazard VFX — Brownfield Enhancement PRD (Ready)

Note: This PRD is sharded for collaboration. See shard files in `docs/prd/` (start at `docs/prd/00-index.md`).

Status: Ready — confirmations applied (typography, palette, IA, epic, contact persistence; sidebar nav not collapsible)
Version: v4

---

## Intro Project Analysis and Context

### Existing Project Overview
- Analysis Source: IDE-based fresh analysis of current repository (`biohazard-vfx-nextjs`).

#### Current Project State
- Type: Next.js 15 (App Router) + React 19 + TypeScript + TailwindCSS
- UI libs: shadcn/ui primitives (via `class-variance-authority`, `tailwindcss-animate`), Lucide icons, custom components
- Motion & scrolling: `framer-motion`/`motion`, `lenis`
- Data layer: Prisma 6 with NextAuth; routes exist for `projects`, `blog`, `faq`, `team`, `assets`
- Observability: Sentry configured (`@sentry/nextjs`), client/server configs present
- IA present today (selected):
  - Public: `/projects`, `/projects/[id]`, `/faq`, `/contact`, `/privacy`, `/terms`
  - Admin: `/admin`, `/admin/{projects,blog,faq}`, `/admin/login`
- Docs: Architecture docs referenced in core-config are missing (`docs/architecture/*`), so this PRD derives from code and brainstorming results.

### Available Documentation Analysis
- Primary input: `docs/brainstorming-session-results.md` (Five Whys, SCAMPER, IA/journeys, sticky split pattern, design tokens, typography pairs).
- Additional docs: `README.md`, `VISUAL_ENHANCEMENTS*` provide context but are not canonical.

### Enhancement Complexity Assessment
- Significant, multi-story enhancement: unify design system, navigation and IA, add sticky split components, standardize pages (Projects, Process, Studio, Contact), and establish tokens/typography. This warrants a full PRD with sequenced stories.

---

## Problem Statement and Goals

### Problem
- UX/UI fragmentation (inconsistent fonts, ad-hoc styles), unclear IA and navigation model, and lack of codified design system hinder clarity, polish, and delivery velocity.

### Goals
- Establish a coherent brand-forward design system (tokens: color, type, spacing, motion).
- Standardize IA and navigation (sidebar nav + command palette) aligned to key user journeys.
- Implement reusable sticky split pattern for narrative + media without scroll‑jacking.
- Upgrade core pages: Projects (reel + case studies), Process, Studio, Contact (smart form).
- Preserve existing functionality and content while improving presentation and flows.

### Out of Scope (initial release)
- Custom CMS; third‑party marketing automation; deep analytics beyond Sentry/basic events.

---

## Users and Stakeholders
- Primary: Directors/Producers evaluating capability and reliability.
- Secondary: Studio partners, collaborators, and recruits.
- Internal: Biohazard team (content ops, case study publishing, admin views).

---

## Functional Requirements (FR)
FR1: Global design tokens for color, typography, spacing, and motion are defined and consumed across components.
FR2: Select and apply one headline/display font and one body font globally; remove conflicting fonts.
FR3: Sidebar navigation (persistent, not collapsible) reflects target IA groups: Projects, Process, Studio, Contact.
FR4: Command palette (Cmd/Ctrl+K) for quick navigation and actions.
FR5: Projects section includes Reel, Case Studies index with filters, and Case Study detail pages.
FR6: Process section includes Pipeline, Tools, and Infrastructure subpages.
FR7: Studio section includes About, Team, Values pages.
FR8: Contact page implements smart intake form (project type, timeline, budget range, refs) with clear confirmation and next steps.
FR9: Sticky Split component pattern implemented and reusable across Home/Projects/Process/Studio.
FR10: Accessibility supports reduced motion, keyboard navigation, and visible focus management.

## Compatibility Requirements (CR)
CR1: Preserve existing public routes behavior and SEO where applicable (redirects if slugs change).
CR2: Maintain database schema and NextAuth integration; no breaking changes to auth flows.
CR3: UI/UX consistency with new tokens without breaking existing admin functions.
CR4: Integration compatibility with current API routes (`/api/*`) and Prisma models.

---

## UI Enhancement Goals

### Integration with Existing UI
- Adopt Tailwind design tokens via CSS variables layered on current config; refactor shadcn components to consume tokens.
- Consolidate color usage to a dark‑first palette (brand black/orange + neutrals) per brainstorming doc.
- Typography: Headings Rajdhani 600/700; Body Kanit 400/500. [Confirmed]

### Modified/New Screens and Views
- Global: Layout with Sidebar Nav (not collapsible) and Command Palette; Footer.
- Projects: Reel, Case Studies index (filters: type/tool/year), Case Study detail.
- Process: Pipeline, Tools, Infrastructure.
- Studio: About, Team, Values.
- Contact: Smart Form + Confirmation page.

### UI Consistency Requirements
- Tokenized spacing scale; motion presets; focus rings; media player wrapper for consistency.
- Sticky Split pattern components and hooks as a shared lib; mobile fallbacks and reduced‑motion support.

---

## Technical Constraints and Integration Requirements

### Existing Technology Stack
**Languages**: TypeScript
**Frameworks**: Next.js 15 (App Router), React 19, TailwindCSS
**Database**: Prisma (SQLite/Postgres depending on env), NextAuth; optional Cloudflare D1 for contact submissions [Approved]
**Infrastructure**: Next build/start, Sentry for monitoring; no infra files for Vercel/CI in repo
**External Dependencies**: framer-motion/motion, lenis, uploadthing, shadcn primitives, zod, react-hook-form

### Integration Approach
**Database Integration Strategy**: No schema changes required; augment only content display and forms; ensure Contact writes via existing patterns or route additions without breaking Prisma clients.
**API Integration Strategy**: Reuse `/api/*` routes; add new endpoints cautiously (e.g., contact submissions) and version if needed. For contact persistence, allow optional integration with a Cloudflare Worker/D1 via server-side fetch, without impacting existing Prisma schema.
**Frontend Integration Strategy**: Introduce tokens and new components incrementally; gate behind feature flags if needed; refactor pages to consume tokens with minimal churn.
**Testing Integration Strategy**: Component tests for tokens and Sticky Split mechanics; route smoke tests; accessibility checks; performance snapshots.

### Code Organization and Standards
**File Structure Approach**: Keep `src/app/*` routes; add shared components under `src/components/ui/*` and `src/components/patterns/sticky-split/*`.
**Naming Conventions**: PascalCase for components, kebab for route segments, token names as `--bh-*`.
**Coding Standards**: ESLint + Prettier existing; maintain strict TS; avoid one‑off inline styles.
**Documentation Standards**: Co-locate README.md per component/pattern for usage; update main docs after shard.

### Deployment and Operations
**Build Process Integration**: Ensure no increase in warnings; tree-shake unused fonts/components.
**Deployment Strategy**: Incremental deploys; feature flags if needed; maintain redirects for IA adjustments.
**Monitoring and Logging**: Extend Sentry breadcrumbs for navigation and key CTA events.
**Configuration Management**: `.env` unchanged; add envs for contact handling only if required (e.g., Cloudflare credentials, D1 binding endpoint).

### Risk Assessment and Mitigation
**Technical Risks**: Global style regressions; performance drops from animation; font loading flashes.
**Integration Risks**: Breaking admin routes/layouts; IA changes affecting deep links.
**Deployment Risks**: CSS purge issues; caching of old assets.
**Mitigation Strategies**: Token gating and gradual rollout; perf budgets (CLS/LCP targets); redirects and manual QA script; font preloading.

---

## Epic and Story Structure

Epic Structure Decision: Single epic focused on UX/UI unification with sequenced, low‑risk increments. [Confirmed]

### Epic 1: UX/UI Unification and Core Pages
**Epic Goal**: Unify design system and IA, implement reusable patterns, and elevate core pages while preserving existing functionality.

**Integration Requirements**: Each story verifies non‑regression on existing routes and key interactions; redirects for IA changes; accessibility and performance checks included.

#### Story 1.1 Design Tokens and Typography
As a visitor, I want a cohesive visual language so that the site feels premium and consistent.

Acceptance Criteria
1: Global CSS variables for color, spacing, radii, shadows, and motion exist and are documented.
2: Headline font and body font applied globally; extraneous fonts removed.
3: Tailwind config consumes tokens; shadcn primitives reflect tokens.
Integration Verification
IV1: No layout regressions in `/projects`, `/faq`, `/contact`.
IV2: Admin pages remain functional and readable.
IV3: Performance: no >10% increase in CSS/JS bundle.

#### Story 1.2 Global Layout, Sidebar Nav, Command Palette
As a user, I want clear navigation so that I can find Projects, Process, Studio, and Contact quickly.

Acceptance Criteria
1: Sidebar navigation (persistent 240px; not collapsible) groups routes as defined.
2: Command palette opens via Cmd/Ctrl+K with navigation to key routes.
3: Footer includes minimal links; responsive behavior verified.
Integration Verification
IV1: Deep links to existing `/projects/[id]` still resolve.
IV2: Keyboard navigation and focus order preserved.
IV3: No layout shift >0.1 CLS on nav open/close.

#### Story 1.3 Sticky Split Pattern Library
As a storyteller, I want a sticky split component so that narrative and media synchronize during scroll.

Acceptance Criteria
1: `<StickySplit.Section/Sticky/Track/Panel>` components implemented with docs.
2: Reduced‑motion mode disables heavy animations gracefully.
3: Mobile layout stacks content; performance budget respected.
Integration Verification
IV1: No scroll‑jacking; passive listeners only.
IV2: A11y tree/focus unaffected.
IV3: Frame budget within 16ms on mid‑range devices.

#### Story 1.4 Projects Section Revamp
As a prospect, I want a Reel and clear Case Studies so that I can assess capability fast.

Acceptance Criteria
1: `/projects` index offers Reel + Case Studies tabs with filters.
2: Case Study detail template with hero, problem, approach, pipeline, results, credits, CTA.
3: Media player wrapper standardized.
Integration Verification
IV1: Existing project data remains valid.
IV2: SEO: titles/descriptions preserved or migrated.
IV3: Page renders within current TTFB/LCP budgets.

#### Story 1.5 Process Pages
As a technical stakeholder, I want pipeline/tools/infrastructure pages so that I understand reliability and stack.

Acceptance Criteria
1: `/process/{pipeline,tools,infrastructure}` pages implemented with sticky split or light reveals.
2: Badge and icon components for stack and capabilities.
3: Cross‑links to Projects and Contact.
Integration Verification
IV1: No regressions to other routes.
IV2: A11y checks pass.
IV3: Bundle size growth <10% vs prior story.

#### Story 1.6 Studio Pages
As a partner, I want About, Team, and Values so that I can understand ethos and people.

Acceptance Criteria
1: `/studio/{about,team,values}` with content placeholders.
2: Quote/testimonial and logo wall optional components.
3: Global tokens applied.
Integration Verification
IV1: Nav and links correct.
IV2: No console errors.
IV3: Lighthouse a11y ≥ 90.

#### Story 1.7 Contact Smart Form
As an inquirer, I want a guided contact form so that I can convey project essentials quickly.

Acceptance Criteria
1: Fields: project type, timeline, budget range, references/links; validation via zod.
2: Success page with next steps/SLA.
3: Optional route to persist submissions (or email integration) without breaking existing auth.
Integration Verification
IV1: Rate limiting or basic abuse mitigation.
IV2: Error states accessible and clear.
IV3: No PII leakage in logs.

#### Story 1.8 Hardening: Performance, Accessibility, SEO
As a steward, I want the site to be fast and accessible so that it reflects professional standards.

Acceptance Criteria
1: CLS < 0.1; LCP within target for hero pages; images lazy‑loaded.
2: Keyboard navigation across all interactive elements; visible focus rings.
3: Sentry breadcrumbs for nav/CTA; basic event tracking for key flows.
Integration Verification
IV1: Compare metrics to pre‑enhancement baselines.
IV2: No new 4xx/5xx in Sentry after launch.
IV3: Sitemap/robots updated if IA changed.

---

## Non‑Functional Requirements (NFR)
- Accessibility: Respect `prefers-reduced-motion`; maintain focus order; ARIA where needed.
- Performance: No story may increase bundle size by >10% without explicit approval.
- Reliability: No breaking changes to existing APIs or auth; error boundaries for new components.
- Observability: Sentry enabled across new interactions; console clean.

---

## Decisions (Resolved)
- Typography: Rajdhani (600/700) headings, Kanit (400/500) body — Approved.
- Brand palette: Dark‑first black/orange + neutrals — Approved.
- Navigation: Left sidebar (240px), not collapsible + Command Palette — Approved.
- IA routes: `/projects`, `/process`, `/studio`, `/contact` with listed children — Approved.
- Epic structure: Single-epic with Story 1.1 → 1.8 — Approved.
- Contact handling: Persist submissions allowed; Cloudflare D1 acceptable; no compliance constraints — Approved.