struxadotcloud/struxa

public

initial commitd4cb9e15 months ago88 lines · 2.8 KB

1	---
2	name: vercel-composition-patterns
3	description: React composition patterns that scale. Use when refactoring components with
4	boolean prop proliferation, building flexible component libraries, or
5	designing reusable APIs. Triggers on tasks involving compound components,
6	render props, context providers, or component architecture. Includes React 19
7	API changes.
8	license: MIT
9	metadata:
10	author: vercel
11	version: "1.0.0"
12	---
13
14	# React Composition Patterns
15
16	Composition patterns for building flexible, maintainable React components. Avoid
17	boolean prop proliferation by using compound components, lifting state, and
18	composing internals. These patterns make codebases easier for both humans and AI
19	agents to work with as they scale.
20
21	## When to Apply
22
23	Reference these guidelines when:
24
25	- Refactoring components with many boolean props
26	- Building reusable component libraries
27	- Designing flexible component APIs
28	- Reviewing component architecture
29	- Working with compound components or context providers
30
31	## Rule Categories by Priority
32
33	\| Priority \| Category \| Impact \| Prefix \|
34	\| -------- \| ----------------------- \|
35	\| 1 \| Component Architecture \| HIGH \| `architecture-
36	\| 2 \| State Management \| MEDIUM \| `state-
37	\| 3 \| Implementation Patterns \| MEDIUM \| `patterns-
38	\| 4 \| React 19 APIs \| MEDIUM \| `react19-
39
40	## Quick Reference
41
42	### 1. Component Architecture (HIGH)
43
44	- `architecture-avoid-boolean-props` - Don't add boolean props to customize
45	behavior; use composition
46	- `architecture-compound-components` - Structure complex components with shared
47	context
48
49	### 2. State Management (MEDIUM)
50
51	- `state-decouple-implementation` - Provider is the only place that knows how
52	state is managed
53	- `state-context-interface` - Define generic interface with state, actions, meta
54	for dependency injection
55	- `state-lift-state` - Move state into provider components for sibling access
56
57	### 3. Implementation Patterns (MEDIUM)
58
59	- `patterns-explicit-variants` - Create explicit variant components instead of
60	boolean modes
61	- `patterns-children-over-render-props` - Use children for composition instead
62	of renderX props
63
64	### 4. React 19 APIs (MEDIUM)
65
66	> **⚠️ React 19+ only.
67
68	- `react19-no-forwardref` - Don't use `forwardRef`; use
69
70	## How to Use
71
72	Read individual rule files for detailed explanations and code examples:
73
74	```
75	rules/architecture-avoid-boolean-props.md
76	rules/state-context-interface.md
77	```
78
79	Each rule file contains:
80
81	- Brief explanation of why it matters
82	- Incorrect code example with explanation
83	- Correct code example with explanation
84	- Additional context and references
85
86	## Full Compiled Document
87
88	For the complete guide with all rules expanded: `AGENTS.md`