BiohazardVFX/biohazard-vfx
2
1
Fork 0
Code Issues 6 Pull Requests Actions Packages Projects Releases Wiki Activity
biohazard-vfx/docs/prd.md
nicholai ed55376b9c
Some checks are pending
Build and Push to Docker Hub / Push Docker image to Docker Hub (push) Waiting to run
Details
Build and Push Docker Image / build-and-push (push) Waiting to run
Details
bmad-planning-complete
2025-09-24 10:54:01 -06:00

13 KiB
Raw Permalink Blame History

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.