Vercel Composition Patterns

核心用法

本 Skill 提供 React 组件组合模式体系，用于构建灵活、可维护的组件架构。核心解决三大痛点：

1. Boolean Prop 泛滥：通过组合模式替代 isOpen、hasHeader 等条件渲染 props
2. 组件库 API 设计：建立 compound components 模式，用显式变体组件替代配置式 props
3. 状态管理解耦：将状态提升至 Provider 层，实现兄弟组件间状态共享

四大规则类别

| 优先级 | 类别 | 关键规则 |

|--------|------|---------|

| HIGH | Component Architecture | `avoid-boolean-props`、`compound-components` |

| MEDIUM | State Management | `lift-state`、`context-interface` |

| MEDIUM | Implementation Patterns | `explicit-variants`、`children-over-render-props` |

| MEDIUM | React 19 APIs | `no-forwardref`（使用 `use()` 替代 `useContext`） |

典型应用场景

• 重构拥有 5+ boolean props 的臃肿组件
• 设计可扩展的 UI 组件库（如 Tabs、Modal、Accordion）
• 实现依赖注入式的状态共享架构

显著优点

• 来源权威性：Vercel 官方出品，与 Next.js 生态深度契合
• 工程可扩展性：模式经过大型项目验证，AI 代理和人类开发者均易理解
• React 19 前瞻：涵盖 use() hook、ref 传递新范式等最新 API
• 优先级分层：HIGH/MEDIUM 分级指导，资源有限时聚焦架构层规则

潜在局限

• 版本锁定：React 19 专属规则对存量 React 18 项目直接不可用
• 学习曲线：compound components 模式对初级开发者需要适应期
• 迁移成本：重构 boolean props 为组合模式需改动调用方代码
• 生态依赖：部分模式（如 Context Provider 嵌套）在极端复杂场景可能影响性能

适合人群

• 构建设计系统或组件库的前端工程师
• 负责重构遗留 React 代码库的 Tech Lead
• 使用 Next.js App Router 的全栈开发者
• 需要统一团队组件架构规范的中大型团队

常规风险

• S 级安全：纯编码规范类 skill，无网络请求、代码执行或数据敏感操作
• 规则文件需配合项目实际技术栈选用，盲目应用 React 19 规则至旧版本将导致构建失败
• 建议配合 TypeScript 使用以获得完整的类型推导收益

核心用法

本 Skill 是一套 React 组件组合模式的系统性指南，旨在解决组件膨胀、布尔属性泛滥等常见问题。核心用法包括：

1. 架构层面：使用复合组件（Compound Components）替代布尔属性控制行为，通过上下文共享状态实现组件间的隐式通信
2. 状态管理：将状态逻辑封装在 Provider 内部，对外暴露统一的 Context 接口，实现状态与 UI 的解耦
3. 实现模式：创建显式变体组件（如 PrimaryButton、SecondaryButton）替代 mode 属性，优先使用 children 组合而非 render props
4. React 19 适配：移除 forwardRef，推荐使用 use() 替代 useContext()

显著优点

• 权威性极高：Vercel 官方出品，与 Next.js 同团队维护，代表业界前沿实践
• 规模化设计：专门针对大型代码库和组件库场景，显著降低长期维护成本
• AI 友好：清晰的架构模式使 AI 代理更容易理解和重构代码
• 零运行时开销：纯设计模式指导，无额外依赖或性能损耗
• 版本前瞻性：包含 React 19 最新 API 的迁移指南

潜在局限性

• 学习曲线：复合组件等模式对初学者有一定理解门槛
• 适用边界：小型项目或快速原型可能不需要如此严格的架构规范
• 生态锁定：部分模式（如 React 19 特性）需要较新的技术栈支持
• 团队共识：需要团队成员统一遵循才能发挥最大价值

适合人群

• 正在构建或维护 React 组件库的前端开发者
• 面临"布尔属性地狱"需要重构的大型项目团队
• 希望提升代码可维护性和 AI 协作效率的技术负责人
• 准备升级至 React 19 并需要迁移指南的开发者

常规风险

无显著风险。本 Skill 为纯文档型指导，无可执行代码、无外部依赖、无网络请求。所有建议均为行业公认的最佳实践，不涉及敏感操作。唯一需注意：React 19 相关模式在低版本项目中无法直接使用。