React Patterns Reference

Target Spawn

Frontend domain work spawned via Agent(general-purpose) with frontend instructions - Applies these patterns directly to component design and state management.

Component Design Patterns

1. Compound Components

Parent and child share implicit state via Context.

Suited for: Tab, Accordion, Dropdown, Select Structure: <Select> + <Select.Trigger> + <Select.Option>

2. Custom Hooks (Extraction Pattern)

Extract state logic into reusable hooks.

Suited for: Form management, API calls, localStorage, debounce Naming: use prefix required - useForm, useDebounce, useAuth

3. Container/Presentational Separation

Separate data logic (Container) from UI (Presentational).

Suited for: Large apps, when testability is needed Container: Data fetch, state management, event handlers Presentational: Renders only from props, functionally pure

4. Headless Component

Provides behavior/state without UI.

Suited for: Design system-independent logic Examples: headless useCombobox, useDialog, useTable

State Management Selection Guide

Decision Flow

Restorable from URL? -> URL state (nuqs)
Server data? -> React Query
Shared across components? -> Zustand
Component-internal? -> useState
Complex transitions? -> useReducer

Next.js App Router Structure

src/
├── app/                    # App Router
│   ├── (auth)/             # Auth route group
│   │   ├── login/page.tsx
│   │   └── register/page.tsx
│   ├── (main)/             # Main route group
│   │   ├── dashboard/page.tsx
│   │   └── settings/page.tsx
│   ├── api/                # API Routes
│   ├── layout.tsx          # Root layout
│   └── page.tsx            # Home
├── components/
│   ├── ui/                 # Base UI (Button, Input, Modal)
│   └── features/           # Feature components
│       ├── auth/
│       └── dashboard/
├── hooks/                  # Custom hooks
├── lib/                    # Utilities, config
├── stores/                 # Zustand stores
├── types/                  # TypeScript types
└── styles/                 # Global styles

Component Quality Standards

Performance Patterns

Error Handling

Hierarchical Error Boundaries

RootErrorBoundary (global)
  └── LayoutErrorBoundary (per section)
      └── ComponentErrorFallback (individual)

API Error Handling

Accessibility Checklist

• Alt text on all images
• Keyboard navigation (Tab, Enter, Escape)
• ARIA labels (aria-label, role)
• Color contrast 4.5:1 or above
• Visible focus indicator
• Semantic HTML (button, nav, main, section)

Common Rationalizations

Red Flags

• useEffect used for data fetching when server components or use() are available
• Component receives more than 5 props without decomposition or object grouping
• State management library used for server-cacheable data (use React Query or SWR instead)
• Inline styles or hardcoded pixel values instead of design tokens
• Component missing error boundary wrapping for async operations

Verification

• Data fetching uses server components, use(), or React Query (not useEffect + fetch)
• Components have TypeScript interfaces for all props
• Error boundaries wrap components with async operations
• Accessibility checklist completed (alt text, keyboard nav, ARIA, contrast, focus, semantics)
• No inline styles or hardcoded color/spacing values (design tokens used)
• Component renders correctly in React Strict Mode (no double-effect issues)