React Component Architecture Guide

You are a senior React architect with deep expertise in building large-scale component libraries and production applications. Design a comprehensive component architecture based on the following project context.

Project Details:
Project Type: [SAAS DASHBOARD/E-COMMERCE/CONTENT PLATFORM/SOCIAL APP/INTERNAL TOOL]
Team Size: [NUMBER OF FRONTEND DEVELOPERS]
Design System Maturity: [NONE/EARLY STAGE/ESTABLISHED]
Component Library: [BUILDING FROM SCRATCH/EXTENDING EXISTING/MIGRATING]
State Complexity: [LOW/MEDIUM/HIGH]
Performance Requirements: [STANDARD/HIGH TRAFFIC/REAL-TIME UPDATES]

Section 1 - Component Hierarchy and Classification:
Define a clear component taxonomy that separates primitive UI atoms like buttons, inputs, and badges from composed molecules like search bars and card headers and from complex organisms like navigation headers, data tables, and form sections. Establish the rules for when a component should be split into smaller pieces based on the single responsibility principle and reusability potential. Create naming conventions that communicate component purpose and scope including prefix conventions for shared versus feature-specific components. Specify the folder structure organizing components by type or by feature with clear guidelines on when to colocate styles, tests, types, and stories alongside component files. Address the strategy for managing component variants using props versus creating separate components and define the threshold for when a component has too many props and should be decomposed.

Section 2 - Composition Patterns and Prop Design:
Define the primary composition patterns the team should use including compound components for complex UI elements like tabs and accordions, render props for flexible rendering logic, and the children pattern for layout components. Establish prop interface design principles covering required versus optional props, default values, prop naming conventions, and when to use discriminated unions for mutually exclusive prop combinations. Create guidelines for the polymorphic as prop pattern that allows components to render as different HTML elements while maintaining type safety. Specify how to handle event handler props including naming conventions like onAction, callback signatures, and whether to pass native events or extracted values. Address the strategy for forwarding refs using forwardRef and when components should expose imperative handles versus relying on declarative state.

Section 3 - Custom Hooks and Logic Separation:
Define the architecture for separating business logic from presentation using custom hooks that encapsulate state, side effects, and computed values. Establish patterns for data fetching hooks that integrate with the chosen data fetching library and return loading, error, and data states in a consistent format across all hooks. Create guidelines for composing hooks together including when to extract shared logic into base hooks that more specific hooks build upon. Specify how hooks should handle cleanup including aborting fetch requests, clearing timers, and unsubscribing from event listeners. Address the testing strategy for custom hooks including using renderHook from React Testing Library and how to mock dependencies within hook tests.

Section 4 - Styling Architecture and Design Tokens:
Recommend the styling approach and justify the choice between CSS Modules, Tailwind CSS, styled-components, or vanilla extract based on the project requirements and team preferences. Define how design tokens for colors, spacing, typography, shadows, and breakpoints should be structured, stored, and consumed by components. Create the responsive design strategy specifying breakpoint values, whether to use mobile-first or desktop-first media queries, and how components should adapt across viewport sizes. Establish guidelines for handling component-level style overrides including whether to support className props, style props, or a dedicated variant and size system. Address the dark mode and theming implementation using CSS custom properties or a theme provider pattern with specific guidance on how components should consume theme values.

Section 5 - Performance Optimization Patterns:
Define when and how to use React.memo for preventing unnecessary re-renders with clear criteria for which components benefit from memoization versus which incur unnecessary overhead. Establish guidelines for useMemo and useCallback usage including the rule of thumb for when the computation or reference stability justifies the memoization cost. Create the code splitting strategy specifying which components should be lazy loaded using React.lazy and Suspense and how to design loading fallbacks that prevent layout shift. Specify how to optimize list rendering using virtualization libraries like react-window or tanstack-virtual for long lists and how to implement proper key strategies for dynamic lists. Address the bundle size management approach including how to audit component dependencies, avoid pulling in entire icon libraries, and tree-shake effectively.

Section 6 - Testing and Documentation Standards:
Define the testing strategy for components including unit tests for utility functions, integration tests for component behavior using React Testing Library, and visual regression tests using tools like Chromatic or Percy. Establish the test file organization and naming conventions with guidelines on what to test including user interactions, conditional rendering, error states, and accessibility and what not to test such as implementation details and internal state. Create the component documentation requirements including prop tables with types and descriptions, usage examples showing common patterns, and do and don't guidelines for proper usage. Specify how to document component APIs using JSDoc comments or TypeScript interfaces that generate documentation automatically. Address the approach for maintaining a component catalog using Storybook or a similar tool with stories for each component variant, state, and interaction pattern.