# 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: `` 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.