main_frontend/.agents/skills/composition-patterns/SKILL.md

name, description

name	description
composition-patterns	Use when writing, reviewing, or refactoring React component APIs that risk boolean prop proliferation, renderHeader/renderFooter-style slots, prop drilling, trapped local state, context-provider architecture, compound components, explicit variants, or React 19 ref/context composition patterns.

Composition Patterns

Overview

Apply scalable React composition patterns from Vercel's composition-patterns skill, adapted for this Next.js/FSD repository. Prefer explicit composed APIs over configuration-heavy components, and keep reusable UI parts decoupled from state implementations.

Workflow

1. Identify whether the component is becoming a mode switcher. Look for multiple boolean props, conditional branches that choose whole UI regions, renderHeader/renderFooter props, or impossible prop combinations.
2. Split behavior into explicit variants when the rendered structure differs. Prefer names such as ThreadComposer, EditComposer, or ForwardComposer over one Composer with isThread, isEditing, and isForwarding.
3. Extract shared pieces into compound components when consumers need to arrange the parts themselves. Use Root/Provider, Frame, Header, Body, Footer, Trigger, Content, Action, or domain-specific names that fit the existing component.
4. Lift shared state into a provider boundary when siblings or custom outer UI need the same state/actions. Keep visual nesting separate from state access: components only need to be inside the provider, not inside the same DOM box.
5. Define a context contract with state, actions, and meta when multiple providers can drive the same UI. UI subcomponents consume the contract, while providers decide whether state comes from local hooks, server-synced data, forms, or feature-specific stores.
6. In this React 19 repo, pass ref as a normal prop and use use(Context) for context reads where the surrounding codebase allows it. Preserve existing conventions if a nearby component has not migrated yet.

Decision Rules

• Do not add a boolean prop to control a large behavior branch until checking whether an explicit variant or child composition would make the state space clearer.
• Use children for static structure composition. Keep render props for cases where the parent must pass item data, measurements, or callback-local state back into the child.
• Keep providers as the only layer that knows a concrete state implementation. Subcomponents should not import feature stores or synchronization hooks unless they are provider components.
• Avoid prop drilling through compound components. Put shared state/actions in a typed context and expose narrow subcomponents.
• Keep FSD boundaries intact: shared compound UI belongs under src/shared/ui; feature-specific variants and providers belong in the appropriate feature, entity, widget, or page layer.

Reference

Read references/rules.md when you need examples, a review checklist, or the upstream rule inventory. It summarizes all files from: https://github.com/vercel-labs/agent-skills/tree/main/skills/composition-patterns at commit ce3e64e468f8fa09a2d075d102771838061fdac0.