home / skills / oimiragieo / agent-studio / composition-patterns-vercel

composition-patterns-vercel skill

safe

/.claude/skills/_archive/dead/composition-patterns-vercel

This skill guides React developers through scalable composition patterns to reduce boolean props and improve reusable APIs across components.

npx playbooks add skill oimiragieo/agent-studio --skill composition-patterns-vercel

Review the files below or copy the command above to add this skill to your agents.

Files (12)

SKILL.md

2.8 KB

---
name: vercel-composition-patterns
description: React composition patterns that scale. Use when refactoring components with
  boolean prop proliferation, building flexible component libraries, or
  designing reusable APIs. Triggers on tasks involving compound components,
  render props, context providers, or component architecture. Includes React 19
  API changes.
license: MIT
metadata:
  author: vercel
  version: '1.0.0'
---

# React Composition Patterns

Composition patterns for building flexible, maintainable React components. Avoid
boolean prop proliferation by using compound components, lifting state, and
composing internals. These patterns make codebases easier for both humans and AI
agents to work with as they scale.

## When to Apply

Reference these guidelines when:

- Refactoring components with many boolean props
- Building reusable component libraries
- Designing flexible component APIs
- Reviewing component architecture
- Working with compound components or context providers

## Rule Categories by Priority

| Priority | Category                | Impact | Prefix          |
| -------- | ----------------------- | ------ | --------------- |
| 1        | Component Architecture  | HIGH   | `architecture-` |
| 2        | State Management        | MEDIUM | `state-`        |
| 3        | Implementation Patterns | MEDIUM | `patterns-`     |
| 4        | React 19 APIs           | MEDIUM | `react19-`      |

## Quick Reference

### 1. Component Architecture (HIGH)

- `architecture-avoid-boolean-props` - Don't add boolean props to customize
  behavior; use composition
- `architecture-compound-components` - Structure complex components with shared
  context

### 2. State Management (MEDIUM)

- `state-decouple-implementation` - Provider is the only place that knows how
  state is managed
- `state-context-interface` - Define generic interface with state, actions, meta
  for dependency injection
- `state-lift-state` - Move state into provider components for sibling access

### 3. Implementation Patterns (MEDIUM)

- `patterns-explicit-variants` - Create explicit variant components instead of
  boolean modes
- `patterns-children-over-render-props` - Use children for composition instead
  of renderX props

### 4. React 19 APIs (MEDIUM)

> **⚠️ React 19+ only.** Skip this section if using React 18 or earlier.

- `react19-no-forwardref` - Don't use `forwardRef`; use `use()` instead of `useContext()`

## How to Use

Read individual rule files for detailed explanations and code examples:

```
rules/architecture-avoid-boolean-props.md
rules/state-context-interface.md
```

Each rule file contains:

- Brief explanation of why it matters
- Incorrect code example with explanation
- Correct code example with explanation
- Additional context and references

## Full Compiled Document

For the complete guide with all rules expanded: `AGENTS.md`

Overview

This skill packs React composition patterns that scale when refactoring components or designing reusable APIs. It focuses on avoiding boolean prop proliferation by using compound components, lifted state, and clear composition primitives. The guidance includes prioritized rules and notes for React 19 API changes.

How this skill works

The skill inspects component designs and suggests patterns such as compound components, provider-driven state, explicit variant components, and children-based composition over boolean flags or render props. It maps issues to rule categories (architecture, state, implementation patterns, React 19) and points to concrete rule files that show incorrect and correct examples. Use it to get prescriptive changes and sample code snippets for refactors and library design.

When to use it

Refactoring components that have many boolean props or mode flags
Building or maintaining a reusable component library or design system
Designing component APIs that need to be extensible and testable
Reviewing component architecture for maintainability and clarity
Working with compound components, context providers, or render-prop-to-children migrations

Best practices

Avoid boolean props; prefer composition or dedicated variant components
Encapsulate state management in provider components and lift state when siblings need access
Define a generic context interface with state, actions, and meta for dependency injection
Prefer children-based composition over render props when simpler and clearer
For React 19+, follow the guidance on use() and avoid forwardRef when recommended

Example use cases

Refactor a Modal or Tabs component that currently uses multiple boolean props into a compound component with a Provider and clearly named subcomponents
Design a Button group API that shares selection state via a provider instead of prop drilling
Convert a render-prop-based component to children composition to simplify usage and improve type inference
Create explicit Variant components (e.g., PrimaryButton, GhostButton) instead of a single Button with variant booleans
Audit a codebase for patterns that will break or improve under React 19 API changes

FAQ

Will this guidance work with React 18 and earlier?

Yes. Most patterns are framework-agnostic. React 19 notes are additive and should be skipped if you target React 18 or earlier.

How do I decide between lifting state and using context providers?

Lift state when a single parent coordinates a few children. Use a provider when many nested or sibling components need shared access and you want a clear, injectable interface.