Refactor React Components with Composition Patterns

React Composition Patterns documents a set of rules for building flexible, maintainable React components by avoiding boolean-prop proliferation - the pattern where a component grows more and more isX/showY/variantZ boolean props to customize its behavior, eventually producing an unmanageable combinatorial explosion of states. Rules are grouped into four priority categories: component architecture (avoid boolean props, use compound components with shared context), state management (decouple implementation so only the provider knows how state works, define a generic context interface with state/actions/meta for dependency injection, lift state into provider components for sibling access), implementation patterns (explicit variant components instead of boolean modes, children over render props for composition), and React 19-specific APIs (no forwardRef, use use() instead of useContext() - applicable only on React 19+).

Use it when refactoring a component that has accumulated many boolean props, building a reusable component library, designing a flexible component API, reviewing component architecture, or working with compound components or context providers. Skip the React 19 section entirely if the project is on React 18 or earlier - those rules don't apply.

Each rule lives in its own file under rules/ (e.g. architecture-avoid-boolean-props.md, state-context-interface.md), containing a brief explanation of why it matters, an incorrect code example with explanation, a correct code example with explanation, and additional context/references. A full compiled document with every rule expanded is available at AGENTS.md for a single-pass read.

The rules are designed to make a codebase easier for both humans and AI coding agents to work with as it scales - the compound-component and lifted-state patterns specifically reduce the surface area an agent has to reason about when extending a component.

React developers refactoring boolean-prop-heavy components, building component libraries, or reviewing architecture, who want a concrete rule set with incorrect/correct code pairs rather than vague "keep it composable" advice.