用途
本技能提供一套用于构建灵活、可维护 React 组件的组合模式（Composition Patterns）。其核心目标是避免布尔属性（boolean prop）泛滥，改用复合组件（compound components）、状态提升（lifting state）和内部组合（composing internals）来实现组件定制。上游来源为 vercel-labs/agent-skills 中的 composition-patterns。
适用范围
适用对象包括：可复用组件 API、复合组件、显式变体（explicit variants）、React 19 的 ref/use() 变更。
不覆盖的内容包括：视觉方向（属于 frontend-design）；Next.js 缓存或 RSC 数据获取（属于 next-v16、vercel-react）。
前提假设
- 典型 Basilic 应用使用 React 19+；在 React 18 上应跳过 React 19 规则部分。
- 服务端/客户端边界已存在；组合不得将服务端数据移入仅客户端的 provider。
原则
- 对于被复用的组件，优先使用组合而非布尔配置。
- 仅当兄弟组件需要时才提升客户端 UI 状态；服务端数据保留在服务端。
- 在出现第二个调用点之后再抽取共享原语，而不是为一次性路由 UI 抽取。
约束
必须（MUST）：
- 仅为共享 UI 包或 2 个以上调用点抽取复合组件，而非单个路由叶子节点。
- 保持 React Server Components 自行获取数据；将服务端渲染的 children 传入客户端叶子节点，而不是把该数据提升到客户端 provider。
- 将 URL 可共享状态、异步服务端状态和分组的本地 UI 状态保留在项目已使用的库上（query-string 解析器、TanStack Query、分组状态 hooks）——不要用通用 context DI 层替换它们。
应当（SHOULD）：
- 除非父组件必须附加 ref，否则跳过 forwardRef。
- 在复用 API 上使用显式变体组件，而非 isX 布尔模式。
- 优先使用 children 而非 renderX 属性。
避免（AVOID）：
- 围绕一次性屏幕的过早抽象。
- 唯一职责是重新导出 RSC 获取的 props 的客户端 provider。
- 为了“组合一切”而破坏现有的 'use client' 放置位置。
交互关系
- App Router / RSC：next-v16
- React 性能：vercel-react
- shadcn 原语：shadcn-v3
- URL 状态：nuqs-v2
- 客户端异步：tanstack-query-v5
- 分组本地状态：ahooks-v3
何时应用
- 重构带有大量布尔属性的组件
- 构建可复用组件库
- 设计灵活的组件 API
- 审查组件架构
- 处理复合组件或 context provider
按优先级划分的规则类别
| 优先级 | 类别 | 影响 | 前缀 |
|---|---|---|---|
| 1 | Component Architecture | HIGH | architecture- |
| 2 | State Management | MEDIUM | state- |
| 3 | Implementation Patterns | MEDIUM | patterns- |
| 4 | React 19 APIs | MEDIUM | react19- |
快速参考
- 组件架构（HIGH）
- architecture-avoid-boolean-props — 不要添加布尔属性来自定义行为；使用组合。
- architecture-compound-components — 使用共享 context 构建复杂组件。
- 状态管理（MEDIUM）
- state-decouple-implementation — Provider 是唯一知道状态如何管理的地方。
- state-context-interface — 定义包含 state、actions、meta 的通用接口，用于依赖注入。
- state-lift-state — 将状态移入 provider 组件以便兄弟组件访问。
仅在上述约束允许的地方应用这些规则。不要提升服务端拥有的数据。
- 实现模式（MEDIUM）
- patterns-explicit-variants — 创建显式变体组件，而非布尔模式。
- patterns-children-over-render-props — 使用 children 进行组合，而非 renderX 属性。
- React 19 API（MEDIUM） 仅限 React 19+。在 React 18 或更早版本上跳过本节。
- react19-no-forwardref — 新组件不要使用 forwardRef。use() 对于条件式 context 读取是可选的；useContext() 仍然受支持。
如何使用
阅读各规则文件以获取详细说明和代码示例：
- rules/architecture-avoid-boolean-props.md
- rules/state-context-interface.md
每个规则文件包含其重要性说明、错误与正确示例以及额外上下文。
完整编译指南（不要将其命名为 AGENTS.md；Cursor 会始终加载该文件名）：references/compiled.md