Product Detail Page Design and Implementation

The Product Detail Page serves as the cornerstone of e-commerce user experience, requiring seamless integration of product data, media, and interactive elements while maintaining optimal performance and accessibility standards.

1. Problem Statement & Requirements

Clarifying questions

1. Target devices/browsers? Will this be optimized for mobile-first, desktop-only, or cross-platform support with specific browser version requirements (e.g., IE11 compatibility)?
2. Authentication and authorization? Do we need to handle guest vs. authenticated user states, or is this a public product page?
3. Real-time vs. static data? Should the PDP support real-time inventory updates, price changes, or is it primarily static content?
4. Offline support needs? Should users be able to view cached product details when offline, or is this strictly online?
5. Accessibility level? What WCAG compliance level is required (AA or AAA), and are there specific assistive technology requirements?
6. i18n requirements? Will this support multiple languages or currencies, and how should we handle RTL layouts?
7. Design system availability? Are there existing design tokens, component libraries (e.g., Material UI, Tailwind), or style guides to integrate with?

Functional requirements

• Display comprehensive product information including title, description, price, availability, and inventory status
• Show multiple product images with thumbnail navigation and zoom capability
• Allow users to select variants (size, color, etc.) and add to cart
• Support product reviews and ratings display
• Show related or recommended products
• Enable users to save products to wishlist/bookmarks
• Provide product comparison functionality (if multiple products are shown side-by-side)
• Support user-generated content like Q&A or product videos
• Enable sharing functionality (social media, copy link)
• Handle user actions like add to cart, buy now, and wishlist toggle

Non-functional requirements

• Performance: Page load time under 2 seconds, LCP < 2.5s, CLS < 0.1
• Accessibility: WCAG 2.1 AA compliance, keyboard navigation support, screen reader compatibility
• Scalability: Handle 10k+ concurrent users viewing product pages with minimal latency
• Reliability: Graceful degradation when API calls fail or content is unavailable
• Responsiveness: Mobile-first design with adaptive layouts for all screen sizes

Constraints and assumptions

• Product data is served via a GraphQL or REST API with structured schema
• The product detail page will be part of an existing e-commerce platform
• Product images are optimized for web delivery (responsive formats, lazy loading)
• Authentication is handled at the application level with session tokens
• The design system provides consistent spacing, typography, and color palette
• No server-side rendering (SSR) is required for this feature

Out of scope

• Product search and filtering capabilities (handled in separate features)
• Shopping cart or checkout flow (handled in separate features)
• Admin panel for product management (handled in separate features)
• Product image editing or upload functionality
• Multi-language content translation (handled in i18n feature)
• Analytics tracking and user behavior measurement (handled in monitoring feature)

2. Component Architecture

Component Tree Diagram

graph TD
    A[ProductDetailPage] --> B[ProductHeader]
    A --> C[ProductImages]
    A --> D[ProductInfo]
    A --> E[ProductActions]
    A --> F[ProductReviews]
    A --> G[RelatedProducts]
    
    D --> H[ProductTitle]
    D --> I[ProductPrice]
    D --> J[ProductDescription]
    D --> K[ProductAttributes]
    
    E --> L[QuantitySelector]
    E --> M[AddToCartButton]
    E --> N[AddToWishlistButton]
    
    F --> O[ReviewList]
    F --> P[ReviewForm]
    
    G --> Q[ProductCard]

Component Breakdown

Smart Components (Container Components):

• ProductDetailPage - orchestrates the entire product detail flow, manages state, and handles API interactions
• ProductHeader - manages breadcrumbs and navigation context
• ProductReviews - handles review loading, submission, and display logic

Dumb Components (Presentational Components):

• ProductImages - displays product image gallery with thumbnails
• ProductTitle - renders product title with proper typography
• ProductPrice - formats and displays pricing information
• ProductDescription - renders rich text product description
• QuantitySelector - handles quantity selection UI
• AddToCartButton - manages cart interaction state
• ReviewList - displays list of reviews with pagination
• ProductCard - reusable card component for related products

TypeScript Props Contracts

// ProductDetailPage Props
interface ProductDetailPageProps {
  productId: string;
  initialProduct?: Product;
  initialReviews?: Review[];
}

// ProductInfo Component Props
interface ProductInfoProps {
  product: Product;
  onQuantityChange?: (quantity: number) => void;
  selectedQuantity: number;
}

// ProductActions Component Props
interface ProductActionsProps {
  product: Product;
  quantity: number;
  onAddToCart: () => void;
  onAddToWishlist: () => void;
  isAddingToCart: boolean;
  isAddingToWishlist: boolean;
}

// ReviewForm Component Props
interface ReviewFormProps {
  productId: string;
  onSubmit: (review: Omit<Review, 'id' | 'createdAt'>) => void;
  isLoading: boolean;
}

UI State Machine Diagram

stateDiagram-v2
    [*] --> Idle
    Idle --> Loading : fetchProduct()
    Loading --> Success : productLoaded
    Loading --> Error : fetchFailed
    Success --> EditingReview : openReviewForm()
    EditingReview --> SubmittingReview : submitReview()
    SubmittingReview --> Success : reviewSubmitted
    SubmittingReview --> Error : reviewFailed
    Error --> Idle : retryFetch()
    Success --> ViewingReviews : viewReviews()
    ViewingReviews --> EditingReview : addReview()

Component Responsibilities and Props

ProductDetailPage:

• Fetches product and reviews data
• Manages overall page state (loading, error, success)
• Handles user interactions and navigation
• Passes data down to child components

ProductHeader:

• Displays breadcrumbs and navigation links
• Handles back navigation
• Manages page title for SEO

ProductImages:

• Renders image gallery with thumbnail navigation
• Handles image loading states and errors
• Implements zoom functionality

ProductInfo:

• Displays core product information (title, price, description)
• Manages quantity selection state
• Formats product attributes for display

ProductActions:

• Handles add to cart and wishlist interactions
• Manages loading states for user feedback
• Implements optimistic UI updates

ProductReviews:

• Loads and displays product reviews
• Manages review submission flow
• Handles pagination and sorting

Reusability Decisions

1. ProductCard is reused across multiple features (related products, search results)
2. ReviewForm is generic and can be reused for product feedback
3. QuantitySelector is a standalone component with consistent API
4. AddToCartButton and AddToWishlistButton are feature-specific but share common UI patterns

Component Lifecycle Considerations

1. Mounting: Fetch initial product data and reviews
2. Updating: Handle quantity changes, review submissions, and state transitions
3. Unmounting: Cancel ongoing requests, clear timeouts, clean up event listeners
4. Error Recovery: Implement retry mechanisms for failed data fetches
5. Performance: Use React.memo for stable props, useCallback for event handlers

The component architecture prioritizes separation of concerns while maintaining performance through proper state management and memoization strategies. The design supports scalability for feature additions like product variants, size charts, or wishlists while maintaining clean component boundaries.

3. State Management Design

Local state vs. global state decisions

For the Product Detail Page, we'll use a hybrid approach:

• Local state: Component-specific UI states like active image index, quantity selector value, and form validation errors
• Global state: Product data, user's cart items, and wishlist status that need to be shared across multiple parts of the app
• Server state: Product details, reviews, and related products that require caching and synchronization

State management approach

Primary choice: React Query + Context API

• React Query for server state management (product data, reviews, related products) due to its robust caching, automatic refetching, and built-in stale-while-revalidate capabilities
• Context API for client state (user preferences, cart items, wishlist) as it's lightweight and sufficient for this scope
• Zustand considered but rejected due to additional bundle size overhead for this feature's complexity

State shape and normalization strategy

// Normalized product state structure
interface ProductState {
  product: Product | null;
  relatedProducts: Product[];
  reviews: Review[];
  loading: boolean;
  error: string | null;
}

interface UserState {
  cartItems: CartItem[];
  wishlistItems: string[]; // product IDs
  preferences: UserPreferences;
}

interface CartItem {
  productId: string;
  quantity: number;
  variant?: ProductVariant;
}

interface Product {
  id: string;
  name: string;
  description: string;
  price: number;
  images: string[];
  variants: ProductVariant[];
  rating: number;
  reviewCount: number;
  inStock: boolean;
  category: string;
}

interface ProductVariant {
  id: string;
  name: string;
  price: number;
  stock: number;
  attributes: Record<string, string>;
}

Server state vs. client state separation

Server state (React Query):

• Product details (fetched via API)
• Reviews and ratings
• Related products

Client state (Context):

• Cart items (persisted in localStorage)
• Wishlist items (persisted in localStorage)
• User preferences (theme, language)

Cache invalidation strategy

• Product updates: Invalidate product cache when user adds to cart or modifies wishlist
• Review updates: Invalidate reviews cache when new review is submitted
• Related products: Cache TTL of 5 minutes with manual invalidation on product changes

Optimistic updates design

For cart operations, we'll implement optimistic UI:

1. Immediately update local state with new item
2. Show loading indicator during API call
3. If API fails, rollback to previous state with error toast

Critical-path hook implementation

// src/features/product-detail/hooks/useProductDetail.ts
import { useState, useEffect } from 'react';
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
import { getProductById, getRelatedProducts, addProductToCart } from '../api';
import { useUserContext } from '@/context/UserContext';

interface ProductDetailState {
  product: Product | null;
  relatedProducts: Product[];
  reviews: Review[];
  loading: boolean;
  error: string | null;
  cartQuantity: number;
  selectedVariant: ProductVariant | null;
  addToCartLoading: boolean;
}

interface UseProductDetailReturn {
  state: ProductDetailState;
  actions: {
    selectVariant: (variant: ProductVariant) => void;
    addToCart: () => Promise<void>;
    updateQuantity: (quantity: number) => void;
  };
}

const useProductDetail = (productId: string): UseProductDetailReturn => {
  const queryClient = useQueryClient();
  const { cartItems, wishlistItems } = useUserContext();
  
  const [cartQuantity, setCartQuantity] = useState(1);
  const [selectedVariant, setSelectedVariant] = useState<ProductVariant | null>(null);
  
  // Server state queries
  const { data: product, isLoading, error } = useQuery({
    queryKey: ['product', productId],
    queryFn: () => getProductById(productId),
    staleTime: 5 * 60 * 1000, // 5 minutes
  });
  
  const { data: relatedProducts } = useQuery({
    queryKey: ['related-products', productId],
    queryFn: () => getRelatedProducts(productId),
    enabled: !!product,
  });
  
  const { data: reviews } = useQuery({
    queryKey: ['reviews', productId],
    queryFn: () => getReviews(productId),
    enabled: !!product,
  });
  
  // Cart mutation
  const { mutateAsync: addToCartMutation, isLoading: addToCartLoading } = useMutation({
    mutationFn: (cartItem: CartItem) => addProductToCart(cartItem),
    onSuccess: () => {
      queryClient.invalidateQueries(['cart']);
      // Show success toast
    },
    onError: (error) => {
      // Show error toast
      console.error('Failed to add to cart:', error);
    }
  });
  
  const selectVariant = (variant: ProductVariant) => {
    setSelectedVariant(variant);
    setCartQuantity(1);
  };
  
  const updateQuantity = (quantity: number) => {
    setCartQuantity(Math.max(1, quantity));
  };
  
  const addToCart = async () => {
    if (!product) return;
    
    const cartItem: CartItem = {
      productId: product.id,
      quantity: cartQuantity,
      variant: selectedVariant || undefined
    };
    
    await addToCartMutation(cartItem);
  };
  
  return {
    state: {
      product,
      relatedProducts,
      reviews,
      loading: isLoading,
      error: error?.message || null,
      cartQuantity,
      selectedVariant,
      addToCartLoading
    },
    actions: {
      selectVariant,
      addToCart,
      updateQuantity
    }
  };
};

export default useProductDetail;

4. Routing & Navigation

Route Structure and Hierarchy

graph TD
    A[Root] --> B[Public Routes]
    A --> C[Protected Routes]
    B --> D[/login]
    B --> E[/register]
    B --> F[/products]
    B --> G[/product/:id]
    C --> H[/dashboard]
    C --> I[/profile]
    F --> G

The product detail page will be accessible at /product/:id where :id is the unique identifier for each product. This route will be protected by authentication middleware and can be accessed from public product listing pages.

Code Splitting Strategy

Route-based code splitting will be implemented using React's lazy and Suspense:

// routes/ProductRoutes.tsx
import { lazy, Suspense } from 'react';
import { Route, Routes } from 'react-router-dom';

const ProductListPage = lazy(() => import('../pages/ProductListPage'));
const ProductDetailPage = lazy(() => import('../pages/ProductDetailPage'));

export const ProductRoutes = () => (
  <Suspense fallback={<div>Loading...</div>}>
    <Routes>
      <Route path="/products" element={<ProductListPage />} />
      <Route path="/product/:id" element={<ProductDetailPage />} />
    </Routes>
  </Suspense>
);

Justification: Route-based splitting is preferred as it aligns with the natural separation of concerns and allows for better bundle size optimization. The PDP page will have a higher initial load cost due to rich media content, so lazy loading ensures users don't pay for unused components.

Navigation Guards and Authentication Flows

Authentication guard will be implemented at the route level:

// guards/AuthGuard.tsx
import { useEffect } from 'react';
import { useNavigate } from 'react-router-dom';
import { useAuthStore } from '../stores/authStore';

export const AuthGuard = ({ children }: { children: React.ReactNode }) => {
  const navigate = useNavigate();
  const { isAuthenticated, isLoading } = useAuthStore();

  useEffect(() => {
    if (!isAuthenticated && !isLoading) {
      navigate('/login', { replace: true });
    }
  }, [isAuthenticated, isLoading, navigate]);

  if (isLoading) return <div>Loading authentication...</div>;
  
  return children;
};

Deep Linking Support and URL Parameter Design

The PDP will support deep linking with the following URL structure:

• /product/12345 - Main product detail page
• /product/12345?tab=reviews - Product with reviews tab preselected
• /product/12345?variant=blue - Product with specific variant selected

URL parameters will be normalized and validated before rendering:

// hooks/useProductParams.ts
import { useParams, useSearchParams } from 'react-router-dom';

export const useProductParams = () => {
  const { id } = useParams<{ id: string }>();
  const [searchParams] = useSearchParams();
  
  const variant = searchParams.get('variant') || '';
  const tab = searchParams.get('tab') || 'overview';
  
  return {
    productId: id,
    variant,
    tab
  };
};

Browser History Management and Scroll Restoration

React Router's built-in scroll restoration will be leveraged:

// app/App.tsx
import { BrowserRouter, useScrollRestoration } from 'react-router-dom';

const App = () => {
  return (
    <BrowserRouter>
      <ScrollRestoration />
      <Routes>
        {/* App routes */}
      </Routes>
    </BrowserRouter>
  );
};

const ScrollRestoration = () => {
  useScrollRestoration();
  return null;
};

For specific navigation behavior, custom scroll handling will be implemented:

// hooks/useProductScroll.ts
import { useEffect } from 'react';
import { useLocation } from 'react-router-dom';

export const useProductScroll = () => {
  const location = useLocation();
  
  useEffect(() => {
    // Scroll to top when navigating to product detail
    window.scrollTo({ top: 0, behavior: 'smooth' });
    
    // Handle tab-specific scrolling
    const tab = new URLSearchParams(location.search).get('tab');
    if (tab) {
      const element = document.getElementById(`tab-${tab}`);
      if (element) {
        element.scrollIntoView({ behavior: 'smooth' });
      }
    }
  }, [location]);
};

This approach ensures proper scroll behavior while maintaining React Router's built-in history management capabilities.

5. API Integration Layer

API Client Design Pattern

We'll implement a centralized Axios instance with request/response interceptors for consistent API handling:

// api/client.ts
import axios, { AxiosInstance } from 'axios';

const apiClient: AxiosInstance = axios.create({
  baseURL: process.env.NEXT_PUBLIC_API_BASE_URL,
  timeout: 10000,
  headers: {
    'Content-Type': 'application/json',
  },
});

// Request interceptor for auth token injection
apiClient.interceptors.request.use(
  (config) => {
    const token = localStorage.getItem('authToken');
    if (token) {
      config.headers.Authorization = `Bearer ${token}`;
    }
    return config;
  },
  (error) => Promise.reject(error)
);

// Response interceptor for error handling and normalization
apiClient.interceptors.response.use(
  (response) => response,
  (error) => {
    if (error.response?.status === 401) {
      // Handle auth errors
      localStorage.removeItem('authToken');
      window.location.href = '/login';
    }
    return Promise.reject(error);
  }
);

export default apiClient;

Request/Response Interceptors

• Authentication: Automatically injects Bearer tokens from localStorage
• Error Normalization: Transforms API errors into consistent error objects with codes and messages
• Retry Logic: Implements exponential backoff for transient network errors (502, 503, 429)

Error Handling and Retry Strategy

// api/errorHandler.ts
export interface ApiError {
  code: string;
  message: string;
  status: number;
  retryable?: boolean;
}

export const handleApiError = (error: any): ApiError => {
  if (error.response) {
    return {
      code: error.response.data?.code || 'API_ERROR',
      message: error.response.data?.message || 'An error occurred',
      status: error.response.status,
      retryable: [429, 502, 503].includes(error.response.status),
    };
  }
  
  return {
    code: 'NETWORK_ERROR',
    message: error.message || 'Network error occurred',
    status: 0,
    retryable: true,
  };
};

// Retry utility with exponential backoff
export const retryWithBackoff = async (
  fn: () => Promise<any>,
  retries = 3,
  delay = 1000
): Promise<any> => {
  for (let i = 0; i < retries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (i === retries - 1 || !handleApiError(error).retryable) {
        throw error;
      }
      await new Promise(resolve => setTimeout(resolve, delay * Math.pow(2, i)));
    }
  }
};

Loading, Error, and Empty States Design

All PDP data fetching follows a consistent pattern:

// components/ProductDetail/useProductData.ts
export interface ProductDataState {
  product: Product | null;
  loading: boolean;
  error: ApiError | null;
  refetch: () => void;
}

export const useProductData = (productId: string): ProductDataState => {
  const [product, setProduct] = useState<Product | null>(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<ApiError | null>(null);

  useEffect(() => {
    const fetchProduct = async () => {
      try {
        setLoading(true);
        const response = await retryWithBackoff(() => 
          apiClient.get(`/products/${productId}`)
        );
        setProduct(response.data);
        setError(null);
      } catch (err) {
        const apiError = handleApiError(err);
        setError(apiError);
      } finally {
        setLoading(false);
      }
    };

    fetchProduct();
  }, [productId]);

  const refetch = useCallback(() => {
    // Implementation for manual refresh
  }, [productId]);

  return { product, loading, error, refetch };
};

Data Fetching Strategy

For PDP, we use Server-Side Rendering (SSR) to ensure:

• Fast first-contentful paint (FCP)
• SEO-friendly content rendering
• Consistent hydration between server and client

// pages/product/[id].tsx
export async function getServerSideProps({ params }: { params: { id: string } }) {
  try {
    const productResponse = await apiClient.get(`/products/${params.id}`);
    const reviewsResponse = await apiClient.get(`/products/${params.id}/reviews`);
    
    return {
      props: {
        product: productResponse.data,
        reviews: reviewsResponse.data,
        revalidate: 300, // Revalidate every 5 minutes
      },
    };
  } catch (error) {
    return {
      notFound: true,
    };
  }
}

API Response Transformation Layer

// api/transformers.ts
export interface Product {
  id: string;
  name: string;
  description: string;
  price: number;
  images: string[];
  rating: number;
  reviewsCount: number;
  inStock: boolean;
  categories: string[];
}

export const transformProductResponse = (rawProduct: any): Product => ({
  id: rawProduct.id,
  name: rawProduct.name,
  description: rawProduct.description,
  price: rawProduct.price,
  images: rawProduct.images.map((img: any) => img.url),
  rating: rawProduct.rating.average,
  reviewsCount: rawProduct.rating.count,
  inStock: rawProduct.stock > 0,
  categories: rawProduct.categories.map((cat: any) => cat.name),
});

Sequence Diagram for Primary Data Flow

sequenceDiagram
    participant U as User
    participant P as ProductDetailPage
    participant A as API Client
    participant S as Server

    U->>P: Navigate to /product/:id
    P->>A: Fetch product data
    A->>S: GET /api/products/:id
    S-->>A: Product response
    A-->>P: Transformed product data
    P->>U: Render product UI with data

Cache Invalidation Strategy

• Product data: Cached for 5 minutes with revalidation
• Reviews: Cached for 1 hour (less volatile)
• Images: CDN cached with long TTLs (30 days)
• User-specific data: Cached per session with invalidation on auth changes

Optimistic Updates for User Actions

For actions like adding to cart or rating, we implement optimistic updates:

// api/cartService.ts
export const addToCart = async (productId: string, quantity: number) => {
  // Optimistically update local state
  const localUpdate = {
    productId,
    quantity,
    timestamp: Date.now(),
  };
  
  // Update local cart store immediately
  updateLocalCart(localUpdate);
  
  try {
    const response = await apiClient.post('/cart', { productId, quantity });
    return response.data;
  } catch (error) {
    // Revert optimistic update on failure
    revertLocalCartUpdate(productId);
    throw error;
  }
};

Rate Limiting and Caching

• API rate limiting: Per-user token-based limits (100 requests/minute)
• Client-side caching: LRU cache for frequently accessed product data (100 items max)
• Stale-while-revalidate: Cache entries remain valid for 5 minutes while background refresh occurs

Data Freshness and Consistency

• Product updates: Immediate cache invalidation on product modification
• Inventory sync: Real-time WebSocket updates for stock status changes (if available)
• Review freshness: Reviews are fetched fresh on page load but cached for 1 hour

6. Performance Design

Core Web Vitals Targets

• Largest Contentful Paint (LCP): <2.5s for 95% of users
• Interaction to Next Paint (INP): <200ms for 90% of interactions
• Cumulative Layout Shift (CLS): <0.1 for 95% of users

Bundle Size Budget per Route

• Product Detail Page: <500KB (including all dependencies and assets)
• Critical JS: <150KB
• Non-critical JS (e.g., image gallery): <200KB

Critical Rendering Path Optimization

• HTML: Inline critical CSS for above-the-fold content (20KB max)
• CSS: Critical path CSS extracted and inlined; non-critical loaded async
• JS: Critical JS (product data fetch, basic UI interactions) inlined or preloaded
• Fonts: Preload key font subsets for content display (e.g., Inter-Bold for product titles)

Image Optimization Strategy

• Formats: WebP for modern browsers, JPEG fallback for older browsers
• Lazy Loading: loading="lazy" attribute on all product images
• Responsive Images: srcset with multiple sizes (320px, 480px, 768px, 1024px)
• Image Compression: Use WebP with 85% quality for product images, 70% for thumbnails

// Example image optimization component
const OptimizedProductImage = ({ src, alt, sizes }: { src: string; alt: string; sizes?: string }) => {
  return (
    <img
      src={src}
      alt={alt}
      loading="lazy"
      sizes={sizes || "(max-width: 768px) 100vw, 50vw"}
      srcSet={`
        ${src}?w=320 320w,
        ${src}?w=480 480w,
        ${src}?w=768 768w,
        ${src}?w=1024 1024w
      `}
      style={{ objectFit: "cover", width: "100%", height: "auto" }}
    />
  );
};

Font Loading Strategy

• Preload: Critical font subsets (e.g., Inter-Bold, Inter-Regular) with preload in HTML head
• Font Display: Use font-display: swap to prevent FOIT (Flash of Invisible Text)
• Font Subsets: Load only necessary character sets (Latin, Cyrillic, etc.) based on locale

Memoization Strategy

• useMemo: For expensive calculations like price formatting, product variant combinations, or image URL generation
• useCallback: For event handlers that are passed down to child components (e.g., handleAddToCart)
• React.memo: For pure presentational components like ProductImageGallery, ProductReviewCard

const ProductDetails = React.memo(({ product, onAddToCart }: { product: Product; onAddToCart: () => void }) => {
  const formattedPrice = useMemo(() => formatCurrency(product.price), [product.price]);
  
  return (
    <div>
      <h1>{product.name}</h1>
      <p>{formattedPrice}</p>
      <button onClick={onAddToCart}>Add to Cart</button>
    </div>
  );
});

Virtualization for Large Lists

• Product Reviews: Use react-window or react-virtual to render only visible reviews
• Related Products: Virtualize if list exceeds 20 items

Prefetching and Preloading Strategy

• Preload: Product images (first 3 thumbnails) with rel="preload" in HTML head
• Prefetch: Related product data (e.g., "Customers also bought") when user hovers over related section
• Preconnect: DNS pre-resolution for image CDN domains (cdn.example.com)

// Example prefetch implementation in useEffect
useEffect(() => {
  const preloadImages = () => {
    const imageUrls = product.images.slice(0, 3).map(img => img.url);
    imageUrls.forEach(url => {
      const link = document.createElement('link');
      link.rel = 'prefetch';
      link.href = url;
      document.head.appendChild(link);
    });
  };

  preloadImages();
}, [product.images]);

Performance Monitoring

• Lighthouse: Run automated audits on all product pages to ensure Core Web Vitals targets are met
• Custom Metrics: Track time to first meaningful paint (TFMP) and interaction readiness
• Bundle Analysis: Use Webpack Bundle Analyzer or Rollup's bundle visualizer to ensure bundle size stays within limits

Caching Strategy

• HTTP Cache Headers: Set appropriate cache policies (e.g., Cache-Control: max-age=3600) for static assets
• Service Workers: Implement caching strategy for product images and metadata to improve offline experience
• CDN: Use CDN to serve static assets with global edge locations for faster delivery

Render Optimization

• Server-Side Rendering (SSR): Use Next.js or similar framework to render initial HTML on server
• Client-Side Hydration: Ensure hydration completes within 100ms to avoid layout shifts
• Code Splitting: Split product detail page into chunks (e.g., ProductGallery, ProductReviews) to reduce initial load time

Memory Usage Considerations

• Memory Leaks: Ensure all event listeners and timers are cleaned up in useEffect cleanup functions
• Large State Objects: Avoid storing large objects (e.g., full product JSON) in React state; use references or IDs instead
• Image Memory: Implement image lazy loading to prevent excessive memory usage from preloaded images

7. Error Handling & Resilience

Error Boundary Placement Strategy

Error boundaries should be strategically placed to prevent cascading failures and provide graceful degradation. The primary placement strategy is:

1. Product Detail Page Level Boundary: Catch all errors within the PDP context (image loading, product data fetch)
2. Image Loading Boundaries: Individual image components should have their own error boundaries to prevent one broken image from affecting the entire product display
3. Review Section Boundary: Isolate review loading and rendering errors from the main product content

graph TD
    A[ProductDetailPage] --> B[ErrorBoundary]
    B --> C[ProductHeader]
    B --> D[ProductImages]
    B --> E[ProductDetails]
    B --> F[ReviewsSection]
    D --> G[ImageErrorBoundary]
    F --> H[ReviewErrorBoundary]

Global Error Handler Design

The global error handler will capture unhandled errors and provide appropriate user feedback:

// ErrorHandlerContext.tsx
import React, { createContext, useContext, useState, useEffect } from 'react';

interface ErrorContextType {
  error: Error | null;
  setError: (error: Error | null) => void;
  clearError: () => void;
}

const ErrorContext = createContext<ErrorContextType | undefined>(undefined);

export const ErrorProvider: React.FC<{ children: React.ReactNode }> = ({ children }) => {
  const [error, setError] = useState<Error | null>(null);

  useEffect(() => {
    const handleError = (event: ErrorEvent) => {
      setError(event.error);
    };

    const handleUnhandledRejection = (event: PromiseRejectionEvent) => {
      setError(event.reason);
    };

    window.addEventListener('error', handleError);
    window.addEventListener('unhandledrejection', handleUnhandledRejection);

    return () => {
      window.removeEventListener('error', handleError);
      window.removeEventListener('unhandledrejection', handleUnhandledRejection);
    };
  }, []);

  const clearError = () => {
    setError(null);
  };

  return (
    <ErrorContext.Provider value={{ error, setError, clearError }}>
      {children}
    </ErrorContext.Provider>
  );
};

export const useError = () => {
  const context = useContext(ErrorContext);
  if (!context) {
    throw new Error('useError must be used within an ErrorProvider');
  }
  return context;
};

Offline / Network Failure Handling

The PDP should gracefully handle offline scenarios with a progressive enhancement approach:

// OfflineHandler.tsx
import React, { useState, useEffect } from 'react';
import { useNetworkStatus } from '../hooks/useNetworkStatus';

interface OfflineHandlerProps {
  children: React.ReactNode;
  fallbackComponent?: React.ReactNode;
}

export const OfflineHandler: React.FC<OfflineHandlerProps> = ({ 
  children, 
  fallbackComponent 
}) => {
  const [isOnline, setIsOnline] = useState<boolean>(true);
  const { isOnline: networkStatus } = useNetworkStatus();

  useEffect(() => {
    setIsOnline(networkStatus);
  }, [networkStatus]);

  if (!isOnline && fallbackComponent) {
    return <>{fallbackComponent}</>;
  }

  return <>{children}</>;
};

// Fallback UI for offline state
export const OfflineFallback: React.FC = () => (
  <div className="offline-fallback">
    <h2>Offline Mode</h2>
    <p>You're currently offline. Some content may not be available.</p>
    <button onClick={() => window.location.reload()}>
      Try Again
    </button>
  </div>
);

Graceful Degradation Patterns

The PDP implements progressive enhancement:

1. Core Product Data: Essential information (name, price) renders even without images
2. Images: Fallback to placeholder when image loading fails
3. Reviews: Load reviews progressively, show skeleton while fetching
4. Dynamic Content: Feature detection for JavaScript-dependent elements

// ProductImage.tsx
import React, { useState } from 'react';

interface ProductImageProps {
  src: string;
  alt: string;
}

export const ProductImage: React.FC<ProductImageProps> = ({ src, alt }) => {
  const [isLoading, setIsLoading] = useState(true);
  const [hasError, setHasError] = useState(false);

  const handleLoad = () => {
    setIsLoading(false);
  };

  const handleError = () => {
    setHasError(true);
    setIsLoading(false);
  };

  return (
    <div className="product-image-container">
      {isLoading && !hasError && (
        <div className="skeleton-loader" />
      )}
      
      {hasError ? (
        <img 
          src="/images/placeholder.png" 
          alt={alt}
          className="fallback-image"
        />
      ) : (
        <img 
          src={src} 
          alt={alt}
          onLoad={handleLoad}
          onError={handleError}
          className={isLoading ? "loading" : "loaded"}
        />
      )}
    </div>
  );
};

User Feedback on Errors

Multiple error feedback mechanisms:

// ToastErrorDisplay.tsx
import React, { useEffect } from 'react';
import { useError } from '../contexts/ErrorContext';

interface ToastErrorDisplayProps {
  autoClose?: boolean;
}

export const ToastErrorDisplay: React.FC<ToastErrorDisplayProps> = ({ 
  autoClose = true 
}) => {
  const { error, clearError } = useError();
  const [isVisible, setIsVisible] = useState(false);

  useEffect(() => {
    if (error) {
      setIsVisible(true);
      if (autoClose) {
        setTimeout(() => {
          setIsVisible(false);
          clearError();
        }, 5000);
      }
    }
  }, [error, autoClose, clearError]);

  if (!isVisible || !error) return null;

  return (
    <div className="toast-error" role="alert">
      <span className="error-icon">⚠️</span>
      <span className="error-message">{error.message}</span>
      <button 
        onClick={() => {
          setIsVisible(false);
          clearError();
        }}
        className="close-button"
        aria-label="Close error"
      >
        ×
      </button>
    </div>
  );
};

Error Recovery Strategy

// RetryHandler.tsx
import React, { useState } from 'react';

interface RetryHandlerProps {
  onRetry: () => void;
  children: React.ReactNode;
}

export const RetryHandler: React.FC<RetryHandlerProps> = ({ 
  onRetry, 
  children 
}) => {
  const [retryCount, setRetryCount] = useState(0);
  const maxRetries = 3;

  const handleRetry = () => {
    if (retryCount < maxRetries) {
      setRetryCount(prev => prev + 1);
      onRetry();
    }
  };

  return (
    <div>
      {children}
      {retryCount < maxRetries && (
        <button onClick={handleRetry} className="retry-button">
          Retry ({maxRetries - retryCount} attempts left)
        </button>
      )}
    </div>
  );
};

8. Testing Strategy

Unit Testing Approach

• Component-level testing: 90%+ coverage for all presentational components using React Testing Library
• Hook-level testing: Full coverage of custom hooks including state transitions and side effects
• Utility function testing: 100% coverage for all data transformation, formatting, and validation utilities
• Test data strategy: Use fixtures with realistic but minimal product data to avoid brittle tests

Integration Testing Strategy

• Feature integration: Test complete user flows like adding to cart, wishlist, and product review submission
• API interaction: Validate proper data fetching and state updates when backend responses change
• State management: Ensure proper propagation of global state changes across components
• Form interactions: Test multi-step forms like size/color selection and quantity adjustment

E2E Testing Scope

• Primary flows: Product browsing, adding to cart, checkout initiation, and wishlist management
• Cross-browser testing: Chrome, Firefox, Safari (focus on mobile viewports)
• Device emulation: Test on iPhone, iPad, and desktop breakpoints
• Tool selection: Playwright for E2E due to better performance and parallelization capabilities

Visual Regression Testing

• Screenshot strategy: Capture key product detail states (default, selected variant, cart added)
• Cross-platform coverage: Test on multiple screen sizes and operating systems
• Baseline management: Automated baseline updates with proper change detection

Accessibility Testing Automation

• Axe-core integration: Run accessibility checks on all major component states
• Keyboard navigation: Test full keyboard-only interaction flows
• Screen reader compatibility: Validate ARIA labels and semantic structure with NVDA/JAWS

Test Data Strategy

• Fixtures: Maintain minimal, stable test data sets with realistic product attributes
• Mocking strategy: Use MSW (Mock Service Worker) for API mocking with realistic response shapes
• Database isolation: Each test runs in isolated environment to prevent cross-contamination

9. Accessibility (A11y)

WCAG 2.1 AA Compliance Checklist

The Product Detail Page must meet WCAG 2.1 AA standards with the following key focus areas:

• Perceivable: All content must be presented in ways that users can perceive (text alternatives, sufficient color contrast, adaptable content)
• Operable: Interface components and navigation must be operable (keyboard accessible, enough time, no content that causes seizures)
• Understandable: Information and user interface must be understandable (clear language, consistent navigation, predictable behavior)
• Robust: Content must be robust enough to be interpreted reliably by assistive technologies

Keyboard Navigation Support

All interactive elements must be fully keyboard accessible:

• Tab order follows logical reading flow (product image → title → description → pricing → add to cart)
• Focus indicators clearly visible (min 3:1 contrast ratio, 3px minimum outline)
• Keyboard trap management for modals and dropdowns
• Skip-to-content link at the beginning of page structure

Focus Management Strategy

Focus Trapping: When modals open (e.g., image gallery lightbox), focus is trapped within the modal until closed.

Focus Restoration: When closing modals or dropdowns, focus returns to the element that originally triggered the interaction.

// Example focus management hook
const useFocusTrap = (isOpen: boolean, modalRef: React.RefObject<HTMLElement>) => {
  useEffect(() => {
    if (!isOpen) return;

    const handleFocusTrap = (e: KeyboardEvent) => {
      if (e.key === 'Tab') {
        const focusableElements = modalRef.current?.querySelectorAll(
          'button, input, select, textarea, [tabindex]:not([tabindex="-1"])'
        ) || [];
        
        const firstElement = focusableElements[0] as HTMLElement;
        const lastElement = focusableElements[focusableElements.length - 1] as HTMLElement;

        if (e.shiftKey && document.activeElement === firstElement) {
          lastElement.focus();
          e.preventDefault();
        } else if (!e.shiftKey && document.activeElement === lastElement) {
          firstElement.focus();
          e.preventDefault();
        }
      }
    };

    document.addEventListener('keydown', handleFocusTrap);
    return () => document.removeEventListener('keydown', handleFocusTrap);
  }, [isOpen]);
};

ARIA Roles and Attributes Plan

Product Image Gallery:

<div role="region" aria-labelledby="gallery-heading">
  <h2 id="gallery-heading">Product Image Gallery</h2>
  <div role="tablist" aria-orientation="horizontal">
    {thumbnails.map((thumb, index) => (
      <button 
        role="tab" 
        aria-controls={`image-${index}`}
        aria-selected={activeIndex === index}
        key={thumb.id}
      >
        {thumb.alt}
      </button>
    ))}
  </div>
</div>

Product Details Section:

<section role="article" aria-label="Product details">
  <h1 id="product-title" tabindex="-1">{product.title}</h1>
  <p aria-describedby="product-description">
    {product.description}
  </p>
  <div role="status" aria-live="polite">
    {product.availabilityStatus}
  </div>
</section>

Add to Cart Button:

<button 
  type="button"
  aria-describedby="cart-button-desc"
  aria-label={`Add ${product.title} to cart`}
>
  Add to Cart
</button>
<span id="cart-button-desc" class="sr-only">
  Adds the product to your shopping cart
</span>

Screen Reader Compatibility

Live Regions:

• Stock availability updates use aria-live="polite" for screen readers
• Add to cart confirmation uses aria-live="assertive"

Screen Reader Only Text:

const ScreenReaderOnly = ({ children }: { children: React.ReactNode }) => (
  <span className="sr-only">{children}</span>
);

Enhanced Product Descriptions:

const ProductDescription = ({ description, features }: { 
  description: string; 
  features: string[] 
}) => (
  <div>
    <p>{description}</p>
    <ul>
      {features.map((feature, i) => (
        <li key={i}>
          <span className="sr-only">Feature {i + 1}: </span>
          {feature}
        </li>
      ))}
    </ul>
  </div>
);

Keyboard Navigation Flow

1. Header: Skip to content link (Tab 1)
2. Main Content:
   • Product image gallery navigation (Tab 2-5)
   • Product title (Tab 6)
   • Description (Tab 7)
   • Pricing section (Tab 8)
   • Add to cart button (Tab 9)
3. Footer: Navigation links (Tab 10+)

Focus Trapping for Interactive Elements

Color Picker Dropdown:

const ColorPicker = ({ 
  colors, 
  selectedColor, 
  onChange 
}: {
  colors: string[];
  selectedColor: string;
  onChange: (color: string) => void;
}) => {
  const [isOpen, setIsOpen] = useState(false);
  const colorPickerRef = useRef<HTMLDivElement>(null);

  useFocusTrap(isOpen, colorPickerRef);

  return (
    <div ref={colorPickerRef} role="combobox" aria-expanded={isOpen}>
      <button 
        onClick={() => setIsOpen(!isOpen)}
        aria-haspopup="listbox"
        aria-controls="color-list"
      >
        {selectedColor}
      </button>
      
      {isOpen && (
        <div role="listbox" id="color-list">
          {colors.map(color => (
            <button 
              key={color}
              role="option"
              onClick={() => {
                onChange(color);
                setIsOpen(false);
              }}
            >
              {color}
            </button>
          ))}
        </div>
      )}
    </div>
  );
};

Dynamic Content Updates

Stock Status Updates:

const StockStatus = ({ inStock }: { inStock: boolean }) => {
  const statusText = inStock ? "In Stock" : "Out of Stock";
  
  return (
    <div 
      role="status" 
      aria-live="polite"
      className={inStock ? "stock-in" : "stock-out"}
    >
      <span className="sr-only">Product is </span>
      {statusText}
    </div>
  );
};

Enhanced Contrast and Readability

Color Contrast Requirements:

• Text contrast ratio: 4.5:1 minimum (3:1 for large text)
• Interactive elements: 3:1 contrast ratio
• Focus indicators: 3:1 contrast with background

Text Size and Readability:

/* Ensure readable font sizes */
.product-title {
  font-size: clamp(1.5rem, 4vw, 2.5rem);
  line-height: 1.3;
}

.product-description {
  font-size: clamp(0.875rem, 2vw, 1.125rem);
  line-height: 1.6;
}

Keyboard Accessible Form Elements

Quantity Selector:

const QuantitySelector = ({ 
  value, 
  onChange 
}: { 
  value: number; 
  onChange: (value: number) => void 
}) => {
  return (
    <div role="group" aria-label="Product quantity">
      <button 
        onClick={() => onChange(Math.max(1, value - 1))}
        aria-label="Decrease quantity"
        disabled={value <= 1}
      >
        -
      </button>
      
      <input
        type="number"
        value={value}
        onChange={(e) => onChange(parseInt(e.target.value) || 1)}
        min="1"
        aria-label="Product quantity"
      />
      
      <button 
        onClick={() => onChange(value + 1)}
        aria-label="Increase quantity"
      >
        +
      </button>
    </div>
  );
};

ARIA Labeling Strategy

Complex Components:

• Use aria-label for icon-only buttons
• Use aria-describedby for complex descriptions
• Use aria-labelledby for grouping related elements
• Use aria-expanded for expandable sections

Enhanced User Experience:

const ProductCard = ({ 
  product, 
  onAddToCart 
}: { 
  product: Product; 
  onAddToCart: () => void 
}) => {
  return (
    <article 
      role="article" 
      aria-label={`Product: ${product.title}`}
      className="product-card"
    >
      <img 
        src={product.image} 
        alt={product.title}
        aria-describedby="product-image-desc"
      />
      
      <div id="product-image-desc" className="sr-only">
        Product image showing {product.title}
      </div>
      
      <h2 tabIndex="-1">{product.title}</h2>
      
      <p aria-describedby="product-price">
        {formatCurrency(product.price)}
      </p>
      
      <button 
        onClick={onAddToCart}
        aria-describedby="add-to-cart-desc"
      >
        Add to Cart
      </button>
      
      <span id="add-to-cart-desc" className="sr-only">
        Adds this product to your shopping cart
      </span>
    </article>
  );
};

10. Security Considerations

XSS Prevention Strategy

The Product Detail Page must prevent Cross-Site Scripting attacks through comprehensive input sanitization and output encoding:

// Sanitization utility for user-generated content
import DOMPurify from 'dompurify';

export const sanitizeHtml = (html: string): string => {
  return DOMPurify.sanitize(html, {
    ALLOWED_TAGS: ['p', 'br', 'strong', 'em', 'ul', 'ol', 'li'],
    ALLOWED_ATTR: ['class'],
    ALLOW_DATA_ATTR: false,
  });
};

// For product descriptions and reviews
const ProductDescription = ({ description }: { description: string }) => {
  const sanitizedDesc = sanitizeHtml(description);
  return <div dangerouslySetInnerHTML={{ __html: sanitizedDesc }} />;
};

CSRF Protection

Implement CSRF token validation for all mutating operations:

// API client with CSRF token handling
const apiClient = axios.create({
  baseURL: '/api',
  withCredentials: true,
});

apiClient.interceptors.request.use((config) => {
  const csrfToken = document.querySelector('meta[name="csrf-token"]')?.getAttribute('content');
  if (csrfToken) {
    config.headers['X-CSRF-Token'] = csrfToken;
  }
  return config;
});

Content Security Policy (CSP) Headers

Configure CSP headers to restrict script execution and external resource loading:

Content-Security-Policy: 
  default-src 'self'; 
  script-src 'self' 'unsafe-inline' https://cdn.example.com; 
  style-src 'self' 'unsafe-inline'; 
  img-src 'self' data: https:; 
  font-src 'self' https:;

Sensitive Data Handling in Frontend State

Protect sensitive product information from exposure:

// Secure state management for PDP data
interface ProductState {
  // Only expose necessary product fields
  id: string;
  name: string;
  price: number;
  description: string;
  images: string[];
  // Never store sensitive fields like inventory counts in client state
}

// Secure data access pattern
const useProductState = () => {
  const [product, setProduct] = useState<ProductState | null>(null);
  
  // Never expose sensitive fields like stock levels or supplier info
  const getPublicProduct = (rawProduct: RawProduct): ProductState => ({
    id: rawProduct.id,
    name: rawProduct.name,
    price: rawProduct.price,
    description: rawProduct.description,
    images: rawProduct.images.map(img => img.url),
  });
};

Input Sanitization Approach

Validate and sanitize all user inputs before processing:

// Input validation for product reviews
const validateReviewInput = (review: ReviewForm): ReviewValidationResult => {
  const errors: string[] = [];
  
  if (review.title.length > 100) {
    errors.push('Title too long');
  }
  
  if (review.rating < 1 || review.rating > 5) {
    errors.push('Invalid rating');
  }
  
  // Sanitize content to prevent script injection
  const sanitizedContent = DOMPurify.sanitize(review.content);
  
  return {
    isValid: errors.length === 0,
    errors,
    sanitizedContent
  };
};

Security Headers Implementation

Enforce security headers through server configuration:

// Server-side header configuration (express example)
app.use((req, res, next) => {
  res.setHeader('X-Content-Type-Options', 'nosniff');
  res.setHeader('X-Frame-Options', 'DENY');
  res.setHeader('X-XSS-Protection', '1; mode=block');
  res.setHeader('Strict-Transport-Security', 'max-age=31536000; includeSubDomains');
  next();
});

Authentication & Authorization

Ensure proper access controls for sensitive product operations:

// Protected route guard with authorization checks
const ProductEditGuard = () => {
  const { user } = useAuth();
  const { product } = useProductContext();
  
  // Verify user has edit permissions for this product
  const canEdit = user?.permissions?.includes('edit_product') && 
                  product?.ownerId === user?.id;
  
  if (!canEdit) {
    return <Navigate to="/unauthorized" replace />;
  }
  
  return <ProductEditPage />;
};

Data Exposure Prevention

Implement proper data filtering to prevent sensitive information leakage:

// API response filtering to prevent sensitive field exposure
const filterProductResponse = (rawProduct: RawProduct): PublicProduct => {
  // Only expose fields that are safe for public consumption
  return {
    id: rawProduct.id,
    name: rawProduct.name,
    price: rawProduct.price,
    description: rawProduct.description,
    images: rawProduct.images.map(img => img.url),
    category: rawProduct.category,
    rating: rawProduct.rating,
    // Never include: inventory, supplier info, pricing history, etc.
  };
};

Secure Image Handling

Validate and sanitize image URLs to prevent malicious content:

// Image URL validation
const validateImageUrl = (url: string): boolean => {
  try {
    const parsedUrl = new URL(url);
    return parsedUrl.origin === 'https://cdn.example.com' || 
           parsedUrl.origin === window.location.origin;
  } catch (e) {
    return false;
  }
};

// Secure image component
const ProductImage = ({ src, alt }: { src: string; alt: string }) => {
  const isValidUrl = validateImageUrl(src);
  
  if (!isValidUrl) {
    return <img src="/fallback-image.png" alt={alt} />;
  }
  
  return <img src={src} alt={alt} loading="lazy" />;
};

Secure Session Management

Implement proper session handling to prevent session hijacking:

// Session validation middleware
const validateSession = async (req, res, next) => {
  const sessionToken = req.headers['x-session-token'];
  
  if (!sessionToken) {
    return res.status(401).json({ error: 'Unauthorized' });
  }
  
  try {
    const session = await validateSessionToken(sessionToken);
    
    if (session.isExpired || !session.isActive) {
      return res.status(401).json({ error: 'Session expired' });
    }
    
    req.session = session;
    next();
  } catch (error) {
    return res.status(401).json({ error: 'Invalid session' });
  }
};

Security Testing Considerations

Implement security scanning and testing:

1. Regular XSS vulnerability scans on user-generated content
2. Input validation testing for all form fields
3. Session management testing (session timeout, token regeneration)
4. Content Security Policy validation checks
5. Authentication bypass attempts testing

The security design prioritizes defense in depth, ensuring that even if one layer is compromised, other protections remain effective. All user inputs are sanitized, sensitive data is filtered from client state, and proper authentication/authorization controls are enforced.

11. Internationalization (i18n)

Translation Key Structure and Naming Convention

• Use hierarchical keys with dot notation: product.detail.title, product.detail.description
• Follow BEM-style naming for components: product.gallery.thumbnail, product.reviews.rating
• Group keys by feature: product, cart, auth, common
• Prefix keys with feature namespace to avoid collisions: product.detail.price

RTL Support Considerations

• Implement CSS classes for right-to-left layout: .rtl .product-container { direction: rtl; }
• Use CSS logical properties for padding/margin: padding-inline-start instead of padding-left
• Handle text alignment with text-align: start and text-align: end
• Ensure image assets support RTL (e.g., arrows pointing left/right)
• Apply RTL-specific styling for component layouts (e.g., product gallery thumbnails order)

Date, Number, Currency Formatting Strategy

• Use Intl.DateTimeFormat for localized dates (e.g., new Intl.DateTimeFormat('fr-FR', { dateStyle: 'long' }).format(date))
• Format currency with Intl.NumberFormat using locale-specific options (e.g., new Intl.NumberFormat('de-DE', { style: 'currency', currency: 'EUR' }).format(price))
• Handle number grouping and decimal separators automatically per locale
• Support multiple currency display options (e.g., USD, EUR, JPY) with proper symbol placement

Locale Detection and Switching Strategy

• Auto-detect browser language via navigator.language or navigator.languages
• Allow manual locale switching through UI dropdown with persistent storage (localStorage)
• Store preferred locale in localStorage or cookie for persistence across sessions
• Implement fallback to default locale (e.g., en-US) when translation files missing
• Update all components dynamically when locale changes using React Context or i18next

// Example i18n context setup
interface I18nContextType {
  locale: string;
  setLocale: (locale: string) => void;
  t: (key: string, params?: Record<string, any>) => string;
  formatCurrency: (amount: number, currency: string) => string;
  formatDate: (date: Date, options?: Intl.DateTimeFormatOptions) => string;
}

const I18nContext = React.createContext<I18nContextType>({
  locale: 'en-US',
  setLocale: () => {},
  t: () => '',
  formatCurrency: () => '',
  formatDate: () => ''
});

Translation File Organization

• Create separate JSON files per locale: locales/en-US.json, locales/fr-FR.json
• Structure translation keys with nested hierarchy for maintainability:

{
  "product": {
    "detail": {
      "title": "Product Title",
      "price": "Price: {{price}}",
      "description": "Product description here"
    }
  }
}

Dynamic Translation Loading

• Implement lazy loading of translation files using dynamic imports to reduce initial bundle size
• Use i18next with i18next-http-middleware or similar for server-side translation loading
• Support fallback language loading when primary locale files are not yet available

Accessibility and i18n Integration

• Ensure all translated content maintains semantic meaning for screen readers
• Use lang attribute on root elements when switching languages (e.g., <html lang="fr-FR">)
• Apply proper ARIA labels for translated content that might change layout or meaning
• Test translated text with screen readers to ensure proper pronunciation and context

Testing i18n Implementation

• Write unit tests for translation key existence across all supported locales
• Validate that all translated content fits within UI constraints (e.g., button text length)
• Test RTL layout rendering with translated content
• Implement integration tests that verify translation loading and switching behavior

12. Monitoring & Observability

Real User Monitoring (RUM) Metrics to Track

The Product Detail Page should capture key RUM metrics to understand user behavior and performance:

• Largest Contentful Paint (LCP): Target <2.5s for main product image/content loading
• First Input Delay (FID): Target <100ms for interactive elements like Add to Cart
• Cumulative Layout Shift (CLS): Target <0.1 for stable layout during image loading
• First Contentful Paint (FCP): Target <1.5s for initial content display
• Time to Interactive (TTI): Target <3s for full page interactivity

Error Tracking Integration

Integrate Sentry or Datadog for comprehensive error monitoring:

// Error tracking integration example
import * as Sentry from '@sentry/react';

Sentry.init({
  dsn: process.env.REACT_APP_SENTRY_DSN,
  integrations: [new Sentry.Integrations.BrowserTracing()],
  tracesSampleRate: 1.0,
  environment: process.env.REACT_APP_ENVIRONMENT,
});

// Error boundary for PDP
class ProductErrorBoundary extends React.Component {
  state = { hasError: false };

  static getDerivedStateFromError(error) {
    return { hasError: true };
  }

  componentDidCatch(error, errorInfo) {
    Sentry.captureException(error, { contexts: { errorInfo } });
  }

  render() {
    if (this.state.hasFlag) {
      return <ErrorFallback />;
    }
    return this.props.children;
  }
}

Custom Events and User Journey Tracking

Track key user interactions:

• product_viewed: When product details are loaded
• product_image_loaded: For each image in carousel
• add_to_cart_clicked: When user clicks Add to Cart
• product_added_to_cart: When item successfully added to cart
• product_review_submitted: For review submission flow

Performance Monitoring and Regression Detection

Implement performance baselines:

// Performance monitoring hook
const usePerformanceMonitoring = () => {
  const [metrics, setMetrics] = useState<PerformanceMetrics>({});

  useEffect(() => {
    if ('performance' in window) {
      const observer = new PerformanceObserver((list) => {
        list.getEntries().forEach((entry) => {
          if (entry.entryType === 'navigation') {
            setMetrics({
              lcp: entry.loadEventEnd - entry.loadEventStart,
              fcp: entry.loadEventEnd - entry.loadEventStart,
              fid: entry.loadEventEnd - entry.loadEventStart,
            });
          }
        });
      });

      observer.observe({ entryTypes: ['navigation'] });
    }
  }, []);

  return metrics;
};

interface PerformanceMetrics {
  lcp?: number;
  fcp?: number;
  fid?: number;
}

Browser Performance Monitoring

Monitor browser-specific performance:

• Page load time distribution (95th percentile)
• Resource loading times (image, script, CSS)
• Memory usage patterns during product image rendering
• Network request timing for API calls

User Journey Tracking

Track end-to-end user flows:

1. Product Discovery → PDP View: Track conversion rate from search/category to detail page
2. Add to Cart Flow: Monitor drop-off points in cart process
3. Review Submission: Track completion rate of review forms

Alerting Strategy

Configure alerts for:

• High Error Rates: >5% error rate on PDP page load
• Performance Degradation: >20% increase in LCP or FCP
• Cart Abandonment: >30% drop-off in Add to Cart flow
• API Response Time: >5s for product data fetch

Data Collection and Privacy Compliance

Ensure all monitoring respects privacy:

• Anonymize user identifiers in performance data
• Comply with GDPR/CCPA for tracking consent
• Implement opt-out mechanisms for analytics
• Log only necessary performance data without PII

Dashboard and Reporting

Create dashboards for:

• Real-time product page performance metrics
• User behavior heatmaps (click tracking)
• Conversion funnel analysis
• Error rate trends over time
• Geographic performance distribution

Integration with Existing Monitoring Stack

Connect to existing observability tools:

• Prometheus/Grafana for metrics visualization
• ELK stack for log aggregation and analysis
• New Relic or similar APM tools for full-stack monitoring
• Slack alerts for critical performance regressions

Version Tracking and Rollback Monitoring

Monitor feature version impact:

• Track which PDP version affects performance
• Implement canary deployment monitoring for new features
• Log feature flag usage and impact on performance

Data Retention and Compliance

Define data retention policies:

• Performance metrics: 90 days
• Error logs: 30 days
• User journey data: 6 months (for analysis)
• Compliance with internal data governance policies

Test Coverage for Monitoring

Ensure monitoring is tested:

• Unit tests for performance measurement hooks
• Integration tests for error boundary behavior
• E2E tests that verify metrics collection
• Load testing to validate monitoring under stress conditions

13. File & Folder Structure

Proposed Directory Structure

/src
├── features/
│   └── product-detail/
│       ├── components/
│       │   ├── ProductDetailPage.tsx
│       │   ├── ProductImages.tsx
│       │   ├── ProductInfo.tsx
│       │   ├── ProductReviews.tsx
│       │   └── AddToCartButton.tsx
│       ├── hooks/
│       │   └── useProductDetail.ts
│       ├── types/
│       │   └── product.types.ts
│       ├── utils/
│       │   └── product.utils.ts
│       └── index.ts
├── shared/
│   ├── components/
│   │   ├── Button.tsx
│   │   ├── Image.tsx
│   │   └── Rating.tsx
│   ├── hooks/
│   │   └── useBreakpoints.ts
│   └── utils/
│       └── formatCurrency.ts
├── routes/
│   └── ProductDetailRoute.tsx
└── store/
    └── product-detail.slice.ts

Module Boundaries and Import Rules

• Feature isolation: Product detail feature is self-contained with no cross-feature imports
• Shared components: Only use shared components for generic UI elements (Button, Image, Rating)
• Barrel exports: Each feature has an index.ts for clean imports from parent directories
• Type safety: All feature-specific types live in their own types/ directory

Shared vs Feature-Specific Code Separation

Shared code (reusable across features):

• Generic UI components (Button, Image, Rating)
• Utility functions (formatCurrency, breakpoints)
• Common hooks (useBreakpoints)

Feature-specific code:

• Product detail page components and logic
• Product-specific types and utilities
• Feature-level state management

This structure follows a feature-based organization that scales well for large teams while maintaining clear module boundaries and reducing coupling between features.

14. Dependencies & Third-Party Libraries

Key Libraries Selected with Justification

React (18.2+) - Core framework for building the UI, providing component-based architecture and concurrent rendering capabilities essential for modern React applications.

TypeScript (5.0+) - Static type checking to catch runtime errors early, improve developer experience with better IDE support, and enable scalable codebase maintenance.

React Router DOM (6.15+) - Industry-standard routing solution with declarative API, nested route support, and seamless integration with React's component model for navigation.

React Query (5.0+) - Advanced data fetching and state management with built-in caching, background updates, and automatic refetching capabilities that outperform traditional approaches.

Zustand (4.3+) - Lightweight state management solution that provides a more intuitive API than Redux, with minimal boilerplate and excellent TypeScript support.

Tailwind CSS (3.3+) - Utility-first CSS framework enabling rapid UI development with consistent design system and easy theme customization.

Framer Motion (10.16+) - Production-ready animation library that provides performant, declarative animations with minimal configuration overhead.

React Hook Form (7.48+) - High-performance form validation with optimal re-renders and comprehensive validation capabilities for complex forms.

date-fns (2.30+) - Modern, immutable date utility library with modular design and excellent TypeScript support for international date handling.

lodash-es (4.17+) - Utility library providing essential functional programming helpers with tree-shaking support to reduce bundle size.

Alternatives Considered and Rejected

Redux Toolkit - While powerful, introduces unnecessary complexity for this feature's state needs. Zustand provides similar capabilities with less boilerplate and better TypeScript integration.

Jotai - Offers fine-grained state management but introduces complexity that isn't justified by the feature's requirements. Zustand provides better developer experience for this use case.

Next.js - Not selected as the primary framework despite its SSR capabilities, since this is a component-based design focused on reusability rather than page-level optimization.

Emotion - Tailwind CSS was chosen for its utility-first approach that aligns better with design system requirements and faster development cycles.

Styled Components - Tailwind CSS provides better performance characteristics and more consistent design system implementation for this feature.

Licensing and Bundle Size Impact Assessment

MIT Licensed Libraries: All selected libraries are MIT licensed, providing flexibility for commercial use with minimal legal considerations.

Bundle Size Impact:

• React + React DOM: ~150KB (minified)
• React Query: ~20KB (minified)
• Zustand: ~3KB (minified)
• Tailwind CSS: ~10KB (minified with purge)
• Framer Motion: ~25KB (minified)
• date-fns: ~15KB (minified with tree-shaking)

Total estimated bundle size impact for core dependencies: ~225KB (minified + gzipped) with proper tree-shaking and optimization.

Tree-shaking Strategy: All libraries support tree-shaking to eliminate unused code. React Query and date-fns are configured with selective imports to minimize bundle size.

Build-time Optimizations:

• Tailwind CSS is configured with purge to remove unused styles
• React Query uses selective imports for query client configuration
• date-fns is imported with specific modules to avoid full library inclusion

Production Bundle Analysis:

• Core dependencies represent ~25% of total bundle size
• Critical path rendering is optimized to load only necessary components and their dependencies
• Lazy loading of non-critical features (like image galleries) is implemented to reduce initial load time

15. Open Questions, Risks & Trade-offs

Decisions that need product/engineering alignment

• Product variant vs. SKU complexity: Should we support multiple variants (size, color) with dynamic pricing, or simplify to single SKU? This directly impacts state management complexity and API surface.
• Image gallery behavior: How many images should be preloaded? Should we support 360-degree views or video embeds? These decisions affect bundle size and performance budget.
• Add-to-cart flow: Should we implement optimistic updates for cart actions, or wait for server confirmation? This affects UX consistency vs. data integrity.

Known trade-offs made in this design

• Performance vs. feature richness: Prioritized core PDP functionality over advanced features like real-time inventory updates or personalized recommendations to meet performance targets.
• State management complexity vs. scalability: Chose React Context API over Redux Toolkit for simpler initial implementation, with potential migration path to Zustand or Jotai if complexity grows.
• Component reusability vs. specificity: Created highly specific components for product detail view rather than generic, reusable components to ensure optimal UX and performance.

Risks and mitigations

• Bundle size bloat: Risk of exceeding 500KB bundle size budget due to image loading and rich media support. Mitigation: Route-based code splitting and lazy loading of non-critical components.
• API latency impact: Risk that third-party product data API will cause slow page loads. Mitigation: Implement server-side rendering with fallbacks and client-side loading states.
• Image optimization failure: Risk that responsive image implementation won't properly handle all device sizes. Mitigation: Comprehensive testing across device breakpoints and fallback to default image sizes.

Technical debt acknowledged

• Hardcoded product type handling: Current implementation assumes all products follow same structure, but future variants may require more flexible data models.
• Limited A/B testing support: No built-in framework for A/B testing different PDP layouts or content variations, which may limit future experimentation capabilities.
• No progressive enhancement for older browsers: Design assumes modern browser support (ES6+ features), with no fallback strategies for legacy environments.