vercel-composition-patterns

vercel-composition-patterns 技能總覽

vercel-composition-patterns 是一個 React 架構技能，用來在「組合」與「過度依賴 props 的元件 API」之間做選擇。它特別適合前端工程師、設計系統作者，以及 AI 協助重構的工作，因為這類情境真正要解決的，通常是減少布林 props 的膨脹、釐清元件邊界，並讓可重用 API 在不破壞呼叫端的前提下更容易擴充。

vercel-composition-patterns 的主要價值在於決策支援：它幫你判斷何時該用 compound components、提升 state、明確 variants、children composition，或是 React 19 專屬 API，而不是把所有東西硬塞進單一可配置元件裡。

前端元件設計的最佳適用情境

當你在做以下事情時，使用 vercel-composition-patterns for Frontend Development：

• 重構一個有太多布林值或模式旗標的元件
• 建立可重用的 UI kit 或產品元件庫
• 審視某個元件 API 是否過於僵硬，或過於「魔術化」
• 將共用 UI state 移到 provider 或 context 結構中
• 更新 React 19 相關程式碼，例如避免使用 forwardRef

它在實務上為什麼有幫助

這個 skill 的立場很鮮明，但對 agent 來說很實用：它會先把架構規則放在前面，再談 state，最後才是實作模式。當你需要的是可擴充的解法，而不只是局部補丁時，這個順序很重要。

什麼時候值得安裝

如果你想要的是比一般 React 提示更接近架構評分表的指引，就安裝 vercel-composition-patterns。如果你只需要一段一次性的元件範例，且不在乎 API 設計、重用性或長期維護，那就可以先跳過。

如何使用 vercel-composition-patterns skill

安裝 skill 並確認規則集

先使用目錄標準 skill manager 的 vercel-composition-patterns install 流程，然後確認 repository 路徑是 skills/composition-patterns。這個 skill 沒有 install script；真正的價值在於規則檔與其排序，而不是產生出來的程式碼。

先從決策規則開始，不要先從實作開始

最有效的 vercel-composition-patterns usage，是先把元件問題丟給模型，而不是直接指定你想要的程式碼長相。範例輸入：

• “Refactor this Composer component with isThread, isDMThread, and isEditing into a composition-based API.”
• “Design a compound component API for a settings panel that shares selection state across subcomponents.”
• “Review this UI library component and suggest whether it should become explicit variants or 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 結構
• 使用者是否需要客製化，還是只有少數固定模式
• 哪些子區塊必須共享 state
• 是否涵蓋 React 19
• 是否需要向下相容

較弱的輸入： “Make this component better.”
較強的輸入： “This component has 6 boolean props, 3 modes, and a shared submit state. Propose a compound-component API that keeps public usage simple and moves internal branching into context.”

vercel-composition-patterns skill 常見問題

vercel-composition-patterns 只適合大型 codebase 嗎？

不是。它在較大型或可重用的元件系統中特別有價值，但即使是較小的元件，只要 API 已經開始變得難以推理，它也能派上用場。判斷重點不只是規模，而是元件是否開始透過 props 而不是結構來表達行為。

這和一般 React 提示有什麼不同？

一般提示可能只會給你一個看起來可行的元件。vercel-composition-patterns 會推著模型去說明 API 形狀、優先考量架構規則，並避免常見退化，例如布林 props 膨脹或過度使用 render props。

這適合初學者嗎？

可以，如果你的目標是學習良好的元件邊界。若你想要的是可直接複製貼上的快速方案，而且不想看取捨說明，那它就沒那麼適合初學者。當你願意先比較設計、再開始寫程式時，這個 skill 會更好用。

什麼情況下不該用它？

不要把 vercel-composition-patterns 用在快速樣式調整、很單純的一次性元件，或是 API 已經固定、不能再改的情況。它最強的時候，是主要風險來自錯誤抽象，而不是單純需要更快把實作做完。

如何改進 vercel-composition-patterns skill

提供現有 API 的形狀

品質提升最大的一步，就是把目前的元件簽章貼出來，尤其是布林值、variant props、callbacks，以及共用 state。只有看得到現在是怎麼過度配置的，skill 才能真正提出更好的 composition 方式。

說明你想要的使用者體驗

告訴模型你希望這個元件從外部看起來是什麼感覺：

• “Consumers should assemble the UI from subcomponents.”
• “Only three variants should be public.”
• “Internal state should stay hidden behind a provider.”

這會讓 vercel-composition-patterns usage 更準，因為最適合的模式取決於預期的 public API，而不只是內部重構本身。

先要模式建議，再要程式碼

有效的流程是：先問架構選擇，再問實作方式。比如：

1. “Should this be compound components, explicit variants, or children composition?”
2. “Now rewrite it using the chosen pattern.”

這種兩步驟做法可以減少過早產生程式碼，也讓 vercel-composition-patterns skill 的結果更穩定。

注意常見失敗模式

常見的失敗模式有：

• 用一樣難懂的神秘 props 去取代布林值
• 不管情況如何，全部元件都硬改成 compound component，明明 variant API 更簡單
• 把 state 移到 context，卻沒有講清楚 state/actions/meta 介面
• 在 React 19 敏感的程式碼中使用 forwardRef

如果第一版輸出看起來太抽象，就把需求再收緊一些：目標 React 版本、相容性限制，以及 public API 是否必須保持穩定。