vercel-composition-patterns

vercel-composition-patterns 技能概览

vercel-composition-patterns 是一个 React 架构技能，用于在组件 API 过度依赖 props 时，优先选择 composition 而不是堆满 props 的设计。它最适合前端工程师、设计系统作者，以及 AI 辅助重构场景：核心目标是减少布尔型 props 膨胀，厘清组件边界，并让可复用 API 更容易扩展，同时不破坏现有调用方。

vercel-composition-patterns 技能的主要价值在于决策支持：它帮助你判断何时该用 compound components、提升状态（lifted state）、显式 variants、children composition，或 React 19 特定 API，而不是把所有东西都硬塞进一个可配置组件里。

前端组件设计的最佳适用场景

当你遇到以下情况时，使用 vercel-composition-patterns for Frontend Development：

• 正在重构一个布尔值或模式标记太多的组件
• 正在搭建可复用的 UI kit 或产品组件库
• 正在评估某个组件 API 是不是太死板，或者太“魔法化”
• 正在把共享 UI 状态迁移到 provider 或 context 结构中
• 正在针对 React 19 的变化更新代码，比如避免使用 forwardRef

它在实践中的价值

这个技能带有明确立场，但这种立场对 agent 很有用：它会先强调架构规则，再谈状态，最后才是实现模式。这个顺序很重要，因为你需要的是一个可扩展的解决方案，而不是一次性的局部修补。

什么时候值得安装

如果你需要的指导更像架构评审标准，而不是泛泛的 React 提示词，那么就安装 vercel-composition-patterns。如果你只想要一个临时可用的组件片段，不在乎 API 设计、复用性或长期维护，那就没必要安装。

如何使用 vercel-composition-patterns 技能

安装技能并确认规则集

通过目录中的标准技能管理器走 vercel-composition-patterns install 流程，然后确认仓库路径是 skills/composition-patterns。这个技能没有安装脚本；它的价值来自规则文件及其排序，而不是自动生成代码。

从决策规则开始，而不是从实现开始

最有效的 vercel-composition-patterns usage 是先把组件问题交给模型，而不是先给它你想要的代码形状。示例输入：

• “把这个带有 isThread、isDMThread 和 isEditing 的 Composer 组件重构成一个基于 composition 的 API。”
• “为一个设置面板设计 compound component API，让各个子组件共享选择状态。”
• “评审这个 UI library 组件，并建议它是否应该改成显式 variants 或 compound components。”

阅读会直接影响输出质量的文件

如果你想得到高质量的 vercel-composition-patterns guide，先看这些文件：

• SKILL.md：高层意图，以及何时适用的指导
• AGENTS.md：编译后的规则层级和优先模式
• rules/_sections.md：理解分类优先级
• rules/architecture-avoid-boolean-props.md
• rules/architecture-compound-components.md
• rules/react19-no-forwardref.md

提供会改变架构选择的上下文

高质量输入包括：

• 当前的 props 和 state 结构
• 消费者是需要自定义能力，还是只需要少量固定模式
• 哪些子部分必须共享状态
• React 19 是否在范围内
• 是否需要向后兼容

弱输入：“把这个组件做得更好。”
更强输入：“这个组件有 6 个布尔 props、3 种模式，还有一个共享提交状态。请提出一个 compound-component API，既保持外部使用简单，又把内部分支逻辑移到 context 中。”

vercel-composition-patterns 技能常见问题

vercel-composition-patterns 只适合大代码库吗？

不是。它在更大的或可复用的组件系统中最有价值，但当小组件的 API 已经开始变得难以推理时，它同样有帮助。关键不只是规模，而是组件是否已经在通过 props 而不是结构来编码行为。

它和普通的 React 提示词有什么不同？

普通提示词可能会给你一个“看起来能用”的组件。vercel-composition-patterns 会推动模型去论证 API 形状，优先考虑架构规则，并避免常见回归，比如布尔 props 泛滥或过度使用 render props。

它适合初学者吗？

适合，前提是你的目标是学习正确的组件边界。如果你只想要一个不解释取舍、能直接复制粘贴的方案，那它就没那么适合初学者。这个技能更适合愿意在动手编码前先比较不同设计的人。

什么时候不该用它？

不要把 vercel-composition-patterns 用在快速样式调整、简单的一次性组件，或者 API 已经固定且不能改的场景。它最强的地方是帮助你处理“抽象设计可能出错”的风险，而不是单纯追求实现速度。

如何改进 vercel-composition-patterns 技能

提供现有的 API 形状

质量提升最大的方式，是把当前组件签名贴出来，尤其是布尔值、variant props、回调和共享状态。只有看见“过度配置”具体长什么样，技能才能更准确地建议你用什么更好的 composition 方式。

说明你希望消费者获得什么体验

告诉模型你希望组件从外部看起来是什么感觉：

• “消费者应该通过子组件来组装 UI。”
• “只允许对外暴露三种 variants。”
• “内部状态应该隐藏在 provider 之后。”

这会提升 vercel-composition-patterns usage 的效果，因为最佳模式取决于你想要的公开 API，而不只是内部重构本身。

先要模式建议，再要代码

更稳妥的工作流是：先问架构选择，再问实现方式。例如：

1. “这里应该用 compound components、显式 variants，还是 children composition？”
2. “现在按选定模式重写它。”

这种两步法可以减少过早生成代码，也让 vercel-composition-patterns skill 的结果更可靠。

注意常见失败模式

主要的失败模式有：

• 把布尔值换成同样晦涩的“魔法 props”
• 不管是否需要，什么组件都改成 compound component
• 把状态挪到 context，却没有说明 state/actions/meta 接口
• 在对 React 19 敏感的代码里使用 forwardRef

如果第一次输出看起来过于抽象，就用约束把需求收紧：目标 React 版本、兼容性限制，以及公开 API 是否必须保持稳定。