composition-patterns-guide

composition-patterns-guide — modern React composition + our colocation rules

This skill is a knowledge guardrail that activates whenever you're designing, refactoring, or reviewing the architecture of a React/RN component. It combines two layers:

1. The 7 Vercel composition-patterns rules (originally from vercel-labs/agent-skills), adapted to our stack.
2. Our colocation rules (Rule of Three for promotion, L0/L1/L2, _components/ and components/shared/<dominio>/).

It does NOT execute refactors — for that, use promote-component. It provides the thinking framework.

When this skill applies

• About to add a 4th boolean prop to an existing component.
• About to write a component with renderHeader, renderFooter, renderActions render-prop callbacks.
• A component grew over ~250 lines and needs structural refactor.
• You see prop drilling 3+ levels deep.
• About to use forwardRef in new code (React 19+ projects).
• Reviewing a PR that touches component architecture.

Orchestrator does NOT route here automatically — invoked by the agent's own judgment when the patterns match.

The 7 composition rules (priority order)

Priority 1 — Component Architecture (HIGH)

Rule 1: Avoid boolean prop proliferation

Wrong:

<Composer
  onSubmit={...}
  isThread={true}
  channelId={42}
  isDMThread={false}
  dmId={null}
  isEditing={true}
  isForwarding={false}
/>

Each boolean doubles the state-space. 5 booleans = 32 possible combinations, most of which are invalid or untested.

Right (composition):

<Composer>
  <Composer.Header />
  <Composer.Input />
  <Composer.ThreadField channelId={42} />
  <Composer.EditActions />
  <Composer.Footer onSubmit={...} />
</Composer>

The consumer composes the parts they need. No invalid states.

Rule 2: Use compound components

A complex component should expose subcomponents that share context, not a single API with N props.

Wrong:

function Card({ title, body, footer, showAvatar, avatarUrl }) {
  return <div>...</div>;
}