vercel-composition-patterns

Overview

What vercel-composition-patterns is

vercel-composition-patterns は、スケールしやすいReactコンポーネント設計に焦点を当てた vercel-labs/agent-skills のフロントエンド開発スキルです。複雑なUIをリファクタリングしたいチーム、再利用可能なコンポーネントライブラリを構築したいチーム、柔軟なコンポーネントの設計方針を標準化したいチームに向けて、実践的なコンポジションパターンをまとめています。

このリポジトリのガイダンスを貫くテーマは明確で、設定を増やすよりコンポジションを優先する、という考え方です。boolean props や render props、分岐ロジックを追加して1つのコンポーネントを肥大化させるのではなく、compound components、共有context、stateのリフトアップ、明示的なcomponent variantsを推奨しています。

What problems this skill helps solve

このスキルは、Reactコンポーネントの見通しが悪くなってきたときに特に役立ちます。とくに、1つのコンポーネントが isEditing や isThread のようなフラグ付きpropsで多数のモードを支えているコードベースでは効果的です。収録されているルールは、次のような問題を減らすことを目的としています。

• boolean props の増殖
• ネストしたUIでの prop drilling
• 拡張しづらい巨大なコンポーネントAPI
• stateと表示ロジックの密結合
• React 19 APIへの移行時に古くなりやすいパターン

リポジトリ内の内容からは、compound components、contextベースのコンポジション、children優先のパターン、明示的なvariants、さらに forwardRef を避けることや use() の活用といったReact 19向けの更新まで、実践的な指針が確認できます。

Who should install it

vercel-composition-patterns は、次のようなケースに適しています。

• 共有UIシステムやコンポーネントライブラリを運用しているReactチーム
• 大規模でstateを多く持つコンポーネントをリファクタリングしているフロントエンド開発者
• Reactアーキテクチャに関する方針を明確にしたいVercelユーザーやAI支援コーディング環境
• コンポーネントAPIの品質や保守性をレビューするエンジニア

特に、人間にもAIエージェントにも一貫して守りやすい設計ルールをチームで整えたい場合に相性のよいスキルです。

What is included in the repository

このスキルには、SKILL.md の高レベルなガイダンス、AGENTS.md の機械向け実装ガイダンス、metadata.json のメタデータ、そして rules/ 配下のルールセットが含まれています。

ルールファイルは、ドキュメント上では次の4領域に整理されています。

• Component Architecture
• State Management
• Implementation Patterns
• React 19 APIs

主なリポジトリファイルは以下のとおりです。

• SKILL.md
• README.md
• AGENTS.md
• metadata.json
• rules/architecture-avoid-boolean-props.md
• rules/architecture-compound-components.md
• rules/state-lift-state.md
• rules/state-context-interface.md
• rules/state-decouple-implementation.md
• rules/patterns-children-over-render-props.md
• rules/patterns-explicit-variants.md
• rules/react19-no-forwardref.md

When vercel-composition-patterns is a strong fit

次のような場面では、このスキルの導入効果が高くなります。

• 再利用可能なReact APIを設計し直している
• モードが増えすぎた大きなコンポーネントを分割したい
• 共有contextを使ったcompound componentsを導入したい
• stateをproviderコンポーネント側へ移したい
• 新規実装をReact 19時代のパターンに揃えたい

When it may not be the best fit

プロジェクトがReactベースではない場合、コンポーネントが意図的にシンプルでローカルに閉じている場合、あるいは設計指針ではなく幅広いUIフレームワークが必要な場合は、このスキルの優先度は下がります。これはコンポーネント実行環境を提供するパッケージではなく、設計判断のためのパターンライブラリです。

How to Use

Install the skill

次のコマンドで、vercel-labs/agent-skills リポジトリから composition-patterns を追加できます。

npx skills add https://github.com/vercel-labs/agent-skills --skill composition-patterns

ローカルで vercel-composition-patterns を使い始めるには、これが最も直接的なインストール方法です。

Review the key files first

インストール後は、個別のルールを読み始める前に、まずスコープや意図をつかめるファイルから確認するのがおすすめです。

• 要約、ユースケース、カテゴリの優先度を把握するための SKILL.md
• リポジトリ構成とルール群の整理を確認するための README.md
• AI支援ワークフローで使われる統合ガイダンスを確認するための AGENTS.md
• バージョン、組織、概要、参照情報を確認するための metadata.json

その後、rules/ ディレクトリに進み、実際のコンポーネントにガイダンスを当てはめていきます。

Use the rules in a practical order

取り入れる順番としては、次の流れが現実的です。

1. rules/architecture-avoid-boolean-props.md を読み、過剰に複雑化したコンポーネントAPIを見つける。
2. rules/architecture-compound-components.md を読み、コンポーネントを組み合わせ可能な部品として再設計する。
3. rules/state-lift-state.md、rules/state-context-interface.md、rules/state-decouple-implementation.md を使って、stateの責務とUIの責務を分離する。
4. rules/patterns-explicit-variants.md と rules/patterns-children-over-render-props.md を適用し、APIの明快さを高める。
5. コードベースでReact 19のパターンを導入するなら、rules/react19-no-forwardref.md を確認する。

What usage looks like in practice

実務のフロントエンド開発では、vercel-composition-patterns はそのまま写経するものというより、リファクタリングやレビューの指針として使うのが適しています。たとえば、レイアウトや振る舞いを複数のフラグで制御する1つの Composer コンポーネントがあるなら、このスキルは次のような方向へ導きます。

• フラグだらけの単一APIではなく、役割ごとに分かれたvariants
• providerベースの共有state
• contextを直接参照するsubcomponents
• 多数のrender callback propsではなく、childrenベースのコンポジション

こうした設計にすることで、コンポーネント境界を拡張しやすくなり、コードレビュー時の理解もしやすくなります。

How to evaluate it before wider rollout

導入を判断する際は、まず1つの課題コンポーネントで試すのが有効です。候補としては、すでに分岐propsが多い modal、composer、form shell、menu、editor wrapper などが向いています。リファクタリングによって条件分岐が減り、variantsの意図がより明確になるなら、フロントエンド全体の標準として広げる価値が高いと考えられます。

References surfaced by the repository

リポジトリのメタデータでは、ドキュメントの方針を裏づけるReact公式ドキュメントへの参照も示されています。

• https://react.dev
• https://react.dev/learn/passing-data-deeply-with-context
• https://react.dev/reference/react/use

FAQ

Does vercel-composition-patterns include ready-made React components?

いいえ。vercel-composition-patterns はコンポーネントライブラリではなく、ガイダンスを提供するスキルです。独自のReactコンポーネントをどう構成するかについて、設計ルール、パターン、例を提供します。

Is vercel-composition-patterns only for large design systems?

いいえ。共有コンポーネントライブラリで特に効果を発揮しますが、1つのコンポーネントがboolean propsやrender props、密結合したstateによって複雑化しているアプリケーションコードでも十分に役立ちます。

What are the main patterns covered?

リポジトリの内容からは、boolean props を避けること、compound components の活用、providerへのstateのリフトアップ、明確なcontext interfaceの定義、実装とUIの分離、render props より children を優先すること、明示的なvariantsの作成、React 19 API変更への対応といったパターンがカバーされていることがわかります。

Is this skill specific to React?

はい。リポジトリの内容は明確にReactのコンポジションパターンを中心にしており、React公式ドキュメントへの参照やReact 19固有のガイダンスも含まれています。

How do I know if I should install composition-patterns?

フロントエンドのコードベースに、きれいに拡張しにくいコンポーネント、多数のモードフラグに依存するコンポーネント、あるいは保守しやすいコンポジションモデルが必要な箇所があるなら、vercel-composition-patterns を導入する価値があります。UIが小規模で単純な場合は、現時点では必要以上にガイダンスが多いと感じるかもしれません。

Where should I start after installation?

まず SKILL.md を読み、次に README.md を確認し、その後 rules/ にある影響度の高いアーキテクチャルールから見ていくのがおすすめです。この順番なら、概要の理解から実践的なReact活用まで最短でつなげられます。