React

React Implementation Patterns

Use this skill to build React UI that is predictable, composable, and easy to reason about under change.

When to Use

• Building, refactoring, or debugging React components, hooks, or client-side interaction flows
• Reviewing React code for component design, state management, or rendering correctness
• Implementing forms, interactive widgets, or data-driven UI with React
• Optimizing React rendering performance (memoization, re-render analysis)

When NOT to Use

• Task is about Next.js-specific routing, SSR, or server components — use react-nextjs (load alongside react)
• Task is about shadcn/ui component styling or Tailwind class hygiene — use shadcn-tailwind (load alongside react)
• Task is about Vue, Nuxt, or SwiftUI — use the appropriate framework skill

Delivery Workflow

Use the checklist below and track progress:

React progress:
- [ ] Step 1: Discover project conventions, routing, and state boundaries
- [ ] Step 2: Define component API and ownership of state
- [ ] Step 3: Implement rendering and interaction flow
- [ ] Step 4: Control effects, async state, and performance
- [ ] Step 5: Verify accessibility and tests

Component Design

• Prefer small focused components with a stable public API.
• Keep state as close as possible to where it is used, but no closer than clarity allows.
• Lift state only when multiple consumers genuinely need shared ownership.
• Separate presentational pieces from data orchestration when complexity grows.
• Reuse existing design-system and shared primitives before creating new ones.

Component Composition

• Use compound components for complex widgets with shared context (Select, Tabs, Accordion).
• Always use forwardRef when building components that wrap native HTML elements or Radix primitives — consumers may need ref access for focus management, scrolling, or measurement.
• Prefer controlled components when the parent needs to read or reset state. Default to uncontrolled when internal state is sufficient and the parent does not observe it.
• Keep one component per file. Export sub-components from the same file only for compound patterns.
• Do not create wrapper components that just pass all props through — that adds indirection without value.

// forwardRef pattern — required for any component wrapping a native element
const Input = forwardRef<HTMLInputElement, InputProps>(
  ({ label, error, ...props }, ref) => (
    <div>
      <label>{label}</label>
      <input ref={ref} aria-invalid={!!error} {...props} />
      {error && <span role="alert">{error}</span>}
    </div>
  )
);
Input.displayName = 'Input';

State and Effects

• Treat derived data as derived data; do not duplicate it in state.
• Use effects only for synchronization with the outside world.
• Avoid effects that merely reshuffle props into state.
• Keep async state explicit: idle, loading, success, empty, error.
• Clean up subscriptions, timers, and in-flight async work where relevant.

Error Boundaries

• Wrap route-level and critical feature sections with error boundaries — one per feature area, not one for the entire app.
• Show meaningful fallback UI, not just "Something went wrong" — include what failed and what the user can do.
• Log error details to monitoring (Sentry, LogRocket) inside the error boundary handler.
• In Next.js App Router: prefer error.tsx route files over custom Error Boundary components.
• Reset the boundary state when the user navigates or retries — use a key prop or resetKeys pattern.

Hooks Guidance

• Keep custom hooks cohesive and named after the capability they provide.
• Do not hide critical side effects inside generic utility hooks.
• Respect hook dependency rules instead of muting them casually.
• Memoize only when it improves observable behavior or avoids real cost.
• Prefer straightforward code over defensive over-abstraction.

Forms and Interaction

• Model validation, dirty state, and submission states explicitly.
• Prevent duplicate submits and inconsistent optimistic UI.
• Keep error messages actionable and close to the affected control.
• Preserve keyboard accessibility and logical tab order.

Rendering Performance

• Avoid re-renders caused by unstable props, inline objects, or unnecessary lifted state.
• Use memoization selectively after identifying a real render issue.
• Keep list keys stable and meaningful.
• Do not solve structural state problems with blanket memo usage.

React Review Checklist

Architecture:
- [ ] Component boundaries are clear
- [ ] State ownership is appropriate
- [ ] Effects are only used for external synchronization

Behavior:
- [ ] Loading, error, and empty states are intentional
- [ ] Forms and interactive flows handle invalid and repeat actions
- [ ] Derived values are not duplicated in state

Quality:
- [ ] Accessibility semantics are present
- [ ] Tests cover critical user behavior
- [ ] Reuse beats one-off component invention

Anti-Patterns to Avoid

Connected Skills

• react-nextjs - use when the task is specifically about Next.js route and rendering behavior
• shadcn-tailwind - use when the UI stack relies on shadcn/ui and Tailwind CSS
• ui-design-quality - apply visual design quality rules for typography, color, spacing, animation, and micro-interactions
• technical-context-discovery - follow project React conventions before editing
• frontend-implementation - apply UI, design-system, and accessibility guidance
• ui-verification - verify implementation against approved designs when relevant